dcmlib.h

   1 // Terminology :
   2 // * in DCMlib     tag = (group, element, name, value representation) e.g.
   3 //   (0x0010, 0x0010, "Patient_Name",    _ID_Patient_Name
   4 //   group   = 16 bit integer
   5 //   element = 16 bit integer
   6 //   name    = char * ("Patient_Name")
   7 //   value representation  (e.g. "AE" = "Application Entity",
   8 //         "FD", "Floating Point Double")
   9 // * in DCMTK  tag = (group, element) but they are many more fields in
  10 //   the implementation (see below). What are the relevant ones ?
  11 //      struct DBI_SimpleEntry {
  12 //         Uint16 group;
  13 //         Uint16 element;
  14 //         Uint16 upperGroup;
  15 //         Uint16 upperElement;
  16 //         DcmEVR evr;
  17 //         const char* tagName;
  18 //         int vmMin;
  19 //         int vmMax;
  20 //         const char* standardVersion;
  21 //         DcmDictRangeRestriction groupRestriction;
  22 //         DcmDictRangeRestriction elementRestriction;
  23 //       };
  24 //
  25 //       static const DBI_SimpleEntry simpleBuiltinDict[] = {
  26 //           { 0x0000, 0x0000, 0x0000, 0x0000,
  27 //             EVR_UL, "CommandGroupLength", 1, 1, "dicom98",
  28 //             DcmDictRange_Unspecified, DcmDictRange_Unspecified },...}
  29
  30 //
  31 // Open questions:
  32 // * in libido a dictionary entry goes :
  33 //   {0x0018,0x1251,"SH","ACQ","Transmitting Coil"}. What does the fourth
  34 //   entry refer to ?
  35 // * what type of Dicom files can this library read ? ACR/NEMA/Dicom v2
  36 //   or v3 part10 ? dcmtk/dcmdata/docs/datadict.txt mentions :all
  37 //   standard DICOM tags (including those found in supplements 1, 2, 3, 4, 5,
  38 //   6, 7, 8, 9, 10), obsolete ACR/NEMA version 2 tags, obsolete SPI tags, and
  39 //   the tags used by Papyrus version 3...
  40 //   Note en DCMTK the dictionary contains a standard version entry, like
  41 //   "dicom98", dicom99", "ACR/NEMA2"
  42 // * the convertion from VR to native types depends on native types of
  43 //   target language (Python, Tcl a priori don't share the same native
  44 //   representations). Where should this go ?
  45 // * the dcmHeader::Set*Tag* family members cannot be defined as protected
  46 //   (Swig limitations for as Has_a dependency between dcmFile and dcmHeader)
  47 //
  48 // Plateforms: Un*xes and Win32/VC++6.0 or Win32/Cygwin
  49
  50
  51 #include <stddef.h>    // For size_t
  52 // Dummy declaration for the time being
  53 typedef int Dict;
  54 typedef int gint16;    // We shall need glib.h !
  55
  56 // The typical usage of objects of this class is to classify a set of
  57 // dicom files according to header information e.g. to create a file hierachy
  58 // reflecting the Patient/Study/Serie informations, or extracting a given
  59 // SerieId. Accesing the content (image[s] or volume[s]) is beyond the
  60 // functionality of this class (see dmcFile below).
  61 class dcmHeader {
  62 private:
  63         Dict* PubDict;          // Public Dictionary
  64         Dict* ShaDict;    // Shadow Dictionary (optional)
  65         int swapcode;
  66 public:
  67         dcmHeader();
  68         dcmHeader(char* filename);
  69         ~dcmHeader();
  70
  71         // Retrieve all potentially available tag [tag = (group, element)] names
  72         // from the standard (or public) dictionary (hence static). Typical usage:
  73         // enable the user of a GUI based interface to select his favorite fields
  74         // for sorting or selection.
  75         static char ** GetDcmTagNames();
  76         char*   GetDcmTag(char* TagName);
  77         // Value Representation (VR) might be needed by caller to convert the
  78         // string typed content to caller's native type (think of C/C++ vs
  79         // Python).
  80         char*   GetDcmTagValRep(char* TagName);
  81
  82         // When some proprietary shadow groups are disclosed, whe can set
  83         // up an additional specific dictionary to access extra information.
  84         int SetShadowDict(char* filename);
  85         int SetShadowDict(char** dictionary);  //????????
  86         int AddShadowDict(char* filename);     //????????
  87         int DelShadowDict();
  88
  89         // Retrieve all potentially available shadowed tag names
  90         char** GetShadowTagNames();
  91         char*  GetShadowTag(char* TagName);
  92
  93         int SetTag(char* content, gint16 group, gint16 element);
  94         int SetTagByName(char* content, char* TagName);
  95         int SetShadowTag(char* content, gint16 group, gint16 element);
  96         int SetShadowTagByName(char* content, char* ShadowTagName);
  97
  98         // Enable caller's low-level manual access to shadowed info
  99         char*   GetDcmTagByNumber(gint16 group, gint16 element);
 100         // Does this make ANY sense ?
 101         char*   GetDcmTagByNumberValRep(char* TagName);
 102         int GetSwapCode();
 103 };
 104
 105 // In addition to Dicom header exploration, this class is designed
 106 // for accessing the image/volume content. One can also use it to
 107 // write Dicom files.
 108 class dcmFile
 109 {
 110 private:
 111         dcmHeader* Header;
 112         void* Data;
 113         int Parsed;            // weather allready parsed
 114         char* OrigalFileName;  // To avoid file overwrite
 115 public:
 116         // Constructor dedicated to writing a new DICOMV3 part10 compliant
 117         // file (see SetFileName, SetDcmTag and Write)
 118         dcmFile();
 119         // Opens (in read only and when possible) an existing file and checks
 120         // for DICOM compliance. Returns NULL on failure.
 121         // Note: the in-memory representation of all available tags found in
 122         //    the DICOM header is post-poned to first header information access.
 123         //    This avoid a double parsing of public part of the header when
 124         //    one sets an a posteriori shadow dictionary (efficiency can be
 125         //    seen a a side effect).
 126         dcmFile(char* filename);
 127         // For promotion (performs a deepcopy of pointed header object)
 128         dcmFile(dcmHeader* header);
 129         ~dcmFile();
 130
 131         // On writing purposes. When instance was created through
 132         // dcmFile(char* filename) then the filename argument MUST be different
 133         // from the constructor's one (no overwriting aloud).
 134         int SetFileName(char* filename);
 135
 136         // Allocates necessary memory, copies the data (image[s]/volume[s]) to
 137         // newly allocated zone and return a pointer to it:
 138         void * GetImageData();
 139         // Returns size (in bytes) of required memory to contain data
 140         // represented in this file.
 141         size_t GetImageDataSize();
 142         // Copies (at most MaxSize bytes) of data to caller's memory space.
 143         // Returns an error code on failure (if MaxSize is not big enough)
 144         int GetImageDataHere(void* destination, size_t MaxSize );
 145         // Allocates ExpectedSize bytes of memory at this->Data and copies the
 146         // pointed data to it.
 147         int SetImageData(void * Data, size_t ExpectedSize);
 148         // Push to disk.
 149         int Write();
 150
 151 ///// Repeat here all the dcmHeader public members !!!
 152 };
 153
 154 //class dcmSerie : dcmFile;
 155 //class dcmMultiFrame : dcmFile;
 156
 157 //
 158 //Examples:
 159 // * dcmFile WriteDicom;
 160 //   WriteDicom.SetFileName("MyDicomFile.dcm");
 161 //      string * AllTags = dcmHeader.GetDcmTagNames();
 162 //   WriteDicom.SetDcmTag(AllTags[5], "253");
 163 //   WriteDicom.SetDcmTag("Patient Name", "bozo");
 164 //   WriteDicom.SetDcmTag("Patient Name", "bozo");
 165 //      WriteDicom.SetImageData(Image);
 166 //   WriteDicom.Write();