DCMTK Version 3.7.0 OFFIS DICOM Toolkit

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

Class for image reference values. More...

Inheritance diagram for DSRImageReferenceValue:

## Public Member Functions
| DSRImageReferenceValue ()
| default constructor
| DSRImageReferenceValue (const OFString &sopClassUID, const OFString &sopInstanceUID, const OFBool check=OFTrue)
| constructor. More...
| DSRImageReferenceValue (const OFString &imageSOPClassUID, const OFString &imageSOPInstanceUID, const OFString &pstateSOPClassUID, const OFString &pstateSOPInstanceUID, const OFBool check=OFTrue)
| constructor. More...
| DSRImageReferenceValue (const DSRImageReferenceValue &referenceValue)
| copy constructor More...
| DSRImageReferenceValue (const DSRCompositeReferenceValue &imageReferenceValue, const DSRCompositeReferenceValue &pstateReferenceValue)
| copy constructor More...
virtual | ~DSRImageReferenceValue ()
| destructor
DSRImageReferenceValue & | operator= (const DSRImageReferenceValue &referenceValue)
| assignment operator More...
virtual void | clear ()
| clear all internal variables. More...
OFBool | isEqual (const DSRImageReferenceValue &referenceValue) const
| check whether values are "equal". More...
OFBool | isNotEqual (const DSRImageReferenceValue &referenceValue) const
| check whether values are "not equal". More...
virtual OFBool | isValid () const
| check whether the current image reference value is valid. More...
virtual OFBool | isShort (const size_t flags) const
| check whether the content is short. More...
virtual OFBool | isSegmentation () const
| check whether the current image reference points to a DICOM segmentation object More...
virtual OFBool | hasIconImage () const
| check whether an icon image is associated with this image reference. More...
virtual OFCondition | print (STD_NAMESPACE ostream &stream, const size_t flags) const
| print image reference. More...
virtual OFCondition | readXML (const DSRXMLDocument &doc, DSRXMLCursor cursor, const size_t flags)
| read image reference from XML document More...
virtual OFCondition | writeXML (STD_NAMESPACE ostream &stream, const size_t flags) const
| write image reference in XML format More...
virtual OFCondition | renderHTML (STD_NAMESPACE ostream &docStream, STD_NAMESPACE ostream &annexStream, size_t &annexNumber, const size_t flags, const char *urlPrefix=NULL) const
| render image reference value in HTML/XHTML format. More...
OFCondition | createIconImage (const OFString &filename, const unsigned long frame=0, const unsigned long width=64, const unsigned long height=64)
| create an icon image from the given DICOM image and associate it with this image reference. More...
OFCondition | createIconImage (DcmObject *object, const E_TransferSyntax xfer=EXS_Unknown, const unsigned long frame=0, const unsigned long width=64, const unsigned long height=64)
| create an icon image from the given DICOM image and associate it with this image reference. More...
OFCondition | createIconImage (const DicomImage *image, const unsigned long width=64, const unsigned long height=64)
| create an icon image from the given DICOM image and associate it with this image reference. More...
void | deleteIconImage ()
| delete the currently stored icon image, i.e. free the associated memory and "forget" the internal reference to it
const DicomImage * | getIconImage () const
| get reference to icon image associated with this image reference value (if any). More...
const DSRImageReferenceValue & | getValue () const
| get reference to image reference value More...
OFCondition | getValue (DSRImageReferenceValue &referenceValue) const
| get copy of image reference value More...
OFCondition | setValue (const DSRImageReferenceValue &referenceValue, const OFBool check=OFTrue)
| set image reference value. More...
const DSRCompositeReferenceValue & | getPresentationState () const
| get reference to presentation state object More...
OFCondition | setPresentationState (const DSRCompositeReferenceValue &pstateValue, const OFBool check=OFTrue)
| set reference to presentation state object. More...
const DSRCompositeReferenceValue & | getRealWorldValueMapping () const
| get reference to real world value mapping object More...
OFCondition | setRealWorldValueMapping (const DSRCompositeReferenceValue &mappingValue, const OFBool check=OFTrue)
| set reference to real world value mapping object. More...
DSRImageFrameList & | getFrameList ()
| get reference to list of referenced frame numbers. More...
const DSRImageFrameList & | getFrameList () const
| get read-only access to list of referenced frame numbers More...
DSRImageSegmentList & | getSegmentList ()
| get reference to list of referenced segment numbers. More...
const DSRImageSegmentList & | getSegmentList () const
| get read-only access to list of referenced segment numbers More...
OFBool | appliesToFrame (const Sint32 frameNumber) const
| check whether the image reference applies to a specific frame. More...
OFBool | appliesToSegment (const Uint16 segmentNumber) const
| check whether the image reference applies to a specific segment. More...
Public Member Functions inherited from DSRCompositeReferenceValue
| DSRCompositeReferenceValue ()
| default constructor
| DSRCompositeReferenceValue (const OFString &sopClassUID, const OFString &sopInstanceUID, const OFBool check=OFTrue)
| constructor More...
| DSRCompositeReferenceValue (const DSRCompositeReferenceValue &referenceValue)
| copy constructor More...
virtual | ~DSRCompositeReferenceValue ()
| destructor
DSRCompositeReferenceValue & | operator= (const DSRCompositeReferenceValue &referenceValue)
| assignment operator More...
OFBool | isEqual (const DSRCompositeReferenceValue &referenceValue) const
| check whether values are "equal" More...
OFBool | isNotEqual (const DSRCompositeReferenceValue &referenceValue) const
| check whether values are "not equal" More...
virtual OFBool | isEmpty () const
| check whether the current reference value is empty. More...
virtual OFBool | isComplete () const
| check whether the current reference value is complete, i.e. whether both mandatory UIDs are non-empty. More...
virtual OFCondition | readSequence (DcmItem &dataset, const DcmTagKey &tagKey, const OFString &type, const size_t flags)
| read referenced SOP sequence from dataset. More...
virtual OFCondition | writeSequence (DcmItem &dataset, const DcmTagKey &tagKey) const
| write referenced SOP sequence to dataset. More...
const OFString & | getSOPClassUID () const
| get SOP class UID More...
const OFString | getSOPClassName (const OFString &defaultName="unknown SOP Class UID") const
| get name associated with the SOP class UID (if any) More...
const OFString & | getSOPInstanceUID () const
| get SOP instance UID More...
const DSRCompositeReferenceValue & | getValue () const
| get reference to composite reference value More...
OFCondition | getValue (DSRCompositeReferenceValue &referenceValue) const
| get copy of composite reference value More...
OFCondition | setValue (const DSRCompositeReferenceValue &referenceValue, const OFBool check=OFTrue)
| set composite reference value. More...
OFCondition | setReference (const OFString &sopClassUID, const OFString &sopInstanceUID, const OFBool check=OFTrue)
| set SOP class UID and SOP instance UID value. More...
OFCondition | setReference (DcmItem &dataset, const OFBool check=OFTrue)
| set SOP class UID and SOP instance UID value from dataset. More...
OFCondition | setSOPClassUID (const OFString &sopClassUID, const OFBool check=OFTrue)
| set SOP class UID value. More...
OFCondition | setSOPClassUID (const DcmElement &delem, const unsigned long pos=0, const OFBool check=OFTrue)
| set SOP class UID value from element. More...
OFCondition | setSOPClassUID (DcmItem &dataset, const DcmTagKey &tagKey, const unsigned long pos=0, const OFBool check=OFTrue)
| set SOP class UID value from dataset. More...
OFCondition | setSOPInstanceUID (const OFString &sopInstanceUID, const OFBool check=OFTrue)
| set SOP instance UID value. More...
OFCondition | setSOPInstanceUID (const DcmElement &delem, const unsigned long pos=0, const OFBool check=OFTrue)
| set SOP instance UID value from element. More...
OFCondition | setSOPInstanceUID (DcmItem &dataset, const DcmTagKey &tagKey, const unsigned long pos=0, const OFBool check=OFTrue)
| set SOP instance UID value from dataset. More...

## Protected Member Functions
DSRImageReferenceValue * | getValuePtr ()
| get pointer to image reference value More...
virtual OFCondition | readItem (DcmItem &dataset, const size_t flags)
| read image reference value from dataset More...
virtual OFCondition | writeItem (DcmItem &dataset) const
| write image reference value to dataset More...
virtual OFBool | isSegmentationObject (const OFString &sopClassUID) const
| check whether the given SOP class UID refers to a DICOM segmentation object More...
virtual OFCondition | checkSOPClassUID (const OFString &sopClassUID, const OFBool reportWarnings=OFFalse) const
| check the specified SOP class UID for validity. More...
virtual OFCondition | checkPresentationState (const DSRCompositeReferenceValue &referenceValue, const OFBool reportWarnings=OFFalse) const
| check the given reference to a presentation state object for validity. More...
virtual OFCondition | checkRealWorldValueMapping (const DSRCompositeReferenceValue &referenceValue, const OFBool reportWarnings=OFFalse) const
| check the given reference to a real world value mapping object for validity. More...
OFCondition | checkListData (const OFString &sopClassUID, const DSRImageFrameList &frameList, const DSRImageSegmentList &segmentList, const OFBool reportWarnings=OFFalse) const
| check the given list of frame and segment numbers for validity. More...
OFCondition | checkCurrentValue (const OFBool reportWarnings=OFFalse) const
| check the currently stored image reference value for validity. More...
void | copyIconImage (DicomImage *image)
| copy the given icon image to replace the currently stored one. More...
Protected Member Functions inherited from DSRCompositeReferenceValue
DSRCompositeReferenceValue * | getValuePtr ()
| get pointer to reference value More...
virtual OFCondition | checkSOPInstanceUID (const OFString &sopInstanceUID, const OFBool reportWarnings=OFFalse) const
| check the specified SOP instance UID for validity. More...
OFCondition | checkCurrentValue (const OFBool reportWarnings=OFFalse) const
| check the currently stored reference value for validity. More...

## Private Attributes
DSRImageFrameList | FrameList
| list of referenced frame numbers (associated DICOM VR=IS, VM=1-n, type 1C)
DSRImageSegmentList | SegmentList
| list of referenced segment numbers (associated DICOM VR=US, VM=1-n, type 1C)
DSRCompositeReferenceValue | PresentationState
| composite reference value (UIDs) to presentation state object (optional)
DSRCompositeReferenceValue | RealWorldValueMapping
| composite reference value (UIDs) to real world value mapping object (optional)
DicomImage * | IconImage
| icon image from Icon Image Sequence (optional)

## Friends
class | DSRContentItem

## Additional Inherited Members
Protected Attributes inherited from DSRCompositeReferenceValue
OFString | SOPClassUID
| reference SOP class UID (VR=UI, type 1)
OFString | SOPInstanceUID
| reference SOP instance UID (VR=UI, type 1)

## Detailed Description

Class for image reference values.

## Constructor & Destructor Documentation

## ◆ DSRImageReferenceValue() [1/4]

DSRImageReferenceValue::DSRImageReferenceValue | ( | const OFString & | sopClassUID,
|  | const OFString & | sopInstanceUID,
|  | const OFBool | check = `OFTrue`
| ) |  |

constructor.

Accepts reference to an image object.

Parameters

  sopClassUID | referenced SOP class UID of the image object. (VR=UI, mandatory)
  sopInstanceUID | referenced SOP instance UID of the image object. (VR=UI, mandatory)
  check | if enabled, check 'sopClassUID' and 'sopInstanceUID' for validity before setting them. See checkXXX() for details. Empty values are never accepted.

## ◆ DSRImageReferenceValue() [2/4]

DSRImageReferenceValue::DSRImageReferenceValue | ( | const OFString & | imageSOPClassUID,
|  | const OFString & | imageSOPInstanceUID,
|  | const OFString & | pstateSOPClassUID,
|  | const OFString & | pstateSOPInstanceUID,
|  | const OFBool | check = `OFTrue`
| ) |  |

constructor.

Accepts reference to both an image and presentation state object.

Parameters

  imageSOPClassUID | referenced SOP class UID of the image object. (VR=UI, mandatory)
  imageSOPInstanceUID | referenced SOP instance UID of the image object. (VR=UI, mandatory)
  pstateSOPClassUID | referenced SOP class UID of the presentation state object. (VR=UI, optional)
  pstateSOPInstanceUID | referenced SOP instance UID of the presentation state object. (VR=UI, optional)
  check | if enabled, check all four UID values for validity before setting them. See checkXXX() for details. Empty values are never accepted.

## ◆ DSRImageReferenceValue() [3/4]

DSRImageReferenceValue::DSRImageReferenceValue | ( | const DSRImageReferenceValue & | referenceValue | ) |

copy constructor

Parameters

  referenceValue | image reference value to be copied (not checked !)

## ◆ DSRImageReferenceValue() [4/4]

DSRImageReferenceValue::DSRImageReferenceValue | ( | const DSRCompositeReferenceValue & | imageReferenceValue,
|  | const DSRCompositeReferenceValue & | pstateReferenceValue
| ) |  |

copy constructor

Parameters

  imageReferenceValue | reference to image object to be copied (not checked !)
  pstateReferenceValue | reference to presentation state object to be copied (not checked !)

## Member Function Documentation

## ◆ appliesToFrame()

OFBool DSRImageReferenceValue::appliesToFrame | ( | const Sint32 | frameNumber | ) | const

check whether the image reference applies to a specific frame.

The image reference applies to a frame (of multiframe images) if the list of referenced frame numbers is empty or the frame number is part of the list.

Parameters

  frameNumber | number of the frame to be checked

Returns
  OFTrue if reference applies to the specified frame, OFFalse otherwise

## ◆ appliesToSegment()

OFBool DSRImageReferenceValue::appliesToSegment | ( | const Uint16 | segmentNumber | ) | const

check whether the image reference applies to a specific segment.

The image reference applies to a segment (of a segmentation image) if the list of referenced segment numbers is empty or the segment number is part of the list.

Parameters

  segmentNumber | number of the segment to be checked

Returns
  OFTrue if reference applies to the specified segment, OFFalse otherwise

## ◆ checkCurrentValue()

OFCondition DSRImageReferenceValue::checkCurrentValue | ( | const OFBool | reportWarnings = `OFFalse` | ) | const
| protected

check the currently stored image reference value for validity.

See above checkXXX() methods and DSRCompositeReferenceValue::checkCurrentValue() for details.

Parameters

  reportWarnings | if enabled, report a warning message on each deviation from an expected value to the logger

Returns
  status, EC_Normal if current value is valid, an error code otherwise

## ◆ checkListData()

OFCondition DSRImageReferenceValue::checkListData | ( | const OFString & | sopClassUID,
|  | const DSRImageFrameList & | frameList,
|  | const DSRImageSegmentList & | segmentList,
|  | const OFBool | reportWarnings = `OFFalse`
| ) |  | const
| protected

check the given list of frame and segment numbers for validity.

Either both lists have to be empty or only one of them has to be non-empty, because otherwise the "type 1C" condition would be violated. Also the list of segment numbers should only be non-empty for one of the DICOM segmentation objects (see isSegmentationObject()).

Parameters

  sopClassUID | SOP class UID of the image object to be checked
  frameList | list of referenced frame numbers to be checked
  segmentList | list of referenced segment numbers to be checked
  reportWarnings | if enabled, report a warning message to the logger

Returns
  status, EC_Normal if checked data is valid, an error code otherwise

## ◆ checkPresentationState()

virtual OFCondition DSRImageReferenceValue::checkPresentationState | ( | const DSRCompositeReferenceValue & | referenceValue,
|  | const OFBool | reportWarnings = `OFFalse`
| ) |  | const
| protected virtual

check the given reference to a presentation state object for validity.

The reference is "valid" if both UIDs are empty or both are not empty and SOP class UID refers to a softcopy presentation state object (see DSRTypes::E_PresentationStateType for a list of supported SOP classes).

Parameters

  referenceValue | value to be checked
  reportWarnings | if enabled, report warning messages to the logger

Returns
  status, EC_Normal if value is valid, an error code otherwise

## ◆ checkRealWorldValueMapping()

virtual OFCondition DSRImageReferenceValue::checkRealWorldValueMapping | ( | const DSRCompositeReferenceValue & | referenceValue,
|  | const OFBool | reportWarnings = `OFFalse`
| ) |  | const
| protected virtual

check the given reference to a real world value mapping object for validity.

The reference is "valid" if both UIDs are empty or both are not empty and SOP class UID refers to the "Real World Value Mapping Storage SOP Class".

Parameters

  referenceValue | value to be checked
  reportWarnings | if enabled, report warning messages to the logger

Returns
  status, EC_Normal if value is valid, an error code otherwise

## ◆ checkSOPClassUID()

virtual OFCondition DSRImageReferenceValue::checkSOPClassUID | ( | const OFString & | sopClassUID,
|  | const OFBool | reportWarnings = `OFFalse`
| ) |  | const
| protected virtual

check the specified SOP class UID for validity.

This method further specializes the checks performed in the base class DSRCompositeReferenceValue. All image and segmentation SOP classes that are defined in DICOM PS 3.6-2023c are allowed.

Parameters

  sopClassUID | SOP class UID to be checked
  reportWarnings | if enabled, report warning messages to the logger

Returns
  status, EC_Normal if value is valid, an error code otherwise

Reimplemented from DSRCompositeReferenceValue.

## ◆ clear()

virtual void DSRImageReferenceValue::clear | ( |  | ) |
| virtual

clear all internal variables.

Since an empty image reference is invalid the reference becomes invalid afterwards.

Reimplemented from DSRCompositeReferenceValue.

Reimplemented in DSRImageTreeNode.

## ◆ copyIconImage()

void DSRImageReferenceValue::copyIconImage | ( | DicomImage * | image | ) |
| protected

copy the given icon image to replace the currently stored one.

The currently stored icon image is always deleted first.

Parameters

  image | pointer to the icon image to be copied (if not NULL)

## ◆ createIconImage() [1/3]

OFCondition DSRImageReferenceValue::createIconImage | ( | const DicomImage * | image,
|  | const unsigned long | width = `64`,
|  | const unsigned long | height = `64`
| ) |  |

create an icon image from the given DICOM image and associate it with this image reference.

According to the DICOM standard, this icon image should be representative of the referenced image and the size of the icon image "may be no greater than 128 rows by 128 columns". Color images are converted automatically to the photometric interpretation "PALETTE COLOR" (with 256 colors) when written to the DICOM dataset. Please note that this icon image is only used in readItem() and writeItem() but not in the other input/output methods.

Parameters

  image | pointer to DICOM image to be used to create the icon image. Only single frame images should be passed since only the first frame is used.
  width | width of the icon image (in pixels). If 0 this value will be calculated automatically based on the given 'height'.
  height | height of the icon image (in pixels). If 0 this value will be calculated automatically based on the given 'width'.

Returns
  status, EC_Normal if successful, an error code otherwise

## ◆ createIconImage() [2/3]

OFCondition DSRImageReferenceValue::createIconImage | ( | const OFString & | filename,
|  | const unsigned long | frame = `0`,
|  | const unsigned long | width = `64`,
|  | const unsigned long | height = `64`
| ) |  |

create an icon image from the given DICOM image and associate it with this image reference.

According to the DICOM standard, this icon image should be representative of the referenced image and the size of the icon image "may be no greater than 128 rows by 128 columns". For monochrome images, either the first stored or an automatically computed min-max VOI window is selected. Color images are converted automatically to the photometric interpretation "PALETTE COLOR" (with 256 colors) when written to the DICOM dataset. Please note that this icon image is only used in readItem() and writeItem() but not in the other input/output methods.

Parameters

  filename | name of the DICOM image file to be used to create the icon image
  frame | number of the frame to be used to create the icon image (0 = 1st frame)
  width | width of the icon image (in pixels). If 0 this value will be calculated automatically based on the given 'height'.
  height | height of the icon image (in pixels). If 0 this value will be calculated automatically based on the given 'width'.

Returns
  status, EC_Normal if successful, an error code otherwise

## ◆ createIconImage() [3/3]

OFCondition DSRImageReferenceValue::createIconImage | ( | DcmObject * | object,
|  | const E_TransferSyntax | xfer = `EXS_Unknown`,
|  | const unsigned long | frame = `0`,
|  | const unsigned long | width = `64`,
|  | const unsigned long | height = `64`
| ) |  |

create an icon image from the given DICOM image and associate it with this image reference.

According to the DICOM standard, this icon image should be representative of the referenced image and the size of the icon image "may be no greater than 128 rows by 128 columns". For monochrome images, either the first stored or an automatically computed min-max VOI window is selected. Color images are converted automatically to the photometric interpretation "PALETTE COLOR" (with 256 colors) when written to the DICOM dataset. Please note that this icon image is only used in readItem() and writeItem() but not in the other input/output methods.

Parameters

  object | pointer to DICOM data structures (fileformat, dataset or item) that contain the DICOM image to be used to create the icon image
  xfer | transfer syntax of the 'object'. In case of a fileformat or dataset, the value EXS_Unknown is also allowed.
  frame | number of the frame to be used to create the icon image (0 = 1st frame)
  width | width of the icon image (in pixels). If 0 this value will be calculated automatically based on the given 'height'.
  height | height of the icon image (in pixels). If 0 this value will be calculated automatically based on the given 'width'.

Returns
  status, EC_Normal if successful, an error code otherwise

## ◆ getFrameList() [1/2]

DSRImageFrameList& DSRImageReferenceValue::getFrameList | ( |  | ) |
| inline

get reference to list of referenced frame numbers.

According to the DICOM standard, this list is required if the referenced image has multiple frames, and the reference does not apply to all frames and the list of referenced segment numbers is empty/absent.

Returns
  reference to frame list

## ◆ getFrameList() [2/2]

const DSRImageFrameList& DSRImageReferenceValue::getFrameList | ( |  | ) | const
| inline

get read-only access to list of referenced frame numbers

Returns
  constant reference to frame list

## ◆ getIconImage()

const DicomImage* DSRImageReferenceValue::getIconImage | ( |  | ) | const
| inline

get reference to icon image associated with this image reference value (if any).

Please note that the icon image might be invalid even if the pointer is not NULL. Therefore, the DicomImage::getStatus() method should always be called to check the status of the image.

Returns
  reference to icon image or NULL if none is present

## ◆ getPresentationState()

const DSRCompositeReferenceValue& DSRImageReferenceValue::getPresentationState | ( |  | ) | const
| inline

get reference to presentation state object

Returns
  reference to presentation state object (might be empty or invalid)

## ◆ getRealWorldValueMapping()

const DSRCompositeReferenceValue& DSRImageReferenceValue::getRealWorldValueMapping | ( |  | ) | const
| inline

get reference to real world value mapping object

Returns
  reference to real world value mapping object (might be empty or invalid)

## ◆ getSegmentList() [1/2]

DSRImageSegmentList& DSRImageReferenceValue::getSegmentList | ( |  | ) |
| inline

get reference to list of referenced segment numbers.

According to the DICOM standard, this list is required if the referenced image is a segmentation object, and the reference does not apply to all segments and the list of referenced frame numbers is empty/absent.

Returns
  reference to segment list

## ◆ getSegmentList() [2/2]

const DSRImageSegmentList& DSRImageReferenceValue::getSegmentList | ( |  | ) | const
| inline

get read-only access to list of referenced segment numbers

Returns
  constant reference to segment list

## ◆ getValue() [1/2]

const DSRImageReferenceValue& DSRImageReferenceValue::getValue | ( |  | ) | const
| inline

get reference to image reference value

Returns
  reference to image reference value

## ◆ getValue() [2/2]

OFCondition DSRImageReferenceValue::getValue | ( | DSRImageReferenceValue & | referenceValue | ) | const

get copy of image reference value

Parameters

  referenceValue | reference to variable in which the value should be stored

Returns
  status, EC_Normal if successful, an error code otherwise

## ◆ getValuePtr()

DSRImageReferenceValue* DSRImageReferenceValue::getValuePtr | ( |  | ) |
| inline protected

get pointer to image reference value

Returns
  pointer to image reference value (never NULL)

## ◆ hasIconImage()

virtual OFBool DSRImageReferenceValue::hasIconImage | ( |  | ) | const
| virtual

check whether an icon image is associated with this image reference.

This method does not check whether the icon image is valid.

Returns
  OFTrue if image reference has an icon image, OFFalse otherwise

## ◆ isEqual()

OFBool DSRImageReferenceValue::isEqual | ( | const DSRImageReferenceValue & | referenceValue | ) | const

check whether values are "equal".

Please note that the optional icon image is not used for comparing the two values.

Parameters

  referenceValue | image reference value that should be compared to the current one

Returns
  OFTrue if both image reference values are equal, OFFalse otherwise

## ◆ isNotEqual()

OFBool DSRImageReferenceValue::isNotEqual | ( | const DSRImageReferenceValue & | referenceValue | ) | const

check whether values are "not equal".

Please note that the optional icon image is not used for comparing the two values.

Parameters

  referenceValue | image reference value that should be compared to the current one

Returns
  OFTrue if both image reference values are not equal, OFFalse otherwise

## ◆ isSegmentation()

virtual OFBool DSRImageReferenceValue::isSegmentation | ( |  | ) | const
| virtual

check whether the current image reference points to a DICOM segmentation object

Returns
  OFTrue if a segmentation object is referenced, OFFalse otherwise

## ◆ isSegmentationObject()

virtual OFBool DSRImageReferenceValue::isSegmentationObject | ( | const OFString & | sopClassUID | ) | const
| protected virtual

check whether the given SOP class UID refers to a DICOM segmentation object

Parameters

  sopClassUID | SOP class UID to be checked

Returns
  OFTrue if the UID refers to a segmentation object, OFFalse otherwise

## ◆ isShort()

virtual OFBool DSRImageReferenceValue::isShort | ( | const size_t | flags | ) | const
| virtual

check whether the content is short.

This method is used to check whether the rendered output of this content item can be expanded inline or not (used for renderHTML()).

Parameters

  flags | flag used to customize the output (see DSRTypes::HF_xxx)

Returns
  OFTrue if the content is short, OFFalse otherwise

Reimplemented in DSRImageTreeNode.

## ◆ isValid()

virtual OFBool DSRImageReferenceValue::isValid | ( |  | ) | const
| virtual

check whether the current image reference value is valid.

The reference value is valid if both SOP class UID and SOP instance UID are valid (see checkSOPClassUID() and checkSOPInstanceUID() for details), as well as the optional presentation state and real world value mapping objects (see checkPresentationState() and checkRealWorldValueMapping(), respectively). Also the presence of the optional list of frame and segment numbers is checked using checkListData().

Returns
  OFTrue if reference value is valid, OFFalse otherwise

Reimplemented from DSRCompositeReferenceValue.

Reimplemented in DSRImageTreeNode.

## ◆ operator=()

DSRImageReferenceValue& DSRImageReferenceValue::operator= | ( | const DSRImageReferenceValue & | referenceValue | ) |

assignment operator

Parameters

  referenceValue | image reference value to be copied (not checked !)

Returns
  reference to this image reference value after 'referenceValue' has been copied

## ◆ print()

virtual OFCondition DSRImageReferenceValue::print | ( | STD_NAMESPACE ostream & | stream,
|  | const size_t | flags
| ) |  | const
| virtual

print image reference.

The output of a typical image reference value looks like this: (CT image,"1.2.3") or (CT image,"1.2.3"),(GSPS,"1.2.3.4") if a presentation state is present. If the SOP class UID is unknown, the UID is printed instead of the related name. Also, the list of referenced frame/segment numbers is shown, but not the two UIDs of the real world value mapping object (if referenced). The optional icon image is never shown.

Parameters

  stream | output stream to which the image reference value should be printed
  flags | flag used to customize the output (see DSRTypes::PF_xxx)

Returns
  status, EC_Normal if successful, an error code otherwise

Reimplemented from DSRCompositeReferenceValue.

Reimplemented in DSRImageTreeNode.

## ◆ readItem()

virtual OFCondition DSRImageReferenceValue::readItem | ( | DcmItem & | dataset,
|  | const size_t | flags
| ) |  |
| protected virtual

read image reference value from dataset

Parameters

  dataset | DICOM dataset from which the value should be read
  flags | flag used to customize the reading process (see DSRTypes::RF_xxx)

Returns
  status, EC_Normal if successful, an error code otherwise

Reimplemented from DSRCompositeReferenceValue.

## ◆ readXML()

virtual OFCondition DSRImageReferenceValue::readXML | ( | const DSRXMLDocument & | doc,
|  | DSRXMLCursor | cursor,
|  | const size_t | flags
| ) |  |
| virtual

read image reference from XML document

Parameters

  doc | document containing the XML file content
  cursor | cursor pointing to the starting node
  flags | flag used to customize the reading process (see DSRTypes::XF_xxx)

Returns
  status, EC_Normal if successful, an error code otherwise

Reimplemented from DSRCompositeReferenceValue.

## ◆ renderHTML()

virtual OFCondition DSRImageReferenceValue::renderHTML | ( | STD_NAMESPACE ostream & | docStream,
|  | STD_NAMESPACE ostream & | annexStream,
|  | size_t & | annexNumber,
|  | const size_t | flags,
|  | const char * | urlPrefix = `NULL`
| ) |  | const
| virtual

render image reference value in HTML/XHTML format.

Please note that the optional icon image is never shown in the rendered output.

Parameters

  docStream | output stream to which the main HTML/XHTML document is written
  annexStream | output stream to which the HTML/XHTML document annex is written
  annexNumber | reference to the variable where the current annex number is stored. Value is increased automatically by 1 after a new entry has been added.
  flags | flag used to customize the output (see DSRTypes::HF_xxx)
  urlPrefix | optional URL prefix used for hyperlink to referenced composite object

Note
  Please note that using parameter 'urlPrefix' can lead to security issues, as an attacker could misuse it to potentially inject dangerous content into the HTML/XHTML output. The value of this parameter is not checked. This is also true for derived classes.

Returns
  status, EC_Normal if successful, an error code otherwise

Reimplemented from DSRCompositeReferenceValue.

## ◆ setPresentationState()

OFCondition DSRImageReferenceValue::setPresentationState | ( | const DSRCompositeReferenceValue & | pstateValue,
|  | const OFBool | check = `OFTrue`
| ) |  |

set reference to presentation state object.

Before setting the reference, it is usually checked. If the value is invalid, the current value is not replaced and remains unchanged.

Parameters

  pstateValue | value to be set
  check | If enabled, check value for validity before setting it. See checkPresentationState() for details. Empty UID values are accepted for disabling the optional presentation state.

Returns
  status, EC_Normal if successful, an error code otherwise

## ◆ setRealWorldValueMapping()

OFCondition DSRImageReferenceValue::setRealWorldValueMapping | ( | const DSRCompositeReferenceValue & | mappingValue,
|  | const OFBool | check = `OFTrue`
| ) |  |

set reference to real world value mapping object.

Before setting the reference, it is usually checked. If the value is invalid, the current value is not replaced and remains unchanged.

Parameters

  mappingValue | value to be set
  check | If enabled, check value for validity before setting it. See checkRealWorldValueMapping() for details. Empty UID values are accepted for disabling the optional presentation state.

Returns
  status, EC_Normal if successful, an error code otherwise

## ◆ setValue()

OFCondition DSRImageReferenceValue::setValue | ( | const DSRImageReferenceValue & | referenceValue,
|  | const OFBool | check = `OFTrue`
| ) |  |

set image reference value.

Before setting the reference, it is usually checked. If the value is invalid, the current value is not replaced and remains unchanged.

Parameters

  referenceValue | value to be set
  check | if enabled, check value for validity before setting it. See checkXXX() for details. Empty values are never accepted.

Returns
  status, EC_Normal if successful, an error code otherwise

## ◆ writeItem()

virtual OFCondition DSRImageReferenceValue::writeItem | ( | DcmItem & | dataset | ) | const
| protected virtual

write image reference value to dataset

Parameters

  dataset | DICOM dataset to which the value should be written

Returns
  status, EC_Normal if successful, an error code otherwise

Reimplemented from DSRCompositeReferenceValue.

## ◆ writeXML()

virtual OFCondition DSRImageReferenceValue::writeXML | ( | STD_NAMESPACE ostream & | stream,
|  | const size_t | flags
| ) |  | const
| virtual

write image reference in XML format

Parameters

  stream | output stream to which the XML document is written
  flags | flag used to customize the output (see DSRTypes::XF_xxx)

Returns
  status, EC_Normal if successful, an error code otherwise

Reimplemented from DSRCompositeReferenceValue.

Reimplemented in DSRImageTreeNode.

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

- dcmsr/include/dcmtk/dcmsr/dsrimgvl.h

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