DCMTK Version 3.7.0 OFFIS DICOM Toolkit

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

an item of the displayed area selection sequence in a presentation state. More...

## Public Member Functions
| DVPSDisplayedArea ()
| default constructor
| DVPSDisplayedArea (const DVPSDisplayedArea &copy)
| copy constructor
DVPSDisplayedArea * | clone ()
| clone method. More...
virtual | ~DVPSDisplayedArea ()
| destructor
OFCondition | read (DcmItem &dset)
| reads an displayed area selection from a DICOM dataset. More...
OFCondition | write (DcmItem &dset)
| writes the displayed area selection managed by this object to a DICOM dataset. More...
OFBool | isApplicable (const char *instanceUID, unsigned long frame)
| checks if this displayed area is applicable to the given image and frame. More...
OFBool | matchesApplicability (const char *instanceUID, unsigned long frame, DVPSObjectApplicability applicability)
| checks if this displayed area matches exactly the applicability defined by the instanceUID, frame and applicability parameters. More...
DVPSPresentationSizeMode | getPresentationSizeMode ()
| gets the presentation size mode for this displayed area selection. More...
double | getPresentationPixelAspectRatio ()
| gets the presentation pixel aspect ratio for this displayed area selection. More...
void | getDisplayedArea (Sint32 &tlhcX, Sint32 &tlhcY, Sint32 &brhcX, Sint32 &brhcY)
| gets the displayed area top lefthand corner and bottom righthand corner. More...
OFCondition | getPresentationPixelSpacing (double &x, double &y)
| gets the presentation pixel spacing for this displayed area if present. More...
OFCondition | getPresentationPixelMagnificationRatio (double &magnification)
| gets the presentation pixel magnification ratio for this displayed area if present. More...
OFCondition | addImageReference (const char *sopclassUID, const char *instanceUID, unsigned long frame, DVPSObjectApplicability applicability)
| add a new image reference. More...
void | removeImageReference (DVPSReferencedSeries_PList &allReferences, const char *instanceUID, unsigned long frame, unsigned long numberOfFrames, DVPSObjectApplicability applicability)
| removes a reference to an image or frame. More...
void | clearImageReferences ()
| removes all image references for this displayed area.
OFBool | imageReferencesEmpty ()
| checks if the list of image references for this displayed area is empty. More...
OFBool | canUseTrueSize ()
| checks if the TRUE SIZE mode is possible, i.e. More...
OFCondition | setDisplayedAreaPixelSpacing (double spacingX, double spacingY)
| sets the displayed area pixel spacing and removes any pixel aspect ratio setting. More...
OFCondition | setDisplayedAreaPixelSpacing (const char *spacing)
| sets the displayed area pixel spacing and removes any pixel aspect ratio setting. More...
OFCondition | setDisplayedAreaPixelAspectRatio (double ratio)
| sets the displayed area pixel spacing and removes any pixel spacing setting. More...
OFCondition | setDisplayedAreaPixelAspectRatio (const char *ratio)
| sets the displayed area pixel spacing and removes any pixel spacing setting. More...
OFCondition | setDisplayedArea (DVPSPresentationSizeMode sizeMode, Sint32 tlhcX, Sint32 tlhcY, Sint32 brhcX, Sint32 brhcY, double magnification=1.0)
| sets the displayed area and size mode. More...
void | rotateAndFlip (DVPSRotationType rotationFrom, OFBool isFlippedFrom, DVPSRotationType rotationTo, OFBool isFlippedTo)
| adjusts the displayed area coordinates for the rotation and flipping status of the image. More...

## Private Member Functions
DVPSDisplayedArea & | operator= (const DVPSDisplayedArea &source)
| undefined private assignment operator
void | switchHorizontalCorners ()
| swaps the horizontal (X) components of TLHC and BRHC
void | switchVerticalCorners ()
| swaps the vertical (Y) components of TLHC and BRHC
void | rotateAndFlipFromOrTo (DVPSRotationType rotation, OFBool isFlipped)
| adjusts the displayed area coordinates for rotation and flipping. More...

## Private Attributes
DVPSReferencedImage_PList | referencedImageList
| ReferencedImageSequence, Type 1c.
DcmSignedLong | displayedAreaTopLeftHandCorner
| VR=SL, VM=2, Type 1.
DcmSignedLong | displayedAreaBottomRightHandCorner
| VR=SL, VM=2, Type 1.
DcmCodeString | presentationSizeMode
| VR=CS, VM=1, Type 1.
DcmDecimalString | presentationPixelSpacing
| VR=DS, VM=2, Type 1c (required if presentationSizeMode is "TRUE SIZE")
DcmIntegerString | presentationPixelAspectRatio
| VR=IS, VM=2, Type 1c (required if presentationPixelSpacing is absent)
DcmFloatingPointSingle | presentationPixelMagnificationRatio
| VR=FL, VM=1, Type 1c (required if presentationSizeMode is "MAGNIFY")

## Detailed Description

an item of the displayed area selection sequence in a presentation state.

## Member Function Documentation

## ◆ addImageReference()

OFCondition DVPSDisplayedArea::addImageReference | ( | const char * | sopclassUID,
|  | const char * | instanceUID,
|  | unsigned long | frame,
|  | DVPSObjectApplicability | applicability
| ) |  |

add a new image reference.

Checks if the referenced SOP instance UID already exists in this sequence. If it exists, an error code is returned. Otherwise a new image reference is created and added to the ReferencedImageSequence.

Parameters

  sopclassUID | the SOP class UID of the image reference to be added.
  instanceUID | the SOP instance UID of the image reference to be added.
  frame | the frame number of the image reference (current image) to be added.
  applicability | the applicability of the image reference (DVPSB_currentFrame or DVPSB_currentImage)

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ canUseTrueSize()

OFBool DVPSDisplayedArea::canUseTrueSize | ( |  | ) |

checks if the TRUE SIZE mode is possible, i.e.

if pixel spacing is known.

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

## ◆ clone()

DVPSDisplayedArea* DVPSDisplayedArea::clone | ( |  | ) |
| inline

clone method.

Returns
  a pointer to a new DVPSDisplayedArea object containing a copy of this object.

## ◆ getDisplayedArea()

void DVPSDisplayedArea::getDisplayedArea | ( | Sint32 & | tlhcX,
|  | Sint32 & | tlhcY,
|  | Sint32 & | brhcX,
|  | Sint32 & | brhcY
| ) |  |

gets the displayed area top lefthand corner and bottom righthand corner.

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

## ◆ getPresentationPixelAspectRatio()

double DVPSDisplayedArea::getPresentationPixelAspectRatio | ( |  | ) |

gets the presentation pixel aspect ratio for this displayed area selection.

Pixel aspect ratio is defined here as the width of a pixel divided by the height of a pixel (x/y).

Returns
  pixel aspect ratio

## ◆ getPresentationPixelMagnificationRatio()

OFCondition DVPSDisplayedArea::getPresentationPixelMagnificationRatio | ( | double & | magnification | ) |

gets the presentation pixel magnification ratio for this displayed area if 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.

## ◆ getPresentationPixelSpacing()

OFCondition DVPSDisplayedArea::getPresentationPixelSpacing | ( | double & | x,
|  | double & | y
| ) |  |

gets the presentation pixel spacing for this displayed area if present.

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.

## ◆ getPresentationSizeMode()

DVPSPresentationSizeMode DVPSDisplayedArea::getPresentationSizeMode | ( |  | ) |

gets the presentation size mode for this displayed area selection.

Returns
  presentation size mode

## ◆ imageReferencesEmpty()

OFBool DVPSDisplayedArea::imageReferencesEmpty | ( |  | ) |
| inline

checks if the list of image references for this displayed area is empty.

Returns
  OFTrue if list of image references is empty, OFFalse otherwise.

## ◆ isApplicable()

OFBool DVPSDisplayedArea::isApplicable | ( | const char * | instanceUID,
|  | unsigned long | frame
| ) |  |

checks if this displayed area is applicable to the given image and frame.

Parameters

  instanceUID | SOP instance UID of the current image
  frame | number of the current frame

Returns
  OFTrue if applicable.

## ◆ matchesApplicability()

OFBool DVPSDisplayedArea::matchesApplicability | ( | const char * | instanceUID,
|  | unsigned long | frame,
|  | DVPSObjectApplicability | applicability
| ) |  |

checks if this displayed area matches exactly the applicability defined by the instanceUID, frame and applicability parameters.

Parameters

  instanceUID | SOP instance UID of the current image
  frame | number of the current frame

Returns
  OFTrue if matching.

## ◆ read()

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

reads an displayed area selection from a DICOM dataset.

The DICOM elements of the displayed area selection item are copied from the dataset to this object. The completeness of the item (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 item of the DisplayedAreaSelectionSequence from which the data is to be read

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ removeImageReference()

void DVPSDisplayedArea::removeImageReference | ( | DVPSReferencedSeries_PList & | allReferences,
|  | const char * | instanceUID,
|  | unsigned long | frame,
|  | unsigned long | numberOfFrames,
|  | DVPSObjectApplicability | applicability
| ) |  |

removes a reference to an image or frame.

If the current reference is empty ("global"), an explicit list of references is constructed from the list of series/instance references. The image or frame reference is removed from the total list of references in this object. If the only reference contained in this object is removed, the reference list becomes empty which means that the current reference becomes "global". This case must be handled by the caller.

Parameters

  allReferences | list of series/instance references registered for the presentation state.
  instanceUID | SOP instance UID of the current image
  frame | number of the current frame
  numberOfFrames | the number of frames of the current image
  applicability | the applicability of the image reference to be removed (DVPSB_currentFrame or DVPSB_currentImage)

## ◆ rotateAndFlip()

void DVPSDisplayedArea::rotateAndFlip | ( | DVPSRotationType | rotationFrom,
|  | OFBool | isFlippedFrom,
|  | DVPSRotationType | rotationTo,
|  | OFBool | isFlippedTo
| ) |  |

adjusts the displayed area coordinates for the rotation and flipping status of the image.

Parameters

  rotationFrom | previous rotation
  isFlippedFrom | previous flip status
  rotationTo | new rotation
  isFlippedTo | new flip status

## ◆ rotateAndFlipFromOrTo()

void DVPSDisplayedArea::rotateAndFlipFromOrTo | ( | DVPSRotationType | rotation,
|  | OFBool | isFlipped
| ) |  |
| private

adjusts the displayed area coordinates for rotation and flipping.

This method can either be used to adjust from unrotated/unflipped to a rotated/flipped status or back from this status to original.

Parameters

  rotation | rotation
  isFlipped | flip status

## ◆ setDisplayedArea()

OFCondition DVPSDisplayedArea::setDisplayedArea | ( | DVPSPresentationSizeMode | sizeMode,
|  | Sint32 | tlhcX,
|  | Sint32 | tlhcY,
|  | Sint32 | brhcX,
|  | Sint32 | brhcY,
|  | double | magnification = `1.0`
| ) |  |

sets the displayed area and size mode.

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.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setDisplayedAreaPixelAspectRatio() [1/2]

OFCondition DVPSDisplayedArea::setDisplayedAreaPixelAspectRatio | ( | const char * | ratio | ) |

sets the displayed area pixel spacing and removes any pixel spacing setting.

Parameters

  ratio | pixel aspect ratio in DICOM IS format.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setDisplayedAreaPixelAspectRatio() [2/2]

OFCondition DVPSDisplayedArea::setDisplayedAreaPixelAspectRatio | ( | double | ratio | ) |

sets the displayed area pixel spacing and removes any pixel spacing setting.

Pixel aspect ratio is defined here as the width of a pixel divided by the height of a pixel (x/y).

Parameters

  ratio | pixel aspect ratio

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setDisplayedAreaPixelSpacing() [1/2]

OFCondition DVPSDisplayedArea::setDisplayedAreaPixelSpacing | ( | const char * | spacing | ) |

sets the displayed area pixel spacing and removes any pixel aspect ratio setting.

Parameters

  spacing | vertical/horizontal spacing in DICOM DS format.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ setDisplayedAreaPixelSpacing() [2/2]

OFCondition DVPSDisplayedArea::setDisplayedAreaPixelSpacing | ( | double | spacingX,
|  | double | spacingY
| ) |  |

sets the displayed area pixel spacing and removes any pixel aspect ratio setting.

Parameters

  spacingX | horizontal pixel spacing in mm
  spacingY | vertical pixel spacing in mm

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ write()

OFCondition DVPSDisplayedArea::write | ( | DcmItem & | dset | ) |

writes the displayed area selection managed by this object to a DICOM dataset.

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

Parameters

  dset | the the item of the DisplayedAreaSelectionSequence to which the data is written

Returns
  EC_Normal if successful, an error code otherwise.

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

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

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