DICOMDIR Introduction

DICOMDIR

The DICOMDIR file format has been defined to organize the access to off-line DICOM part 10 files. For instance, DICOM-compliant data CDs contain a DICOMDIR at the root level which contains a description and access information for all the studies on the CD.

The DICOMDIR file is a patient/study/series/image directory that points to the other files on the media.

It is a DICOM dataset encoded as per part 5 and 10, and its contents are described in detail in Annex F of part 3.

The intent is to provide in a compact form sufficient information about all the files on the media to build 'a browser from which the user can select relevant images to view, without having to parse every file on the media for names and IDs etc.

Please refer to DICOM standards part 10 document to get more information on DICOMDIR.
DICOMDIR does not contain other dicom files inside, but it contents the references to the files which are contained in the File-Set for which the DICOMDIR is made.

The DICOMDIR references files, rather than contains them.

The use of the DICOMDIR is defined in PS 3.10 6.2.3.3 "DICOM Medical Information Directory", and its contents are defined by PS 3.3 Annex F "Basic Directory Information Object Definition".

It is non-trivial to build and you will require a toolkit to do it.

A DICOMDIR will reference those DICOM files (=DICOM File Set). See DICOM Part 12 , Annex F. So it's not just a directory, but a special DICOM Dataset.

A DICOMDIR is not a "directory"...but a file that contains a reference to a specific set of DICOM files (wisely called file-set). Like a pointer to a set of files hierarchically organized tree-like in Patient, Study, Series and Instances. This file is therefore used in addition to all the files referenced by it to define a set of files (for media storage, etc...). More info can be found in the Part 10 of the DICOM standard.

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.

To create a DICOMDIR use DCMTK Tool's DcmDicomDir class. This 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.

The Structure of DICOMDIR

DICOMDIR acts as a "Directory" for DICOM file sets and holds a full 4 level hierarchy (PATIENT --> STUDY --> SERIES --> IMAGE) as shown below:

For the creation of a DICOMDIR an easy to use wrapper class has been introduced with DCMTK 3.5.3. The following example from the toolkit's documentation shows how to use the class DicomDirInterface (dcmdata/include/dcddirif.h) : 

Code:

DicomDirInterface dicomdir;

OFCondition status = dicomdir.createNewDicomDir();

if (status.good())

{

  while ( /* there are files */ )

    dicomdir.addDicomFile( /* current filename */ );

  status = dicomdir.writeDicomDir();

  if (status.bad())

    cerr << "Error: cannot write DICOMDIR (" << status.text() << ")" << endl;

} else

  cerr << "Error: cannot create DICOMDIR (" << status.text() << ")" << endl;

A more comprehensive example is provided as part of the command line tool "dcmgpdir". 

 In order to access particular records of a DICOMDIR one needs to use a different approach: 

DICOMDIR files can be read through class DcmDicomDir (see dcmdata/include/dcdicdir.h). This class has a constructor to which the path and filename ("DICOMDIR") can be passed. This class allows you to read a DICOMDIR file and to browse through the logical structure (patient - study - series - instance) of the directory records. The individual records are accessed through class DcmDirectoryRecord. These two classes maintain a "logical" view of the DICOMDIR contents, i.e. you can browse through the logical tree structure and don't need to resolve the byte offsets that create the logical linking on top of the physical sequence structure within the DICOMDIR file. 

So basically, follow these steps:

create an instance of class DcmDicomDir

get the root of the DICOMDIR tree using DcmDicomDir::getRootRecord()

navigate through the tree using DcmDirectoryRecord::nextSub()

the type of each record can be determined using DcmDirectoryRecord::getRecordType()

Since the class DicomDirInterface also relies on these classes and methods you should check its implementation for a working example.

Use DcmDicomDir::getRootRecord() to get access to the root directory record, then use methods of class DcmDirectoryRecord to walk through the tree.

DicomDirInterface is, as the documentation suggests, only a helper class (a wrapper around class DcmDicomDir) that simplifies the task of creating or extending a DICOMDIR from a number of DICOM files.

We can read and write the DICOMDIR file by using DcmDicomDir class.

This class strictly compliant to DICOM specification, so we need to care especially the "Transfer syntax" and "File name".

DcmDicomDir* myDir = new DcmDicomDir("/data/dicomdir"); 

// THis is a valid dicom dir 

DcmDirectoryRecord *myDcmDirRec = &(myDir->getRootRecord());

dcmmkdir utility

dcmgpdir utility