Gdcm News

Missing features

• Decoders
  • gdcm doesn't read yet JPEG-LS encoded files.
    We said 'JPEG-LS', not Lossless Jpeg ...
    [JPEG-LS is the basis for new lossless/near-lossless compression standard for continuous-tone images intended for JPEG2000. The standard is based on the LOCO-I algorithm (LOw COmplexity LOssless COmpression for Images) developed at Hewlett-Packard Laboratories]
  • gdcm doesn't read yet all JPEG2000 encoded files.
    But we are working on it (a lot of troubles with Jasper). Update: as of Oct 10 2005, we are currently investigating another library: openjpeg. The problem still exist for this library but one of the author is currently working on it: http://www.openjpeg.org/forum/viewtopic.php?t=18
  • gdcm doesn't read yet MPEG2 encoded files.
• Reader
  • Allow user to tell gdcm::Document constructor he just wants to load a given list of DocEntries (to save CPU time and RAM space)
  • Allow 'frame by frame' reading (should be helpfull for huge multiframe images)
  • Allow subvolume selection / frames selection before reading.
  • Expose Read/Decompression mechanisms to allow user getting information from DICOMDIR
    -or from his own Data Base- and reading his images without parsing the header, one more time.
• Writer
  • Allow user to tell the Writer he doesn't want to write down SeqEntry (if any)
  • Allow user to tell the Writer he doesn't want to write down Shadow groups (if any)
  • Allow user to tell the Writer which compression mode he wants
    (Right now, no one is available)
  • Allow user to tell the Writer he wants to split a Multiframe image into a serie of Single frame images.
  • Allow user to tell the Writer he wants to agregate a Serie of Single frame images into a Multiframe image.
• Reader / Writer
  • Full Icon Image management (Read and Write)
  • Full Overlays management (Read and Write)
    both for 'ACR-NEMA style' (using groups 0x6000 and next) and 'DICOM V3 style' (using Sequences)
• DICOMDIR
  • DICOMDIR full management (not limited to PATIENT/STUDY/SERIE/IMAGE)
  • Allow user to add an entry (belonging to the file header Dicom entries)to the default entry list, before making a DICOMDIR from a root directory
  • Allow user to add an entry of his owns (for instance an Icon to each image, or to each Serie).
• SerieHelper
  • An accurate SerieHelper
    Right now SerieHelper only works on 'bona fide Series', and breaks on wrongly forged Series.
    We are still looking for any heuristics...
  • A SerieHelper that would use the DICOMDIR (if any) instead of parsing all the files within the Root Directory
• Other
  • 16-bits-LUT full Management
  • User friendly management of Rescale Slope and Rescale Intercept.
    (Well... Maybe it's up to the application to deal with it, not to gdcm ?)
  • Allow manual adjunction / automatic recognition (pfff!...) of the private Dicom Dictionary to be used to parse Shadow groups against.
  • User friendly way of anonymizing image when Patient's name is carved in the Pixels :-(

Current Version (CVS)

• Missing Features
• State of the art
  • gdcm UML Class Diagram current version.
  • User Documentation
  • Developper Documentation
  • New Features
    • To try to make gdcm images PACS usable, user is now allowed to gdcm what kind of image he wants to write, using :
      void FileHelper::SetContentType (ImageContentType c);
      Four different types are identify (probabely more will be added) :
      • 1) user created ex nihilo his own image and wants to write it as a Dicom image.
        c : USER_OWN_IMAGE
      • 2) user modified the pixels of an existing image, using mathematical operations.
        c : FILTERED_IMAGE
      • 3) user created a new image, using existing images (eg MIP, MPR, cartography image)
        c : CREATED_IMAGE
      • 4) user modified/added some tags *without processing* the pixels (anonymization, etc)
        c : UNMODIFIED_PIXELS_IMAGE
    • Stupid difference between gdcm::ValEntry and gdcm::BinEntry removed.
      Only gdcm::DataEntry exist, now. Should have been considered as a 'Bug Fix'.
      Actually, it's an API breaking modification ...
      • std::string const &DataEntry::GetString() const
        returns as a string (when possible) the value of the DataEntry
      • void DataEntry::SetString(std::string const &value)
        Sets the 'value' of a DataEntry, passed as a std::string
      • void DataEntry::SetBinArea( uint8_t *area, bool self )
        Sets the value (non string) of the current Dicom DataEntry
      • void DataEntry::CopyBinArea( uint8_t *area, uint32_t length )
        Inserts the value (non string) into the current DataEntry
      • void DataEntry::SetValue(const uint32_t &id, const double &val)
        Inserts the elementary (non string) value into the current (multivaluated) DataEntry, at the id> position.
      • double DataEntry::GetValue(const uint32_t &id) const
        returns, as a double one of the values (when entry is multivaluated), identified by its index id.
    • DocEntrySet::GetEntryValue() replaced by DocEntrySet::GetEntryString()
      
    • SerieHelper :
      Add some methods, to split a 'SingleSerieUID' Fileset into 'Extra Coherent' FileSets.
      They return a std::map of 'Filesets' (actually : std::vector of gdcm::File*)
      The key is the 'Orientation', the 'Position' or the value of a user choosen 'Tag'
      - XCoherentFileSetmap SplitOnOrientation(FileList *fileSet);
      - XCoherentFileSetmap SplitOnPosition(FileList *fileSet);
      - XCoherentFileSetmap SplitOnTagValue(FileList *fileSet, uint16_t group, uint16_t element);
      These methods must be called by user, depending on what he wants to do, at application time.- *he* only knows what his Series contain !-
    • To avoid memory leaks and seg faults the user intended classes use now a Reference Counter.
      
      • new() and delete() are replaced by New() and Delete()
      • Register() and Unregister() methods are available.
      • --> Well ... People from ITK don't seem to agree too much with that feature.
        They demand to be allowed to allocate gdcm objects in the stack as well, not only in the heap.
  • API breaking modifications (since previous version)
    • Stupid difference between gdcm::ValEntry and gdcm::BinEntry removed.
      Only gdcm::DataEntry exist, now.
      

         ValEntry(DictEntry *e);
         BinEntry(DictEntry *e);
      -->DataEntry *New(uint16_t group,uint16_t elem, VRKey const &vr);
      
         std::string const &ValEntry::GetValue() const;
         std::string const &BinEntry::GetValue() const;
      -->std::string const &DataEntry::GetString() const;
      
         uint8_t *BinEntry::GetBinArea();
      -->uint8_t *DataEntry::GetBinArea();
      
         void ValEntry::SetValue(std::string const &value);
         void BinEntry::SetValue(std::string const &value);   
      -->void DataEntry::SetString(std::string const &value);
      
         void BinEntry::SetBinArea( uint8_t *area, bool self = true );
      -->void DataEntry::SetBinArea( uint8_t *area, bool self = true );
      
         void ValEntry::CopyValEntry(uint16_t gr, uint16_t el);
      -->void DataEntry::CopyDataEntry(uint16_t gr, uint16_t el, VRKey const &vr);
      

      Example :
      
      old way :
              DocEntry *p3 = item2->GetDocEntry(0x0018,0x0050);
              if( !p3 ) return false;
              ContentEntry *entry2 = dynamic_cast(p3);
              std::string thickness = entry2->GetValue();
      
      new way :
              DocEntry *p3 = item2->GetDocEntry(0x0018,0x0050);
              if( !p3 ) return false;
              DataEntry *entry2 = dynamic_cast(p3);
              std::string thickness = entry2->GetString();
      
      

    • Avoid tons of CPU time consuming accesses to DICOM Dictionnary

         DataEntry *FileHelper::CopyDataEntry(uint16_t group, uint16_t elem);
      -->DataEntry *FileHelper::CopyDataEntry(uint16_t group, uint16_t elem, 
                                              const VRKey &vr = GDCM_VRUNKNOWN);
      
         void FileHelper::CheckMandatoryEntry(uint16_t group, uint16_t elem, std::string value);
      -->void FileHelper::CheckMandatoryEntry(uint16_t group, uint16_t elem, std::string value,
                                              const VRKey &vr = GDCM_VRUNKNOWN);
            
         void FileHelper::SetMandatoryEntry(uint16_t group, uint16_t elem, std::string value);       
      -->void FileHelper::SetMandatoryEntry(uint16_t group, uint16_t elem, std::string value,
                                            const VRKey &vr = GDCM_VRUNKNOWN);
      
         void FileHelper::CopyMandatoryEntry(uint16_t group, uint16_t elem, std::string value);      
      -->void FileHelper::CopyMandatoryEntry(uint16_t group, uint16_t elem, std::string value,
                                             const VRKey &vr = GDCM_VRUNKNOWN);
      

      CopyMandatoryEntry(0x0002,0x0003,sop)
    • New features :

      For multivaluated numeric DataEntries
      -->void DataEntry::SetValue(const uint32_t &id,const double &val);
      -->double DataEntry::GetValue(const uint32_t &id) const;
      -->uint32_t DataEntry::GetValueCount() const;
      
      For converting 'Decimal String'
      -->bool GetDSValue(std::vector <double> &valueVector);  
            
  • Bug fixes
    • Implicit VR - Big Endian (G.E Private) Transfert Syntax 16 Bits images are now read correctly.
    • File::GetZOrigin() returns accurate result in any case.
  • Known Bugs
    • Use of Implicit Value Representation writting mode may causes troubles, when there are some SQ belonging to a Shadow Group.
      Better you use Explicit Value Representation writting mode ...
    • Troubles on 'Big endian' processors (i.e. Apple/Motorola, SunSparc ...) when writting 16 Bits images.
    • Troubles on 64-bits processors.
    
    
    

  ---

  Version 1.1 (September 14 2005)

• State of the art
  • gdcm 1.1 UML Class Diagram version.
  • User Documentation
  • Developper Documentation
  • New Features
    • Add the methods gdcm::Dict:AddDict(std::string fullPathPrivateDictionaryFileName)
      and
      gdcm::Dict::RemoveDict(std::string fullPathPrivateDictionaryFileName)
      to allow user to choose the 'Private Dictionary' he wants to work with.
      One can dream about a better API;
      This one allow right now anybody to see very easyly if the use of a given private dicom dictionary is of any help or not.
      
      
    • PrintFile has now a new command line argument manager option :
      dict=fullPathNamePrivateDictionaryFile
      to allow user to see with no extra coding what differences makes the use or not of a private Dicom Dictionary.
      e.g. : use it as follow
      PrintFile filein=myGEdicomFile.dcm dict=/user/userName/gdcm/Dicts/GEMS-Advance.dic
      
      
    • (Not a great one ...) Stupid method names :
      DicomDir::WriteDicomDir() and DicomDir::AnonymizeDicomDir()
      replaced by :
      DicomDir::Write() and DicomDir::Anonymize()
      
      
    • void Document::AddForceLoadElement(uint16_t group, uint16_t elem);
      allows user to tell gdcm::Document Loader he wants to force the loading of a given set of DocEntries, even if their length exceeds the current MAX_SIZE_LOAD_ELEMENT_VALUE.
      
      
    • Many users expect from vtkGdcmReader it 'orders' the images (that's the job of gdcm::SerieHelper ...)
      When user knows the files with same Serie UID have same sizes, same 'pixel' type, same color convention, ... the right way to proceed is as follow :

              gdcm::SerieHelper *sh= new gdcm::SerieHelper();
         //      if user wants *not* to load some parts of the file headers
              sh->SetLoadMode(loadMode);
      
         //      if user wants *not* to load some files
              sh->AddRestriction(group, element, value, operator);
              sh->AddRestriction( ...
              sh->SetDirectory(directoryWithImages);
      
         //      if user *knows* how to order his files
              sh->SetUserLessThanFunction(userSuppliedComparisonFunction);
         //      or/and
         //      if user wants to sort reverse order
              sh->SetSortOrderToReverse();
         
         //      here, we suppose only the first 'Single SerieUID' Fileset is of interest
         //      Just iterate using sh->NextSingleSerieUIDFileSet()
         //      if you want to get all of them
              gdcm::FileList *l = sh->GetFirstSingleSerieUIDFileSet();
      
         //      if user is doesn't trust too much the files with same Serie UID
              if ( !sh->IsCoherent(l) )
                 return; // not same sizes, or not same 'pixel type' -> stop
      
              sh->OrderFileList(l);        // sort the list
      
              vtkGdcmReader *reader = vtkGdcmReader::New();
         //      if user wants to modify pixel order (Mirror, TopDown, ...)
         //      he has to supply the function that does the job
         //      (a *very* simple example is given in vtkgdcmSerieViewer.cxx)
              reader->SetUserFunction (userSuppliedFunction);
      
         //      to pass a 'Single SerieUID' Fileset as produced by gdcm::SerieHelper
              reader->SetCoherentFileList(l);
              reader->Update();
         

      You can see a full example in vtk/vtkgdcmSerieViewer.cxx
      e.g.
      vtkgdcmSerieViewer dirname=Dentist mirror
      vtkgdcmSerieViewer dirname=Dentist reverse
      vtkgdcmSerieViewer dirname=Dentist reverse topdown
      
      
    • vtkGdcmReader::SetUserFunction (userSuppliedFunction)
      with :
      void userSuppliedFunction(uint8_t *imageData, File *f);
      allows user to reorganize the pixels of each image just after reading it (to mirror, or topdown the image, for instance)
      Note : uint8_t * doesn't mean it works only on 8 Bits images.
      It's for prototyping. Feel free to cast it.
      
      
    • SerieHelper::SetUserLessThanFunction(userSuppliedComparisonFunction)
      with :
      bool userSuppliedComparisonFunction(File *, File *);
      allows user -when he knows more about his files than gdcm does- to give his own comparison function.
    • SerieHelper::SetSortOrderToReverse allows user to ask to sort the Files reverse order.
    • SerieHelper::AddRestriction has now a new constructor
      AddRestriction(group, element, value, operator);
      allows user to exclude some files from the sorting, according to any comparison operator
      (GDCM_EQUAL, GDCM_DIFFERENT, GDCM_GREATER, GDCM_GREATEROREQUAL, GDCM_LESS, GDCM_LESSOREQUAL), not only on the equality.
      
      
    • AnonymizeNoLoad used with dirin=inputDirectoryName anonymizes all the files within the given Directory.
      User may also choose extra elements he wants to rub out:
      rubout=listOfElementsToRubOut
      with listOfElementsToRubOut : group1-elem1,group2-elem2, ... (in hexa, no space within the list )
      
      
    • gdcm::SerieHelper() has a new method void AddGdcmFile(File *header), that allows aware user to create a 'FileList' (actually a std::vector< File* > ).
      The FileList created this way will be the 'first one' in the gdcm::FileHelper() (retrieve it with FileList *GetFirstCoherentFileList() ).
      It may be sorted using OrderFileList.
      No 'coherence check' will be performed on this FileList before sorting.
      It may be passed to a vtkGdcmReader (to avoid parsing twice the files)
      
      
    • vtkGdcmReader can now get the result of gdcm::SerieHelper (to avoid parsing twice the files)
      Proceed as follow :
      

                 gdcmSerieHelper *sh = new gdcmSerieHelper();
                 sh->SetDirectory(myImageDirectory, true);
                 gdcmFileList *l = s->GetFirstCoherentFileList();
                 s->OrderFileList(l);
      
                 vtkGdcmReader *gr = new vtkGdcmReader();
                 gr->SetCoherentFileList(l);
                 gr->Update();  
                 

      This works with a directory that contains only one 'Serie' (same Serie UID for all the images).
      If it contains more than one Serie, you'll have to loop on the Series, using GetNextCoherentFileList();
      It will be up to the user to delete the gdcm::File.
      
      See vtkgdcmSerieViewer for an example.
      
      
    • Both vtkgdcmViewer and vtkgdcmViewer2 are available to allow easy displaying of single/multiframe GreyLevel/RGB/PaletteColor images
      
      
    • DICOMDIR anonymiser (Load and Noload mode)
      
      
    • Because the gdcm::DicomDir::Load() method may be used either for loading an already made DICOMDIR file or for parsing all the dicom files with a given root directory we syntaxically separated the operations:
      For loading an already made DICOMDIR file, use :
      

                 gdcm::DicomDir *d = new gdcm::DicomDir();
                 d->SetFileName(fileName);
                 d->Load( );  
                 

      For parsing all the dicom files within a given root directory, use :
      

                 gdcm::DicomDir *d = new gdcm::DicomDir();
                 d->SetDirectoryName(dirName);
                 d->Load( )  
                 

      Don't use any longer old deprecated style:
      gdcm::DicomDir *d = new gdcm::DicomDir();
      d->SetParseDir(true); // or d->SetParseDir(false);
      d->Load( fileName );
      
      
    • User is now allowed to tell gdcm::Document constructor he doesn't want to deal with SeqEntry (every time it's possible, i.e for 'true length' Sequences)
      and/or he doesn't want to deal with Shadow groups (every time it's possible i.e. when element 0x0000 exists for this Group)
      or he doesn't want to deal with SeqEntry that belong to a Shadow group (every time it's possible -'true length' Sequence-)
      use :
      

                 gdcm::File *f = new gdcm::File();
                        f->SetLoadMode(NO_SEQ);            | depending on what
                        f->SetLoadMode(NO_SHADOW);         | you want *not* 
                        f->SetLoadMode(NO_SEQ | NO_SHADOW);| to load from the
                        f->SetLoadMode(NO_SHADOWSEQ);      | target file
                  f->SetFileName(fileName);
                  f->Load( );
                  

      Don't use any longer old deprecated style:
      gdcm::File *f = new gdcm::File(fileName);
      
      
    • User is now allowed to tell gdcm::DicomDir constructor he doesn't want to deal with SeqEntry (every time it's possible, i.e for 'true length' Sequences)
      and/or he doesn't want to deal with Shadow groups (every time it's possible i.e. when element 0x0000 exists for this Group)
      or he doesn't want to deal with SeqEntry that belong to a Shadow group (every time it's possible -'true length' Sequence-)
      when he parses all the Dicom files within a given directory.
      use :
      

                   gdcm::DicomDir *f = new gdcm::DicomDir();
                        f->SetLoadMode(NO_SEQ);            | depending on what
                        f->SetLoadMode(NO_SHADOW);         | you want *not* 
                        f->SetLoadMode(NO_SEQ | NO_SHADOW);| to load from the files
                        f->SetLoadMode(NO_SHADOWSEQ);      | within the root directory 
                   f->SetDirectoryName(rootDirectoryName);
                   f->Load( );
                  

      Don't use any longer old deprecated style:
      gdcm::DicomDir *dcmdir = new gdcm::DicomDir(dirName, true);
      
      
  • Bug fixes
    • No more trouble when the 'endianess' switches within Sequences.
    • No more trouble with 'no length Sequences' belonging to a Shadow Group when they are 'Implicit VR'.
    • The difference between MONOCHROME1 (low values = bright, high values = dark) and MONOCHROME2 (low values = dark, high values = bright) is now taken into account.
      It's no longer up to the user to change the pixels value
    • Writing a 'True Dicom' image after reading an ACR-NEMA image does not request any longer from the user to build up 'manually' the Meta Elements group (0x0002)
    • Old '24 Bits' ACR-NEMA are now correctly re-written in DICOM V3 mode.
    • Element 0x0000 of Shadow groups is always forced to be a ValEntry and its VR is forced to UL
      
      
  • A.P.I. breaking modifications (since previous version : 1.0)
    • NEVER more API breaking modifications !!!
      
      
  • Known bugs

  ---

  Version 1.0 (Feb 14 2005)

  • State of the art
    • gdcm 1.0 UML Class Diagram version.
    • User Documentation"
    • Developper Documentation"
    • Final check of the jpeg sub-library: all 'classical' jpeg compressed Dicom files can be read
      
    • All the previously gdcm-breaker images are now readable
      
    • A huge number of memory leaks removed
    • Improvement of write process
  • A.P.I. breaking modifications (since previous version : 0.6)
    • Use of namespace : all the methods formerly named className::gdcmXxx() are now named className::Xxx()
      End user will have to call them as gdcm::className::Xxx()
    • a gdcm::Document is now specialized in :
      • gdcm::DicomDir
      • gdcm::File
    • a gdcm::DicomElementSet is composed of a set of gdcm::DicomDocEntry
    • a gdcm::DicomDocEntry can be :
      • a gdcm::ContentEntry, specialized in :
        • gdcm::ValEntry
        • gdcm::BinEntry (no longer a specialization of gdcm::ValEntry)
      • a gdcm::SeqEntry
    • Removal of useless accessors GetXxxByname, SetXxxByname
    • Renaming of accessors GetXxxByNumber, SetXxxByNumber as follow :
      • GetEntryByNumber       --> GetEntryValue
      • GetEntryLengthByNumber --> GetEntryLength
      • GetEntryOffsetByNumber --> GetEntryOffset
      • GetEntryVRByNumber     --> GetEntryVR
      • GetDocEntryByNumber    --> GetDocEntry
      • GetValEntryByNumber    --> GetValEntry
      • GetBinEntryByNumber    --> GetBinEntry
      • GetSeqEntryByNumber    --> GetSeqEntry

  ---

  Version 0.6 (June 8 2004)

  This version will be used by Insight Tool Kit (ITK 2.0) at the beginning of 2005.
  It's not yet packaged ...
  
  
  • User Documentation"
  • Developper Documentation"
  • The new gdcmDocument class is a parent class of gdcmHeader class and gdcmDicomDir class.
  • Massive modifications in the Class Diagram :
    • any dicom related file is a gdcmDocument
    • a gdcmDocument can be :
      • a gdcmHeader, if it contains pixel data
      • a gdcmDicomDir, if it contains only informations on the files in a given directory
    • a gdcmDocument is_a gdcmElementSet, composed of a set of gdcmEntry separated into :
      • gdcmValEntry
        a specialization of gdcmValEntry, for 'non std::string representable' values is gdcmBinEntry
      • gdcmSeqEntry (VR = SQ, i.e Dicom Sequences)
        they are dealt as tree-like structures :
        - a gdcmSeqEntry is considered as a set of gdcmSQItem,
        - a gdcmSQItem is_a gdcmElementSet, composed of gdcmDocEntries, recursively
        
  • Improvement of the jpeg sub-library: jpeg compressed Dicom files (lossless and lossy) might be read (check-it out)

  ---

  Version 0.4 (February 6 2004)

  • gdcm 0.4 UML Class Diagram.
  • User Documentation"
  • Developper Documentation
  • Introduction of a jpeg sub-library: some very simple jpeg-lossy compressed Dicom files might be working (check-it out).
  • And also, fewer memory leaks, cleaned-up stl usage (should work with gcc-3.x), python disutil installer (see file setup.py) supporting both Swig and vtk wrapping.
  • Introduction of a RLE (Run-Time Encoding) library
  • Color images (RGB or Palette Color) are dealt with
  • Confusing names gdcmPatient, gdcmStudy, gdcmSerie, gdcmPatient changed to gdcmDicomDirPatient, gdcmDicomDirStudy, gdcmDicomDirSerie, gdcmDicomDirPatient

  ---

  Version 0.3 (July 8 2003)

  • gdcmFile class now enables acces to the data i.e. the image[s] content. Previously only parsing of the Dicom header was available through usage of gdcmHeader class.
  • a VTK plugin of gdcm is now available through the vtkGdcmReader vtk class (see it as a vtk wrapper of gdcm), which enables
    • Loading of a single image,
    • Loading of a stack of images from multiple Dicom files,
    • this class is wrapped for vtkPython (by using native vtk wrappers).
  • Introduction of a jpeg sub-library: lossless-jpeg compressed Dicom files work.
  • vtkgdcmViewer allows easy displaying of single/multiframe GreyLevel/RGB/PaletteColor images

  ---

  Version 0.1 (April 1 2003)

  ---

  Version 0.0 (March 14 2003)

  ---