developers, dicom

Hacking classical DICOM : A Hello World primer

This weekend, I am at PennApps, a fantastic hackathon event in Philadelphia. It got me thinking about sharing some simple steps to hit the ground running, with classic DICOM (notwithstanding all of the amazing advances of #DICOMweb).

DISCLAIMER: This information is provided as-is, the content might be incorrect or out of date, and could harm kittens or even worse if used improperly.

I will also continue to update this post as necessary.

Step 0 : Understanding enough about DICOM to start

Skip this section and come back to it as you follow the steps below. Below you’ll find some basic explainers of DICOM concepts. These are over-simplified to the point of technical inaccuracy – but I’ve added some DICOM-geek-spoilers to help technically clarify statements. If you’re just starting out, ignore those notes in red.

  • A medical image file can be referred to as a DICOM file.
    • Technically, the fact that we have actual files is just a matter of convenience / an implementation detail – DICOM is more about specifying the file structure and the transportation layer, and leave “how you save the files to your disk” up to you. 
  • A DICOM file is very much similar to a JPG or PNG, that you take from your camera. Unlike most image files, double-clicking them won’t open up those images – there isn’t a viewer available by default on computers today.
  • A DICOM file has headers and pixel data.
    • Headers are made up of a series of “parameters” (or tags, or attributes), a “parameter type” (like string, or integer), and a value / set of values. See here for a general list of tags (easy to use browser find to look at tag names).
  • A piece of medical equipment that captures medical images is sometimes called a “modality”. In most modalities, multiple images are taken as part of a medical exam. Here are a few examples:
    • X-rays are taken when you have fractured a bone. There’s usually a few different views taken.
    • Ultrasounds are taken when looking at softer tissue. Sometimes they are a series of snapshots taken over the course of the exam; other times they are a series of images in “real-time” (like watching the heart).
    • CTs and MRIs are used to see inside the body – and they are stored as “slices”. Think of your body being cut horizontally, millimetre by millimetre – each one of these is an image. There could be 64 slices, or there could be 10,000 slices or more.
  • Individual images that were captured as a group are collected into a “series”, for example all the CT slices that make up a brain volume. A number of series can then grouped into a study, which is what a doctor orders, for example a PET series and a CT series in a combined PET/CT scan of a tumor.

Step 1 : Get some images

There are a lot of places to grab images from. Google terms like “DICOM Sample Images” to find some. Here’s a couple of places to get you started:

These sites typically package DICOM images into a ZIP file for download, containing a set of folders (which represent each series), and each of those folders containing a set of DCM files. If the ZIP is a set of studies, there might be an additional layer (directory of studies, each containing directories of series, each containing directories of DCM files).

So, let’s assume you have some DICOM. Now, we need to have a look inside. Unzip them somewhere and remember where you saved them.

Step 2: Have a look at the images

For this step, you need an image viewer. There are a number of open-source viewers out there – here’s a couple :

Once you have installed viewer software, you can open up the DCM files you have saved from the previous step. Typically, viewers allow you to open up a “directory”, which will discover all related images in a series or study.

Once you’ve opened up a study, have a look around! Medical imaging is a fascinating and beautiful thing to behold.

Okay – so, now you have the data – but how do you unlock that information?

Step 3: Getting at the header and pixel data

Now we get to the programming aspect. For this, you need a library. There are a number of libraries available, for all sorts of languages. Server-side, I’ve been brought up on Java, so I use a library called DCM4CHE (start with the BIN download). It also has command line tools, so it is worthwhile even if ultimately you don’t want to use Java.

With DCM4CHE, there are a number of tools with command line apps pre-compiled with it. Two very quick wins with these tools will allow you to get header data (in XML or JSON), and getting the image housed within it.

Getting the header data

Use the command dcm2xml. You can pass in a DICOM file and it will spit out XML of all of the DICOM tags. It works very simply:

dcm2xml <path-to-dicom-file>/<file-name>

And this will write to the console the XML file. There is a lot of very useful information that can be gleaned by exploring the header data, such as learning about the patient and about the study being performed.

Although not documented on the site, I have seen a JSON rendition of this tool as well.

Getting the image (pixel data)

Use the command dcm2jpg, you can pass in a DICOM file and it will spit out a JPG for all your viewing needs. It also works very simply:

dcm2jpg <path-to-dicom-file>/<dicom-file-name> <path-to-jpg-file>/<dicom-jpg-name>

And this will drop the file as an image. Now, depending on your version of Java, you may need a JPG library that can actually encode the out as JPG.

Other DCM4CHE notes

  • When you actually use the image library inside of Java, you can use buffers and streams to more efficiently work with the pixel data (and header data, for what it’s worth).
  • There are many other tools to explore from here, including creating DICOM files, manipulating them, and transmitting them.

Other library options

There are other libraries like DCM4CHE depending on your needs and preferences. DVTk is another example.

Step 4: Do Awesome

Now that you have the basic building blocks of a DICOM image file, you can now begin to create imaging magic. It only gets better from here. Some resources to keep you moving forward:

healthcare API, REST

I need a REST interface

I was thinking the other day – after going through the mail and other daily meanderings, how awesome it would be if I were to have a REST interface. It would work like this: if I became a resource (for example,, then I could receive all sorts of communications in a fashion that would be extremely streamlined. If someone wanted to send a bill to me, just POST it to If someone wanted to check the status of my calendar, simply query for my busy/free times. Of course, it would be secured with OAuth tokens, so I can grant elevated rights where necessary (I wouldn’t want a buddy posting cable bills to me, or telemarketers scheduling annoying calls into my calendar).

This got me thinking, though, on another problem I think about – healthcare and patient empowerment. There is a lot of talk about the pros and the cons of patient data sharing, but I think, in general, it is a good thing. Personally, I am a strong advocate of the Quantified Self movement, and subscribe to self-measuring whenever I can, and fill up spreadsheets, and graph, and nerd out. I understand the limits and challenges, though (i.e., if I were able to notice I am low on iron, I know enough to talk it over with my healthcare provider, before self-medicating and ODing on iron supplements). But, as I collect this information on myself, it empowers me as I move through the healthcare system; it guarantees that each provider is as knowledgable as the last. I am in control of my health, as best as I possibly can.

However, it would be a humongous job for every health care provider and those associated to healthcare to provide me the information they collect on me. Getting paper copies without some sort of incredible OCR system means a lot of unnecessary work. I can’t imagine having a username and password in every hospital for me to access this information. I don’t think OpenID is a decent enough solution (the permanency of accounts concerns me), and OAuth won’t really be viable either (in a distributed repository sense – who would hold all of my tokens?). I think something like Google Health was a good start, but I think, thinking bigger, a solution is possible.

So – back to my opening question – what if I had a RESTful endpoint? Everyone could post relevant healthcare content to me. POSTing to would be an excellent way to deliver content to me personally. How I manage this mailbox of stuff, is really up to whatever application provider I use. If I wanted to parse the raw data and make all kinds of cool graphs (Brad’s Totally Awesome Hematocrit Counts), so be it. And if I wanted to, in turn, share this lab report with another healthcare provider, I could simply share the REST link for a GET, as long as we have an OAuth handshake in advance. I would be my own advocate in the healthcare system. There are tons of uses for this – POSTing prescriptions, medication information sheets, dietary guidelines, scheduling follow-up tests – an integrated system instead of a disparate one.

This wouldn’t be without problems, of course. Handling spam would be paramount, lest I have a lot of garbage to manage. Managing access would have to be incredibly streamlined (maybe this could work in conjunction with the Big Blue Button initiative). Educating the masses to such a system may very well be the biggest challenge. But, there are so many interesting uses of this data – population health, widespread research – that, with the proper controls in place, could change the way we look at health from a national perspective. With great knowledge, comes great responsibility, for sure.

This is a pipe dream, for sure. Especially for a statistic junkie like me. But boy, it sure would be powerful.


What Drives Me

I spent the last couple of days at the I Love APIs 2013 conference. There were fantastic presentations, great and insightful conversations, and hacker-esque food (although no fried chicken and waffles). Listening to and being among those that are as passionate about APIs as me, is very inspirational – and it gave me pause to consider what drives me to do what I love to do.

My passion really compromises of two halves. First of all, after spending a decade cutting my teeth on healthcare information technology has really changed and shaped my perspective. Knowing the state of healthcare – how it is now, and where is it going – is really quite fascinating. For a vertical that truly means the difference between life or death, it boggles my mind that it has been so far behind other industries. It reminds me of a Jerry Seinfeld parable, where he talks about science and seedless watermelons. We have so many different areas that need attention – AIDS, cancer, heart disease, and we have scientists using their time developing a better seedless watermelon. It is staggering. Technologically speaking, while I imagine that there is a time and place for flatulence sound applications, there shouldn’t be much more paramount than healthcare. Health will eventually fail for us all. Healthcare needs the attention, the brunt and the force, of the developer. And the best way to mobilize this force, is with the API.

The API (application programming interface), my other passion, changes and transforms everything it touches. In the last few years, APIs have become more and more intertwined in our daily lives – it has become ubiquitous, and don’t even know it is happening. APIs provide the gateway to information. It is amazing, for me, to watch the bits align, like stars, as information is unlocked to create knowledge. It truly is a beautiful thing. 

These two circles, healthcare IT and the API, where they intersect, is incredibly exciting. I think that we are on the cusp for things that have never been seen before. 

Bonus: If I were to equate my love with the API with another brief TV vignette, it would be an episode of episode of Futurama in which space pilots Fry and Leela attempt a rescue of their colleague Bender by disguising themselves as robots, only to be faced with robot guards meant to prevent humans from entering. To safeguard this, they had a skill testing question. “Which would you rather have – a) a puppy, b) a flower from your sweetie, or c) a large, properly formatted data file?”. Indeed, a large, properly formatted data file is something magical.

healthcare API

The Healthcare API: A Brief History

The evolution of the healthcare API is a peculiar one. The healthcare API world was born in the 1990s, before many other API domains developed, and then followed quite a different evolutionary path than other verticals. Before the rise of the internet, other verticals developed closed software, adding any integration points that fit directly into their vision along the way. As the internet became common place, software became web-based and APIs took hold. It opened up new worlds. The trajectory and momentum started slowly, but with the advent of first SOAP, and then REST, and supporting technologies like OAuth, rose to a fevered pitch. APIs have taken off and transformed forever the ways we live and work. Mashing APIs into dashboards, portals, and ultimately, into apps, have become common place.

Healthcare is different. Before I explain why, there is something critical to understand about this vertical. I often equate it to this example: take any other vertical, like banking. When you look at the banking software stack in any company, it consists of single-sourced core software, and back office software (like HR, payroll, staff scheduling, e-mail, etc.). Restaurants – same thing – a core piece of software, and back-office. Airline industry – same thing. Healthcare, on the other hand, consists of many different functions – patient registration, laboratory systems, radiology scheduling systems, radiology imaging systems, modality software, operating room software, nurse call software, the list goes on and on and on – and these are all provided by individual best of breed vendors. And they all need to talk to each other – otherwise, dire consequences.

So, for this reason, healthcare realized early on that they had to build interoperability first. Vendors came together and agreed on standard ways to communicate between each other. Baked into its very DNA, healthcare standards have taken to heart the need to work in harmony. Two of the core healthcare standards – HL7 and DICOM – have focused on communication between systems – transferring data and triggering workflow between and amongst each provider of software. This level of cooperation is relatively rare. This divergence from the evolution of other APIs happened early on, and has become more pronounced in recent years. 

While healthcare interoperability is clearly a strength, many people – physicians, nurses, patients, IT analysts, governments – all wondered – how is it that one can book a flight to anywhere in the world, share this information instantly to all their friends electronically, and explore the area they are traveling to by navigating virtual streets of continuous photos – and yet, schedule their CT examination on paper-based systems? The focus on interoperability as the common denominator has deprived the systems of what APIs make possible. Rapid growth by the armies of Red Bull guzzling developers have simply not been available. Forays into healthcare of those that built their business on the web API have failed in epic proportions. So – the question we needed to ask ourselves was, what can the healthcare industry learn? How can it benefit from these advancements? How can it transform itself like so many other industries have?

It is beginning to happen. We are seeing a renaissance in the healthcare API. Transformations are occurring – the advancements in API technology in other verticals is moving to this industry. It is happening fast, and it is happening furious. It is an exciting time to be a part of it.