4 // * gdcmlib is a library dedicated to reading and writing dicom files.
5 // * LGPL for the license
6 // * lightweigth as opposed to CTN or DCMTK which come bundled which try
7 // to implement the full DICOM standard (networking...). gdcmlib concentrates
8 // on reading and writing
9 // * Formats: this lib should be able to read ACR-NEMA v1 and v2, Dicom v3 (as
10 // stated in part10). [cf dcmtk/dcmdata/docs/datadict.txt]
11 // * Targeted plateforms: Un*xes and Win32/VC++6.0
15 // The declarations commented out and starting with "TODO Swig" needed
16 // to be temporarily removed for swig to proceed correctly (in fact
17 // problems appears at loading of _gdcm.[so/dll]). So, simply uncomment
18 // the declaration once you provided the definition of the method...
22 using namespace std; // string type lives in the std namespace on VC++
26 #include <stddef.h> // For size_t
27 #include <stdio.h> // FIXME For FILE on GCC only
31 // The requirement for the hash table (or map) that
33 // 1/ First, next, last (iterators)
34 // 2/ should be sortable (i.e. sorted by TagKey). This
35 // condition shall be droped since the Win32/VC++
36 // implementation doesn't look a sorted one. Pffff....
37 // 3/ Make sure we can setup some default size value,
38 // which should be around 4500 entries which is the
39 // average dictionary size (said JPR)
41 // En fait, je disais que dans LE Directory Dicom (dans son etat 2002)
42 // il y a 1600 entrees.
43 // Une valeur raisonable pour un majorant du nombre d'entrees
44 // dans une entete DICOM d'une image semble semble etre 300
45 // Si on 'decortique' les elements SQ (ce qui ne semble pas etre fait pour le moment)
46 // on risque en fait de depasser ... un nombre non previsible dans le cas d'une entree SQ
47 // contenant lui même un tres grand nombre d'entrees ?!?)
48 // Quant au nombre d'entrees dans un DICOMDIR, c'est encore pire : il n'est limité
49 // que par la taille d'un CD-ROM (les DVD-ROM ne sont pas encore pris en compte)
50 // On peut s'attendre a 30 entrees par fichier dicom présent sur le CD-ROM
51 // REMARQUE : il faudra se pencher sur le pb de la creation du DICOMDIR lorsqu'on voudra
52 // exporter des images lisibles par les consoles cliniques
53 // et pas seulement importables dans e-film.
58 #define guint16 uint16_t
59 #define guint32 uint32_t
63 typedef unsigned short guint16;
64 typedef unsigned int guint32;
68 #define GDCM_EXPORT __declspec( dllexport )
75 // ---------------------------------------------------- gdcmDictEntry
77 // c'est une ligne du Dictionnaire Dicom
81 ////////////////////////////////////////////////////////////////////////////
82 // Tag based hash tables.
83 // We shall use as keys the strings (as the C++ type) obtained by
84 // concatenating the group value and the element value (both of type
85 // unsigned 16 bit integers in Dicom) expressed in hexadecimal.
86 // Example: consider the tag given as (group, element) = (0x0010, 0x0010).
87 // Then the corresponding TagKey shall be the string 0010|0010 (where
88 // the | (pipe symbol) acts as a separator). Refer to
89 // gdcmDictEntry::TranslateToKey for this conversion function.
91 typedef string TagKey;
93 class GDCM_EXPORT gdcmDictEntry {
95 guint16 group; // e.g. 0x0010
96 guint16 element; // e.g. 0x0103
97 string vr; // Value Representation i.e. some clue about the nature
98 // of the data represented e.g. "FD" short for
99 // "Floating Point Double"
100 // CLEANME: find the official dicom name for this field !
101 string fourth; // Fourth field containing some semantics.
102 string name; // e.g. "Patient_Name"
103 TagKey key; // Redundant with (group, element) but we add it
104 // on efficiency purposes.
105 // DCMTK has many fields for handling a DictEntry (see below). What are the
106 // relevant ones for gdcmlib ?
107 // struct DBI_SimpleEntry {
108 // Uint16 upperGroup;
109 // Uint16 upperElement;
111 // const char* tagName;
114 // const char* standardVersion;
115 // DcmDictRangeRestriction groupRestriction;
116 // DcmDictRangeRestriction elementRestriction;
120 // fabrique une ligne de Dictionnaire Dicom à partir des parametres en entrée
122 gdcmDictEntry(guint16 group, guint16 element,
123 string vr = "Unknown",
124 string fourth = "Unknown",
125 string name = "Unknown");
127 // fabrique une 'clé' par concaténation du numGroupe et du numElement
129 static TagKey TranslateToKey(guint16 group, guint16 element);
131 guint16 GetGroup(void) { return group;};
132 guint16 GetElement(void){return element;};
133 string GetVR(void) {return vr; };
135 bool IsVrUnknown(void);
136 string GetFourth(void) {return fourth;};
137 string GetName(void) {return name;};
138 string GetKey(void) {return key;};
142 // ---------------------------------------------------- gdcmDict
144 // c'est le Dictionnaire Dicom
147 ////////////////////////////////////////////////////////////////////////////
148 // A single DICOM dictionary i.e. a container for a collection of dictionary
149 // entries. There should be a single public dictionary (THE dictionary of
150 // the actual DICOM v3) but as many shadow dictionaries as imagers
151 // combined with all software versions...
153 typedef map<TagKey, gdcmDictEntry*> TagHT;
154 // Table de Hachage (group,Elem) --> pointeur vers une ligne du Dictionnaire Dicom
156 typedef map<TagKey, gdcmDictEntry*> TagHT;
158 class GDCM_EXPORT gdcmDict {
163 // rempli le Dictionnaire Dicom à partir d'un fichier texte
164 gdcmDict(const char* FileName); // Read Dict from disk
167 // Ca doit ajouter une nouvelle entrée 'a la fin', ou 'a sa place' ?
169 // TODO Swig int AppendEntry(gdcmDictEntry* NewEntry);
171 // renvoie une ligne de Dictionnaire Dicom à partir de (numGroup, numElement)
172 gdcmDictEntry * GetTag(guint32 group, guint32 element);
173 void Print(ostream&);
174 TagHT & GetEntries(void) { return entries; }
179 // ---------------------------------------------------- gdcmDictSet
181 // Ensemble de Dictionnaires Dicom (le public + 'des' privés)
182 // Au cas ou l'on traiterait un jour les 'dictionnaires privés'
183 // - pratiquement un par constructeur, par machine, et par version du logiciel -
187 ////////////////////////////////////////////////////////////////////////////
188 // Container for managing a set of loaded dictionaries. Sharing dictionaries
190 // * reloading an allready loaded dictionary,
191 // * having many in memory representations of the same dictionary.
193 typedef string DictKey;
194 typedef map<DictKey, gdcmDict*> DictSetHT;
196 class GDCM_EXPORT gdcmDictSet {
198 string DictPath; // Directory path to dictionaries
200 int AppendDict(gdcmDict* NewDict);
201 int LoadDictFromFile(string filename, DictKey);
202 void SetDictPath(void);
204 gdcmDictSet(void); // loads THE DICOM v3 dictionary
205 // TODO Swig int LoadDictFromFile(string filename);
206 // QUESTION: the following function might not be thread safe !? Maybe
207 // we need some mutex here, to avoid concurent creation of
208 // the same dictionary !?!?!
209 // TODO Swig int LoadDictFromName(string filename);
210 // TODO Swig int LoadAllDictFromDirectory(string DirectoryName);
211 // TODO Swig string* GetAllDictNames();
213 // Question : ne faudra-t-il pas mettre LE dictionnaire DICOM dans un Directory
214 // et les eventuels 'dictionnaires prives' dans un autre?
216 int LoadDicomV3Dict(void);
217 void Print(ostream&);
218 gdcmDict* GetDict(DictKey DictName);
219 gdcmDict* GetDefaultPublicDict(void);
224 // ---------------------------------------------------- ElValue
226 // C'est un Element Dicom
227 // (ce qu'on a trouve dans l'entete de l'image
228 // + ce qu'on est allé chercher dans le Dictionnaire Dicom)
233 // Ne faudrait-il pas trouver un autre nom, qui preterait moins à confusion?
234 // ElValue n'EST PAS la 'valeur d'un Element', mais la reunion d'infos
235 // trouvees dans l'Entete du fichier ET dans le Dictionnaire DICOM
238 // The dicom header of a Dicom file contains a set of such ELement VALUES
239 // (when successfuly parsed against a given Dicom dictionary)
241 class GDCM_EXPORT ElValue {
243 gdcmDictEntry *entry;
245 bool ImplicitVr; // Even when reading explicit vr files, some
246 // elements happen to be implicit. Flag them here
247 // since we can't use the entry->vr without breaking
248 // the underlying dictionary.
249 // Might prove of some interest (see _ID_DCM_ELEM)
252 string value; // used to be char * valeurElem
253 size_t Offset; // Offset from the begining of file for direct user access
254 ElValue(gdcmDictEntry*);
255 void SetDictEntry(gdcmDictEntry *NewEntry) { entry = NewEntry; };
257 bool IsVrUnknown(void) { return entry->IsVrUnknown(); };
258 void SetLength(guint32 l){ LgrElem = l; };
259 void SetValue(string val){ value = val; };
260 void SetOffset(size_t of){ Offset = of; };
261 void SetImplicitVr(void) { ImplicitVr = true; };
262 bool IsImplicitVr(void) { return ImplicitVr; };
265 string GetValue(void) { return value; };
266 guint32 GetLength(void) { return LgrElem; };
267 size_t GetOffset(void) { return Offset; };
268 guint16 GetGroup(void) { return entry->GetGroup(); };
269 guint16 GetElement(void) { return entry->GetElement(); };
270 string GetKey(void) { return entry->GetKey(); };
271 string GetName(void) { return entry->GetName(); };
276 // ---------------------------------------------------- ElValSet
278 // ... un ensemble d'Elements Dicom
279 // ... le résultat de l'analyse d'une entete d'image, par exemple
281 ////////////////////////////////////////////////////////////////////////////
282 // Container for a set of successfully parsed ElValues.
283 typedef map<TagKey, ElValue*> TagElValueHT;
284 typedef map<string, ElValue*> TagElValueNameHT;
286 class GDCM_EXPORT ElValSet {
287 // We need both accesses with a TagKey and the Dictentry.Name
290 TagElValueNameHT NameHt;
293 void Print(ostream &);
294 void PrintByName(ostream &);
295 ElValue* GetElementByNumber(guint32 group, guint32 element);
296 ElValue* GetElementByName (string);
297 string GetElValueByNumber(guint32 group, guint32 element);
298 string GetElValueByName (string);
299 TagElValueHT & GetTagHt(void);
301 int SetElValueByNumber(string content, guint32 group, guint32 element);
302 int SetElValueByName(string content, string TagName);
307 // ---------------------------------------------------- gdcmHeader
309 // C'est le Dicom Header d'une image donnée
310 // (tous les elements Dicom qui la composent
311 // + des info 'de service')
314 ////////////////////////////////////////////////////////////////////////////
315 // The typical usage of instances of class gdcmHeader is to classify a set of
316 // dicom files according to header information e.g. to create a file hierarchy
317 // reflecting the Patient/Study/Serie informations, or extracting a given
318 // SerieId. Accesing the content (image[s] or volume[s]) is beyond the
319 // functionality of this class and belong to gdmcFile (see below).
321 // * the various entries of the explicit value representation (VR) shall
322 // be managed within a dictionary which is shared by all gdcmHeader instances
323 // * the gdcmHeader::Set*Tag* family members cannot be defined as protected
324 // (Swig limitations for as Has_a dependency between gdcmFile and gdcmHeader)
327 typedef string VRKey; // Ne devrait-elle pas etre utilisee dans la definition de VRHT ?
328 typedef string VRAtr;
329 typedef map<TagKey, VRAtr> VRHT; // Value Representation Hash Table
330 // Cette Table de Hachage ne devrait servir qu'a determiner
331 // si deux caractères correspondent à une VR existante ?
333 class GDCM_EXPORT gdcmHeader {
334 void SkipBytes(guint32);
336 static VRHT *dicom_vr;
337 // Dictionaries of data elements:
340 // Pourquoi mettre un pointeur statique vers le container des dictionnaires
341 // (qui est une H-table de pointeurs vers des dictionnaires)
342 // en plus des pointeurs vers chacun des dictionnaires ?
343 // Ces derniers n'auraient-ils pas suffit ?
345 static gdcmDictSet* Dicts; // global dictionary container
346 gdcmDict* RefPubDict; // public dictionary
347 gdcmDict* RefShaDict; // shadow dictionary (optional)
348 // Parsed element values:
349 ElValSet PubElVals; // parsed with Public Dictionary
350 ElValSet ShaElVals; // parsed with Shadow Dictionary
351 string filename; // refering underlying file
353 // The tag Image Location ((0028,0200) containing the address of
354 // the pixels) is not allways present. Then we store this information
359 // Qu'y a-t-il a corriger ?
361 // outside of the elements:
365 // Ne faudrait-il pas une indication sur la presence ou non
366 // du 'groupe des pixels' dans l'entete?
367 // (voir pb du DICOMDIR)
369 // Swap code (little, big, bad-big, bad-little endian): this code is not fixed
370 // during parsing.FIXME sw should be an enum e.g.
378 // Only the elements whose size is below this bound will be loaded.
379 // By default, this upper bound is limited to 1024 (which looks reasonable
380 // when one considers the definition of the various VR contents).
381 guint32 MaxSizeLoadElementValue;
383 guint16 ReadInt16(void);
384 guint32 ReadInt32(void);
385 guint16 SwapShort(guint16);
386 guint32 SwapLong(guint32);
387 void Initialise(void);
388 void CheckSwap(void);
389 void FindLength(ElValue *);
390 guint32 FindLengthOB(void);
391 void FindVR(ElValue *);
392 void LoadElementValue(ElValue *);
393 void LoadElementValueSafe(ElValue *);
394 void SkipElementValue(ElValue *);
395 void InitVRDict(void);
396 void SwitchSwapToBigEndian(void);
397 void FixFoundLength(ElValue*, guint32);
398 bool IsAnInteger(ElValue *);
400 bool IsImplicitVRLittleEndianTransferSyntax(void);
401 bool IsExplicitVRLittleEndianTransferSyntax(void);
402 bool IsDeflatedExplicitVRLittleEndianTransferSyntax(void);
403 bool IsExplicitVRBigEndianTransferSyntax(void);
404 bool IsJPEGBaseLineProcess1TransferSyntax(void);
405 bool IsJPEGExtendedProcess2_4TransferSyntax(void);
406 bool IsJPEGExtendedProcess3_5TransferSyntax(void);
407 bool IsJPEGSpectralSelectionProcess6_8TransferSyntax(void);
410 // Il y en a encore DIX-SEPT, comme ça.
411 // Il faudrait trouver qq chose + rusé ...
414 void SetMaxSizeLoadElementValue(long);
415 ElValue * ReadNextElement(void);
416 gdcmDictEntry * IsInDicts(guint32, guint32);
424 ACR_LIBIDO}; // CLEANME
427 int anonymize(ostream&); // FIXME : anonymize should be a friend ?
429 void LoadElements(void);
430 virtual void ParseHeader(void);
431 gdcmHeader(const char* filename);
432 virtual ~gdcmHeader();
434 size_t GetPixelOffset(void);
435 void GetPixels(size_t, void *);
436 int GetSwapCode(void) { return sw; }
438 // TODO Swig int SetPubDict(string filename);
439 // When some proprietary shadow groups are disclosed, we can set up
440 // an additional specific dictionary to access extra information.
441 // TODO Swig int SetShaDict(string filename);
443 // Retrieve all potentially available tag [tag = (group, element)] names
444 // from the standard (or public) dictionary. Typical usage: enable the
445 // user of a GUI based interface to select his favorite fields for sorting
447 list<string> * GetPubTagNames(void);
448 map<string, list<string> > * GetPubTagNamesByCategory(void);
449 // Get the element values themselves:
451 string GetPubElValByName(string TagName);
452 string GetPubElValByNumber(guint16 group, guint16 element);
454 // Getting the element value representation (VR) might be needed by caller
455 // to convert the string typed content to caller's native type
456 // (think of C/C++ vs Python).
458 string GetPubElValRepByName(string TagName);
459 string GetPubElValRepByNumber(guint16 group, guint16 element);
461 TagElValueHT & GetPubElVal(void) { return PubElVals.GetTagHt(); };
462 void PrintPubElVal(ostream & os = cout);
463 void PrintPubDict(ostream &);
465 // Same thing with the shadow :
466 // TODO Swig string* GetShaTagNames();
467 string GetShaElValByName(string TagName);
468 string GetShaElValByNumber(guint16 group, guint16 element);
469 string GetShaElValRepByName(string TagName);
470 string GetShaElValRepByNumber(guint16 group, guint16 element);
472 // Wrappers of the above (public is privileged over shadow) to avoid
473 // bugging the caller with knowing if ElVal is from the public or shadow
475 string GetElValByName(string TagName);
476 string GetElValByNumber(guint16 group, guint16 element);
477 string GetElValRepByName(string TagName);
478 string GetElValRepByNumber(guint16 group, guint16 element);
480 int SetPubElValByName(string content, string TagName);
481 int SetPubElValByNumber(string content, guint16 group, guint16 element);
482 int SetShaElValByName(string content, string ShadowTagName);
483 int SetShaElValByNumber(string content, guint16 group, guint16 element);
488 // ---------------------------------------------------- gdcmFile
490 // un fichier EST_UNE entete, ou A_UNE entete ?
495 ////////////////////////////////////////////////////////////////////////////
496 // In addition to Dicom header exploration, this class is designed
497 // for accessing the image/volume content. One can also use it to
498 // write Dicom files.
499 ////// QUESTION: this looks still like an open question wether the
500 ////// relationship between a gdcmFile and gdcmHeader is of
501 ////// type IS_A or HAS_A !
503 class GDCM_EXPORT gdcmFile: public gdcmHeader
507 // Data pointe sur quoi?
508 // sur les Pixels lus?
509 // --> j'ajoute un champ public : Pixels
510 // (il faudra que l'utilisateur puisse modifier les pixels ?)
513 int Parsed; // weather allready parsed
514 string OrigFileName; // To avoid file overwrite
516 // je ne suis pas sur d'avoir compris *où* il serait légitime de ranger ca.
517 // on pourra tjs le deplacer, et mettre des accesseurs
521 // Constructor dedicated to writing a new DICOMV3 part10 compliant
522 // file (see SetFileName, SetDcmTag and Write)
523 // TODO Swig gdcmFile();
524 // Opens (in read only and when possible) an existing file and checks
525 // for DICOM compliance. Returns NULL on failure.
526 // Note: the in-memory representation of all available tags found in
527 // the DICOM header is post-poned to first header information access.
528 // This avoid a double parsing of public part of the header when
529 // one sets an a posteriori shadow dictionary (efficiency can be
530 // seen as a side effect).
532 gdcmFile(string & filename);
534 // For promotion (performs a deepcopy of pointed header object)
535 // TODO Swig gdcmFile(gdcmHeader* header);
536 // TODO Swig ~gdcmFile();
538 // On writing purposes. When instance was created through
539 // gdcmFile(string filename) then the filename argument MUST be different
540 // from the constructor's one (no overwriting allowed).
541 // TODO Swig int SetFileName(string filename);
543 // Allocates necessary memory, copies the data (image[s]/volume[s]) to
544 // newly allocated zone and return a pointer to it:
546 void * GetImageData();
548 // Returns size (in bytes) of required memory to contain data
549 // represented in this file.
551 size_t GetImageDataSize();
553 // Copies (at most MaxSize bytes) of data to caller's memory space.
554 // Returns an error code on failure (if MaxSize is not big enough)
556 int PutImageDataHere(void* destination, size_t MaxSize );
558 // Allocates ExpectedSize bytes of memory at this->Data and copies the
559 // pointed data to it.
560 // TODO Swig int SetImageData(void * Data, size_t ExpectedSize);
562 // A NE PAS OUBLIER : que fait-on en cas de Transfert Syntax (dans l'entete)
563 // incohérente avec l'ordre des octets en mémoire
564 // TODO Swig int Write();
566 // Ecrit sur disque les pixels d'UNE image
567 // Aucun test n'est fait sur l'"Endiannerie" du processeur.
568 // C'est à l'utilisateur d'appeler son Reader correctement
570 int WriteRawData (string nomFichier);
574 // ---------------------------------------------------- gdcmSerie
576 // une serie EST_UN fichier ????
580 //class gdcmSerie : gdcmFile;
583 // ---------------------------------------------------- gdcmMultiFrame
585 // un fichierMultiFrame EST_UN fichier
589 //class gdcmMultiFrame : gdcmFile;