1 /* 2 * 3 * Copyright (C) 1998-2012, 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: dcmpstat 15 * 16 * Author: Marco Eichelberg 17 * 18 * Purpose: 19 * classes: DVPSImageBoxContent_PList 20 * 21 */ 22 23 #ifndef DVPSIBL_H 24 #define DVPSIBL_H 25 26 #include "dcmtk/config/osconfig.h" /* make sure OS specific configuration is included first */ 27 #include "dcmtk/dcmpstat/dvpstyp.h" /* for enum types */ 28 #include "dcmtk/dcmpstat/dpdefine.h" 29 #include "dcmtk/dcmdata/dcitem.h" 30 #include "dcmtk/dcmdata/dcvrui.h" 31 32 class DVPSImageBoxContent; 33 class DVPSPresentationLUT_PList; 34 35 /** the list of Image Boxes contained in a stored print object. 36 * This class manages the data structures comprising one complete 37 * Image Box Content Sequence in a Stored Print object. 38 */ 39 40 class DCMTK_DCMPSTAT_EXPORT DVPSImageBoxContent_PList 41 { 42 public: 43 44 /// default constructor 45 DVPSImageBoxContent_PList(); 46 47 /// copy constructor 48 DVPSImageBoxContent_PList(const DVPSImageBoxContent_PList& copy); 49 50 /** clone method. 51 * @return a pointer to a new DVPSImageBoxContent_PList object containing 52 * a deep copy of this object. 53 */ clone()54 DVPSImageBoxContent_PList *clone() { return new DVPSImageBoxContent_PList(*this); } 55 56 /// destructor 57 virtual ~DVPSImageBoxContent_PList(); 58 59 /** reads a list of image boxes (ImageBoxContentSequence) from a DICOM dataset. 60 * The DICOM elements of the image boxes are copied from the dataset to this object. 61 * The completeness of all items (presence of all required elements, 62 * value multiplicity) is checked. 63 * If this method returns an error code, the object is in undefined state afterwards. 64 * @param dset the DICOM dataset from which the sequence is to be read 65 * @param presentationLUTList list of presentation LUTs which may be referenced 66 * @return EC_Normal if successful, an error code otherwise. 67 */ 68 OFCondition read(DcmItem &dset, DVPSPresentationLUT_PList& presentationLUTList); 69 70 /** writes the list of image boxes managed by this object to a DICOM dataset. 71 * Copies of the DICOM element managed by this object are inserted into 72 * the DICOM dataset. 73 * @param dset the DICOM dataset to which the ImageBoxContentSequence is written 74 * @param writeRequestedImageSize if false, the Requested Image Size attributes are not written, 75 * e.g. because they are not supported by the target printer. 76 * @param numItems the number of items (from the beginning of the list) to be written. 77 * Default: all items are written. 78 * @param ignoreEmptyImages if true, all image boxes without image box position are ignored 79 * when writing. 80 * @param writeReferencedPLUTSQ if false, the Referenced Presentation LUT Sequence is not written, 81 * e.g. because a "general" presentation LUT is used instead of those referenced by the image boxes. 82 * @return EC_Normal if successful, an error code otherwise. 83 */ 84 OFCondition write( 85 DcmItem &dset, 86 OFBool writeRequestedImageSize, 87 size_t numItems, 88 OFBool ignoreEmptyImages, 89 OFBool writeReferencedPLUTSQ = OFTrue); 90 91 /** reset the object to initial state. 92 * After this call, the object is in the same state as after 93 * creation with the default constructor. 94 */ 95 void clear(); 96 97 /** gets the number of image boxes in this list. 98 * @return the number of image boxes. 99 */ size()100 size_t size() const { return list_.size(); } 101 102 /** create default values for all missing type 1 elements. 103 * Called before a stored print object is written. 104 * @param renumber if true, new imageBoxPosition values are created 105 * @param ignoreEmptyImages if true, an empty image box position does not cause an error. 106 * @return EC_Normal if successful, an error code otherwise. 107 */ 108 OFCondition createDefaultValues(OFBool renumber, OFBool ignoreEmptyImages); 109 110 /** adds all image SOP classes referenced in the image box list to 111 * the given sequence. Duplicate entries are suppressed. 112 * @param seq sequence to be added to, should be a PrintManagementCapabilitiesSequence. 113 * @param numItems number of items of this list to be taken into account. 114 * Default: all items. 115 * @return EC_Normal if successful, an error code otherwise. 116 */ 117 OFCondition addImageSOPClasses(DcmSequenceOfItems& seq, size_t numItems=0); 118 119 /** creates a new image box object and sets the content of this image box object. 120 * @param instanceuid SOP instance UID of this image box 121 * @param retrieveaetitle retrieve AETITLE of the referenced image 122 * @param refstudyuid study instance UID of the referenced image 123 * @param refseriesuid series instance UID of the referenced image 124 * @param refsopclassuid SOP class UID of the referenced image 125 * @param refsopinstanceuid SOP instance UID of the referenced image 126 * @param requestedimagesize requested images size for this image, default: absent 127 * @param patientid patient ID for the referenced image, default: absent 128 * @return EC_Normal if successful, an error code otherwise. 129 */ 130 OFCondition addImageBox( 131 const char *instanceuid, 132 const char *retrieveaetitle, 133 const char *refstudyuid, 134 const char *refseriesuid, 135 const char *refsopclassuid, 136 const char *refsopinstanceuid, 137 const char *requestedimagesize, 138 const char *patientid, 139 const char *presentationlutuid); 140 141 /** adds the given image box object to the list managed by this object. 142 * @param box image box object to be added. 143 * @return EC_Normal if successful, an error code otherwise. 144 */ 145 OFCondition addImageBox(DVPSImageBoxContent *box); 146 147 /** sets the (optional) requested decimate/crop behaviour 148 * for all image boxes managed by this object. 149 * @param value new enumerated value. The caller is responsible for 150 * making sure that the selected printer supports decimate/crop 151 * if a non-default value is set. 152 * @return EC_Normal if successful, an error code otherwise. 153 */ 154 OFCondition setRequestedDecimateCropBehaviour(DVPSDecimateCropBehaviour value); 155 156 /** deletes one of the registered images. 157 * @param idx index, must be < size() 158 * @return EC_Normal if successful, an error code otherwise. 159 */ 160 OFCondition deleteImage(size_t idx); 161 162 /** deletes multiple of the registered images, starting with the first one. 163 * @param number number of images to delete, must be <= size() 164 * @return EC_Normal if successful, an error code otherwise. 165 */ 166 OFCondition deleteMultipleImages(size_t number); 167 168 /** checks if one of the registered images has additional settings that are not 169 * default values on the image box level. 170 * @param idx index, must be < getNumberOfImages() 171 * @return EC_Normal if successful, an error code otherwise. 172 */ 173 OFBool imageHasAdditionalSettings(size_t idx); 174 175 /** sets the polarity for the given registered image box. 176 * @param idx index, must be < getNumberOfImages() 177 * @param value new attribute value (NORMAL or REVERSE), may be NULL. 178 * @return EC_Normal if successful, an error code otherwise. 179 */ 180 OFCondition setImagePolarity(size_t idx, const char *value); 181 182 /** sets the requested size for the given registered image box. 183 * @param idx index, must be < getNumberOfImages() 184 * @param value new attribute value, may be NULL. 185 * @return EC_Normal if successful, an error code otherwise. 186 */ 187 OFCondition setImageRequestedSize(size_t idx, const char *value); 188 189 /** sets the (optional) magnification type for the given registered image box. 190 * @param idx index, must be < getNumberOfImages() 191 * @param value new attribute value, may be NULL. 192 * The caller is responsible for making sure 193 * that the value is valid for the selected printer. 194 * @return EC_Normal if successful, an error code otherwise. 195 */ 196 OFCondition setImageMagnificationType(size_t idx, const char *value); 197 198 /** sets the (optional) smoothing type for the given registered image box. 199 * @param idx index, must be < getNumberOfImages() 200 * @param value new attribute value, may be NULL. 201 * The caller is responsible for making sure 202 * that the value is valid for the selected printer. 203 * @return EC_Normal if successful, an error code otherwise. 204 */ 205 OFCondition setImageSmoothingType(size_t idx, const char *value); 206 207 /** sets the (optional) configuration information for the given registered image box. 208 * @param idx index, must be < getNumberOfImages() 209 * @param value new attribute value, may be NULL. 210 * The caller is responsible for making sure 211 * that the value is valid for the selected printer. 212 * @return EC_Normal if successful, an error code otherwise. 213 */ 214 OFCondition setImageConfigurationInformation(size_t idx, const char *value); 215 216 /** sets the SOP instance UID for the given image box. 217 * @param idx index, must be < getNumberOfImages() 218 * @param value new attribute value, must not be NULL. 219 * @return EC_Normal if successful, an error code otherwise. 220 */ 221 OFCondition setImageSOPInstanceUID(size_t idx, const char *value); 222 223 /** sets magnification type, smoothing type and configuration information back to default 224 * for all registered images. 225 * @return EC_Normal if successful, an error code otherwise. 226 */ 227 OFCondition setAllImagesToDefault(); 228 229 /** gets the polarity for the given registered image box. 230 * @param idx index, must be < getNumberOfImages() 231 * @return polarity, may be NULL. 232 */ 233 const char *getImagePolarity(size_t idx); 234 235 /** gets the requested size for the given registered image box. 236 * @param idx index, must be < getNumberOfImages() 237 * @return requested size, may be NULL. 238 */ 239 const char *getImageRequestedSize(size_t idx); 240 241 /** gets the (optional) magnification type for the given registered image box. 242 * @param idx index, must be < getNumberOfImages() 243 * @return magnification type, may be NULL. 244 */ 245 const char *getImageMagnificationType(size_t idx); 246 247 /** gets the (optional) smoothing type for the given registered image box. 248 * @param idx index, must be < getNumberOfImages() 249 * @return smoothing type, may be NULL. 250 */ 251 const char *getImageSmoothingType(size_t idx); 252 253 /** gets the (optional) configuration information for the given registered image box. 254 * @param idx index, must be < getNumberOfImages() 255 * @return configuration information, may be NULL. 256 */ 257 const char *getImageConfigurationInformation(size_t idx); 258 259 /** gets the current SOP Instance UID for the given registered image box.. 260 * @param idx index, must be < getNumberOfImages() 261 * @return SOP Instance UID, may be NULL. 262 */ 263 const char *getSOPInstanceUID(size_t idx); 264 265 /** gets the referenced Presentation LUT SOP Instance UID for the given registered image box.. 266 * @param idx index, must be < getNumberOfImages() 267 * @return SOP Instance UID, may be NULL. 268 */ 269 const char *getReferencedPresentationLUTInstanceUID(size_t idx); 270 271 /** returns the image UIDs that are required to look up the referenced image in the database 272 * @param idx index, must be < getNumberOfImages() 273 * @param studyUID Study UID of the image 274 * @param seriesUID series UID of the image 275 * @param instanceUID instance UID of the image 276 * @return EC_Normal if successful, an error code otherwise. 277 */ 278 OFCondition getImageReference(size_t idx, const char *&studyUID, const char *&seriesUID, const char *&instanceUID); 279 280 /** writes the attributes managed by the referenced object that are part of a 281 * basic grayscale image box N-SET request into the DICOM dataset. 282 * Copies of the DICOM element managed by this object are inserted into 283 * the DICOM dataset. 284 * @param idx index, must be < getNumberOfImages() 285 * @param dset the dataset to which the data is written 286 * @return EC_Normal if successful, an error code otherwise. 287 */ 288 OFCondition prepareBasicImageBox(size_t idx, DcmItem &dset); 289 290 /** checks whether the given SOP instance UID is used as 291 * referenced Presentation LUT SOP Instance UID inside the list of 292 * image boxes managed by this object. 293 * @param uid name of UID 294 * @return OFTrue if UID is used, OFFalse otherwise. 295 */ 296 OFBool presentationLUTInstanceUIDisUsed(const char *uid); 297 298 /** if only one Presentation LUT is required to render all images 299 * managed by this object, returns the UID of this presentation LUT. 300 * Otherwise returns NULL. 301 * @param filmBox UID of Presentation LUT specified on Film Box 302 * level. May be NULL or empty string if absent. 303 * @return UID of Presentation LUT if found, NULL or empty string otherwise. 304 */ 305 const char *haveSinglePresentationLUTUsed(const char *filmBox); 306 307 /** creates a number of image boxes as part of a Print SCP N-CREATE operation. 308 * The previous content of the list is deleted. 309 * @param numBoxes number of boxes to be created 310 * @param studyUID study instance UID under which Hardcopy Grayscale images will be saved 311 * @param seriesUID series instance UID under which Hardcopy Grayscale images will be saved 312 * @param aetitle retrieve AE title for Hardcopy Grayscale images 313 * @return OFTrue if successful, OFFalse otherwise. 314 */ 315 OFBool printSCPCreate( 316 unsigned long numBoxes, 317 DcmUniqueIdentifier& studyUID, 318 DcmUniqueIdentifier& seriesUID, 319 const char *aetitle); 320 321 /** writes a Referenced Image Box Sequence for the image boxes 322 * managed by this object. Used in a Print SCP N-CREATE operation. 323 * @param dset the dataset to which the data is written 324 * @return EC_Normal if successful, an error code otherwise. 325 */ 326 OFCondition writeReferencedImageBoxSQ(DcmItem &dset); 327 328 /** checks whether the given Presentation LUT type could be used together 329 * with all image boxes in this list on a Print SCP that requires a matching 330 * alignment between a Presentation LUT and the image pixel data. 331 * @param align LUT alignment type 332 * @return OFTrue if matching, OFFalse otherwise 333 */ 334 OFBool matchesPresentationLUT(DVPSPrintPresentationLUTAlignment align) const; 335 336 /** looks up the image box with the given SOP instance UID in this list 337 * and returns a pointer to a new object containing a copy of this 338 * image box. If the object is not found, NULL is returned. 339 * @param uid SOP instance UID of the image box to be looked up 340 * @return pointer to copied image box object, may be NULL. 341 */ 342 DVPSImageBoxContent *duplicateImageBox(const char *uid); 343 344 /** checks whether any of the image boxes managed by this list 345 * has the same position as the given one, but a different 346 * SOP instance UID. This is used during an Print SCP N-SET operation 347 * to check whether a position clash exists. 348 * @param uid SOP instance UID of the image box to be looked up 349 * @param position image position to be looked up 350 */ 351 OFBool haveImagePositionClash(const char *uid, Uint16 position); 352 353 /** adds the given image box object to this list. Any other object existing 354 * in the list with the same SOP instance UID is removed. 355 * Used during a Print SCP image box N-SET operation. 356 * @param newImageBox new image box object to be added to the list. 357 */ 358 void replace(DVPSImageBoxContent *newImageBox); 359 360 /** checks whether any of the image boxes has an image box position 361 * assigned. If no image box position is assigned, the object list 362 * cannot be written and a Print SCP should return a warning 363 * status upon receipt of an N-ACTION request. 364 * @return OFTrue if empty page (no image box position assigned), OFFalse otherwise. 365 */ 366 OFBool emptyPageWarning(); 367 368 private: 369 370 /** private undefined assignment operator 371 */ 372 DVPSImageBoxContent_PList& operator=(const DVPSImageBoxContent_PList&); 373 374 /** returns a pointer to the image box with the given 375 * index or NULL if it does not exist. 376 * @param idx index, must be < size() 377 * @return pointer to image box object or NULL 378 */ 379 DVPSImageBoxContent *getImageBox(size_t idx); 380 381 /** the list maintained by this object 382 */ 383 OFList<DVPSImageBoxContent *> list_; 384 385 }; 386 387 388 #endif 389