src/gdcm.h

   1 // gdcmlib Intro:
   2 // * gdcmlib is a library dedicated to reading and writing dicom files.
   3 // * LGPL for the license
   4 // * lightweigth as opposed to CTN or DCMTK wich come bundled which try
   5 //   to implement the full DICOM standard (networking...). gdcmlib concentrates
   6 //   on reading and
   7 // * Formats: this lib should be able to read ACR-NEMA v1 and v2, Dicom v3 (as
   8 //   stated in part10). [cf dcmtk/dcmdata/docs/datadict.txt]
   9 // * Targeted plateforms: Un*xes and Win32/VC++6.0
  10 //
  11 //
  12 // TODO
  13 // The declarations commented out and starting with "TODO Swig" needed
  14 // to be temporarily removed for swig to proceed correctly (in fact
  15 // problems appears at loading of _gdcm.[so/dll]). So, simply uncomment
  16 // the declaration once you provided the definition of the method...
  17
  18 #include <string>
  19 #ifdef _MSC_VER
  20 using namespace std;  // string type lives in the std namespace on VC++
  21 #endif
  22
  23 #include <iostream>
  24 #include <stddef.h>   // For size_t
  25 #include <stdio.h>    // FIXME For FILE on GCC only
  26 #include <list>
  27 #include <map>
  28
  29 #ifdef __GNUC__
  30 #include <stdint.h>
  31 #define guint16 uint16_t
  32 #define guint32 uint32_t
  33 #endif
  34
  35 #ifdef _MSC_VER
  36 typedef  unsigned short guint16;
  37 typedef  unsigned int guint32;
  38 #endif
  39
  40 #ifdef _MSC_VER
  41 #define GDCM_EXPORT __declspec( dllexport )
  42 #else
  43 #define GDCM_EXPORT
  44 #endif
  45
  46 ////////////////////////////////////////////////////////////////////////////
  47 // Tag based hash tables.
  48 // We shall use as keys the strings (as the C++ type) obtained by
  49 // concatenating the group value and the element value (both of type
  50 // unsigned 16 bit integers in Dicom) expressed in hexadecimal.
  51 // Example: consider the tag given as (group, element) = (0x0010, 0x0010).
  52 // Then the corresponding TagKey shall be the string 0010|0010 (where
  53 // the | (pipe symbol) acts as a separator). Refer to
  54 // gdcmDictEntry::TranslateToKey for this conversion function.
  55 typedef string TagKey;
  56
  57 class GDCM_EXPORT gdcmDictEntry {
  58 private:
  59         guint16 group;    // e.g. 0x0010
  60         guint16 element;  // e.g. 0x0010
  61         string  vr;       // Value Representation i.e. some clue about the nature
  62                           // of the data represented e.g. "FD" short for
  63                           // "Floating Point Double"
  64         // CLEANME: find the official dicom name for this field !
  65         string  fourth;   // Fourth field containing some semantics.
  66         string  name;     // e.g. "Patient_Name"
  67         TagKey  key;      // Redundant with (group, element) but we add it
  68                           // on efficiency purposes.
  69         // DCMTK has many fields for handling a DictEntry (see below). What are the
  70         // relevant ones for gdcmlib ?
  71         //      struct DBI_SimpleEntry {
  72         //         Uint16 upperGroup;
  73         //         Uint16 upperElement;
  74         //         DcmEVR evr;
  75         //         const char* tagName;
  76         //         int vmMin;
  77         //         int vmMax;
  78         //         const char* standardVersion;
  79         //         DcmDictRangeRestriction groupRestriction;
  80         //         DcmDictRangeRestriction elementRestriction;
  81         //       };
  82 public:
  83         gdcmDictEntry(guint16 group, guint16 element,
  84                       string vr     = "Unknown",
  85                       string fourth = "Unknown",
  86                       string name   = "Unknown");
  87         static TagKey TranslateToKey(guint16 group, guint16 element);
  88         guint16 GetGroup(void)  { return group;};
  89         guint16 GetElement(void){return element;};
  90         string  GetVR(void)     {return vr; };
  91         void    SetVR(string);
  92         bool    IsVrUnknown(void);
  93         string  GetFourth(void) {return fourth;};
  94         string  GetName(void)   {return name;};
  95         string  GetKey(void)    {return key;};
  96 };
  97
  98 ////////////////////////////////////////////////////////////////////////////
  99 // A single DICOM dictionary i.e. a container for a collection of dictionary
 100 // entries. There should be a single public dictionary (THE dictionary of
 101 // the actual DICOM v3) but as many shadow dictionaries as imagers
 102 // combined with all software versions...
 103 typedef map<TagKey, gdcmDictEntry*> TagHT;
 104
 105 class GDCM_EXPORT gdcmDict {
 106         string name;
 107         string filename;
 108         TagHT entries;
 109 public:
 110         gdcmDict(const char* FileName);   // Read Dict from disk
 111         // TODO Swig int AppendEntry(gdcmDictEntry* NewEntry);
 112         gdcmDictEntry * GetTag(guint32 group, guint32 element);
 113         void Print(ostream&);
 114         TagHT & GetEntries(void) { return entries; }
 115 };
 116
 117 ////////////////////////////////////////////////////////////////////////////
 118 // Container for managing a set of loaded dictionaries. Sharing dictionaries
 119 // should avoid :
 120 // * reloading an allready loaded dictionary,
 121 // * having many in memory representations of the same dictionary.
 122 typedef string DictKey;
 123 typedef map<DictKey, gdcmDict*> DictSetHT;
 124
 125 class GDCM_EXPORT gdcmDictSet {
 126 private:
 127         string DictPath;      // Directory path to dictionaries
 128         DictSetHT dicts;
 129         int AppendDict(gdcmDict* NewDict);
 130         int LoadDictFromFile(string filename, DictKey);
 131         void SetDictPath(void);
 132 public:
 133         gdcmDictSet(void);    // loads THE DICOM v3 dictionary
 134         // TODO Swig int LoadDictFromFile(string filename);
 135    // QUESTION: the following function might not be thread safe !? Maybe
 136    //           we need some mutex here, to avoid concurent creation of
 137    //           the same dictionary !?!?!
 138         // TODO Swig int LoadDictFromName(string filename);
 139         // TODO Swig int LoadAllDictFromDirectory(string DirectoryName);
 140         // TODO Swig string* GetAllDictNames();
 141         int LoadDicomV3Dict(void);
 142         void Print(ostream&);
 143         gdcmDict* GetDict(DictKey DictName);
 144         gdcmDict* GetDefaultPublicDict(void);
 145 };
 146
 147 ////////////////////////////////////////////////////////////////////////////
 148 // The dicom header of a Dicom file contains a set of such ELement VALUES
 149 // (when successfuly parsed against a given Dicom dictionary)
 150 class GDCM_EXPORT ElValue {
 151 private:
 152         gdcmDictEntry *entry;
 153         guint32 LgrElem;
 154         bool ImplicitVr;       // Even when reading explicit vr files, some
 155                                // elements happen to be implicit. Flag them here
 156                                // since we can't use the entry->vr without breaking
 157                                // the underlying dictionary.
 158         // Might prove of some interest (see _ID_DCM_ELEM)
 159         // int Swap;
 160 public:
 161         string  value;     // used to be char * valeurElem
 162         size_t Offset;     // Offset from the begining of file for direct user access
 163         ElValue(gdcmDictEntry*);
 164         void SetDictEntry(gdcmDictEntry *NewEntry) { entry = NewEntry; };
 165
 166         bool   IsVrUnknown(void) { return entry->IsVrUnknown(); };
 167         void SetLength(guint32 l){LgrElem = l; };
 168         void SetValue(string val){ value = val; };
 169         void SetOffset(size_t of){ Offset = of; };
 170         void SetImplicitVr(void) { ImplicitVr = true; };
 171         bool  IsImplicitVr(void) { return ImplicitVr; };
 172         void    SetVR(string);
 173         string  GetVR(void);
 174         string  GetValue(void)   { return value; };
 175         guint32 GetLength(void)  { return LgrElem; };
 176         size_t  GetOffset(void)  { return Offset; };
 177         guint16 GetGroup(void)   { return entry->GetGroup(); };
 178         guint16 GetElement(void) { return entry->GetElement(); };
 179         string  GetKey(void)     { return entry->GetKey(); };
 180         string  GetName(void)    { return entry->GetName();};
 181 };
 182
 183 ////////////////////////////////////////////////////////////////////////////
 184 // Container for a set of succefully parsed ElValues.
 185 typedef map<TagKey, ElValue*> TagElValueHT;
 186 typedef map<string, ElValue*> TagElValueNameHT;
 187
 188 class GDCM_EXPORT ElValSet {
 189                 // We need both accesses with a TagKey and the Dictentry.Name
 190         TagElValueHT tagHt;
 191         TagElValueNameHT NameHt;
 192 public:
 193         void Add(ElValue*);
 194         void Print(ostream &);
 195         void PrintByName(ostream &);
 196         ElValue* GetElementByNumber(guint32 group, guint32 element);
 197         ElValue* GetElementByName(string);
 198         string GetElValueByNumber(guint32 group, guint32 element);
 199         string GetElValueByName(string);
 200         TagElValueHT & GetTagHt(void);
 201 };
 202
 203 ////////////////////////////////////////////////////////////////////////////
 204 // The typical usage of instances of class gdcmHeader is to classify a set of
 205 // dicom files according to header information e.g. to create a file hierachy
 206 // reflecting the Patient/Study/Serie informations, or extracting a given
 207 // SerieId. Accesing the content (image[s] or volume[s]) is beyond the
 208 // functionality of this class and belong to gdmcFile (see below).
 209 // Notes:
 210 // * the various entries of the explicit value representation (VR) shall
 211 //   be managed within a dictionary which is shared by all gdcmHeader instances
 212 // * the gdcmHeader::Set*Tag* family members cannot be defined as protected
 213 //   (Swig limitations for as Has_a dependency between gdcmFile and gdcmHeader)
 214
 215 typedef string VRKey;
 216 typedef string VRAtr;
 217 typedef map<TagKey, VRAtr> VRHT;    // Value Representation Hash Table
 218
 219 class GDCM_EXPORT gdcmHeader {
 220         void SkipBytes(guint32);
 221 private:
 222         static VRHT *dicom_vr;
 223         // Dictionaries of data elements:
 224         static gdcmDictSet* Dicts;  // global dictionary container
 225         gdcmDict* RefPubDict;       // public dictionary
 226         gdcmDict* RefShaDict;       // shadow dictionary (optional)
 227         // Parsed element values:
 228         ElValSet PubElVals;         // parsed with Public Dictionary
 229         ElValSet ShaElVals;         // parsed with Shadow Dictionary
 230         string filename;            // refering underlying file
 231         FILE * fp;
 232         // The tag Image Location ((0028,0200) containing the address of
 233         // the pixels) is not allways present. When we store this information
 234         // FIXME
 235         // outside of the elements:
 236         guint16 grPixel;
 237         guint16 numPixel;
 238         // Swap code (little, big, big-bad endian): this code is not fixed
 239         // during parsing.FIXME sw should be an enum e.g.
 240         //enum EndianType {
 241                 //LittleEndian,
 242                 //BadLittleEndian,
 243                 //BigEndian,
 244                 //BadBigEndian};
 245         int sw;
 246         // Only the elements whose size are below this bound shall be loaded.
 247         // By default, this upper bound is limited to 1024 (which looks reasonable
 248         // when one considers the definition of the various VR contents).
 249         guint32 MaxSizeLoadElementValue;
 250
 251         guint16 ReadInt16(void);
 252         guint32 ReadInt32(void);
 253         guint16 SwapShort(guint16);
 254         guint32 SwapLong(guint32);
 255         void Initialise(void);
 256         void CheckSwap(void);
 257         void FindLength(ElValue *);
 258         guint32 FindLengthOB(void);
 259         void FindVR(ElValue *);
 260         void LoadElementValue(ElValue *);
 261         void LoadElementValueSafe(ElValue *);
 262         void SkipElementValue(ElValue *);
 263         void InitVRDict(void);
 264         void SwitchSwapToBigEndian(void);
 265         void FixFoundLength(ElValue*, guint32);
 266         bool IsAnInteger(ElValue *);
 267         bool IsBigEndianTransferSyntax(void);
 268         void SetMaxSizeLoadElementValue(long);
 269         ElValue       * ReadNextElement(void);
 270         gdcmDictEntry * IsInDicts(guint32, guint32);
 271         size_t GetPixelOffset(void);
 272 protected:
 273         enum FileType {
 274                 Unknown = 0,
 275                 TrueDicom,
 276                 ExplicitVR,
 277                 ImplicitVR,
 278                 ACR,
 279                 ACR_LIBIDO};  // CLEANME
 280         FileType filetype;
 281         int write(ostream&);
 282         int anonymize(ostream&);  // FIXME : anonymize should be a friend ?
 283 public:
 284         void LoadElements(void);
 285         virtual void ParseHeader(void);
 286         gdcmHeader(const char* filename);
 287         virtual ~gdcmHeader();
 288
 289         // TODO Swig int SetPubDict(string filename);
 290         // When some proprietary shadow groups are disclosed, whe can set
 291         // up an additional specific dictionary to access extra information.
 292         // TODO Swig int SetShaDict(string filename);
 293
 294         // Retrieve all potentially available tag [tag = (group, element)] names
 295         // from the standard (or public) dictionary. Typical usage: enable the
 296         // user of a GUI based interface to select his favorite fields for sorting
 297         // or selection.
 298         list<string> * GetPubTagNames(void);
 299         map<string, list<string> > * GetPubTagNamesByCategory(void);
 300         // Get the element values themselves:
 301         string GetPubElValByName(string TagName);
 302         string GetPubElValByNumber(guint16 group, guint16 element);
 303         // Getting the element value representation (VR) might be needed by caller
 304         // to convert the string typed content to caller's native type (think
 305         // of C/C++ vs Python).
 306         string GetPubElValRepByName(string TagName);
 307         string GetPubElValRepByNumber(guint16 group, guint16 element);
 308         TagElValueHT & GetPubElVal(void) { return PubElVals.GetTagHt(); };
 309         void   PrintPubElVal(ostream & os = cout);
 310         void   PrintPubDict(ostream &);
 311
 312         // Same thing with the shadow :
 313         // TODO Swig string* GetShaTagNames();
 314         string GetShaElValByName(string TagName);
 315         string GetShaElValByNumber(guint16 group, guint16 element);
 316         string GetShaElValRepByName(string TagName);
 317         string GetShaElValRepByNumber(guint16 group, guint16 element);
 318
 319         // Wrappers of the above (public is privileged over shadow) to avoid
 320         // bugging the caller with knowing if ElVal is from the public or shadow
 321         // dictionary.
 322         string GetElValByName(string TagName);
 323         string GetElValByNumber(guint16 group, guint16 element);
 324         string GetElValRepByName(string TagName);
 325         string GetElValRepByNumber(guint16 group, guint16 element);
 326
 327         // TODO Swig int SetPubElValByName(string content, string TagName);
 328         // TODO Swig int SetPubElValByNumber(string content, guint16 group, guint16 element);
 329         // TODO Swig int SetShaElValByName(string content, string ShadowTagName);
 330         // TODO Swig int SetShaElValByNumber(string content, guint16 group, guint16 element);
 331
 332         // TODO Swig int GetSwapCode();
 333 };
 334
 335 ////////////////////////////////////////////////////////////////////////////
 336 // In addition to Dicom header exploration, this class is designed
 337 // for accessing the image/volume content. One can also use it to
 338 // write Dicom files.
 339 ////// QUESTION: this looks still like an open question wether the
 340 //////           relationship between a gdcmFile and gdcmHeader is of
 341 //////           type IS_A or HAS_A !
 342 class GDCM_EXPORT gdcmFile: gdcmHeader
 343 {
 344 private:
 345         void* Data;
 346         int Parsed;          // weather allready parsed
 347         string OrigFileName; // To avoid file overwrite
 348 public:
 349         // Constructor dedicated to writing a new DICOMV3 part10 compliant
 350         // file (see SetFileName, SetDcmTag and Write)
 351         // TODO Swig gdcmFile();
 352         // Opens (in read only and when possible) an existing file and checks
 353         // for DICOM compliance. Returns NULL on failure.
 354         // Note: the in-memory representation of all available tags found in
 355         //    the DICOM header is post-poned to first header information access.
 356         //    This avoid a double parsing of public part of the header when
 357         //    one sets an a posteriori shadow dictionary (efficiency can be
 358         //    seen a a side effect).
 359         gdcmFile(string & filename);
 360         // For promotion (performs a deepcopy of pointed header object)
 361         // TODO Swig gdcmFile(gdcmHeader* header);
 362         // TODO Swig ~gdcmFile();
 363
 364         // On writing purposes. When instance was created through
 365         // gdcmFile(string filename) then the filename argument MUST be different
 366         // from the constructor's one (no overwriting aloud).
 367         // TODO Swig int SetFileName(string filename);
 368
 369         // Allocates necessary memory, copies the data (image[s]/volume[s]) to
 370         // newly allocated zone and return a pointer to it:
 371         // TODO Swig void * GetImageData();
 372         // Returns size (in bytes) of required memory to contain data
 373         // represented in this file.
 374         // TODO Swig size_t GetImageDataSize();
 375         // Copies (at most MaxSize bytes) of data to caller's memory space.
 376         // Returns an error code on failure (if MaxSize is not big enough)
 377         // TODO Swig int PutImageDataHere(void* destination, size_t MaxSize );
 378         // Allocates ExpectedSize bytes of memory at this->Data and copies the
 379         // pointed data to it.
 380         // TODO Swig int SetImageData(void * Data, size_t ExpectedSize);
 381         // Push to disk.
 382         // TODO Swig int Write();
 383 };
 384
 385 //class gdcmSerie : gdcmFile;
 386 //class gdcmMultiFrame : gdcmFile;