Wednesday, June 28, 2023

DICOMDIR and Media Interchange

[update 24 March 2023: Latest releases of HRZ software can be found on HRZ website -]

DICOMDIR, Have you heard this term? What does it mean? Do I need this in my system? Lots of questions. Let's try to answer some.

Here's a list with quick information about DICOMDIR:

  1. Standard DICOM CD/DVD should have a file named DICOMDIR in its root directory.
  2. The DICOMDIR file has in it records that hold paths to DICOM files on the media.
  3. DICOMDIR is a DICOM Object holding a sequence of DICOMDIR records nodes each having a type like PATIENT, STUDY, SERIES and IMAGE
  4. The DICOMDIR file include key attributes from the data on the media such as Patient Name, Patient ID, Study ID, Study Date.
  5. The file names of DICOM files on a standard DICOM CD/DVD should be capital alphanumeric up to 8 characters with no suffix.
  6. The CD/DVD may include other files that are not DICOM. The DICOMDIR file does not reference them.
  7. The mandatory elements of the DICOMDIR nodes are not 1-2-1 with the mandatory elements in the DICOM Objects. For example Study ID which is Type 2 in DICOM Image objects is Type 1 in DICOMDIR STUDY Record. So when creating your DICOM images if you intend to create DICOMDIR for them, add these elements too.
There are two ways DICOM application can collaborate with one another. They can communicate over TCP/IP network connection or they can exchange files over some physical media.

The first figure in the DIOM standard makes sense eventually
The picture above, which is by the way the first figure in the DICOM standard (page 10 of chapter 1), explains that very well although when I first looked at thirteen years ago it it didn't mean anything to me.
It is worth staying a bit longer on this figure because it has a lot of valuable information in it so lets work it top to bottom.

At a first view, ignoring its content and looking only at the shape, it looks like some kind of humanoid robot with flat oval head walking on two clumsy legs made of crude blocks. Well, at least that's what I see.

The oval head that reads "Medical Information" is representing your application data. 

The gray body box is your DICOM implementation (e.g. using the RZDCX toolkit) taking its data and putting it into DICOM Objects encoded properly. Then it is ready to be shared or sent to other applications, not yours, that can read the data and make useful things with it because that application too, just like your application, speaks the same language - DICOM!

Now comes the split between the two legs. The DICOM Objects can be either be written into DICOM files and then take the right side (or the left foot if this robot is facing us) through some physical media like a CD, DVD and USB, or it can take the left side and be sent over a TCP/IP network connection using DICOM commands like C-STORE.

This post is about the right side, exchanging physical media.. I've already discussed part of it, the DICOM File Meta Header, when talking about DICOM Transfer Syntax

Let's say we got a CD from someone that tells us there's DICOM files on this CD with the information of the patient we are looking for. If we have no more information then that, we need to open the CD, look at every file on it and check if its a DICOM file, read it, figure out what's in it and decide if this is what we are looking for. Doable but slow, specially with slow media like CD, But, when this CD is made according to the standard, there's a better way. All we need to do then is to read the DICOMDIR file, find the record in it with our patient's ID and get from there the references to the DICOM files that we are looking for on the CD. The DICOMDIR is exactly what it names suggests. Its a directory record with information about DICOM files on the media. Because search actions on CD's are much slower then on a hard drive, using the DICOMDIR should theoretically shorten the time required to find and display to the user the information on the media.

With RZDCX I try to make things easier by providing the very basic API to carry out the task. Many times ease of use considerations supersede complete options and flexibility because I take the decision to implement the DICOM internals in a certain way that will be most integrative and still correct. When I take such decisions its because I assume that RZDCX users want to focus on the their strengths and count on RZDCX to do the right thing DICOM-wise. This prolog is made to explain the very thin API of the DICOMDIR Implementation class DCXDICOMDIR.

The DCXDICOMDIR class has methods to search and iterate over the different records within the DICOMDIR file. So for example to go over all the patients in the media you use the getPatientIterator method and get back an object iterator where each DCXOBJ in it is one DICOMDIR patient record.

To create a DICOMDIR use ScanAndCreate. This method scans a directory for DICOM files and writes a DICOMDIR file in its root. Before calling it, make sure your files are named properly. I use the following naming convention:

  • Create a directory PA001 for every patient
  • Inside PA001 create a directory ST001 for every study
  • Inside ST001 create a directory SE001 for every series
  • Inside SE001 create the DICOM files and name them IM000001, IM000002 ...
Remember not to use prefixes and keep your filenames to 8 characters long, capital with alphabetic first letter. Here's a short code from the new DICOMIZER that crates a valid DICOMDIR:

        private void CreateDICOMDIR(string SourceFolder)
                DCXDICOMDIRClass dir = new DCXDICOMDIRClass();

                dir.ScanAndCreate(SourceFolder, APPLICATION_PROFILE.AP_GENERAL_PURPOSE, "RZ DICOMIZER", false);
            catch (Exception ex)


  1. Hi Rony, Is there any way to manipulate the DICOM file information so that you can have in a database? this procedure would guarantee this security vulnerability data null, Thanks

  2. How I can extract the information from a DICOM file and place it in a database and thus prevent information breaches in it?

    1. You can use DCXOBJ.getElementByTag to get the value of the elements you need in the database. Then put the data into your database and add a field of the filename where you took the data from.

    2. Hi thanks for the reply, I am learning about DICOM, does the command or statement from DICOMIZER right? i try to create a PACS, i guess i am going in right way, thanks again

  3. Hi! Regarding the use of icons (thumbnails) in a DICOMDIR - is that common? Is it even mandatory under certain conditions?

    1. Hi,
      Very good question.
      The DICOM Standard Part 11 defines 'Media Storage Application Profiles'.
      In short, application profiles define a set of rules on what objects can be put on a media and in what way, e.g. the transfer syntax to use, and so in, even the media to use. It also defines the way the DICOMDIR file is constructed and if an icon image should be set in it or not.
      For example, The Basic Cardiac X-ray Angiographic Application Profile (from part 11 of the standard) require that an icon image should be set in every image node of the DICOMDIR object.
      Most of this work in the standard is around the conformance statement of the application.
      I have to admit that I didn't explore deep into this ally in the DICOM Standard because there was never a real need to do so.
      The thing that puzzles me is that I didn't find any way to know according to what application profile a physical media was created just by checking the value of an element in its DICOMDIR file.
      I would expect to have a tag like (2200,000C) 'Requested Media Application Profile' in the DICOMDIR file but it is not there.
      So practically, if I had to use icon images from DICOMDIR file, I would wrap it with a massive and solid try catch block.
      I hope this helps

  4. i am creating a dicom directory, after having an image converted to dicom from jpeg, the file meta data is present.
    how can i resolve this? how to add file group length and version to a dicom file?

  5. How do I know that a file is a DICOMDIR? I believe that not all products follow the file name 'DICOMDIR'? Can I safely check that the SOP Class UID is 1.2.840.10008.1.3.10 (Media Storage Directory Storage)? Or is it possible for some other DICOM file to also have this SOP class UID?