DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | List of all members
DVPresentationState Class Reference

a Grayscale Softcopy Presentation State. More...

Inheritance diagram for DVPresentationState:

## Public Member Functions
| DVPresentationState (DiDisplayFunction **dispFunction=NULL, unsigned long minPrintBitmapX=0, unsigned long minPrintBitmapY=0, unsigned long maxPrintBitmapX=0, unsigned long maxPrintBitmapY=0, unsigned long maxPreviewImageX=0, unsigned long maxPreviewImageY=0)
| default constructor More...
virtual | ~DVPresentationState ()
| destructor
void | clear ()
| resets the object to initial state. More...
OFCondition | read (DcmItem &dset)
| reads a presentation state from a DICOM dataset. More...
OFCondition | createFromImage (DcmItem &dset, DVPSoverlayActivation overlayActivation=DVPSO_copyOverlays, DVPSVOIActivation voiActivation=DVPSV_preferVOILUT, OFBool curveActivation=OFTrue, OFBool shutterActivation=OFTrue, OFBool presentationActivation=OFTrue, DVPSGraphicLayering layering=DVPSG_twoLayers, const char *aetitle=NULL, const char *filesetID=NULL, const char *filesetUID=NULL)
| creates a default presentation state for a DICOM image. More...
OFCondition | addImageReferenceAttached (const char *aetitle=NULL, const char *filesetID=NULL, const char *filesetUID=NULL)
| adds a reference to the currently attached image to this presentation state. More...
OFCondition | removeImageReferenceAttached ()
| removes a reference to the currently attached image from this presentation state. More...
OFCondition | setCurrentPresentationLUT (DVPSPresentationLUTType newType)
| sets the current Presentation LUT type. More...
OFCondition | setDefaultPresentationLUTShape ()
| resets the Presentation LUT to the default LUT shape which is DVPSP_identity for MONOCHROME2 images and DVPSP_inverse for MONOCHROME1. More...
OFCondition | setPresentationLookupTable (DcmUnsignedShort &lutDescriptor, DcmUnsignedShort &lutData, DcmLongString &lutExplanation)
| stores a presentation lookup table in the presentation state. More...
OFCondition | setPresentationLookupTable (DcmItem &dset)
| stores a presentation lookup table in the presentation state. More...
OFCondition | writePresentationLUTforPrint (DcmItem &dset)
| writes the current Presentation LUT to a DICOM dataset. More...
OFBool | isMonochrome1Image ()
| checks whether the attached image is MONOCHROME1. More...
OFBool | haveActiveVOIWindow ()
| check if a VOI window is currently active More...
OFBool | haveActiveVOILUT ()
| check if a VOI LUT is currently active More...
const char * | getCurrentVOIDescription ()
| returns a description string for a currently active VOI transform. More...
OFCondition | getCurrentWindowWidth (double &w)
| gets the width of the current VOI window. More...
OFCondition | getCurrentWindowCenter (double &c)
| get the center of the current VOI window. More...
size_t | getNumberOfVOILUTsInImage ()
| gets the number of VOI LUTs available in the attached image.
size_t | getNumberOfVOIWindowsInImage ()
| gets the number of VOI Windows available in the attached image.
const char * | getDescriptionOfVOILUTsInImage (size_t idx)
| returns a description string for the given VOI LUT in the attached image. More...
const char * | getDescriptionOfVOIWindowsInImage (size_t idx)
| returns a description string for the given VOI Window in the attached image. More...
OFCondition | setVOILUTFromImage (size_t idx, DVPSObjectApplicability applicability=DVPSB_currentImage)
| activates one of the VOI LUTs from the attached image. More...
OFCondition | setVOIWindowFromImage (size_t idx, DVPSObjectApplicability applicability=DVPSB_currentImage)
| activates one of the VOI Windows from the attached image. More...
OFCondition | setVOIWindow (double wCenter, double wWidth, const char *description=NULL, DVPSObjectApplicability applicability=DVPSB_currentImage)
| sets a user defined VOI window center and width. More...
OFCondition | setVOILUT (DcmUnsignedShort &lutDescriptor, DcmUnsignedShort &lutData, DcmLongString &lutExplanation, DVPSObjectApplicability applicability=DVPSB_currentImage)
| stores a VOI lookup table in the presentation state. More...
void | deactivateVOI (DVPSObjectApplicability applicability=DVPSB_currentImage)
| deactivates the current VOI transformation. More...
OFCondition | setGammaVOILUT (double gammaValue, DVPSObjectApplicability applicability=DVPSB_currentImage)
| stores VOI lookup table with a gamma curve shape in the presentation state. More...
DVPSPresentationSizeMode | getDisplayedAreaPresentationSizeMode ()
| gets the presentation size mode for the current image and frame. More...
double | getDisplayedAreaPresentationPixelAspectRatio ()
| gets the presentation pixel aspect ratio for for the current image and frame. More...
OFCondition | getStandardDisplayedArea (Sint32 &tlhcX, Sint32 &tlhcY, Sint32 &brhcX, Sint32 &brhcY)
| gets the displayed area top lefthand corner and bottom righthand corner for the current potentially rotated and flipped image and frame. More...
OFCondition | getImageRelativeDisplayedArea (Sint32 &tlhcX, Sint32 &tlhcY, Sint32 &brhcX, Sint32 &brhcY)
| gets the displayed area top lefthand corner and bottom righthand corner for the current image and frame, as if the image was unrotated This method may only be called when an image is attached to the presentation state. More...
OFCondition | getDisplayedAreaPresentationPixelSpacing (double &x, double &y)
| gets the presentation pixel spacing for the current image and frame if it is known. More...
OFCondition | getDisplayedAreaPresentationPixelMagnificationRatio (double &magnification)
| gets the presentation pixel magnification ratio for the current image and frame if it is present. More...
OFBool | canUseDisplayedAreaTrueSize ()
| checks if "TRUE SIZE" can be used as presentation size mode for the current image and frame (i.e. More...
OFCondition | setStandardDisplayedArea (DVPSPresentationSizeMode sizeMode, Sint32 tlhcX, Sint32 tlhcY, Sint32 brhcX, Sint32 brhcY, double magnification=1.0, DVPSObjectApplicability applicability=DVPSB_currentImage)
| sets the displayed area and size mode (for the current frame, the current image or all images referenced by the presentation state object). More...
OFCondition | setImageRelativeDisplayedArea (DVPSPresentationSizeMode sizeMode, Sint32 tlhcX, Sint32 tlhcY, Sint32 brhcX, Sint32 brhcY, double magnification=1.0, DVPSObjectApplicability applicability=DVPSB_currentImage)
| sets the displayed area and size mode (for the current frame, the current image or all images referenced by the presentation state object). More...
void | removeShutter (DVPSShutterType type)
| deactivates display shutter of given type. More...
OFCondition | setRectShutter (Sint32 lv, Sint32 rv, Sint32 uh, Sint32 lh)
| sets and activates rectangular display shutter. More...
OFCondition | setCircularShutter (Sint32 centerX, Sint32 centerY, Sint32 radius)
| sets and activates circular display shutter. More...
OFCondition | addPolyShutterVertex (Sint32 x, Sint32 y)
| sets polygonal display shutter point. More...
OFCondition | removeGraphicLayer (size_t idx)
| removes and deletes a graphic layer. More...
size_t | getNumberOfTextObjects (size_t layer)
| returns the number of text objects for the given graphic layer. More...
DVPSTextObject * | getTextObject (size_t layer, size_t idx)
| gets the text object with the given index on the given layer. More...
DVPSTextObject * | addTextObject (size_t layer, DVPSObjectApplicability applicability=DVPSB_allImages)
| creates a new text object on the given layer. More...
OFCondition | removeTextObject (size_t layer, size_t idx)
| deletes the text object with the given index on the given layer. More...
OFCondition | moveTextObject (size_t old_layer, size_t idx, size_t new_layer, DVPSObjectApplicability applicability=DVPSB_allImages)
| moves the text object with the given index on the given layer to a different layer. More...
size_t | getNumberOfGraphicObjects (size_t layer)
| returns the number of graphic objects for the given graphic layer. More...
DVPSGraphicObject * | getGraphicObject (size_t layer, size_t idx)
| gets the graphic object with the given index on the given layer. More...
DVPSGraphicObject * | addGraphicObject (size_t layer, DVPSObjectApplicability applicability=DVPSB_allImages)
| creates a new graphic object on the given layer. More...
OFCondition | removeGraphicObject (size_t layer, size_t idx)
| deletes the graphic object with the given index on the given layer. More...
OFCondition | moveGraphicObject (size_t old_layer, size_t idx, size_t new_layer, DVPSObjectApplicability applicability=DVPSB_allImages)
| moves the graphic object with the given index on the given layer to a different layer. More...
DVPSCurve * | getCurve (size_t layer, size_t idx)
| gets the curve with the given index on the given layer. More...
size_t | getNumberOfCurvesInImage ()
| returns the number of curves in the attached image that could be activated in the presentation state. More...
DVPSCurve * | getCurveInImage (size_t idx)
| gets the curve with the given index from the attached image. More...
OFCondition | addCurve (size_t layer, size_t curveidxinimage)
| activates curve in presentation state. More...
const char * | getActiveOverlayLabel (size_t layer, size_t idx)
| gets the overlay label of the given activated overlay. More...
const char * | getActiveOverlayDescription (size_t layer, size_t idx)
| gets the overlay description of the given activated overlay. More...
OFBool | activeOverlayIsROI (size_t layer, size_t idx)
| checks whether the given activated overlay is a ROI (region of interest) overlay. More...
OFCondition | getOverlayData (size_t layer, size_t idx, const void *&overlayData, unsigned int &width, unsigned int &height, unsigned int &left_pos, unsigned int &top_pos, OFBool &isROI, Uint16 &fore, unsigned int bits=8)
| gets one overlay bitmap. More...
size_t | getNumberOfOverlaysInImage ()
| gets the number of overlays which are embedded in the image currently attached to the presentation state. More...
Uint16 | getOverlayInImageGroup (size_t idx)
| gets the repeating group number of the given overlay in the attached image. More...
const char * | getOverlayInImageLabel (size_t idx)
| gets the overlay label of the given overlay in the attached image. More...
const char * | getOverlayInImageDescription (size_t idx)
| gets the overlay description of the given overlay in the attached image. More...
size_t | getOverlayInImageActivationLayer (size_t idx)
| gets the index of the activation layer on which the given overlay from the attached image is activated. More...
OFBool | overlayInImageIsROI (size_t idx)
| checks whether the given overlay in the attached image is a ROI (region of interest) overlay. More...
OFCondition | removeOverlayFromPresentationState (size_t idx)
| removes an overlay from the presentation state. More...
OFCondition | changeOverlayGroupInPresentationState (size_t idx, Uint16 newGroup=0)
| changes the repeating group used for an overlay in the presentation state. More...
OFCondition | addOverlayToPresentationState (DcmItem &overlayIOD, Uint16 groupInItem, Uint16 newGroup=0)
| adds a new overlay bitmap to the presentation state. More...
OFBool | overlayIsSuitableAsBitmapShutter (size_t idx)
| checks if an overlay from the presentation state is suitable for use as a bitmap shutter. More...
OFCondition | activateOverlayInImage (size_t layer, size_t idx)
| activates the given overlay from the attached image on the given graphic layer. More...
OFCondition | activateOverlayInPresentationState (size_t layer, size_t idx)
| activates the given overlay from the presentation state on the given graphic layer. More...
OFCondition | activateOverlayAsBitmapShutter (size_t idx)
| activates an overlay as bitmap shutter. More...
OFCondition | deactivateOverlay (size_t layer, size_t idx)
| removes activation for an overlay which may be embedded in the attached image or part of the presentation state. More...
OFCondition | attachImage (DcmDataset *dataset, OFBool transferOwnership)
| attaches an image to the presentation state. More...
OFCondition | attachImage (DcmFileFormat *fileformat, OFBool transferOwnership)
| attaches an image to the presentation state. More...
void | detachImage ()
| detaches and frees the image (incl. More...
OFBool | isInverse ()
| checks whether image is inverse (shape, plut or mono1). More...
OFCondition | invertImage ()
| inverts image by changing presentation state LUT or presentation state LUT shape. More...
OFCondition | getPixelData (const void *&pixelData, unsigned long &width, unsigned long &height)
| applies presentation state to attached image and returns image bitmap. More...
OFCondition | getPixelData (void *pixelData, unsigned long size)
| same as method above apart from the fact that the storage area is handled externally. More...
const char * | getAttachedImageSOPClassUID ()
| returns the SOP Class UID of the currently attached image. More...
const char * | getAttachedImageSOPInstanceUID ()
| returns the SOP Instance UID of the currently attached image. More...
OFCondition | getImageWidth (unsigned long &width)
| gets the width of the attached image. More...
OFCondition | getImageHeight (unsigned long &height)
| gets the height of the attached image. More...
unsigned long | getPrintBitmapSize ()
| gets number of bytes used for the print bitmap. More...
OFCondition | setMinimumPrintBitmapWidthHeight (unsigned long width, unsigned long height)
| sets the minimum print bitmap width and height. More...
OFCondition | setMaximumPrintBitmapWidthHeight (unsigned long width, unsigned long height)
| sets the maximum print bitmap width and height. More...
OFCondition | getPrintBitmapWidthHeight (unsigned long &width, unsigned long &height)
| gets width and height of print bitmap. More...
OFCondition | getPrintBitmapWidth (unsigned long &width)
| gets width of print bitmap. More...
OFCondition | getPrintBitmapHeight (unsigned long &height)
| gets height of print bitmap. More...
double | getPrintBitmapPixelAspectRatio ()
| gets the presentation pixel aspect ratio for the print bitmap. More...
OFCondition | getPrintBitmapRequestedImageSize (OFString &requestedImageSize)
| gets requested image size for print bitmap. More...
OFCondition | getPrintBitmap (void *bitmap, unsigned long size, OFBool inversePLUT=OFFalse)
| writes the bitmap data into the given buffer. More...
OFCondition | createPreviewImage (unsigned long maxWidth, unsigned long maxHeight, OFBool clipMode=OFFalse)
| creates a new preview image based on the current image and pstate. More...
void | deletePreviewImage ()
| deletes and disables the current preview image.
unsigned long | getPreviewImageSize ()
| gets number of bytes used for the preview image bitmap. More...
OFCondition | getPreviewImageWidthHeight (unsigned long &width, unsigned long &height)
| gets current width and height of the preview image. More...
OFCondition | getPreviewImageWidth (unsigned long &width)
| gets current width of the preview image. More...
OFCondition | getPreviewImageHeight (unsigned long &height)
| gets current height of the preview image. More...
OFCondition | getPreviewImageBitmap (void *bitmap, unsigned long size)
| writes the bitmap data of the preview image into the given buffer. More...
OFCondition | getImageMinMaxPixelRange (double &minValue, double &maxValue)
| gets smallest and biggest possible pixel value in the attached image. More...
OFCondition | getImageMinMaxPixelValue (double &minValue, double &maxValue)
| gets smallest and biggest occurring pixel value in the attached image. More...
OFCondition | getImageNumberOfFrames (unsigned long &frames)
| gets the number of frames of the current (attached) image. More...
OFCondition | selectImageFrameNumber (unsigned long frame)
| selects one frame of a multiframe image. More...
unsigned long | getSelectedImageFrameNumber ()
| gets the index of the currently selected frame in a multi-frame image. More...
DVPSDisplayTransform | getDisplayTransform ()
| gets the currently selected display transform. More...
void | setDisplayTransform (DVPSDisplayTransform transform)
| activates or deactivates display correction. More...
Uint16 | convertPValueToDDL (Uint16 pvalue, unsigned int bits=8)
| converts a 16-bit P-Value to an 8-bit DDL value for on-sceen display. More...
OFCondition | writeHardcopyImageAttributes (DcmItem &dset)
| writes the patient module attributes and a source image sequence for a grayscale hardcopy image. More...
const char * | getCurrentImageModality ()
| gets the modality of the attached image. More...
Uint16 | findOverlayGroup (Uint16 currentGroup=0)
| tries to find an overlay repeating group that is not used in the presentation state or the attached image. More...
void | renderPixelData (OFBool display=OFTrue)
| prepares pixel data for image and overlays for access. More...
DVPSDisplayedArea * | getDisplayedAreaSelection ()
| attempts to find the displayed area selection for the current image and frame. More...
DVPSSoftcopyVOI * | getCurrentSoftcopyVOI ()
| attempts to find the Softcopy VOI LUT item for the current image and frame. More...
Public Member Functions inherited from DcmPresentationState
| DcmPresentationState ()
| default constructor
virtual | ~DcmPresentationState ()
| destructor
OFCondition | read (DcmItem &dset)
| reads a presentation state from a DICOM dataset. More...
OFCondition | write (DcmItem &dset, OFBool replaceSOPInstanceUID)
| writes the presentation state managed by this object to a DICOM dataset. More...
const char * | createInstanceUID ()
| generates a new SOP Instance UID for the Presentation State. More...
const char * | getInstanceUID ()
| returns the current SOP Instance UID for the Presentation State. More...
const char * | getSOPClassUID ()
| returns the (currently hard-coded) SOP Class UID of the Presentation State. More...
const char * | getPatientID ()
| returns the patient ID of the presentation state
const char * | getStudyUID ()
| returns the Study Instance UID of the presentation state. More...
OFCondition | addImageReference (const char *studyUID, const char *seriesUID, const char *sopclassUID, const char *instanceUID, const char *frames=NULL, const char *aetitle=NULL, const char *filesetID=NULL, const char *filesetUID=NULL)
| adds a reference to an image to this presentation state. More...
OFCondition | addImageReference (DcmItem &dset, const char *aetitle=NULL, const char *filesetID=NULL, const char *filesetUID=NULL)
| adds a reference to an image to this presentation state. More...
OFCondition | removeImageReference (const char *studyUID, const char *seriesUID, const char *instanceUID)
| removes a reference to an image from this presentation state. More...
OFCondition | removeImageReference (DcmItem &dset)
| removes a reference to an image from this presentation state. More...
size_t | numberOfImageReferences ()
| gets the number of image references in all series managed by this list. More...
OFCondition | getImageReference (size_t idx, OFString &studyUID, OFString &seriesUID, OFString &sopclassUID, OFString &instanceUID, OFString &frames, OFString &aetitle, OFString &filesetID, OFString &filesetUID)
| gets an image reference with the given index. More...
void | clear ()
| resets the object to initial state. More...
OFCondition | createFromImage (DcmItem &dset, DVPSoverlayActivation overlayActivation=DVPSO_copyOverlays, DVPSVOIActivation voiActivation=DVPSV_preferVOILUT, OFBool curveActivation=OFTrue, OFBool shutterActivation=OFTrue, OFBool presentationActivation=OFTrue, DVPSGraphicLayering layering=DVPSG_twoLayers, const char *aetitle=NULL, const char *filesetID=NULL, const char *filesetUID=NULL)
| creates a default presentation state for a DICOM image. More...
DVPSPresentationLUTType | getPresentationLUT ()
| gets the current Presentation LUT type. More...
OFBool | havePresentationLookupTable ()
| checks if a real Presentation LUT (not shape) is available in the presentation state. More...
const char * | getCurrentPresentationLUTExplanation ()
| gets a description of the current presentation LUT. More...
const char * | getPresentationLUTExplanation ()
| returns the LUT explanation of the presentation LUT if it exists and is non-empty. More...
DVPSPresentationLUT * | getPresentationLUTData ()
| gets the current Presentation LUT object. More...
DVPSRotationType | getRotation ()
| gets the current rotation status of the presentation state. More...
OFBool | getFlip ()
| gets the current horizontal flip status of the presentation state. More...
OFCondition | setRotation (DVPSRotationType rotation)
| sets rotation status of the presentation state. More...
OFCondition | setFlip (OFBool isFlipped)
| sets horizontal flip status of the presentation state. More...
OFBool | haveShutter (DVPSShutterType type)
| checks if a display shutter of given type is active. More...
Sint32 | getRectShutterLV ()
| gets rectangular shutter left vertical edge. More...
Sint32 | getRectShutterRV ()
| gets rectangular shutter right vertical edge. More...
Sint32 | getRectShutterUH ()
| gets rectangular shutter upper horitontal edge. More...
Sint32 | getRectShutterLH ()
| gets rectangular shutter lower horizontal edge. More...
Sint32 | getCenterOfCircularShutter_x ()
| gets circular shutter center x component. More...
Sint32 | getCenterOfCircularShutter_y ()
| gets circular shutter center y component. More...
Sint32 | getRadiusOfCircularShutter ()
| gets circular shutter radius. More...
size_t | getNumberOfPolyShutterVertices ()
| gets polygonal shutter number of points. More...
OFCondition | getPolyShutterVertex (size_t idx, Sint32 &x, Sint32 &y)
| get polygonal shutter point. More...
OFCondition | setPolyShutterOrigin (Sint32 x, Sint32 y)
| sets polygonal display shutter origin. More...
Uint16 | getShutterPresentationValue ()
| gets the shutter presentation value. More...
OFCondition | setShutterPresentationValue (Uint16 pvalue)
| sets the shutter presentation value to the given P-value. More...
const char * | getPresentationLabel ()
| returns a label for the presentation state. More...
const char * | getPresentationDescription ()
| returns a description for the presentation state. More...
const char * | getPresentationCreatorsName ()
| returns the creator's name for the presentation state. More...
OFCondition | setPresentationLabel (const char *label)
| sets the presentation state label. More...
OFCondition | setPresentationDescription (const char *descr)
| sets the presentation state description. More...
OFCondition | setPresentationCreatorsName (const char *name)
| sets the presentation state creator's name. More...
OFCondition | setCharset (DVPScharacterSet charset)
| sets the specific character set for this presentation state. More...
DVPScharacterSet | getCharset ()
| gets the specific character set for this presentation state. More...
const char * | getCharsetString ()
| gets the specific character set string for this presentation state. More...
void | sortGraphicLayers ()
| sorts the graphic layers according to the graphic layer order. More...
size_t | getNumberOfGraphicLayers ()
| returns the number of graphic layers. More...
const char * | getGraphicLayerName (size_t idx)
| gets the unique name of the graphic layer with the given index. More...
size_t | getGraphicLayerIndex (const char *name)
| gets the index of the graphic layer with the given unique name. More...
const char * | getGraphicLayerDescription (size_t idx)
| gets a description string for the graphic layer with the given index. More...
OFBool | haveGraphicLayerRecommendedDisplayValue (size_t idx)
| checks whether a recommended display value (grayscale, color or both) for the given graphic layer exists. More...
OFCondition | getGraphicLayerRecommendedDisplayValueGray (size_t idx, Uint16 &gray)
| gets the recommended grayscale display value for the given graphic layer. More...
OFCondition | getGraphicLayerRecommendedDisplayValueRGB (size_t idx, Uint16 &r, Uint16 &g, Uint16 &b)
| gets the recommended RGB display value for the given graphic layer. More...
OFCondition | setGraphicLayerRecommendedDisplayValueGray (size_t idx, Uint16 gray)
| set graphic layer recommended grayscale display value for the given graphic layer. More...
OFCondition | setGraphicLayerRecommendedDisplayValueRGB (size_t idx, Uint16 r, Uint16 g, Uint16 b)
| set graphic layer recommended RGB display value for the given graphic layer. More...
void | removeGraphicLayerRecommendedDisplayValue (size_t idx, OFBool rgb, OFBool monochrome)
| removes recommended display values for the given graphic layer. More...
OFCondition | setGraphicLayerName (size_t idx, const char *name)
| assigns a new unique name to the given graphic layer. More...
OFCondition | setGraphicLayerDescription (size_t idx, const char *descr)
| sets a new description to the given graphic layer. More...
OFCondition | toFrontGraphicLayer (size_t idx)
| makes a graphic layer the highest layer for display. More...
OFCondition | toBackGraphicLayer (size_t idx)
| makes a graphic layer the lowest layer for display. More...
OFCondition | exchangeGraphicLayers (size_t idx1, size_t idx2)
| exchanges the layer order of the two graphic layers with the given indices. More...
OFCondition | addGraphicLayer (const char *gLayer, const char *gLayerDescription=NULL)
| creates a new graphic layer with the given name and optional description. More...
size_t | getNumberOfCurves (size_t layer)
| returns the number of curve activations for the given graphic layer. More...
OFCondition | removeCurve (size_t layer, size_t idx)
| deletes the curve activation with the given index on the given layer. More...
OFCondition | moveCurve (size_t old_layer, size_t idx, size_t new_layer)
| moves the curve activation with the given index on the given layer to a different layer. More...
size_t | getNumberOfActiveOverlays (size_t layer)
| gets the number of overlays that are currently activated on the given graphic layer. More...
Uint16 | getActiveOverlayGroup (size_t layer, size_t idx)
| gets the repeating group number of the given activated overlay. More...
size_t | getNumberOfOverlaysInPresentationState ()
| gets the number of overlays which are embedded in the presentation state. More...
Uint16 | getOverlayInPresentationStateGroup (size_t idx)
| gets the repeating group number of the given overlay in the presentation state. More...
const char * | getOverlayInPresentationStateLabel (size_t idx)
| gets the overlay label of the given overlay in the presentation state. More...
const char * | getOverlayInPresentationStateDescription (size_t idx)
| gets the overlay description of the given overlay in the presentation state. More...
size_t | getOverlayInPresentationStateActivationLayer (size_t idx)
| gets the index of the activation layer on which the given overlay from the presentation state is activated. More...
OFBool | overlayIsBitmapShutter (size_t idx)
| checks if the given overlay in the presentation state is currently activated as a bitmap shutter. More...
OFBool | overlayInPresentationStateIsROI (size_t idx)
| checks whether the given overlay in the presentation state is a ROI (region of interest) overlay. More...
OFCondition | moveOverlay (size_t old_layer, size_t idx, size_t new_layer)
| moves the overlay activation with the given index on the given layer to a different layer. More...

## Private Member Functions
| DVPresentationState (const DVPresentationState &other)
| private undefined copy constructor
DVPresentationState & | operator= (const DVPresentationState &other)
| private undefined assignment operator

## Static Private Member Functions
static OFCondition | activateOverlayHelper (DVPSOverlay &ovl, DicomImage &image, OFBool asShutter=OFFalse, Uint16 pvalue=0)
| helper method that activates the given overlay in the given image More...

## Private Attributes
DcmDataset * | currentImageDataset
| a pointer to the DICOM dataset comprising the image to which the presentation state is currently applied
DcmFileFormat * | currentImageFileformat
| a pointer to the fileformat (if it exists) of the DICOM dataset comprising the image to which the presentation state is currently applied
DicomImage * | currentImage
| a pointer to the dcmimage representation of the image to which the presentation state is currently applied
DicomImage * | previewImage
| a pointer to the dcmimage representation of the (smaller) preview image to which the presentation state is currently applied
unsigned long | currentImageWidth
| contains the width of the attached image without consideration of rotation.
unsigned long | currentImageHeight
| contains the height of the attached image without consideration of rotation.
unsigned long | renderedImageWidth
| contains the width of the attached image after pixel data have been rendered (w/o clipping).
unsigned long | renderedImageHeight
| contains the height of the attached image after pixel data have been rendered (w/o clipping).
signed long | renderedImageTop
| contains the top hand corner of the attached image after pixel data have been rendered.
signed long | renderedImageLeft
| contains the left hand corner of the attached image after pixel data have been rendered. More...
signed long | renderedImageBottom
| contains the bottom hand corner of the attached image after pixel data have been rendered. More...
signed long | renderedImageRight
| contains the right hand corner of the attached image after pixel data have been rendered.
char * | currentImageSOPClassUID
| contains the SOP Class UID of the attached image
char * | currentImageSOPInstanceUID
| contains the SOP Instance UID of the attached image
unsigned long | currentImageSelectedFrame
| contains the current selected frame number of the attached image. More...
OFBool | currentImageOwned
| a flag describing whether the presentation state is owner of the DICOM dataset in currentImageDataset/currentImageFileformat. More...
OFBool | currentImageVOIValid
| a flag describing whether the VOI settings in currentImage match the ones in the presentation state.
OFBool | currentImagePLUTValid
| a flag describing whether the presentation LUT settings in currentImage match the ones in the presentation state.
OFBool | currentImageFlip
| a flag describing whether currentImage has been flipped
DVPSRotationType | currentImageRotation
| a flag describing the current rotation angle of currentImage
int | currentImageOverlaysValid
| a flag describing whether the Overlay settings in currentImage match the ones in the presentation state. More...
DVPSCurve_PList | currentImageCurveList
| list of curves of the currently attached image
DVPSVOILUT_PList | currentImageVOILUTList
| list of VOI LUTs of the currently attached image
DVPSVOIWindow_PList | currentImageVOIWindowList
| list of VOI Windows of the currently attached image
DcmCodeString | currentImageModality
| modality of currently attached image (if any)
OFBool | currentImageMonochrome1
| true if attached image is MONOCHROME1
DVPSDisplayTransform | displayTransform
| flag indicating the currently selected display transform DVPSD_none if switched off
OFBool | imageInverse
| a flag describing whether current image is inverse
DiDisplayFunction ** | displayFunction
| reference to list of display functions if existing
unsigned long | minimumPrintBitmapWidth
| minimum width of print bitmap (used for implicit scaling)
unsigned long | minimumPrintBitmapHeight
| minimum height of print bitmap (used for implicit scaling)
unsigned long | maximumPrintBitmapWidth
| maximum width of print bitmap (used for implicit scaling)
unsigned long | maximumPrintBitmapHeight
| maximum height of print bitmap (used for implicit scaling)
unsigned long | maximumPreviewImageWidth
| maximum width of (optional) preview image
unsigned long | maximumPreviewImageHeight
| maximum height of (optional) preview image

## Additional Inherited Members
Protected Member Functions inherited from DcmPresentationState
OFCondition | createDefaultDisplayedArea (DcmItem &dset)
| creates a default displayed area selection for the given dataset. More...
Protected Attributes inherited from DcmPresentationState
DcmPersonName | patientName
| Module=Patient, VR=PN, VM=1, Type 1.
DcmLongString | patientID
| Module=Patient, VR=LO, VM=1, Type 2.
DcmDate | patientBirthDate
| Module=Patient, VR=DA, VM=1, Type 2.
DcmCodeString | patientSex
| Module=Patient, VR=CS, VM=1, Type 2.
DcmUniqueIdentifier | studyInstanceUID
| Module=General_Study, VR=UI, VM=1, Type 1.
DcmDate | studyDate
| Module=General_Study, VR=DA, VM=1, Type 2.
DcmTime | studyTime
| Module=General_Study, VR=TM, VM=1, Type 2.
DcmPersonName | referringPhysicianName
| Module=General_Study, VR=PN, VM=1, Type 2.
DcmShortString | studyID
| Module=General_Study, VR=SH, VM=1, Type 2.
DcmShortString | accessionNumber
| Module=General_Study, VR=SH, VM=1, Type 2.
DcmUniqueIdentifier | seriesInstanceUID
| Module=General_Series, VR=UI, VM=1, Type 1.
DcmIntegerString | seriesNumber
| Module=General_Series, VR=IS, VM=1, Type 2.
DcmLongString | manufacturer
| Module=General_Equipment, VR=LO, VM=1, Type 2.
DVPSDisplayedArea_PList | displayedAreaSelectionList
| Module=Displayed_Area, VR=SQ, Card=1-n, Type 1.
DVPSPresentationLUT | presentationLUT
| Module=Softcopy_Presentation_LUT, VR=SQ, Card=1, Type 1C.
DcmIntegerString | imageNumber
| Module=Presentation_State, VR=IS, VM=1, Type 1.
DcmCodeString | presentationLabel
| Module=Presentation_State, VR=CS, VM=1, Type 1.
DcmLongString | presentationDescription
| Module=Presentation_State, VR=LO, VM=1, Type 2.
DcmDate | presentationCreationDate
| Module=Presentation_State, VR=DA, VM=1, Type 1.
DcmTime | presentationCreationTime
| Module=Presentation_State, VR=TM, VM=1, Type 1.
DcmPersonName | presentationCreatorsName
| Module=Presentation_State, VR=PN, VM=1, Type 2.
DVPSReferencedSeries_PList | referencedSeriesList
| ReferencedSeriesSequence, Module=Presentation_State.
DcmUniqueIdentifier | sOPInstanceUID
| Module=SOP_Common, VR=UI, VM=1, Type 1.
DcmCodeString | specificCharacterSet
| Module=SOP_Common, VR=CS, VM=1-n, Type 1C.
DcmDate | instanceCreationDate
| Module=SOP_Common, VR=DA, VM=1, Type 3.
DcmTime | instanceCreationTime
| Module=SOP_Common, VR=TM, VM=1, Type 3.
DcmUniqueIdentifier | instanceCreatorUID
| Module=SOP_Common, VR=UI, VM=1, Type 3.
OFBool | useShutterRectangular
| if true, a rectangular shutter is in use
OFBool | useShutterCircular
| if true, a circular shutter is in use
OFBool | useShutterPolygonal
| if true, a polygonal shutter is in use
OFBool | useShutterBitmap
| if true, a bitmap shutter is in use
DcmCodeString | shutterShape
| Module=Display_Shutter, VM=CS, VR=1-3, Type 1.
DcmIntegerString | shutterLeftVerticalEdge
| Module=Display_Shutter, VR=IS, VM=1, Type 1C.
DcmIntegerString | shutterRightVerticalEdge
| Module=Display_Shutter, VR=IS, VM=1, Type 1C.
DcmIntegerString | shutterUpperHorizontalEdge
| Module=Display_Shutter, VR=IS, VM=1, Type 1C.
DcmIntegerString | shutterLowerHorizontalEdge
| Module=Display_Shutter, VR=IS, VM=1, Type 1C.
DcmIntegerString | centerOfCircularShutter
| Module=Display_Shutter, VR=IS, VM=2, Type 1C.
DcmIntegerString | radiusOfCircularShutter
| Module=Display_Shutter, VR=IS, VM=1, Type 1C.
DcmIntegerString | verticesOfThePolygonalShutter
| Module=Display_Shutter, VR=IS, VM=2-2n, Type 1C.
DcmUnsignedShort | shutterPresentationValue
| Module=Display_Shutter, VR=US, VM=1, Type 3 (1c in other modules)
DcmUnsignedShort | shutterOverlayGroup
| Module=Bitmap_Display_Shutter, VR=US, VM=1, Type 1.
DVPSOverlay_PList | overlayList
| Overlay(s), Module=Overlay_Plane.
DVPSOverlayCurveActivationLayer_PList | activationLayerList
| Overlay/Curve Activation Layer(s), Module=Overlay_Activation/Curve_Activation.
DVPSGraphicAnnotation_PList | graphicAnnotationList
| GraphicAnnotationSequence, Module=Graphic_Annotation.
DcmUnsignedShort | imageRotation
| Module=Spatial_Transform, VR=US, VM=1, Type 1.
DcmCodeString | imageHorizontalFlip
| Module=Spatial_Transform, VR=CS, VM=1, Type 1.
DVPSGraphicLayer_PList | graphicLayerList
| GraphicLayerSequence, Module=Graphic_Layer.
OFBool | useModalityRescale
| if true, a modality rescale slope/intercept is set
OFBool | useModalityLUT
| if true, a modality LUT is set
DcmUnsignedShort | modalityLUTDescriptor
| Module=Modality_LUT, VR=xs, VM=3, Type 1c.
DcmLongString | modalityLUTExplanation
| Module=Modality_LUT, VR=LO, VM=1, Type 3.
DcmLongString | modalityLUTType
| Module=Modality_LUT, VR=LO, VM=1, Type 3.
DcmUnsignedShort | modalityLUTData
| Module=Modality_LUT, VR=xs, VM=1-n, Type 1c.
DcmDecimalString | rescaleIntercept
| Module=Modality_LUT, VR=DS, VM=1, Type 1c.
DcmDecimalString | rescaleSlope
| Module=Modality_LUT, VR=DS, VM=1, Type 1c.
DcmLongString | rescaleType
| Module=Modality_LUT, VR=LO, VM=1, Type 1c.
DVPSSoftcopyVOI_PList | softcopyVOIList
| Module=Softcopy_VOI_LUT, VR=SQ, Card=1-n, Type 1.

## Detailed Description

a Grayscale Softcopy Presentation State.

This class manages the data structures comprising a Presentation State object. Presentation states can be created, read, written, and modified.

## Constructor & Destructor Documentation

## ◆ DVPresentationState()

DVPresentationState::DVPresentationState | ( | DiDisplayFunction ** | dispFunction = `NULL`,
|  | unsigned long | minPrintBitmapX = `0`,
|  | unsigned long | minPrintBitmapY = `0`,
|  | unsigned long | maxPrintBitmapX = `0`,
|  | unsigned long | maxPrintBitmapY = `0`,
|  | unsigned long | maxPreviewImageX = `0`,
|  | unsigned long | maxPreviewImageY = `0`
| ) |  |

default constructor

Parameters

  dispFunction | list of objects describing the display characteristics of the monitor. Used to implement the standard display function. The parameter should be an array with DVPSD_max entries (see DVInterface). If absent, no display transform is performed.
  minPrintBitmapX | default value for minimum print bitmap size X
  minPrintBitmapY | default value for minimum print bitmap size Y
  maxPrintBitmapX | default value for maximum print bitmap size X
  maxPrintBitmapY | default value for maximum print bitmap size Y
  maxPreviewImageX | default value for maximum preview image size X
  maxPreviewImageY | default value for maximum preview image size Y

## Member Function Documentation

## ◆ activateOverlayAsBitmapShutter()

OFCondition DVPresentationState::activateOverlayAsBitmapShutter | ( | size_t | idx | ) |

activates an overlay as bitmap shutter.

The overlay must not be activated on a graphic layer (i.e. getOverlayInPresentationStateActivationLayer(idx) != DVPS_IDX_NONE, otherwise this method fails.

Parameters

  idx | index of the overlay, must be < getNumberOfOverlaysInPresentationState().

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ activateOverlayHelper()

static OFCondition DVPresentationState::activateOverlayHelper | ( | DVPSOverlay & | ovl,
|  | DicomImage & | image,
|  | OFBool | asShutter = `OFFalse`,
|  | Uint16 | pvalue = `0`
| ) |  |
| static private

helper method that activates the given overlay in the given image

Parameters

  ovl | overlay to activate
  image | image to be rendered
  asShutter | true if overlay should be used as bitmap shutter
  pvalue | pvalue for overlay foreground

Returns
  EC_Normal if successful, an error code otherwise

## ◆ activateOverlayInImage()

OFCondition DVPresentationState::activateOverlayInImage | ( | size_t | layer,
|  | size_t | idx
| ) |  |

activates the given overlay from the attached image on the given graphic layer.

If the overlay is already activated (i.e. getOverlayInImageActivationLayer(idx) != DVPS_IDX_NONE) this method fails.

Parameters

  layer | index of the graphic layer, must be < getNumberOfGraphicLayers()
  idx | index of the overlay, must be < getNumberOfOverlaysInImage().

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ activateOverlayInPresentationState()

OFCondition DVPresentationState::activateOverlayInPresentationState | ( | size_t | layer,
|  | size_t | idx
| ) |  |

activates the given overlay from the presentation state on the given graphic layer.

If the overlay is already activated or used as a bitmap overlay (i.e. getOverlayInPresentationStateActivationLayer(idx) != DVPS_IDX_NONE or overlayIsBitmapShutter(idx) == OFTrue) this method fails.

Parameters

  layer | index of the graphic layer, must be < getNumberOfGraphicLayers()
  idx | index of the overlay, must be < getNumberOfOverlaysInPresentationState().

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ activeOverlayIsROI()

OFBool DVPresentationState::activeOverlayIsROI | ( | size_t | layer,
|  | size_t | idx
| ) |  |

checks whether the given activated overlay is a ROI (region of interest) overlay.

Parameters

  layer | index of the graphic layer, must be < getNumberOfGraphicLayers()
  idx | index of the overlay, must be < getNumberOfActiveOverlays().

Returns
  OFTrue if overlay exists and is ROI, OFFalse otherwise.

## ◆ addCurve()

OFCondition DVPresentationState::addCurve | ( | size_t | layer,
|  | size_t | curveidxinimage
| ) |  |

activates curve in presentation state.

This method adds an activation for the given curve from the attached image to the given graphic layer in the presentation state.

Parameters

  layer | index of the graphic layer, must be < getNumberOfGraphicLayers()
  curveidxinimage | index of the curve in the attached image, must be < getNumberOfCurvesInImage()

Returns
  EC_Normal upon success, an error code otherwise

## ◆ addGraphicObject()

DVPSGraphicObject* DVPresentationState::addGraphicObject | ( | size_t | layer,
|  | DVPSObjectApplicability | applicability = `DVPSB_allImages`
| ) |  |

creates a new graphic object on the given layer.

Returns a pointer to the new graphic object. If the creation of the graphic object fails or if the graphic layer does not exist, NULL is returned.

Parameters

  layer | index of the graphic layer, must be < getNumberOfGraphicLayers()
  applicability | defines to which images/frames the new object applies. Default: all images referenced by the presentation state.

Returns
  a pointer to the new graphic object

## ◆ addImageReferenceAttached()

OFCondition DVPresentationState::addImageReferenceAttached | ( | const char * | aetitle = `NULL`,
|  | const char * | filesetID = `NULL`,
|  | const char * | filesetUID = `NULL`
| ) |  |

adds a reference to the currently attached image to this presentation state.

This method checks if the given image is not yet referenced and if its Study UID and SOP class match for this presentation state and returns an error code otherwise.

Parameters

  aetitle | the series retrieveAETitle. Must be a valid DICOM 'AE' value. Default: value absent.
  filesetID | the series storageMediaFileSetID. Must be a valid DICOM 'SH' value. Default: value absent.
  filesetUID | the series storageMediaFileSetUID. Must be a valid DICOM UID. Default: value absent.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ addOverlayToPresentationState()

OFCondition DVPresentationState::addOverlayToPresentationState | ( | DcmItem & | overlayIOD,
|  | Uint16 | groupInItem,
|  | Uint16 | newGroup = `0`
| ) |  |

adds a new overlay bitmap to the presentation state.

The overlay is read from a DICOM dataset which must contain the attributes required for a graphic or ROI overlay, see class DVPSOverlay. The dataset can be an image or standalone overlay IOD. The overlay data is copied into the presentation state, i.e. the DICOM dataset can be deleted after execution of this method.

Parameters

  overlayIOD | the DICOM dataset from which the overlay is to be read
  groupInItem | the repeating group 0x6000..0x61F (even) of the overlay to be read
  newGroup | repeating group number 0x6000-0x601F (even) to be used for the overlay in the presentation state. If this optional parameter is omitted, the method attempts to automatically determine a new group number so that no overlay in the attached image is shadowed any more. If this is impossible, a group number so far unused in the presentation state is taken.

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ addPolyShutterVertex()

OFCondition DVPresentationState::addPolyShutterVertex | ( | Sint32 | x,
|  | Sint32 | y
| ) |  |

sets polygonal display shutter point.

This method adds a point to the polygonal display shutter, which must already have at least an origin. If the point set with this method is identical to the origin of the shutter, the shutter is activated and a possible bitmap shutter is deactivated. If no shutter display value exists, a default of 0 (black) is set.

Parameters

  x | the x component of the shutter origin
  y | the x component of the shutter origin

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ addTextObject()

DVPSTextObject* DVPresentationState::addTextObject | ( | size_t | layer,
|  | DVPSObjectApplicability | applicability = `DVPSB_allImages`
| ) |  |

creates a new text object on the given layer.

Returns a pointer to the new text object. If the creation of the text object fails or if the graphic layer does not exist, NULL is returned.

Parameters

  layer | index of the graphic layer, must be < getNumberOfGraphicLayers()
  applicability | defines to which images/frames the new object applies. Default: all images referenced by the presentation state.

Returns
  a pointer to the new text object

## ◆ attachImage() [1/2]

OFCondition DVPresentationState::attachImage | ( | DcmDataset * | dataset,
|  | OFBool | transferOwnership
| ) |  |

attaches an image to the presentation state.

If an image is already attached to the presentation state, the old image is detached (and freed if necessary) and the new image is attached. A preview image is created automatically (if values for preview resolution are valid).

Parameters

  dataset | pointer to the DICOM image as DcmDataset.
  transferOwnership | if true, the presentation state assumes ownership of the passed DcmDataset, which is freed when a different image is attached or the presentation state is deleted.

Returns
  EC_Normal if successful, an error code otherwise. If an error code is returned, the presentation state has the same state as before the call to this method.

## ◆ attachImage() [2/2]

OFCondition DVPresentationState::attachImage | ( | DcmFileFormat * | fileformat,
|  | OFBool | transferOwnership
| ) |  |

attaches an image to the presentation state.

If an image is already attached to the presentation state, the old image is detached (and freed if necessary) and the new image is attached. A preview image is created automatically (if values for preview resolution are valid).

Parameters

  fileformat | pointer to the DICOM image as DcmFileFormat.
  transferOwnership | if true, the presentation state assumes ownership of the passed DcmFileFormat, which is freed when a different image is attached or the presentation state is deleted.

Returns
  EC_Normal if successful, an error code otherwise. If an error code is returned, the presentation state has the same state as before the call to this method.

## ◆ canUseDisplayedAreaTrueSize()

OFBool DVPresentationState::canUseDisplayedAreaTrueSize | ( |  | ) |

checks if "TRUE SIZE" can be used as presentation size mode for the current image and frame (i.e.

pixel spacing is known).

Returns
  OFTrue if TRUE SIZE mode is available, OFFalse otherwise.

## ◆ changeOverlayGroupInPresentationState()

OFCondition DVPresentationState::changeOverlayGroupInPresentationState | ( | size_t | idx,
|  | Uint16 | newGroup = `0`
| ) |  |

changes the repeating group used for an overlay in the presentation state.

Since overlays in the presentation state can shadow overlays in the attached image, execution of this method may change the number of overlays reported in the attached image.

Parameters

  idx | index of the overlay, must be < getNumberOfOverlaysInPresentationState().
  newGroup | new repeating group number 0x6000-0x601F (even). If this optional parameter is omitted, the method attempts to automatically determine a new group number so that no overlay in the attached image is shadowed any more. If this is impossible, the method fails and leaves the overlay repeating group unchanged.

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ clear()

void DVPresentationState::clear | ( |  | ) |

resets the object to initial state.

After this call, the object is in the same state as after creation with the default constructor.

## ◆ convertPValueToDDL()

Uint16 DVPresentationState::convertPValueToDDL | ( | Uint16 | pvalue,
|  | unsigned int | bits = `8`
| ) |  |

converts a 16-bit P-Value to an 8-bit DDL value for on-sceen display.

If a display function is set and enabled (see setDisplayTransform()), the DDL is corrected for the nonlinearity of the display, otherwise a simple linear mapping is performed. For 12-bit DDL values (hardcopy) the display function is automatically disabled.

Parameters

  pvalue | P-Value 0..0xFFFF
  bits | number of bits used for the output DDL value (8 = softcopy, 12 = hardcopy)

Returns
  display driving level (DDL), 0..0xFF (8 bit) / 0..0xFFF (12 bit)

## ◆ createFromImage()

OFCondition DVPresentationState::createFromImage | ( | DcmItem & | dset,
|  | DVPSoverlayActivation | overlayActivation = `DVPSO_copyOverlays`,
|  | DVPSVOIActivation | voiActivation = `DVPSV_preferVOILUT`,
|  | OFBool | curveActivation = `OFTrue`,
|  | OFBool | shutterActivation = `OFTrue`,
|  | OFBool | presentationActivation = `OFTrue`,
|  | DVPSGraphicLayering | layering = `DVPSG_twoLayers`,
|  | const char * | aetitle = `NULL`,
|  | const char * | filesetID = `NULL`,
|  | const char * | filesetUID = `NULL`
| ) |  |

creates a default presentation state for a DICOM image.

A number of flags specify how curves, overlays, VOI transformations, a display shutter and a presentation LUT shape should be treated when found in the image IOD. If this method returns an error code, the object is in undefined state afterwards.

Parameters

  dset | the DICOM dataset containing the image IOD
  overlayActivation | flag defining how overlays should be handled (copied, activated or ignored). Default: Copy overlays.
  voiActivation | flag defining how VOI LUTs or VOI window width/center should be handled. Default: Use VOI and prefer VOI LUT from VOI window.
  curveActivation | flag defining whether curves in the image should be activated. Default: Activate curves.
  shutterActivation | flag defining whether a shutter (not bitmap shutter) should be copied to the presentation state when found in the image. Default: Copy shutter.
  presentationActivation | flag defining whether a presentation LUT shape should be copied to the presentation state when found in the image. Default: Copy presentation LUT shape.
  layering | flag defining how graphic layers should be created for activated overlays and curves. Default: Create one layer for all overlays and another layer for all curves.
  aetitle | the series retrieveAETitle. Must be a valid DICOM 'AE' value. Default: value absent.
  filesetID | the series storageMediaFileSetID. Must be a valid DICOM 'SH' value. Default: value absent.
  filesetUID | the series storageMediaFileSetUID. Must be a valid DICOM UID. Default: value absent.

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ createPreviewImage()

OFCondition DVPresentationState::createPreviewImage | ( | unsigned long | maxWidth,
|  | unsigned long | maxHeight,
|  | OFBool | clipMode = `OFFalse`
| ) |  |

creates a new preview image based on the current image and pstate.

The maximum size of this image is specified by the two parameters maxWidth and maxHeight. The actual size should be determined using one of the following appropriate methods (e.g. getPreviewImageWidthHeight) since the original pixel aspect ratio is alsways considered. The preview image includes all grayscale and spatial transformations performed on the current image so far. The method renderPixelData also renders the preview image (if existing). Therefore the preview image is always held consistent with the current image. Overlays, bitmapped shutters and any other annotations are not rendered into the preview image.

Parameters

  maxWidth | the maximum width used to create the preview image
  maxHeight | the maximum height used to create the preview image
  clipMode | specifies whether to clip the preview image to the displayed area (not implemented!)

Returns
  EC_Normal upon success, an error code otherwise

## ◆ deactivateOverlay()

OFCondition DVPresentationState::deactivateOverlay | ( | size_t | layer,
|  | size_t | idx
| ) |  |

removes activation for an overlay which may be embedded in the attached image or part of the presentation state.

Parameters

  layer | index of the graphic layer on which this overlay is activated, must be < getNumberOfGraphicLayers().
  idx | index of the overlay activation on the given layer, must be < getNumberOfActiveOverlays(layer).

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ deactivateVOI()

void DVPresentationState::deactivateVOI | ( | DVPSObjectApplicability | applicability = `DVPSB_currentImage` | ) |

deactivates the current VOI transformation.

The applicability of the deactivation is controlled by the applicability parameter. After a call to this method, no VOI transform is active for the current image and frame.

Parameters

  applicability | defines the applicability of the new VOI transform.

## ◆ detachImage()

void DVPresentationState::detachImage | ( |  | ) |

detaches and frees the image (incl.

preview) attached to the presentation state.

## ◆ findOverlayGroup()

Uint16 DVPresentationState::findOverlayGroup | ( | Uint16 | currentGroup = `0` | ) |

tries to find an overlay repeating group that is not used in the presentation state or the attached image.

If that does not exist, it returns a group number that is unused in the presentation state but used in the image.

Parameters

  currentGroup | the current group number of the overlay to be changed (if any)

Returns
  group number 0x6000..0x601F if found, 0 otherwise.

## ◆ getActiveOverlayDescription()

const char* DVPresentationState::getActiveOverlayDescription | ( | size_t | layer,
|  | size_t | idx
| ) |  |

gets the overlay description of the given activated overlay.

Parameters

  layer | index of the graphic layer, must be < getNumberOfGraphicLayers()
  idx | index of the overlay, must be < getNumberOfActiveOverlays().

Returns
  description string if it exists, NULL otherwise.

## ◆ getActiveOverlayLabel()

const char* DVPresentationState::getActiveOverlayLabel | ( | size_t | layer,
|  | size_t | idx
| ) |  |

gets the overlay label of the given activated overlay.

Parameters

  layer | index of the graphic layer, must be < getNumberOfGraphicLayers()
  idx | index of the overlay, must be < getNumberOfActiveOverlays().

Returns
  label string if it exists, NULL otherwise.

## ◆ getAttachedImageSOPClassUID()

const char* DVPresentationState::getAttachedImageSOPClassUID | ( |  | ) |

returns the SOP Class UID of the currently attached image.

Returns
  SOP class UID of current image, NULL if absent

## ◆ getAttachedImageSOPInstanceUID()

const char* DVPresentationState::getAttachedImageSOPInstanceUID | ( |  | ) |

returns the SOP Instance UID of the currently attached image.

Returns
  SOP instance UID of current image, NULL if absent

## ◆ getCurrentImageModality()

const char* DVPresentationState::getCurrentImageModality | ( |  | ) |

gets the modality of the attached image.

Returns
  modality string if it exists, NULL or empty string otherwise.

## ◆ getCurrentSoftcopyVOI()

DVPSSoftcopyVOI* DVPresentationState::getCurrentSoftcopyVOI | ( |  | ) |

attempts to find the Softcopy VOI LUT item for the current image and frame.

If not found, returns NULL.

Returns
  softcopy VOI LUT item for current image and frame if found, NULL otherwise

## ◆ getCurrentVOIDescription()

const char* DVPresentationState::getCurrentVOIDescription | ( |  | ) |

returns a description string for a currently active VOI transform.

If no description is available, NULL is returned.

Returns
  a pointer to a string or NULL.

## ◆ getCurrentWindowCenter()

OFCondition DVPresentationState::getCurrentWindowCenter | ( | double & | c | ) |

get the center of the current VOI window.

May only be called if haveActiveVOIWindow() is OFTrue.

Parameters

  c | the window center is returned in this parameter

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ getCurrentWindowWidth()

OFCondition DVPresentationState::getCurrentWindowWidth | ( | double & | w | ) |

gets the width of the current VOI window.

May only be called if haveActiveVOIWindow() is OFTrue.

Parameters

  w | the window width is returned in this parameter

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ getCurve()

DVPSCurve* DVPresentationState::getCurve | ( | size_t | layer,
|  | size_t | idx
| ) |  |

gets the curve with the given index on the given layer.

If the curve or the graphic layer does not exist, NULL is returned.

Parameters

  layer | index of the graphic layer, must be < getNumberOfGraphicLayers()
  idx | index of the curve, must be < getNumberOfCurves(layer)

Returns
  a pointer to the curve

## ◆ getCurveInImage()

DVPSCurve* DVPresentationState::getCurveInImage | ( | size_t | idx | ) |

gets the curve with the given index from the attached image.

If the curve does not exist, NULL is returned.

Parameters

  idx | index of the curve, must be < getNumberOfCurvesInImage()

Returns
  a pointer to the curve

## ◆ getDescriptionOfVOILUTsInImage()

const char* DVPresentationState::getDescriptionOfVOILUTsInImage | ( | size_t | idx | ) |

returns a description string for the given VOI LUT in the attached image.

If no description for the given index is available, NULL is returned.

Parameters

  idx | index, must be < getNumberOfVOILUTsInImage()

Returns
  a pointer to a string or NULL.

## ◆ getDescriptionOfVOIWindowsInImage()

const char* DVPresentationState::getDescriptionOfVOIWindowsInImage | ( | size_t | idx | ) |

returns a description string for the given VOI Window in the attached image.

If no description for the given index is available, NULL is returned.

Parameters

  idx | index, must be < getNumberOfVOIWindowsInImage()

Returns
  a pointer to a string or NULL.

## ◆ getDisplayedAreaPresentationPixelAspectRatio()

double DVPresentationState::getDisplayedAreaPresentationPixelAspectRatio | ( |  | ) |

gets the presentation pixel aspect ratio for for the current image and frame.

Pixel aspect ratio is defined here as the width of a pixel divided by the height of a pixel (x/y). This method may only be called when an image is attached to the presentation state.

Returns
  pixel aspect ratio

## ◆ getDisplayedAreaPresentationPixelMagnificationRatio()

OFCondition DVPresentationState::getDisplayedAreaPresentationPixelMagnificationRatio | ( | double & | magnification | ) |

gets the presentation pixel magnification ratio for the current image and frame if it is present.

Parameters

  magnification | the magnification ratio is returned in this parameter upon success

Returns
  EC_Normal if successful, an error code if no magnification ratio is available.

## ◆ getDisplayedAreaPresentationPixelSpacing()

OFCondition DVPresentationState::getDisplayedAreaPresentationPixelSpacing | ( | double & | x,
|  | double & | y
| ) |  |

gets the presentation pixel spacing for the current image and frame if it is known.

Parameters

  x | the horizontal pixel spacing (mm) is returned in this parameter upon success
  y | the vertical pixel spacing (mm) is returned in this parameter upon success

Returns
  EC_Normal if successful, an error code if no presentation pixel spacing is available.

## ◆ getDisplayedAreaPresentationSizeMode()

DVPSPresentationSizeMode DVPresentationState::getDisplayedAreaPresentationSizeMode | ( |  | ) |

gets the presentation size mode for the current image and frame.

This method may only be called when an image is attached to the presentation state.

Returns
  presentation size mode

## ◆ getDisplayedAreaSelection()

DVPSDisplayedArea* DVPresentationState::getDisplayedAreaSelection | ( |  | ) |

attempts to find the displayed area selection for the current image and frame.

If not found, creates a default.

Returns
  displayed area selection item. If creation of a default failed or no image is attached to the presentation state, returns NULL.

## ◆ getDisplayTransform()

DVPSDisplayTransform DVPresentationState::getDisplayTransform | ( |  | ) |
| inline

gets the currently selected display transform.

Display transform will only be performed if switched on and a valid monitor characteristics description exists. Default after creation of a presentation state is "on".

Returns
  current display transform if on, DVPSD_none if off.

## ◆ getGraphicObject()

DVPSGraphicObject* DVPresentationState::getGraphicObject | ( | size_t | layer,
|  | size_t | idx
| ) |  |

gets the graphic object with the given index on the given layer.

If the graphic object or the graphic layer does not exist, NULL is returned. Only the objects that are applicable to the current (attached) image and the selected frame number are used by this method.

Parameters

  layer | index of the graphic layer, must be < getNumberOfGraphicLayers()
  idx | index of the graphic object, must be < getNumberOfGraphicObjects(layer)

Returns
  a pointer to the graphic object

## ◆ getImageHeight()

OFCondition DVPresentationState::getImageHeight | ( | unsigned long & | height | ) |

gets the height of the attached image.

The rotation status of the presentation state is not taken into account, i.e. the height of an unrotated image is returned. This method may only be called when an image is attached to the presentation state.

Parameters

  height | upon success, the image height (pixels) is returned in this parameter.

Returns
  EC_Normal upon success, an error code otherwise

## ◆ getImageMinMaxPixelRange()

OFCondition DVPresentationState::getImageMinMaxPixelRange | ( | double & | minValue,
|  | double & | maxValue
| ) |  |

gets smallest and biggest possible pixel value in the attached image.

These values are defined as the smallest and biggest number that could possibly be contained in the image after application of the Modality transform, but before any VOI, Presentation or display transform. This method may only be called when an image is attached to the presentation state.

Parameters

  minValue | upon success, the smallest value is returned in this parameter.
  maxValue | upon success, the biggest value is returned in this parameter.

Returns
  EC_Normal upon success, an error code otherwise

## ◆ getImageMinMaxPixelValue()

OFCondition DVPresentationState::getImageMinMaxPixelValue | ( | double & | minValue,
|  | double & | maxValue
| ) |  |

gets smallest and biggest occurring pixel value in the attached image.

These values are defined as the smallest and biggest number that are actually contained in the image after application of the Modality transform, but before any VOI, Presentation or display transform. This method may only be called when an image is attached to the presentation state.

Parameters

  minValue | upon success, the smallest value is returned in this parameter.
  maxValue | upon success, the biggest value is returned in this parameter.

Returns
  EC_Normal upon success, an error code otherwise

## ◆ getImageNumberOfFrames()

OFCondition DVPresentationState::getImageNumberOfFrames | ( | unsigned long & | frames | ) |

gets the number of frames of the current (attached) image.

This method may only be called when an image is attached to the presentation state.

Parameters

  frames | upon success, the number of frames is returned in this parameter.

Returns
  EC_Normal upon success, an error code otherwise

## ◆ getImageRelativeDisplayedArea()

OFCondition DVPresentationState::getImageRelativeDisplayedArea | ( | Sint32 & | tlhcX,
|  | Sint32 & | tlhcY,
|  | Sint32 & | brhcX,
|  | Sint32 & | brhcY
| ) |  |

gets the displayed area top lefthand corner and bottom righthand corner for the current image and frame, as if the image was unrotated This method may only be called when an image is attached to the presentation state.

Parameters

  tlhcX | the displayed area top lefthand corner X value is returned in this parameter
  tlhcY | the displayed area top lefthand corner Y value is returned in this parameter
  brhcX | the displayed area bottom righthand corner X value is returned in this parameter
  brhcY | the displayed area bottom righthand corner Y value is returned in this parameter

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ getImageWidth()

OFCondition DVPresentationState::getImageWidth | ( | unsigned long & | width | ) |

gets the width of the attached image.

The rotation status of the presentation state is not taken into account, i.e. the width of an unrotated image is returned. This method may only be called when an image is attached to the presentation state.

Parameters

  width | upon success, the image width (pixels) is returned in this parameter.

Returns
  EC_Normal upon success, an error code otherwise

## ◆ getNumberOfCurvesInImage()

size_t DVPresentationState::getNumberOfCurvesInImage | ( |  | ) |

returns the number of curves in the attached image that could be activated in the presentation state.

Returns
  number of available curves

## ◆ getNumberOfGraphicObjects()

size_t DVPresentationState::getNumberOfGraphicObjects | ( | size_t | layer | ) |

returns the number of graphic objects for the given graphic layer.

Only the objects that are applicable to the current (attached) image and the selected frame number are used by this method.

Parameters

  layer | index of the graphic layer, must be < getNumberOfGraphicLayers()

Returns
  number of graphic objects

## ◆ getNumberOfOverlaysInImage()

size_t DVPresentationState::getNumberOfOverlaysInImage | ( |  | ) |

gets the number of overlays which are embedded in the image currently attached to the presentation state.

Overlays in the image are counted only if they are not shadowed by overlays that are embedded in the presentation state and use the same repeating group number.

Returns
  number of overlays in attached image

## ◆ getNumberOfTextObjects()

size_t DVPresentationState::getNumberOfTextObjects | ( | size_t | layer | ) |

returns the number of text objects for the given graphic layer.

Only the objects that are applicable to the current (attached) image and the selected frame number are used by this method.

Parameters

  layer | index of the graphic layer, must be < getNumberOfGraphicLayers()

Returns
  number of text objects

## ◆ getOverlayData()

OFCondition DVPresentationState::getOverlayData | ( | size_t | layer,
|  | size_t | idx,
|  | const void *& | overlayData,
|  | unsigned int & | width,
|  | unsigned int & | height,
|  | unsigned int & | left_pos,
|  | unsigned int & | top_pos,
|  | OFBool & | isROI,
|  | Uint16 & | fore,
|  | unsigned int | bits = `8`
| ) |  |

gets one overlay bitmap.

Parameters

  layer | index of the graphic layer on which this overlay is activated, must be < getNumberOfGraphicLayers().
  idx | index of the overlay activation on the given layer, must be < getNumberOfActiveOverlays(layer).
  overlayData | upon success a pointer to the overlay plane is passed back in this parameter. The overlay plane is organized as one byte or one word per pixel. The byte/word values are already transformed from pvalues to DDLs.
  width | upon success the width of the overlay bitmap in pixels is returned in this parameter.
  height | upon success the height of the overlay bitmap in pixels is returned in this parameter.
  left_pos | upon success the horizontal position of the overlay relative to the image is returned. 0 means that the overlay is left aligned with the image. Since the overlay is cropped at the borders of the image, values < 0 are impossible.
  top_pos | upon success the vertical position of the overlay relative to the image is returned.
  isROI | returns OFTrue if the overlay is ROI, OFFalse if the overlay is Graphic.
  fore | returns value of foreground color (pvalue), all other values are transparent
  bits | number of bits used for overlayData (valid: 8 or 12, default: 8). If bits is less than or equal to 8 the resulting overlayData is an array of 8 bit values, an array 16 bit values otherwise.

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ getOverlayInImageActivationLayer()

size_t DVPresentationState::getOverlayInImageActivationLayer | ( | size_t | idx | ) |

gets the index of the activation layer on which the given overlay from the attached image is activated.

Parameters

  idx | index of the overlay, must be < getNumberOfOverlaysInImage().

Returns
  layer index (which is < getNumberOfGraphicLayers()) if overlay exists and is activated, DVPS_IDX_NONE otherwise.

## ◆ getOverlayInImageDescription()

const char* DVPresentationState::getOverlayInImageDescription | ( | size_t | idx | ) |

gets the overlay description of the given overlay in the attached image.

Parameters

  idx | index of the overlay, must be < getNumberOfOverlaysInImage().

Returns
  description string if it exists, NULL otherwise.

## ◆ getOverlayInImageGroup()

Uint16 DVPresentationState::getOverlayInImageGroup | ( | size_t | idx | ) |

gets the repeating group number of the given overlay in the attached image.

Parameters

  idx | index of the overlay, must be < getNumberOfOverlaysInImage().

Returns
  repeating group number if found, 0 otherwise.

## ◆ getOverlayInImageLabel()

const char* DVPresentationState::getOverlayInImageLabel | ( | size_t | idx | ) |

gets the overlay label of the given overlay in the attached image.

Parameters

  idx | index of the overlay, must be < getNumberOfOverlaysInImage().

Returns
  label string if it exists, NULL otherwise.

## ◆ getPixelData() [1/2]

OFCondition DVPresentationState::getPixelData | ( | const void *& | pixelData,
|  | unsigned long & | width,
|  | unsigned long & | height
| ) |  |

applies presentation state to attached image and returns image bitmap.

This method sets all parameter required to correctly render the pixel data in the image attached to the presentation state and then creates the required pixel data which contains all grayscale transformations but none of the none-grayscale transformations of the presentation state "burned in" into the pixel data. The pixel data returned is already corrected by a display transform for the current display device and can be mapped directly to digital driving levels of the graphics board. The pointer to the pixel data remains valid until the next call to this function, or until the image is detached or the presentation state is deleted.

Parameters

  pixelData | in this parameter a pointer to the pixel data is returned (array of 8 bit values). The storage area allocated for this pointer must not be freed by the caller. If the return value is an error code, no valid pixel data pointer may be assumed.
  width | returns the width of the bitmap in pixels
  height | returns the height of the bitmap in pixels

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ getPixelData() [2/2]

OFCondition DVPresentationState::getPixelData | ( | void * | pixelData,
|  | unsigned long | size
| ) |  |

same as method above apart from the fact that the storage area is handled externally.

Parameters

  pixelData | pointer to storage area where the pixel data is copied to (array of 8 bit values). The storage area must be allocated and deleted from the calling method.
  size | specifies size of the storage area in bytes.

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ getPreviewImageBitmap()

OFCondition DVPresentationState::getPreviewImageBitmap | ( | void * | bitmap,
|  | unsigned long | size
| ) |  |

writes the bitmap data of the preview image into the given buffer.

The storage area must be allocated and deleted from the calling method.

Parameters

  bitmap | pointer to storage area where the pixel data is copied to (array of 8 bit values)
  size | specifies size of the storage area in bytes

Returns
  EC_Normal upon success, an error code otherwise

## ◆ getPreviewImageHeight()

OFCondition DVPresentationState::getPreviewImageHeight | ( | unsigned long & | height | ) |

gets current height of the preview image.

Parameters

  height | upon success, the image height (in pixels) is returned in this parameter

Returns
  EC_Normal upon success, an error code otherwise

## ◆ getPreviewImageSize()

unsigned long DVPresentationState::getPreviewImageSize | ( |  | ) |

gets number of bytes used for the preview image bitmap.

(depends on width and height)

Returns
  number of bytes used for the preview image bitmap

## ◆ getPreviewImageWidth()

OFCondition DVPresentationState::getPreviewImageWidth | ( | unsigned long & | width | ) |

gets current width of the preview image.

Parameters

  width | upon success, the image width (in pixels) is returned in this parameter

Returns
  EC_Normal upon success, an error code otherwise

## ◆ getPreviewImageWidthHeight()

OFCondition DVPresentationState::getPreviewImageWidthHeight | ( | unsigned long & | width,
|  | unsigned long & | height
| ) |  |

gets current width and height of the preview image.

Parameters

  width | upon success, the image width (in pixels) is returned in this parameter
  height | upon success, the image height (in pixels) is returned in this parameter

Returns
  EC_Normal upon success, an error code otherwise

## ◆ getPrintBitmap()

OFCondition DVPresentationState::getPrintBitmap | ( | void * | bitmap,
|  | unsigned long | size,
|  | OFBool | inversePLUT = `OFFalse`
| ) |  |

writes the bitmap data into the given buffer.

The bitmap has the format: 12 bits stored and 16 bits allocated. This method is used to create the preformatted bitmap where the annotations are later burned in. Implicit scaling is performed if the bitmap is too small (see minimum bitmap size). The storage area must be allocated and deleted from the calling method.

Parameters

  bitmap | pointer to storage area where the pixel data is copied to.
  size | specifies size of the storage area in bytes
  inversePLUT | render inverse PLUT into bitmap if OFTrue (optional)

Returns
  EC_Normal upon success, an error code otherwise

## ◆ getPrintBitmapHeight()

OFCondition DVPresentationState::getPrintBitmapHeight | ( | unsigned long & | height | ) |

gets height of print bitmap.

bitmap size depends on implicit scaling, a heuristic is used for very small images The return value depends on the current minimum/maximum print bitmaps width/height values!

Parameters

  height | upon success, the image height (in pixels) is returned in this parameter

Returns
  EC_Normal upon success, an error code otherwise

## ◆ getPrintBitmapPixelAspectRatio()

double DVPresentationState::getPrintBitmapPixelAspectRatio | ( |  | ) |

gets the presentation pixel aspect ratio for the print bitmap.

Pixel aspect ratio is defined here as the width of a pixel divided by the height of a pixel (x/y). The related image is already rotated and flipped!

Returns
  pixel aspect ratio

## ◆ getPrintBitmapRequestedImageSize()

OFCondition DVPresentationState::getPrintBitmapRequestedImageSize | ( | OFString & | requestedImageSize | ) |

gets requested image size for print bitmap.

If the presentation state mode is DVPSD_trueSize, this method computes the true physical width (in mm) of the print image (under consideration of the rotation status) and writes it to the requestedImageSize string.

Parameters

  requestedImageSize | requested image size is written to this parameter upon successful return. Otherwise string is empty upon return.

Returns
  EC_Normal upon success, an error code otherwise

## ◆ getPrintBitmapSize()

unsigned long DVPresentationState::getPrintBitmapSize | ( |  | ) |

gets number of bytes used for the print bitmap.

(depends on width, height and depth)

Returns
  number of bytes used for the print bitmap

## ◆ getPrintBitmapWidth()

OFCondition DVPresentationState::getPrintBitmapWidth | ( | unsigned long & | width | ) |

gets width of print bitmap.

Bitmap size depends on implicit scaling, a heuristic is used for very small images. The return value depends on the current minimum/maximum print bitmaps width/height values!

Parameters

  width | upon success, the image width (in pixels) is returned in this parameter

Returns
  EC_Normal upon success, an error code otherwise

## ◆ getPrintBitmapWidthHeight()

OFCondition DVPresentationState::getPrintBitmapWidthHeight | ( | unsigned long & | width,
|  | unsigned long & | height
| ) |  |

gets width and height of print bitmap.

Bitmap size depends on implicit scaling, a heuristic is used for very small images. The return values depend on the current minimum/maximum print bitmap width/height values!

Parameters

  width | upon success, the bitmap width (in pixels) is returned in this parameter
  height | upon success, the bitmap height (in pixels) is returned in this parameter

Returns
  EC_Normal upon success, an error code otherwise

## ◆ getSelectedImageFrameNumber()

unsigned long DVPresentationState::getSelectedImageFrameNumber | ( |  | ) |

gets the index of the currently selected frame in a multi-frame image.

Returns
  index of the currently selected frame, 0 if an error occurred

## ◆ getStandardDisplayedArea()

OFCondition DVPresentationState::getStandardDisplayedArea | ( | Sint32 & | tlhcX,
|  | Sint32 & | tlhcY,
|  | Sint32 & | brhcX,
|  | Sint32 & | brhcY
| ) |  |

gets the displayed area top lefthand corner and bottom righthand corner for the current potentially rotated and flipped image and frame.

This method may only be called when an image is attached to the presentation state.

Parameters

  tlhcX | the displayed area top lefthand corner X value is returned in this parameter
  tlhcY | the displayed area top lefthand corner Y value is returned in this parameter
  brhcX | the displayed area bottom righthand corner X value is returned in this parameter
  brhcY | the displayed area bottom righthand corner Y value is returned in this parameter

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ getTextObject()

DVPSTextObject* DVPresentationState::getTextObject | ( | size_t | layer,
|  | size_t | idx
| ) |  |

gets the text object with the given index on the given layer.

If the text object or the graphic layer does not exist, NULL is returned. Only the objects that are applicable to the current (attached) image and the selected frame number are used by this method.

Parameters

  layer | index of the graphic layer, must be < getNumberOfGraphicLayers()
  idx | index of the text object, must be < getNumberOfTextObjects(layer)

Returns
  a pointer to the text object

## ◆ haveActiveVOILUT()

OFBool DVPresentationState::haveActiveVOILUT | ( |  | ) |

check if a VOI LUT is currently active

Returns
  OFTrue if a VOI LUT is active

## ◆ haveActiveVOIWindow()

OFBool DVPresentationState::haveActiveVOIWindow | ( |  | ) |

check if a VOI window is currently active

Returns
  OFTrue if a VOI window is active

## ◆ invertImage()

OFCondition DVPresentationState::invertImage | ( |  | ) |

inverts image by changing presentation state LUT or presentation state LUT shape.

Pixel data has to be re-get after this transformation.

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ isInverse()

OFBool DVPresentationState::isInverse | ( |  | ) |

checks whether image is inverse (shape, plut or mono1).

Returns
  OFTrue if image is inverse, OFFalse otherwise.

## ◆ isMonochrome1Image()

OFBool DVPresentationState::isMonochrome1Image | ( |  | ) |
| inline

checks whether the attached image is MONOCHROME1.

In this case, the presentation LUT must be reversed when applied to the print bitmap which is always MONOCHROME2.

Returns
  OFTrue if attached image is MONOCHROME1, OFFalse otherwise.

## ◆ moveGraphicObject()

OFCondition DVPresentationState::moveGraphicObject | ( | size_t | old_layer,
|  | size_t | idx,
|  | size_t | new_layer,
|  | DVPSObjectApplicability | applicability = `DVPSB_allImages`
| ) |  |

moves the graphic object with the given index on the given layer to a different layer.

Only the objects that are applicable to the current (attached) image and the selected frame number are used by this method.

Parameters

  old_layer | index of the graphic layer on which the graphic object is, must be < getNumberOfGraphicLayers()
  idx | index of the graphic object, must be < getNumberOfGraphicObjects(layer)
  new_layer | index of the graphic layer to which the graphic object is moved, must be < getNumberOfGraphicLayers()
  applicability | defines to which images/frames the new object applies from now on. Default: all images referenced by the presentation state.

Returns
  EC_Normal upon success, an error code otherwise

## ◆ moveTextObject()

OFCondition DVPresentationState::moveTextObject | ( | size_t | old_layer,
|  | size_t | idx,
|  | size_t | new_layer,
|  | DVPSObjectApplicability | applicability = `DVPSB_allImages`
| ) |  |

moves the text object with the given index on the given layer to a different layer.

Only the objects that are applicable to the current (attached) image and the selected frame number are used by this method.

Parameters

  old_layer | index of the graphic layer on which the text object is, must be < getNumberOfGraphicLayers()
  idx | index of the text object, must be < getNumberOfTextObjects(layer)
  new_layer | index of the graphic layer to which the text object is moved, must be < getNumberOfGraphicLayers()
  applicability | defines to which images/frames the new object applies from now on. Default: all images referenced by the presentation state.

Returns
  EC_Normal upon success, an error code otherwise

## ◆ overlayInImageIsROI()

OFBool DVPresentationState::overlayInImageIsROI | ( | size_t | idx | ) |

checks whether the given overlay in the attached image is a ROI (region of interest) overlay.

Parameters

  idx | index of the overlay, must be < getNumberOfOverlaysInImage().

Returns
  OFTrue if overlay exists and is ROI, OFFalse otherwise.

## ◆ overlayIsSuitableAsBitmapShutter()

OFBool DVPresentationState::overlayIsSuitableAsBitmapShutter | ( | size_t | idx | ) |

checks if an overlay from the presentation state is suitable for use as a bitmap shutter.

An overlay is suitable if it is a graphic overlay with the same size as the attached image and with the origin 1\1. This method does not check whether the overlay is already activated as overlay or bitmap shutter.

Parameters

  idx | index of the overlay, must be < getNumberOfOverlaysInPresentationState().

Returns
  OFTrue if overlay can be used as display shutter.

## ◆ read()

OFCondition DVPresentationState::read | ( | DcmItem & | dset | ) |

reads a presentation state from a DICOM dataset.

The DICOM elements of the presentation state are copied from the dataset to this object. The completeness and correctness of the presentation state (presence of all required elements, value multiplicity) is checked. If this method returns an error code, the object is in undefined state afterwards.

Parameters

  dset | the dataset from which the presentation state is to be read

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ removeGraphicLayer()

OFCondition DVPresentationState::removeGraphicLayer | ( | size_t | idx | ) |

removes and deletes a graphic layer.

All text, graphic, curve and overlay objects on this graphic layer are also deleted or deactivated, respectively.

Parameters

  idx | index of the graphic layer, must be < getNumberOfGraphicLayers()

Returns
  EC_Normal upon success, an error code otherwise

## ◆ removeGraphicObject()

OFCondition DVPresentationState::removeGraphicObject | ( | size_t | layer,
|  | size_t | idx
| ) |  |

deletes the graphic object with the given index on the given layer.

Only the objects that are applicable to the current (attached) image and the selected frame number are used by this method.

Parameters

  layer | index of the graphic layer, must be < getNumberOfGraphicLayers()
  idx | index of the graphic object, must be < getNumberOfGraphicObjects(layer)

Returns
  EC_Normal upon success, an error code otherwise

## ◆ removeImageReferenceAttached()

OFCondition DVPresentationState::removeImageReferenceAttached | ( |  | ) |

removes a reference to the currently attached image from this presentation state.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ removeOverlayFromPresentationState()

OFCondition DVPresentationState::removeOverlayFromPresentationState | ( | size_t | idx | ) |

removes an overlay from the presentation state.

If the overlay is activated, the activation is also removed. Since overlays in the presentation state can shadow overlays in the attached image, execution of this method may change the number of overlays reported in the attached image.

Parameters

  idx | index of the overlay, must be < getNumberOfOverlaysInPresentationState().

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ removeShutter()

void DVPresentationState::removeShutter | ( | DVPSShutterType | type | ) |

deactivates display shutter of given type.

After a call to this method haveShutter(type) will return OFFalse.

Parameters

  type | the shutter type

## ◆ removeTextObject()

OFCondition DVPresentationState::removeTextObject | ( | size_t | layer,
|  | size_t | idx
| ) |  |

deletes the text object with the given index on the given layer.

Only the objects that are applicable to the current (attached) image and the selected frame number are used by this method.

Parameters

  layer | index of the graphic layer, must be < getNumberOfGraphicLayers()
  idx | index of the text object, must be < getNumberOfTextObjects(layer)

Returns
  EC_Normal upon success, an error code otherwise

## ◆ renderPixelData()

void DVPresentationState::renderPixelData | ( | OFBool | display = `OFTrue` | ) |

prepares pixel data for image and overlays for access.

This method is called internally before any image pixel data or overlay bitmaps is created. It makes sure that the following settings of the presentation state are reflected in the dcmimage-based image processing routines: VOI transformation, Presentation LUT, rotation, flip, overlay activation.

Parameters

  display | use current display function if OFTrue, don't use otherwise

## ◆ selectImageFrameNumber()

OFCondition DVPresentationState::selectImageFrameNumber | ( | unsigned long | frame | ) |

selects one frame of a multiframe image.

This affects the image bitmap that is rendered, the overlay bitmaps and the visibility of graphic and text objects. This method may only be called when an image is attached to the presentation state.

Parameters

  frame | frame number in the range [1..getImageNumberOfFrames()]

Returns
  EC_Normal upon success, an error code otherwise

## ◆ setCircularShutter()

OFCondition DVPresentationState::setCircularShutter | ( | Sint32 | centerX,
|  | Sint32 | centerY,
|  | Sint32 | radius
| ) |  |

sets and activates circular display shutter.

If a bitmap shutter is exists, it is deactivated if this method returns successfully. If no shutter display value exists, a default of 0 (black) is set.

Parameters

  centerX | the X component of the shutter center
  centerY | the Y component of the shutter center
  radius | the (horizontal) radius of the shutter

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ setCurrentPresentationLUT()

OFCondition DVPresentationState::setCurrentPresentationLUT | ( | DVPSPresentationLUTType | newType | ) |

sets the current Presentation LUT type.

DVPSP_table can only be used if the presentation state contains a lookup table, i.e. if havePresentationLookupTable() returns OFTrue.

Parameters

  newType | the new presentation LUT type.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setDefaultPresentationLUTShape()

OFCondition DVPresentationState::setDefaultPresentationLUTShape | ( |  | ) |

resets the Presentation LUT to the default LUT shape which is DVPSP_identity for MONOCHROME2 images and DVPSP_inverse for MONOCHROME1.

DVPSP_table can only be used if the presentation state contains a lookup table, i.e. if havePresentationLookupTable() returns OFTrue.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setDisplayTransform()

void DVPresentationState::setDisplayTransform | ( | DVPSDisplayTransform | transform | ) |
| inline

activates or deactivates display correction.

Display transform will only be performed if switched on and a valid display function object exists.

Parameters

  transform | display transform to be set, DVPSD_none to switch off.

## ◆ setGammaVOILUT()

OFCondition DVPresentationState::setGammaVOILUT | ( | double | gammaValue,
|  | DVPSObjectApplicability | applicability = `DVPSB_currentImage`
| ) |  |

stores VOI lookup table with a gamma curve shape in the presentation state.

If a VOI window is currently active the center and width values are used to specify the number of LUT entries and the first value mapped, otherwise the full pixel range is used. The output range of the LUT is always 16 bit (data is stored as OW). This method stores a VOI lookup table in the presentation state and activates it. The LUT is copied to the presentation state. If the method returns an error code, an old LUT is left unchanged. The applicability of the VOI LUT is controlled by the applicability parameter.

Parameters

  gammaValue | gamma value used to create the VOI LUT data
  applicability | defines the applicability of the new VOI transform.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setImageRelativeDisplayedArea()

OFCondition DVPresentationState::setImageRelativeDisplayedArea | ( | DVPSPresentationSizeMode | sizeMode,
|  | Sint32 | tlhcX,
|  | Sint32 | tlhcY,
|  | Sint32 | brhcX,
|  | Sint32 | brhcY,
|  | double | magnification = `1.0`,
|  | DVPSObjectApplicability | applicability = `DVPSB_currentImage`
| ) |  |

sets the displayed area and size mode (for the current frame, the current image or all images referenced by the presentation state object).

Treats the image as if it was neither rotated nor flipped.

Parameters

  sizeMode | presentation size mode.
  tlhcX | displayed area top lefthand corner X
  tlhcY | displayed area top lefthand corner Y
  brhcX | displayed area bottom righthand corner X
  brhcY | displayed area bottom righthand corner Y
  magnification | magnification factor - ignored unless sizeMode==DVPSD_magnify.
  applicability | defines the applicability of the new displayed area definition. Possible choices are: DVPSB_currentFrame - current frame only, DVPSB_currentImage - all frames of current image (default), and DVPSB_allImages - all images referenced by this presentation state. The last choice should be used with care because it will also cause the pixel spacing or pixel aspect ratio of the current image to be applied to all images referenced by the presentation state.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setMaximumPrintBitmapWidthHeight()

OFCondition DVPresentationState::setMaximumPrintBitmapWidthHeight | ( | unsigned long | width,
|  | unsigned long | height
| ) |  |

sets the maximum print bitmap width and height.

Larger images are scaled down by an appropriate integer factor. Both maximum values need to be twice greater than the maximum of the minimum values.

Parameters

  width | maximum width of print bitmap (in pixels)
  height | maximum height of print bitmap (in pixels)

Returns
  EC_Normal upon success, an error code otherwise

## ◆ setMinimumPrintBitmapWidthHeight()

OFCondition DVPresentationState::setMinimumPrintBitmapWidthHeight | ( | unsigned long | width,
|  | unsigned long | height
| ) |  |

sets the minimum print bitmap width and height.

Smaller images are scaled up by an appropriate integer factor. Both maximum values need to be twice greater than the maximum of the minimum values.

Parameters

  width | minimum width of print bitmap (in pixels)
  height | minimum height of print bitmap (in pixels)

Returns
  EC_Normal upon success, an error code otherwise

## ◆ setPresentationLookupTable() [1/2]

OFCondition DVPresentationState::setPresentationLookupTable | ( | DcmItem & | dset | ) |

stores a presentation lookup table in the presentation state.

This method stores a presentation lookup table in the presentation state and activates it. The LUT is copied to the presentation state. Overwrites old LUT. If unsuccessful, LUT is set to DVPSP_identity. This method keeps the inverse/not inverse status intact, i.e. inverses the LUT if necessary.

Parameters

  dset | dataset from which the Presentation LUT SQ or Shape is read.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setPresentationLookupTable() [2/2]

OFCondition DVPresentationState::setPresentationLookupTable | ( | DcmUnsignedShort & | lutDescriptor,
|  | DcmUnsignedShort & | lutData,
|  | DcmLongString & | lutExplanation
| ) |  |

stores a presentation lookup table in the presentation state.

This method stores a presentation lookup table in the presentation state and activates it. The LUT is copied to the presentation state. If the method returns EC_Normal, any old presentation LUT in the presentation state is overwritten. This method keeps the inverse/not inverse status intact, i.e. inverses the LUT if necessary.

Parameters

  lutDescriptor | the LUT Descriptor in DICOM format (VM=3)
  lutData | the LUT Data in DICOM format
  lutExplanation | the LUT Explanation in DICOM format, may be empty.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setRectShutter()

OFCondition DVPresentationState::setRectShutter | ( | Sint32 | lv,
|  | Sint32 | rv,
|  | Sint32 | uh,
|  | Sint32 | lh
| ) |  |

sets and activates rectangular display shutter.

If a bitmap shutter is exists, it is deactivated if this method returns successfully. If no shutter display value exists, a default of 0 (black) is set.

Parameters

  lv | the left vertical edge
  rv | the right vertical edge
  uh | the upper horizontal edge
  lh | the lower horizontal edge

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ setStandardDisplayedArea()

OFCondition DVPresentationState::setStandardDisplayedArea | ( | DVPSPresentationSizeMode | sizeMode,
|  | Sint32 | tlhcX,
|  | Sint32 | tlhcY,
|  | Sint32 | brhcX,
|  | Sint32 | brhcY,
|  | double | magnification = `1.0`,
|  | DVPSObjectApplicability | applicability = `DVPSB_currentImage`
| ) |  |

sets the displayed area and size mode (for the current frame, the current image or all images referenced by the presentation state object).

Parameters

  sizeMode | presentation size mode.
  tlhcX | displayed area top lefthand corner X
  tlhcY | displayed area top lefthand corner Y
  brhcX | displayed area bottom righthand corner X
  brhcY | displayed area bottom righthand corner Y
  magnification | magnification factor - ignored unless sizeMode==DVPSD_magnify.
  applicability | defines the applicability of the new displayed area definition. Possible choices are: DVPSB_currentFrame - current frame only, DVPSB_currentImage - all frames of current image (default), and DVPSB_allImages - all images referenced by this presentation state. The last choice should be used with care because it will also cause the pixel spacing or pixel aspect ratio of the current image to be applied to all images referenced by the presentation state.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setVOILUT()

OFCondition DVPresentationState::setVOILUT | ( | DcmUnsignedShort & | lutDescriptor,
|  | DcmUnsignedShort & | lutData,
|  | DcmLongString & | lutExplanation,
|  | DVPSObjectApplicability | applicability = `DVPSB_currentImage`
| ) |  |

stores a VOI lookup table in the presentation state.

This method stores a VOI lookup table in the presentation state and activates it. The LUT is copied to the presentation state. If the method returns an error code, an old LUT is left unchanged. The applicability of the VOI LUT is controlled by the applicability parameter.

Parameters

  lutDescriptor | the LUT Descriptor in DICOM format (VM=3)
  lutData | the LUT Data in DICOM format
  lutExplanation | the LUT Explanation in DICOM format, may be empty.
  applicability | defines the applicability of the new VOI transform.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setVOILUTFromImage()

OFCondition DVPresentationState::setVOILUTFromImage | ( | size_t | idx,
|  | DVPSObjectApplicability | applicability = `DVPSB_currentImage`
| ) |  |

activates one of the VOI LUTs from the attached image.

The applicability of the activation is controlled by the applicability parameter.

Parameters

  idx | index of the VOI transform, must be < getNumberOfVOILUTsInImage().
  applicability | defines the applicability of the new VOI transform.

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ setVOIWindow()

OFCondition DVPresentationState::setVOIWindow | ( | double | wCenter,
|  | double | wWidth,
|  | const char * | description = `NULL`,
|  | DVPSObjectApplicability | applicability = `DVPSB_currentImage`
| ) |  |

sets a user defined VOI window center and width.

The applicability of the VOI window is controlled by the applicability parameter.

Parameters

  wCenter | the window center
  wWidth | the window width
  description | an optional description. Default: absent.
  applicability | defines the applicability of the new VOI transform.

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ setVOIWindowFromImage()

OFCondition DVPresentationState::setVOIWindowFromImage | ( | size_t | idx,
|  | DVPSObjectApplicability | applicability = `DVPSB_currentImage`
| ) |  |

activates one of the VOI Windows from the attached image.

The applicability of the activation is controlled by the applicability parameter.

Parameters

  idx | index of the VOI transform, must be < getNumberOfVOIWindowsInImage().
  applicability | defines the applicability of the new VOI transform.

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ writeHardcopyImageAttributes()

OFCondition DVPresentationState::writeHardcopyImageAttributes | ( | DcmItem & | dset | ) |

writes the patient module attributes and a source image sequence for a grayscale hardcopy image.

Copies of the DICOM elements managed by this object are inserted into the DICOM dataset.

Parameters

  dset | the dataset to which the data is written

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ writePresentationLUTforPrint()

OFCondition DVPresentationState::writePresentationLUTforPrint | ( | DcmItem & | dset | ) |

writes the current Presentation LUT to a DICOM dataset.

Copies of the DICOM element managed by this object are inserted into the DICOM dataset. In the case of a MONOCHROME1 image an inverted LUT is written to dataset because the print bitmap is always MONOCHROME2.

Parameters

  dset | the dataset to which the Presentation LUT SQ/Shape is written

Returns
  EC_Normal if successful, an error code otherwise.

## Member Data Documentation

## ◆ currentImageOverlaysValid

int DVPresentationState::currentImageOverlaysValid
| private

a flag describing whether the Overlay settings in currentImage match the ones in the presentation state.

values: 0=invalid, 1=invalid, but no external overlay added, 2=valid

## ◆ currentImageOwned

OFBool DVPresentationState::currentImageOwned
| private

a flag describing whether the presentation state is owner of the DICOM dataset in currentImageDataset/currentImageFileformat.

If the presentation state is owner, it will delete the dataset upon its own destruction or attachment of a different image.

## ◆ currentImageSelectedFrame

unsigned long DVPresentationState::currentImageSelectedFrame
| private

contains the current selected frame number of the attached image.

Frame numbers are counted from 1 (like in DICOM, unlike dcmimgle).

## ◆ renderedImageBottom

signed long DVPresentationState::renderedImageBottom
| private

contains the bottom hand corner of the attached image after pixel data have been rendered.

(the following equation is always true: renderedImageLeft <= renderedImageRight)

## ◆ renderedImageLeft

signed long DVPresentationState::renderedImageLeft
| private

contains the left hand corner of the attached image after pixel data have been rendered.

(the following equation is always true: renderedImageTop <= renderedImageBottom)

The documentation for this class was generated from the following file:

- dcmpstat/include/dcmtk/dcmpstat/dvpstat.h

Generated on Mon Dec 15 2025 for DCMTK Version 3.7.0 by Doxygen 1.9.1