dcmlib.h

   1 // Open questions:
   2 // * End user API are prefixed with GDL (Gnu Dicom Librrary) ???
   3 // * should RefPubDict be a key in a hashtable (implementation and not API)
   4 //   or a pointer to a dictionary ?
   5
   6
   7 // DCMlib general notes:
   8 // * Formats:DCMlib should be able to read ACR-NEMA v1 and v2, Dicom v3 (as
   9 //   stated in part10). [cf dcmtk/dcmdata/docs/datadict.txt]
  10 // * Targeted plateforms: Un*xes and Win32/VC++6.0 (and hopefully Win32/Cygwin)
  11
  12 #include <string>
  13 #include <stddef.h>    // For size_t
  14 // Dummy declaration for the time being
  15 typedef int guint16;    // We shall need glib.h !
  16
  17 // Notes on the implemenation of the dictionary entry in DCMTK :
  18 //   They are many fields in this implementation (see below). What are the
  19 //   relevant ones for us ?
  20 //      struct DBI_SimpleEntry {
  21 //         Uint16 group;
  22 //         Uint16 element;
  23 //         Uint16 upperGroup;
  24 //         Uint16 upperElement;
  25 //         DcmEVR evr;
  26 //         const char* tagName;
  27 //         int vmMin;
  28 //         int vmMax;
  29 //         const char* standardVersion;
  30 //         DcmDictRangeRestriction groupRestriction;
  31 //         DcmDictRangeRestriction elementRestriction;
  32 //       };
  33 //
  34 //       static const DBI_SimpleEntry simpleBuiltinDict[] = {
  35 //           { 0x0000, 0x0000, 0x0000, 0x0000,
  36 //             EVR_UL, "CommandGroupLength", 1, 1, "dicom98",
  37 //             DcmDictRange_Unspecified, DcmDictRange_Unspecified },...}
  38 class DictEntry {
  39 private:
  40         guint16 group;          // e.g. 0x0010
  41         guint16 element;        // e.g. 0x0010
  42         string  name;           // e.g. "Patient_Name"
  43         string  ValRep; // Value Representation i.e. some clue about the nature
  44                                                         // of the data represented e.g. "FD" short for
  45                                                         // "Floating Point Double"
  46 public:
  47         DictEntry();
  48         DictEntry(guint16 group, guint16 element, string  name, string  VR);
  49 };
  50
  51 // A single DICOM dictionary i.e. a container for a collection of dictionary
  52 // entries. There should be a single public dictionary (THE dictionary of
  53 // the actual DICOM v3) but as many shadow dictionaries as imagers
  54 // combined with all software versions...
  55 class Dict {
  56         string name;
  57         string filename;
  58         DictEntry* entries;
  59 public:
  60         Dict();
  61         Dict(string filename);  // Read Dict from disk
  62         int AppendEntry(DictEntry* NewEntry);
  63 };
  64
  65 // Container for managing a set of loaded dictionaries. Sharing dictionaries
  66 // should avoid :
  67 // * reloading an allready loaded dictionary.
  68 // * having many in memory representations of the same dictionary.
  69 class DictSet {
  70 private:
  71         Dict* dicts;
  72         int AppendDict(Dict* NewDict);
  73 public:
  74         DictSet();              // Default constructor loads THE DICOM v3 dictionary
  75         int LoadDictFromFile(string filename);
  76         int LoadDictFromName(string filename);
  77         int LoadAllDictFromDirectory(string directorynanme);
  78         string* GetAllDictNames();
  79         Dict* GetDict(string DictName);
  80 };
  81
  82 // The dicom header of a Dicom file contains a set of such ELement VALUES
  83 // (when successfuly parsed against a given Dicom dictionary)
  84 class ElValue {
  85         guint16 group;          // e.g. 0x0010
  86         guint16 element;        // e.g. 0x0010
  87         string  value;
  88 };
  89
  90 // Container for a set of succefully parsed ElValues.
  91 class ElValSet {
  92         ElValue* values;
  93 };
  94
  95 // The typical usage of objects of this class is to classify a set of
  96 // dicom files according to header information e.g. to create a file hierachy
  97 // reflecting the Patient/Study/Serie informations, or extracting a given
  98 // SerieId. Accesing the content (image[s] or volume[s]) is beyond the
  99 // functionality of this class (see dmcFile below).
 100 // Notes:
 101 // * the dcmHeader::Set*Tag* family members cannot be defined as protected
 102 //   (Swig limitations for as Has_a dependency between dcmFile and dcmHeader)
 103 class dcmHeader {
 104 private:
 105         static DictSet* Dicts;  // Global dictionary container
 106         Dict* RefPubDict;                       // Public Dictionary
 107         Dict* RefShaDict;                       // Shadow Dictionary (optional)
 108         int swapcode;
 109         ElValSet PubElVals;             // Element Values parsed with Public Dictionary
 110         ElValSet ShaElVals;             // Element Values parsed with Shadow Dictionary
 111 public:
 112         dcmHeader();
 113         dcmHeader(string filename);
 114         ~dcmHeader();
 115
 116         int SetPubDict(string filename);
 117         // When some proprietary shadow groups are disclosed, whe can set
 118         // up an additional specific dictionary to access extra information.
 119         int SetShaDict(string filename);
 120
 121         // Retrieve all potentially available tag [tag = (group, element)] names
 122         // from the standard (or public) dictionary (hence static). Typical usage:
 123         // enable the user of a GUI based interface to select his favorite fields
 124         // for sorting or selection.
 125         string* GetPubTagNames();
 126         // Get the element values themselves:
 127         string GetPubElValByName(string TagName);
 128         string GetPubElValByNumber(guint16 group, guint16 element);
 129         // Get the element value representation: (VR) might be needed by caller
 130         // to convert the string typed content to caller's native type (think
 131         // of C/C++ vs Python).
 132         string GetPubElValRepByName(string TagName);
 133         string GetPubElValRepByNumber(guint16 group, guint16 element);
 134
 135         // Same thing with the shadow :
 136         string* GetShaTagNames();
 137         string GetShaElValByName(string TagName);
 138         string GetShaElValByNumber(guint16 group, guint16 element);
 139         string GetShaElValRepByName(string TagName);
 140         string GetShaElValRepByNumber(guint16 group, guint16 element);
 141
 142         // Wrappers of the above (both public and shadow) to avoid bugging the
 143         // caller with knowing if ElVal is from the public or shadow dictionary.
 144         string GetElValByName(string TagName);
 145         string GetElValByNumber(guint16 group, guint16 element);
 146         string GetElValRepByName(string TagName);
 147         string GetElValRepByNumber(guint16 group, guint16 element);
 148
 149         int SetPubElValByName(string content, string TagName);
 150         int SetPubElValByNumber(string content, guint16 group, guint16 element);
 151         int SetShaElValByName(string content, string ShadowTagName);
 152         int SetShaElValByNumber(string content, guint16 group, guint16 element);
 153
 154         int GetSwapCode();
 155 };
 156
 157 // In addition to Dicom header exploration, this class is designed
 158 // for accessing the image/volume content. One can also use it to
 159 // write Dicom files.
 160 class dcmFile
 161 {
 162 private:
 163         dcmHeader* Header;
 164         void* Data;
 165         int Parsed;                             // weather allready parsed
 166         string OrigFileName;    // To avoid file overwrite
 167 public:
 168         // Constructor dedicated to writing a new DICOMV3 part10 compliant
 169         // file (see SetFileName, SetDcmTag and Write)
 170         dcmFile();
 171         // Opens (in read only and when possible) an existing file and checks
 172         // for DICOM compliance. Returns NULL on failure.
 173         // Note: the in-memory representation of all available tags found in
 174         //    the DICOM header is post-poned to first header information access.
 175         //    This avoid a double parsing of public part of the header when
 176         //    one sets an a posteriori shadow dictionary (efficiency can be
 177         //    seen a a side effect).
 178         dcmFile(string filename);
 179         // For promotion (performs a deepcopy of pointed header object)
 180         dcmFile(dcmHeader* header);
 181         ~dcmFile();
 182
 183         // On writing purposes. When instance was created through
 184         // dcmFile(string filename) then the filename argument MUST be different
 185         // from the constructor's one (no overwriting aloud).
 186         int SetFileName(string filename);
 187
 188         // Allocates necessary memory, copies the data (image[s]/volume[s]) to
 189         // newly allocated zone and return a pointer to it:
 190         void * GetImageData();
 191         // Returns size (in bytes) of required memory to contain data
 192         // represented in this file.
 193         size_t GetImageDataSize();
 194         // Copies (at most MaxSize bytes) of data to caller's memory space.
 195         // Returns an error code on failure (if MaxSize is not big enough)
 196         int GetImageDataHere(void* destination, size_t MaxSize );
 197         // Allocates ExpectedSize bytes of memory at this->Data and copies the
 198         // pointed data to it.
 199         int SetImageData(void * Data, size_t ExpectedSize);
 200         // Push to disk.
 201         int Write();
 202
 203 ///// Repeat here all the dcmHeader public members !!!
 204 };
 205
 206 //class dcmSerie : dcmFile;
 207 //class dcmMultiFrame : dcmFile;
 208
 209 //
 210 //Examples:
 211 // * dcmFile WriteDicom;
 212 //   WriteDicom.SetFileName("MyDicomFile.dcm");
 213 //      string * AllTags = dcmHeader.GetDcmTagNames();
 214 //   WriteDicom.SetDcmTag(AllTags[5], "253");
 215 //   WriteDicom.SetDcmTag("Patient Name", "bozo");
 216 //   WriteDicom.SetDcmTag("Patient Name", "bozo");
 217 //      WriteDicom.SetImageData(Image);
 218 //   WriteDicom.Write();