DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Public Member Functions | Protected Member Functions | Protected Attributes | Private Member Functions | List of all members
DcmPresentationState Class Reference

a Grayscale Softcopy Presentation State. More...

Inheritance diagram for DcmPresentationState:

## Public Member Functions
| 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...

## Protected Member Functions
OFCondition | createDefaultDisplayedArea (DcmItem &dset)
| creates a default displayed area selection for the given dataset. More...

## Protected Attributes
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.

## Private Member Functions
| DcmPresentationState (const DcmPresentationState &copy)
| private undefined copy constructor
DcmPresentationState & | operator= (const DcmPresentationState &obj)
| private undefined assignment operator
OFCondition | createDummyValues (OFBool replaceSOPInstanceUID)
| create dummy values for all missing type 1 elements. More...
void | cleanupLayers ()
| removes and deletes all graphic layer for which no matching text, graphic, curve or overlay object exists. More...

## 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.

## Member Function Documentation

## ◆ addGraphicLayer()

OFCondition DcmPresentationState::addGraphicLayer | ( | const char * | gLayer,
|  | const char * | gLayerDescription = `NULL`
| ) |  |

creates a new graphic layer with the given name and optional description.

The new name must be unique, otherwise an error code is returned. The toFrontGraphicLayer() method is implicitly called for the new layer.

Parameters

  gLayer | the name of the graphic layer. Must be a valid DICOM Code String.
  gLayerDescription | the optional description of the graphic layer. Must be a valid DICOM Long String.

Returns
  EC_Normal upon success, an error code otherwise

## ◆ addImageReference() [1/2]

OFCondition DcmPresentationState::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.

This method checks if the given SOP class and Study UID match for this presentation state and returns an error code otherwise.

Parameters

  studyUID | the Study Instance UID of the image reference to be added.
  seriesUID | the Series Instance UID of the image reference to be added.
  sopclassUID | the SOP class UID of the image reference to be added.
  instanceUID | the SOP instance UID of the image reference to be added.
  frames | a list of frame numbers in DICOM IS format (integer numbers separated by '\' characters). Default: frame numbers absent. The frame numbers are required if the referenced image is a multiframe image.
  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.

## ◆ addImageReference() [2/2]

OFCondition DcmPresentationState::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.

This method checks if the given SOP class and Study UID match for this presentation state and returns an error code otherwise.

Parameters

  dset | the DICOM dataset containing the image IOD
  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.

## ◆ cleanupLayers()

void DcmPresentationState::cleanupLayers | ( |  | ) |
| private

removes and deletes all graphic layer for which no matching text, graphic, curve or overlay object exists.

Also deletes all graphic annotation sequence items containing no text and no graphic object. Called before writing a presentation state.

## ◆ clear()

void DcmPresentationState::clear | ( |  | ) |

resets the object to initial state.

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

## ◆ createDefaultDisplayedArea()

OFCondition DcmPresentationState::createDefaultDisplayedArea | ( | DcmItem & | dset | ) |
| protected

creates a default displayed area selection for the given dataset.

Used in createFromImage().

Parameters

  dset | the DICOM dataset containing the image IOD

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ createDummyValues()

OFCondition DcmPresentationState::createDummyValues | ( | OFBool | replaceSOPInstanceUID | ) |
| private

create dummy values for all missing type 1 elements.

Called before a presentation state is written to make sure that the presentation state is complete.

Parameters

  replaceSOPInstanceUID | flag indicating whether the SOP Instance UID should be replaced by a new UID. If true, a new UID is always generated. If false, a new UID is generated only if no UID has been assigned before.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ createFromImage()

OFCondition DcmPresentationState::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.

## ◆ createInstanceUID()

const char* DcmPresentationState::createInstanceUID | ( |  | ) |

generates a new SOP Instance UID for the Presentation State.

Returns
  new SOP Instance UID if successfully set, NULL otherwise.

## ◆ exchangeGraphicLayers()

OFCondition DcmPresentationState::exchangeGraphicLayers | ( | size_t | idx1,
|  | size_t | idx2
| ) |  |

exchanges the layer order of the two graphic layers with the given indices.

This method does not sort or renumber the graphic layers.

Parameters

  idx1 | index of the first graphic layer, must be < getNumberOfGraphicLayers()
  idx2 | index of the second graphic layer, must be < getNumberOfGraphicLayers()

Returns
  EC_Normal upon success, an error code otherwise

## ◆ getActiveOverlayGroup()

Uint16 DcmPresentationState::getActiveOverlayGroup | ( | size_t | layer,
|  | size_t | idx
| ) |  |

gets the repeating group number of the given activated overlay.

Parameters

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

Returns
  repeating group number if found, 0 otherwise.

## ◆ getCenterOfCircularShutter_x()

Sint32 DcmPresentationState::getCenterOfCircularShutter_x | ( |  | ) |

gets circular shutter center x component.

May only be called if a circular shutter is active.

Returns
  the circ shutter center x component

## ◆ getCenterOfCircularShutter_y()

Sint32 DcmPresentationState::getCenterOfCircularShutter_y | ( |  | ) |

gets circular shutter center y component.

May only be called if a circular shutter is active.

Returns
  the circ shutter center y component

## ◆ getCharset()

DVPScharacterSet DcmPresentationState::getCharset | ( |  | ) |

gets the specific character set for this presentation state.

Returns
  character set identifier

## ◆ getCharsetString()

const char* DcmPresentationState::getCharsetString | ( |  | ) |

gets the specific character set string for this presentation state.

Returns
  character set if present, NULL otherwise

## ◆ getCurrentPresentationLUTExplanation()

const char* DcmPresentationState::getCurrentPresentationLUTExplanation | ( |  | ) |
| inline

gets a description of the current presentation LUT.

For well-known presentation LUT shapes, a standard text is returned. For presentation LUTs, the LUT explanation is returned if it exists and a standard text otherwise. This method never returns NULL.

Returns
  a pointer to a string describing the current presentation LUT.

## ◆ getFlip()

OFBool DcmPresentationState::getFlip | ( |  | ) |

gets the current horizontal flip status of the presentation state.

Returns
  OFTrue if flip is on, OFFalse if flip is off.

## ◆ getGraphicLayerDescription()

const char* DcmPresentationState::getGraphicLayerDescription | ( | size_t | idx | ) |

gets a description string for the graphic layer with the given index.

If no layer for the given index exists, or if the description is empty, NULL is returned.

Parameters

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

Returns
  description of the graphic layer

## ◆ getGraphicLayerIndex()

size_t DcmPresentationState::getGraphicLayerIndex | ( | const char * | name | ) |

gets the index of the graphic layer with the given unique name.

If no matching layer is found, DVPS_IDX_NONE is returned.

Parameters

  name | name of the graphic layer

Returns
  index of the graphic layer

## ◆ getGraphicLayerName()

const char* DcmPresentationState::getGraphicLayerName | ( | size_t | idx | ) |

gets the unique name of the graphic layer with the given index.

If no layer for the given index exists, NULL is returned.

Parameters

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

Returns
  name of the graphic layer

## ◆ getGraphicLayerRecommendedDisplayValueGray()

OFCondition DcmPresentationState::getGraphicLayerRecommendedDisplayValueGray | ( | size_t | idx,
|  | Uint16 & | gray
| ) |  |

gets the recommended grayscale display value for the given graphic layer.

If the graphic layer contains an RGB display value but no grayscale display value, the RGB value is implicitly converted to grayscale.

Parameters

  idx | index of the graphic layer, must be < getNumberOfGraphicLayers()
  gray | the recommended display value as an unsigned 16-bit P-value is returned in this parameter.

Returns
  EC_Normal upon success, an error code otherwise

## ◆ getGraphicLayerRecommendedDisplayValueRGB()

OFCondition DcmPresentationState::getGraphicLayerRecommendedDisplayValueRGB | ( | size_t | idx,
|  | Uint16 & | r,
|  | Uint16 & | g,
|  | Uint16 & | b
| ) |  |

gets the recommended RGB display value for the given graphic layer.

If the graphic layer contains a grayscale display value but no RGB display value, the grayscale value is implicitly converted to RGB.

Parameters

  idx | index of the graphic layer, must be < getNumberOfGraphicLayers()
  r | returns the R component of the recommended display value as unsigned 16-bit P-value
  g | returns the G component of the recommended display value as unsigned 16-bit P-value
  b | returns the B component of the recommended display value as unsigned 16-bit P-value

Returns
  EC_Normal upon success, an error code otherwise

## ◆ getImageReference()

OFCondition DcmPresentationState::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.

Parameters

  idx | index, must be < numberOfImageReferences().
  studyUID | the Study Instance UID is returned in this string
  seriesUID | the Series Instance UID is returned in this string
  sopclassUID | the SOP Class UID is returned in this string
  instanceUID | the SOP Instance UID is returned in this string
  frames | the list of frames is returned in this string
  aetitle | the series retrieveAETitle is returned in this string
  filesetID | the series storageMediaFileSetID is returned in this string
  filesetUID | the series storageMediaFileSetUID is returned in this string

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ getInstanceUID()

const char* DcmPresentationState::getInstanceUID | ( |  | ) |

returns the current SOP Instance UID for the Presentation State.

Returns
  SOP Instance UID if present, NULL otherwise.

## ◆ getNumberOfActiveOverlays()

size_t DcmPresentationState::getNumberOfActiveOverlays | ( | size_t | layer | ) |

gets the number of overlays that are currently activated on the given graphic layer.

Parameters

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

Returns
  number of active overlays

## ◆ getNumberOfCurves()

size_t DcmPresentationState::getNumberOfCurves | ( | size_t | layer | ) |

returns the number of curve activations for the given graphic layer.

Parameters

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

Returns
  number of curves

## ◆ getNumberOfGraphicLayers()

size_t DcmPresentationState::getNumberOfGraphicLayers | ( |  | ) |

returns the number of graphic layers.

Returns
  number of graphic layers

## ◆ getNumberOfOverlaysInPresentationState()

size_t DcmPresentationState::getNumberOfOverlaysInPresentationState | ( |  | ) |

gets the number of overlays which are embedded in the presentation state.

Returns
  number of overlays in presentation state

## ◆ getNumberOfPolyShutterVertices()

size_t DcmPresentationState::getNumberOfPolyShutterVertices | ( |  | ) |

gets polygonal shutter number of points.

May only be called if a polygonal shutter is active.

Returns
  the number of points describing the poly shutter

## ◆ getOverlayInPresentationStateActivationLayer()

size_t DcmPresentationState::getOverlayInPresentationStateActivationLayer | ( | size_t | idx | ) |

gets the index of the activation layer on which the given overlay from the presentation state is activated.

If an overlay is used as a bitmap shutter, it is reported as being not activated by this method.

Parameters

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

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

## ◆ getOverlayInPresentationStateDescription()

const char* DcmPresentationState::getOverlayInPresentationStateDescription | ( | size_t | idx | ) |

gets the overlay description of the given overlay in the presentation state.

Parameters

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

Returns
  description string if it exists, NULL otherwise.

## ◆ getOverlayInPresentationStateGroup()

Uint16 DcmPresentationState::getOverlayInPresentationStateGroup | ( | size_t | idx | ) |

gets the repeating group number of the given overlay in the presentation state.

Parameters

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

Returns
  repeating group number if found, 0 otherwise.

## ◆ getOverlayInPresentationStateLabel()

const char* DcmPresentationState::getOverlayInPresentationStateLabel | ( | size_t | idx | ) |

gets the overlay label of the given overlay in the presentation state.

Parameters

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

Returns
  label string if it exists, NULL otherwise.

## ◆ getPolyShutterVertex()

OFCondition DcmPresentationState::getPolyShutterVertex | ( | size_t | idx,
|  | Sint32 & | x,
|  | Sint32 & | y
| ) |  |

get polygonal shutter point.

May only be called if a polygonal shutter is active. Shutter points are relative to the origin 1\1 which is the left upper edge of the image.

Parameters

  idx | the index of the shutter point, must be < getNumberOfPolyShutterVertices()
  x | returns the x component of the point
  y | returns the y component of the point

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ getPresentationCreatorsName()

const char* DcmPresentationState::getPresentationCreatorsName | ( |  | ) |

returns the creator's name for the presentation state.

If no name is available, NULL is returned.

Returns
  a pointer to a string or NULL.

## ◆ getPresentationDescription()

const char* DcmPresentationState::getPresentationDescription | ( |  | ) |

returns a description for the presentation state.

If no description is available, NULL is returned.

Returns
  a pointer to a string or NULL.

## ◆ getPresentationLabel()

const char* DcmPresentationState::getPresentationLabel | ( |  | ) |

returns a label for the presentation state.

If no label is available, NULL is returned.

Returns
  a pointer to a string or NULL.

## ◆ getPresentationLUT()

DVPSPresentationLUTType DcmPresentationState::getPresentationLUT | ( |  | ) |
| inline

gets the current Presentation LUT type.

Returns
  the current presentation LUT type

## ◆ getPresentationLUTData()

DVPSPresentationLUT* DcmPresentationState::getPresentationLUTData | ( |  | ) |
| inline

gets the current Presentation LUT object.

Returns
  the current presentation LUT object

## ◆ getPresentationLUTExplanation()

const char* DcmPresentationState::getPresentationLUTExplanation | ( |  | ) |
| inline

returns the LUT explanation of the presentation LUT if it exists and is non-empty.

Otherwise returns NULL.

Returns
  a string pointer

## ◆ getRadiusOfCircularShutter()

Sint32 DcmPresentationState::getRadiusOfCircularShutter | ( |  | ) |

gets circular shutter radius.

May only be called if a circular shutter is active. Note: In DICOM, a circular shutter must be rendered with consideration of the image pixel aspect ratio. The radius returned by this method is the number of pixels describing a horizontal line from the center of the circle to its border. See sample figures in NEMA PS3.3:1998.

Returns
  the circ shutter radius

## ◆ getRectShutterLH()

Sint32 DcmPresentationState::getRectShutterLH | ( |  | ) |

gets rectangular shutter lower horizontal edge.

May only be called if a rectangular shutter is active.

Returns
  the rect shutter LH edge.

## ◆ getRectShutterLV()

Sint32 DcmPresentationState::getRectShutterLV | ( |  | ) |

gets rectangular shutter left vertical edge.

May only be called if a rectangular shutter is active.

Returns
  the rect shutter LV edge.

## ◆ getRectShutterRV()

Sint32 DcmPresentationState::getRectShutterRV | ( |  | ) |

gets rectangular shutter right vertical edge.

May only be called if a rectangular shutter is active.

Returns
  the rect shutter RV edge.

## ◆ getRectShutterUH()

Sint32 DcmPresentationState::getRectShutterUH | ( |  | ) |

gets rectangular shutter upper horitontal edge.

May only be called if a rectangular shutter is active.

Returns
  the rect shutter UH edge.

## ◆ getRotation()

DVPSRotationType DcmPresentationState::getRotation | ( |  | ) |

gets the current rotation status of the presentation state.

Returns
  the current rotation status

## ◆ getShutterPresentationValue()

Uint16 DcmPresentationState::getShutterPresentationValue | ( |  | ) |

gets the shutter presentation value.

If no shutter display value exists, a default of 0 (black) is set.

Returns
  the shutter presentation value as 16bit unsigned P-value

## ◆ getSOPClassUID()

const char* DcmPresentationState::getSOPClassUID | ( |  | ) |

returns the (currently hard-coded) SOP Class UID of the Presentation State.

Returns
  SOP Class UID of the presentation state

## ◆ getStudyUID()

const char* DcmPresentationState::getStudyUID | ( |  | ) |

returns the Study Instance UID of the presentation state.

Returns
  Study Instance UID if successful, NULL otherwise.

## ◆ haveGraphicLayerRecommendedDisplayValue()

OFBool DcmPresentationState::haveGraphicLayerRecommendedDisplayValue | ( | size_t | idx | ) |

checks whether a recommended display value (grayscale, color or both) for the given graphic layer exists.

Parameters

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

Returns
  OFTrue if a recommended display value exists

## ◆ havePresentationLookupTable()

OFBool DcmPresentationState::havePresentationLookupTable | ( |  | ) |
| inline

checks if a real Presentation LUT (not shape) is available in the presentation state.

Returns
  OFTrue if the presentation state contains a presentation LUT, no matter if it is activated or not. Returns OFFalse otherwise.

## ◆ haveShutter()

OFBool DcmPresentationState::haveShutter | ( | DVPSShutterType | type | ) |

checks if a display shutter of given type is active.

Parameters

  type | the shutter type

Returns
  OFTrue if this type of shutter is currently active.

## ◆ moveCurve()

OFCondition DcmPresentationState::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.

Parameters

  old_layer | index of the graphic layer on which the curve is, must be < getNumberOfGraphicLayers()
  idx | index of the curve activation, must be < getNumberOfCurves(layer)
  new_layer | index of the graphic layer to which the curve is moved, must be < getNumberOfGraphicLayers()

Returns
  EC_Normal upon success, an error code otherwise

## ◆ moveOverlay()

OFCondition DcmPresentationState::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.

Parameters

  old_layer | index of the graphic layer on which the curve is, must be < getNumberOfGraphicLayers()
  idx | index of the overlay activation, must be < getNumberOfActiveOverlays(layer)
  new_layer | index of the graphic layer to which the curve is moved, must be < getNumberOfGraphicLayers()

Returns
  EC_Normal upon success, an error code otherwise

## ◆ numberOfImageReferences()

size_t DcmPresentationState::numberOfImageReferences | ( |  | ) |

gets the number of image references in all series managed by this list.

Returns
  number of image references

## ◆ overlayInPresentationStateIsROI()

OFBool DcmPresentationState::overlayInPresentationStateIsROI | ( | size_t | idx | ) |

checks whether the given overlay in the presentation state is a ROI (region of interest) overlay.

Parameters

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

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

## ◆ overlayIsBitmapShutter()

OFBool DcmPresentationState::overlayIsBitmapShutter | ( | size_t | idx | ) |

checks if the given overlay in the presentation state is currently activated as a bitmap shutter.

Parameters

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

Returns
  OFTrue if overlay exists and is activated as bitmap shutter, OFFalse otherwise.

## ◆ read()

OFCondition DcmPresentationState::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.

## ◆ removeCurve()

OFCondition DcmPresentationState::removeCurve | ( | size_t | layer,
|  | size_t | idx
| ) |  |

deletes the curve activation with the given index on the given layer.

Parameters

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

Returns
  EC_Normal upon success, an error code otherwise

## ◆ removeGraphicLayerRecommendedDisplayValue()

void DcmPresentationState::removeGraphicLayerRecommendedDisplayValue | ( | size_t | idx,
|  | OFBool | rgb,
|  | OFBool | monochrome
| ) |  |

removes recommended display values for the given graphic layer.

Parameters

  idx | index of the graphic layer, must be < getNumberOfGraphicLayers()
  rgb | if true, the RGB recommended display value is removed
  monochrome | if true the monochrome recommended display value is removed

## ◆ removeImageReference() [1/2]

OFCondition DcmPresentationState::removeImageReference | ( | const char * | studyUID,
|  | const char * | seriesUID,
|  | const char * | instanceUID
| ) |  |

removes a reference to an image from this presentation state.

Parameters

  studyUID | the Study Instance UID of the image reference to be removed.
  seriesUID | the Series Instance UID of the image reference to be removed.
  instanceUID | the SOP instance UID of the image reference to be removed.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ removeImageReference() [2/2]

OFCondition DcmPresentationState::removeImageReference | ( | DcmItem & | dset | ) |

removes a reference to an image from this presentation state.

Parameters

  dset | the DICOM dataset containing the image IOD

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setCharset()

OFCondition DcmPresentationState::setCharset | ( | DVPScharacterSet | charset | ) |

sets the specific character set for this presentation state.

Parameters

  charset | the new character set for this text object

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setFlip()

OFCondition DcmPresentationState::setFlip | ( | OFBool | isFlipped | ) |

sets horizontal flip status of the presentation state.

Parameters

  isFlipped | the flip status, OFTrue for on, OFFalse for off.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setGraphicLayerDescription()

OFCondition DcmPresentationState::setGraphicLayerDescription | ( | size_t | idx,
|  | const char * | descr
| ) |  |

sets a new description to the given graphic layer.

Parameters

  idx | index of the graphic layer, must be < getNumberOfGraphicLayers()
  descr | description of the graphic layer. Must be a valid DICOM Long String.

Returns
  EC_Normal upon success, an error code otherwise

## ◆ setGraphicLayerName()

OFCondition DcmPresentationState::setGraphicLayerName | ( | size_t | idx,
|  | const char * | name
| ) |  |

assigns a new unique name to the given graphic layer.

The new name must be unique, otherwise an error code is returned. Upon success, all references (for graphic annotations, curves and overlays) to the given graphic layer are also renamed so that the presentation state remains consistent.

Parameters

  idx | index of the graphic layer, must be < getNumberOfGraphicLayers()
  name | the new name of the graphic layer. Must be a valid DICOM Code String.

Returns
  EC_Normal upon success, an error code otherwise

## ◆ setGraphicLayerRecommendedDisplayValueGray()

OFCondition DcmPresentationState::setGraphicLayerRecommendedDisplayValueGray | ( | size_t | idx,
|  | Uint16 | gray
| ) |  |

set graphic layer recommended grayscale display value for the given graphic layer.

This method does not affect (set or modify) the recommended RGB display value which should be set separately.

Parameters

  idx | index of the graphic layer, must be < getNumberOfGraphicLayers()
  gray | the recommended display value as an unsigned 16-bit P-value

Returns
  EC_Normal upon success, an error code otherwise

## ◆ setGraphicLayerRecommendedDisplayValueRGB()

OFCondition DcmPresentationState::setGraphicLayerRecommendedDisplayValueRGB | ( | size_t | idx,
|  | Uint16 | r,
|  | Uint16 | g,
|  | Uint16 | b
| ) |  |

set graphic layer recommended RGB display value for the given graphic layer.

This method does not affect (set or modify) the recommended grayscale display value which should be set separately.

Parameters

  idx | index of the graphic layer, must be < getNumberOfGraphicLayers()
  r | the R component of the recommended display value as unsigned 16-bit P-value
  g | the G component of the recommended display value as unsigned 16-bit P-value
  b | the B component of the recommended display value as unsigned 16-bit P-value

Returns
  EC_Normal upon success, an error code otherwise

## ◆ setPolyShutterOrigin()

OFCondition DcmPresentationState::setPolyShutterOrigin | ( | Sint32 | x,
|  | Sint32 | y
| ) |  |

sets polygonal display shutter origin.

This method creates a polygonal shutter consisting only of a single point. The polygonal display shutter is deactivated after this method.

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.

## ◆ setPresentationCreatorsName()

OFCondition DcmPresentationState::setPresentationCreatorsName | ( | const char * | name | ) |

sets the presentation state creator's name.

The passed string must be a valid DICOM Person Name String (see NEMA PS3.5:1998).

Parameters

  name | the new creator's name

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ setPresentationDescription()

OFCondition DcmPresentationState::setPresentationDescription | ( | const char * | descr | ) |

sets the presentation state description.

The passed string must be a valid DICOM Long String (i.e. max 64 characters, no backslash or control chars).

Parameters

  descr | the new presentation state description

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ setPresentationLabel()

OFCondition DcmPresentationState::setPresentationLabel | ( | const char * | label | ) |

sets the presentation state label.

The passed string must be a valid DICOM Code String (i.e. max 16 characters, only uppercase and numbers).

Parameters

  label | the new presentation state label

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ setRotation()

OFCondition DcmPresentationState::setRotation | ( | DVPSRotationType | rotation | ) |

sets rotation status of the presentation state.

Parameters

  rotation | the rotation to be set

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setShutterPresentationValue()

OFCondition DcmPresentationState::setShutterPresentationValue | ( | Uint16 | pvalue | ) |

sets the shutter presentation value to the given P-value.

Parameters

  pvalue | the shutter presentation value.

Returns
  EC_Normal upon success, an error code otherwise.

## ◆ sortGraphicLayers()

void DcmPresentationState::sortGraphicLayers | ( |  | ) |

sorts the graphic layers according to the graphic layer order.

Layers with lower order have lower indices after sorting which means that the layers can be drawn to the screen in ascending index order. Calling this routine may result in a re-numbering of the graphic layer orders in a way that does not affect their sequence.

## ◆ toBackGraphicLayer()

OFCondition DcmPresentationState::toBackGraphicLayer | ( | size_t | idx | ) |

makes a graphic layer the lowest layer for display.

This method assigns a graphic layer order lower than all existing graphic layer orders to the given graphic layer, sorts and renumbers the list of graphic layers. Upon success, the given graphic layer is guaranteed to have the new index 0.

Parameters

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

Returns
  EC_Normal upon success, an error code otherwise

## ◆ toFrontGraphicLayer()

OFCondition DcmPresentationState::toFrontGraphicLayer | ( | size_t | idx | ) |

makes a graphic layer the highest layer for display.

This method assigns a graphic layer order higher than all existing graphic layer orders to the given graphic layer, sorts and renumbers the list of graphic layers. Upon success, the given graphic layer is guaranteed to have the new index (getNumberOfGraphicLayers()-1).

Parameters

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

Returns
  EC_Normal upon success, an error code otherwise

## ◆ write()

OFCondition DcmPresentationState::write | ( | DcmItem & | dset,
|  | OFBool | replaceSOPInstanceUID
| ) |  |

writes the presentation state managed by this object to a DICOM dataset.

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

Parameters

  dset | the dataset to which the presentation state is written
  replaceSOPInstanceUID | flag indicating whether the SOP Instance UID should be replaced by a new UID. If true, a new UID is always generated. If false, a new UID is generated only if no UID has been assigned before.

Returns
  EC_Normal if successful, an error code otherwise.

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

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

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