DCMTK Version 3.7.0 OFFIS DICOM Toolkit

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

the list of graphic layers contained in a presentation state (internal use only). More...

## Public Member Functions
| DVPSGraphicLayer_PList ()
| default constructor
| DVPSGraphicLayer_PList (const DVPSGraphicLayer_PList &copy)
| copy constructor
DVPSGraphicLayer_PList * | clone ()
| clone method. More...
virtual | ~DVPSGraphicLayer_PList ()
| destructor
OFCondition | read (DcmItem &dset)
| reads the Graphic Layer Sequence from a DICOM dataset. More...
OFCondition | write (DcmItem &dset)
| writes the Graphic Layer Sequence managed by this object to a DICOM dataset. More...
void | clear ()
| reset the object to initial state. More...
OFCondition | addGraphicLayer (const char *gLayer, const Sint32 gLayerOrder, const char *gLayerDescription=NULL)
| adds a new graphic layer to the list. 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 | size () const
| get number of graphic layer objects in this list. More...
void | sortGraphicLayers (Sint32 lowestLayer=1)
| sorts the graphic layers according to the graphic layer order. 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 | removeGraphicLayer (size_t idx)
| removes and deletes a graphic layer. More...
void | cleanupLayers (DVPSOverlayCurveActivationLayer_PList &activations, DVPSGraphicAnnotation_PList &annotations)
| removes and deletes all graphic layers for which no matching text, graphic, curve or overlay object exists. More...

## Private Member Functions
DVPSGraphicLayer_PList & | operator= (const DVPSGraphicLayer_PList &)
| private undefined assignment operator
DVPSGraphicLayer * | getGraphicLayer (size_t idx)
| gets the the graphic layer with the given index. More...

## Private Attributes
OFList< DVPSGraphicLayer * > | list_
| the list maintained by this object

## Detailed Description

the list of graphic layers contained in a presentation state (internal use only).

This class manages the data structures comprising the complete Graphic Layer Sequence in a Presentation State object.

## Member Function Documentation

## ◆ addGraphicLayer() [1/2]

OFCondition DVPSGraphicLayer_PList::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

## ◆ addGraphicLayer() [2/2]

OFCondition DVPSGraphicLayer_PList::addGraphicLayer | ( | const char * | gLayer,
|  | const Sint32 | gLayerOrder,
|  | const char * | gLayerDescription = `NULL`
| ) |  |

adds a new graphic layer to the list.

The recommended display value of the new graphic layer remains undefined and can be set later.

Parameters

  gLayer | name of the graphic layer. Must be unique within the sequence, i.e. no other graphic layer with the same name may exist, otherwise an error code is returned.
  gLayerOrder | graphic layer order of the new layer.
  gLayerDescription | (optional) description of the new layer. Default: description absent.

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ cleanupLayers()

void DVPSGraphicLayer_PList::cleanupLayers | ( | DVPSOverlayCurveActivationLayer_PList & | activations,
|  | DVPSGraphicAnnotation_PList & | annotations
| ) |  |

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

Called before writing a presentation state.

## ◆ clear()

void DVPSGraphicLayer_PList::clear | ( |  | ) |

reset the object to initial state.

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

## ◆ clone()

DVPSGraphicLayer_PList* DVPSGraphicLayer_PList::clone | ( |  | ) |
| inline

clone method.

Returns
  a pointer to a new DVPSGraphicLayer_PList object containing a deep copy of this object.

## ◆ exchangeGraphicLayers()

OFCondition DVPSGraphicLayer_PList::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

## ◆ getGraphicLayer()

DVPSGraphicLayer* DVPSGraphicLayer_PList::getGraphicLayer | ( | size_t | idx | ) |
| private

gets the 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
  pointer to the graphic layer

## ◆ getGraphicLayerDescription()

const char* DVPSGraphicLayer_PList::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 DVPSGraphicLayer_PList::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* DVPSGraphicLayer_PList::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 DVPSGraphicLayer_PList::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 DVPSGraphicLayer_PList::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

## ◆ haveGraphicLayerRecommendedDisplayValue()

OFBool DVPSGraphicLayer_PList::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

## ◆ read()

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

reads the Graphic Layer Sequence from a DICOM dataset.

The completeness of the sequence items (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 DICOM dataset from which the overlays are read

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ removeGraphicLayer()

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

removes and deletes a graphic layer.

Parameters

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

Returns
  EC_Normal upon success, an error code otherwise

## ◆ removeGraphicLayerRecommendedDisplayValue()

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

removes recommended display values for the given graphic layer.

Parameters

  rgb | if true, the RGB recommended display value is removed
  monochrome | if true the monochrome recommended display value is removed

## ◆ setGraphicLayerDescription()

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

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 DVPSGraphicLayer_PList::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 DVPSGraphicLayer_PList::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

## ◆ size()

size_t DVPSGraphicLayer_PList::size | ( |  | ) | const
| inline

get number of graphic layer objects in this list.

Returns
  the number of objects.

## ◆ sortGraphicLayers()

void DVPSGraphicLayer_PList::sortGraphicLayers | ( | Sint32 | lowestLayer = `1` | ) |

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.

Parameters

  lowestLayer | is the lowest number assigned to a layer during the renumbering.

## ◆ toBackGraphicLayer()

OFCondition DVPSGraphicLayer_PList::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 DVPSGraphicLayer_PList::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 DVPSGraphicLayer_PList::write | ( | DcmItem & | dset | ) |

writes the Graphic Layer Sequence 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 DICOM dataset to which the sequence 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/dvpsgll.h

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