1 /* 2 * 3 * Copyright (C) 1996-2014, OFFIS e.V. 4 * All rights reserved. See COPYRIGHT file for details. 5 * 6 * This software and supporting documentation were developed by 7 * 8 * OFFIS e.V. 9 * R&D Division Health 10 * Escherweg 2 11 * D-26121 Oldenburg, Germany 12 * 13 * 14 * Module: dcmimgle 15 * 16 * Author: Joerg Riesmeier 17 * 18 * Purpose: DicomDocument (Header) 19 * 20 */ 21 22 23 #ifndef DIDOCU_H 24 #define DIDOCU_H 25 26 #include "dcmtk/config/osconfig.h" 27 28 #include "dcmtk/dcmdata/dctypes.h" 29 #include "dcmtk/dcmdata/dcfilefo.h" 30 #include "dcmtk/dcmdata/dcxfer.h" 31 #include "dcmtk/dcmimgle/diobjcou.h" 32 #include "dcmtk/ofstd/ofstring.h" 33 34 #define INCLUDE_CSTDDEF 35 #include "dcmtk/ofstd/ofstdinc.h" 36 37 38 /*------------------------* 39 * forward declarations * 40 *------------------------*/ 41 42 class DcmStack; 43 class DcmObject; 44 class DcmTagKey; 45 class DcmElement; 46 class DcmPixelData; 47 class DcmSequenceOfItems; 48 49 50 /*---------------------* 51 * class declaration * 52 *---------------------*/ 53 54 /** Interface class to DICOM data management (dcmdata). 55 * NB: This is an internal class of module dcmimgle/dcmimage. Please do not 56 * use it for accessing DICOM data structures. Instead use the classes 57 * and functions provided by dcmdata (e.g. class DcmFileFormat, DcmItem). 58 */ 59 class DCMTK_DCMIMGLE_EXPORT DiDocument 60 : public DiObjectCounter 61 { 62 63 public: 64 65 /** constructor, open a DICOM file 66 * 67 ** @param filename the DICOM file 68 * @param flags configuration flags (only stored for later use) 69 * @param fstart first frame to be processed (only stored for later use) 70 * @param fcount number of frames (only stored for later use) 71 */ 72 DiDocument(const char *filename, 73 const unsigned long flags = 0, 74 const unsigned long fstart = 0, 75 const unsigned long fcount = 0); 76 77 /** constructor, use a given DcmObject 78 * 79 ** @param object pointer to DICOM data structures (fileformat, dataset or item) 80 * @param xfer transfer syntax of the 'object'. 81 * (could also be EXS_Unknown in case of fileformat or dataset) 82 * @param flags configuration flags (only stored for later use) 83 * @param fstart first frame to be processed (only stored for later use) 84 * @param fcount number of frames (only stored for later use) 85 */ 86 DiDocument(DcmObject *object, 87 const E_TransferSyntax xfer, 88 const unsigned long flags = 0, 89 const unsigned long fstart = 0, 90 const unsigned long fcount = 0); 91 92 /** destructor 93 */ 94 virtual ~DiDocument(); 95 96 /** check whether current document is valid 97 * 98 ** @return status, true if successful, false otherwise 99 */ good()100 inline int good() const 101 { 102 return Object != NULL; 103 } 104 105 /** get current DICOM object (dataset) 106 * 107 ** @return pointer to DICOM object 108 */ getDicomObject()109 inline DcmObject *getDicomObject() const 110 { 111 return Object; 112 } 113 114 /** get current DICOM dataset 115 * 116 ** @return pointer to DICOM dataset 117 */ getDataset()118 inline DcmDataset *getDataset() const 119 { 120 return OFstatic_cast(DcmDataset *, Object); 121 } 122 123 /** get first frame to be processed 124 * 125 ** @return first frame to be processed 126 */ getFrameStart()127 inline unsigned long getFrameStart() const 128 { 129 return FrameStart; 130 } 131 132 /** get number of frames to be processed 133 * 134 ** @return number of frames to be processed 135 */ getFrameCount()136 inline unsigned long getFrameCount() const 137 { 138 return FrameCount; 139 } 140 141 /** get configuration flags 142 * 143 ** @return configuration flags 144 */ getFlags()145 inline unsigned long getFlags() const 146 { 147 return Flags; 148 } 149 150 /** get transfer syntax of the DICOM dataset 151 * 152 ** @return transfer syntax 153 */ getTransferSyntax()154 inline E_TransferSyntax getTransferSyntax() const 155 { 156 return Xfer; 157 } 158 159 /** get photometric interpretation (color model). 160 * Please note that this is the color model of the decompressed image which might 161 * deviate from the color model of the original compressed image. 162 * 163 ** @return photometric interpretation of the DICOM object 164 */ getPhotometricInterpretation()165 inline const char *getPhotometricInterpretation() const 166 { 167 return PhotometricInterpretation.c_str(); 168 } 169 170 /** get pixel data object 171 * 172 ** @return reference to pixel data object (might be NULL) 173 */ getPixelData()174 inline DcmPixelData *getPixelData() const 175 { 176 return PixelData; 177 } 178 179 /** check whether pixel data only exist in compressed format 180 * 181 ** @return true if pixel data is compressed, false if an uncompressed version exists 182 */ isCompressed()183 inline OFBool isCompressed() const 184 { 185 return DcmXfer(Xfer).isEncapsulated(); 186 } 187 188 /** search for given tag 189 * 190 ** @param tag tag to search for 191 * @param obj element in the dataset where the search should start (default: root) 192 * 193 ** @return pointer to element if successful, NULL otherwise 194 */ 195 DcmElement *search(const DcmTagKey &tag, 196 DcmObject *obj = NULL) const; 197 198 /** search for given tag and put result(s) on a stack 199 * 200 ** @param tag tag to search for 201 * @param stack stack where the result(s) should be stored 202 * 203 ** @return status, true if successful, false otherwise 204 */ 205 int search(const DcmTagKey &tag, 206 DcmStack &stack) const; 207 208 209 /** get value multiplicity (VM) of given tag 210 * 211 ** @param tag tag to be searched 212 * 213 ** @return VM if successful, 0 otherwise 214 */ 215 unsigned long getVM(const DcmTagKey &tag) const; 216 217 /** get value of given tag (Uint16) 218 * 219 ** @param tag tag to search for 220 * @param returnVal reference to the storage area for the resulting value 221 * @param pos position in multi-valued elements (starting with 0) 222 * @param item pointer to item in dataset where to start (default: main dataset) 223 * @param allowSigned also allow signed value (Sint16) if true 224 * 225 ** @return VM if successful, 0 otherwise 226 */ 227 unsigned long getValue(const DcmTagKey &tag, 228 Uint16 &returnVal, 229 const unsigned long pos = 0, 230 DcmItem *item = NULL, 231 const OFBool allowSigned = OFFalse) const; 232 233 /** get value of given tag (Sint16) 234 * 235 ** @param tag tag to search for 236 * @param returnVal reference to the storage area for the resulting value 237 * @param pos position in multi-valued elements (starting with 0) 238 * @param item pointer to item in dataset where to start (default: main dataset) 239 * 240 ** @return VM if successful, 0 otherwise 241 */ 242 unsigned long getValue(const DcmTagKey &tag, 243 Sint16 &returnVal, 244 const unsigned long pos = 0, 245 DcmItem *item = NULL) const; 246 247 /** get value of given tag (Uint32) 248 * 249 ** @param tag tag to search for 250 * @param returnVal reference to the storage area for the resulting value 251 * @param pos position in multi-valued elements (starting with 0) 252 * @param item pointer to item in dataset where to start (default: main dataset) 253 * 254 ** @return VM if successful, 0 otherwise 255 */ 256 unsigned long getValue(const DcmTagKey &tag, 257 Uint32 &returnVal, 258 const unsigned long pos = 0, 259 DcmItem *item = NULL) const; 260 261 /** get value of given tag (Sint32) 262 * 263 ** @param tag tag to search for 264 * @param returnVal reference to the storage area for the resulting value 265 * @param pos position in multi-valued elements (starting with 0) 266 * @param item pointer to item in dataset where to start (default: main dataset) 267 * 268 ** @return VM if successful, 0 otherwise 269 */ 270 unsigned long getValue(const DcmTagKey &tag, 271 Sint32 &returnVal, 272 const unsigned long pos = 0, 273 DcmItem *item = NULL) const; 274 275 /** get value of given tag (double) 276 * 277 ** @param tag tag to search for 278 * @param returnVal reference to the storage area for the resulting value 279 * @param pos position in multi-valued elements (starting with 0) 280 * @param item pointer to item in dataset where to start (default: main dataset) 281 * 282 ** @return VM if successful, 0 otherwise 283 */ 284 unsigned long getValue(const DcmTagKey &tag, 285 double &returnVal, 286 const unsigned long pos = 0, 287 DcmItem *item = NULL) const; 288 289 /** get value of given tag (Uint16 array) 290 * 291 ** @param tag tag to search for 292 * @param returnVal reference to the storage area for the resulting value 293 * @param item pointer to item in dataset where to start (default: main dataset) 294 * 295 ** @return VM / number of values if successful, 0 otherwise 296 */ 297 unsigned long getValue(const DcmTagKey &tag, 298 const Uint16 *&returnVal, 299 DcmItem *item = NULL) const; 300 301 /** get value of given tag (const char *) 302 * 303 ** @param tag tag to search for 304 * @param returnVal reference to the storage area for the resulting value 305 * @param item pointer to item in dataset where to start (default: main dataset) 306 * 307 ** @return VM if successful, 0 otherwise 308 */ 309 unsigned long getValue(const DcmTagKey &tag, 310 const char *&returnVal, 311 DcmItem *item = NULL) const; 312 313 /** get value of given tag (OFString) 314 * 315 ** @param tag tag to search for 316 * @param returnVal reference to the storage area for the resulting value 317 * @param pos position in multi-valued elements (starting with 0) 318 * @param item pointer to item in dataset where to start (default: main dataset) 319 * 320 ** @return VM if successful, 0 otherwise 321 */ 322 unsigned long getValue(const DcmTagKey &tag, 323 OFString &returnVal, 324 const unsigned long pos = 0, 325 DcmItem *item = NULL) const; 326 327 /** get sequence of given tag 328 * 329 ** @param tag tag to search for 330 * @param seq reference to the storage area for the resulting value 331 * @param item pointer to item in dataset where to start (default: main dataset) 332 * 333 ** @return cardinality if successful, 0 otherwise 334 */ 335 unsigned long getSequence(const DcmTagKey &tag, 336 DcmSequenceOfItems *&seq, 337 DcmItem *item = NULL) const; 338 339 // --- static helper functions --- 340 341 /** get value of given element (Uint16) 342 * 343 ** @param elem element where the value is stored 344 * @param returnVal reference to the storage area for the resulting value 345 * @param pos position in multi-valued elements (starting with 0) 346 * @param allowSigned also allow signed value (Sint16) if true 347 * 348 ** @return VM if successful, 0 otherwise 349 */ 350 static unsigned long getElemValue(const DcmElement *elem, 351 Uint16 &returnVal, 352 const unsigned long pos = 0, 353 const OFBool allowSigned = OFFalse); 354 355 /** get value of given element (Uint16 array) 356 * 357 ** @param elem element where the value is stored 358 * @param returnVal reference to the storage area for the resulting value 359 * 360 ** @return VM / number of values if successful, 0 otherwise 361 */ 362 static unsigned long getElemValue(const DcmElement *elem, 363 const Uint16 *&returnVal); 364 365 /** get value of given element (const char *) 366 * 367 ** @param elem element where the value is stored 368 * @param returnVal reference to the storage area for the resulting value 369 * 370 ** @return VM if successful, 0 otherwise 371 */ 372 static unsigned long getElemValue(const DcmElement *elem, 373 const char *&returnVal); 374 375 /** get value of given element (OFString) 376 * 377 ** @param elem element where the value is stored 378 * @param returnVal reference to the storage area for the resulting value 379 * @param pos position in multi-valued elements (starting with 0) 380 * 381 ** @return VM if successful, 0 otherwise 382 */ 383 static unsigned long getElemValue(const DcmElement *elem, 384 OFString &returnVal, 385 const unsigned long pos = 0); 386 387 388 protected: 389 390 /** convert pixel data to uncompressed representation (if required) 391 */ 392 void convertPixelData(); 393 394 395 private: 396 397 /// reference to DICOM dataset (in memory) 398 DcmObject *Object; 399 /// reference to DICOM fileformat (read from file, maybe NULL) 400 DcmFileFormat *FileFormat; 401 /// reference to pixel data object 402 DcmPixelData *PixelData; 403 /// transfer syntax used for reading the dataset 404 E_TransferSyntax Xfer; 405 406 /// first frame to be processed 407 unsigned long FrameStart; 408 /// number of frames to be processed 409 unsigned long FrameCount; 410 411 /// configuration flags 412 unsigned long Flags; 413 414 /// photometric interpretation (color model) 415 OFString PhotometricInterpretation; 416 417 // --- declarations to avoid compiler warnings 418 419 DiDocument(const DiDocument &); 420 DiDocument &operator=(const DiDocument &); 421 }; 422 423 424 #endif 425