DCMTK Version 3.7.0 OFFIS DICOM Toolkit

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

Class to handle a single overlay plane. More...

## Public Member Functions
| DiOverlayPlane (const DiDocument *docu, const unsigned int group, Uint16 alloc, const Uint16 stored, const Uint16 high)
| constructor More...
| DiOverlayPlane (const unsigned int group, const Sint16 left_pos, const Sint16 top_pos, const Uint16 columns, const Uint16 rows, const DcmOverlayData &data, const DcmLongString &label, const DcmLongString &description, const EM_Overlay mode)
| constructor, additional More...
| DiOverlayPlane (DiOverlayPlane *plane, const unsigned int bit, const Uint16 *data, Uint16 *temp, const Uint16 width, const Uint16 height, const Uint16 columns, const Uint16 rows)
| constructor, copy More...
| ~DiOverlayPlane ()
| destructor
Sint16 | getLeft (const Sint32 left_pos=0) const
| get x-coordinate of overlay plane origin More...
Sint16 | getTop (const Sint32 top_pos=0) const
| get y-coordinate of overlay plane origin More...
Uint16 | getWidth () const
| get width of overlay plane More...
Uint16 | getHeight () const
| get height of overlay plane More...
Uint16 | getRight (const Sint32 left_pos=0) const
| get right border of overlay plane origin More...
Uint16 | getBottom (const Sint32 top_pos=0) const
| get bottom border of overlay plane origin More...
int | isValid () const
| check whether overlay plane is valid More...
int | isVisible () const
| check whether overlay plane is visible More...
void | show ()
| make overlay plane visible
void | hide ()
| make overlay plane invisible
void | place (const signed int left_pos, const signed int top_pos)
| move overlay plane to a new place More...
void | setScaling (const double xfactor, const double yfactor)
| set scaling factor in x- and y-direction More...
void | setFlipping (const int horz, const int vert, const signed long columns, const signed long rows)
| set flipping More...
void | setRotation (const int degree, const signed long left_pos, const signed long top_pos, const Uint16 columns, const Uint16 rows)
| set rotation More...
void | show (const double fore, const double thresh, const EM_Overlay mode)
| make overlay plane visible and set parameters More...
int | show (const Uint16 pvalue)
| make overlay plane visible and set p-value. More...
unsigned long | getNumberOfFrames () const
| get number of frames More...
double | getForeground () const
| get foreground color of the plane More...
double | getThreshold () const
| get threshold value of the plane More...
Uint16 | getPValue () const
| get p-value of the plane. More...
EM_Overlay | getMode () const
| get overlay plane mode More...
int | isMultiframe () const
| check whether overlay plane is a multi-frame overlay. More...
int | isEmbedded () const
| check whether overlay plane is embedded in the pixel data More...
const char * | getLabel () const
| get label of overlay plane More...
const char * | getDescription () const
| get description of overlay plane More...
Uint16 | getGroupNumber () const
| get group number of overlay plane More...
void * | getData (const unsigned long frame, const Uint16 xmin, const Uint16 ymin, const Uint16 xmax, const Uint16 ymax, const int bits, const Uint16 fore, const Uint16 back, const OFBool useOrigin=OFTrue)
| get overlay plane data as an array of 1/8/16 bit values. More...
unsigned long | create6xxx3000Data (Uint8 *&buffer, unsigned int &width, unsigned int &height, unsigned long &frames)
| create overlay plane data in (6xxx,3000) format. More...
int | reset (const unsigned long frame)
| reset internal 'cursor' to the beginning of the specified frame More...
int | getNextBit ()
| get value of the current overlay plane bit and move 'cursor' to the next position More...
void | setStart (const Uint16 x, const Uint16 y, const OFBool useOrigin=OFTrue)
| set internal 'cursor' to a specific position More...

## Protected Attributes
Uint32 | NumberOfFrames
| number of frames
Uint16 | ImageFrameOrigin
| number of starting frame
Uint32 | FirstFrame
| first frame to be processed (from DicomImage constructor)
Sint16 | Top
| y-coordinate of overlay plane's origin
Sint16 | Left
| x-coordinate of overlay plane's origin
Uint16 | Height
| visible height
Uint16 | Width
| visible width
Uint16 | Rows
| number of (stored) rows
Uint16 | Columns
| number of (stored) columns
Uint16 | BitsAllocated
| number of allocated bits per pixel
Uint16 | BitPosition
| position of overlay plane bit
double | Foreground
| "color" of overlay plane (in percent: '0.0' = dark, '1.0' = bright)
double | Threshold
| threshold value used for "threshold replace"
Uint16 | PValue
| P-value used for bitmap shutters.
EM_Overlay | Mode
| current overlay mode
EM_Overlay | DefaultMode
| default (stored) overlay mode
OFString | Label
| label of overlay plane
OFString | Description
| textual description of overlay plane
Uint16 | GroupNumber
| group number of overlay plane
int | Valid
| validity status
int | Visible
| visibility status

## Private Attributes
unsigned long | BitPos
| current bit position
unsigned long | StartBitPos
| starting bit position of current frame
unsigned int | StartLeft
| x-coordinate of first pixel in surrounding memory buffer
unsigned int | StartTop
| y-coordinate of first pixel in surrounding memory buffer
int | MultiframeOverlay
| true if overlay plane is a multi-frame overlay
int | EmbeddedData
| true if overlay data is embedded in pixel data
const Uint16 * | Ptr
| pointer to current element of 'Data'
const Uint16 * | StartPtr
| pointer to starting element of current frame
const Uint16 * | Data
| pointer to overlay data (standalone) or pixel data (embedded)

## Detailed Description

Class to handle a single overlay plane.

## Constructor & Destructor Documentation

## ◆ DiOverlayPlane() [1/3]

DiOverlayPlane::DiOverlayPlane | ( | const DiDocument * | docu,
|  | const unsigned int | group,
|  | Uint16 | alloc,
|  | const Uint16 | stored,
|  | const Uint16 | high
| ) |  |

constructor

Parameters

  docu | pointer to dataset (encapsulated)
  group | group number of the overlay plane
  alloc | value for bits allocated of the surrounding image
  stored | value for bits stored of the surrounding image
  high | value for high bit of the surrounding image

## ◆ DiOverlayPlane() [2/3]

DiOverlayPlane::DiOverlayPlane | ( | const unsigned int | group,
|  | const Sint16 | left_pos,
|  | const Sint16 | top_pos,
|  | const Uint16 | columns,
|  | const Uint16 | rows,
|  | const DcmOverlayData & | data,
|  | const DcmLongString & | label,
|  | const DcmLongString & | description,
|  | const EM_Overlay | mode
| ) |  |

constructor, additional

Parameters

  group | group number of the overlay plane
  left_pos | x-coordinate of the plane origin
  top_pos | y-coordinate of the plane origin
  columns | width of the overlay plane
  rows | height of the overlay plane
  data | element containing the plane data
  label | element containing the plane label
  description | element containing the plane description
  mode | overlay plane mode

## ◆ DiOverlayPlane() [3/3]

DiOverlayPlane::DiOverlayPlane | ( | DiOverlayPlane * | plane,
|  | const unsigned int | bit,
|  | const Uint16 * | data,
|  | Uint16 * | temp,
|  | const Uint16 | width,
|  | const Uint16 | height,
|  | const Uint16 | columns,
|  | const Uint16 | rows
| ) |  |

constructor, copy

Parameters

  plane | reference overlay plane to be copied
  bit | position of the plane bit
  data | pointer to buffer for plane data
  temp | temporary buffer used to extract plane information
  width | width of the array where the plane is stored
  height | height of the array where the plane is stored
  columns | width of the overlay plane
  rows | height of the overlay plane

## Member Function Documentation

## ◆ create6xxx3000Data()

unsigned long DiOverlayPlane::create6xxx3000Data | ( | Uint8 *& | buffer,
|  | unsigned int & | width,
|  | unsigned int & | height,
|  | unsigned long & | frames
| ) |  |

create overlay plane data in (6xxx,3000) format.

(1 bit allocated and stored, foreground color is 1, background color is 0, data is 16 bit padded - even length) Memory isn't handled internally and must therefore be deleted from calling program.

Parameters

  buffer | stores pointer to overlay data (memory is allocated internally)
  width | returns width of overlay plane (in pixels)
  height | returns height of overlay plane (in pixels)
  frames | returns number of frames (multiple overlay frames possible!)

Returns
  number of bytes allocated for the 'buffer' if successful, 0 otherwise

## ◆ getBottom()

Uint16 DiOverlayPlane::getBottom | ( | const Sint32 | top_pos = `0` | ) | const
| inline

get bottom border of overlay plane origin

Parameters

  top_pos | offset to be subtracted from the actual value (optional).

Returns
  bottom border of overlay plane origin. Negative values are set to 0.

## ◆ getData()

void* DiOverlayPlane::getData | ( | const unsigned long | frame,
|  | const Uint16 | xmin,
|  | const Uint16 | ymin,
|  | const Uint16 | xmax,
|  | const Uint16 | ymax,
|  | const int | bits,
|  | const Uint16 | fore,
|  | const Uint16 | back,
|  | const OFBool | useOrigin = `OFTrue`
| ) |  |

get overlay plane data as an array of 1/8/16 bit values.

Overlay plane is clipped to the area specified by the four min/max coordinates. Memory isn't handled internally and must therefore be deleted from calling program.

Parameters

  frame | number of frame
  xmin | x-coordinate of the top left hand corner
  ymin | y-coordinate of the top left hand corner
  xmax | x-coordinate of the bottom right hand corner
  ymax | y-coordinate of the bottom right hand corner
  bits | number of bits (stored) in the resulting array
  fore | foreground color used for the plane (0..2^bits-1)
  back | transparent background color (0..2^bits-1)
  useOrigin | use overlay plane's origin for calculating the start position if true (default), ignore it otherwise

Returns
  pointer to pixel data if successful, NULL otherwise

## ◆ getDescription()

const char* DiOverlayPlane::getDescription | ( |  | ) | const
| inline

get description of overlay plane

Returns
  description if successful, NULL otherwise

## ◆ getForeground()

double DiOverlayPlane::getForeground | ( |  | ) | const
| inline

get foreground color of the plane

Returns
  foreground color (in percent: 0.0-1.0)

## ◆ getGroupNumber()

Uint16 DiOverlayPlane::getGroupNumber | ( |  | ) | const
| inline

get group number of overlay plane

Returns
  group number (0x6000-0x60ff)

## ◆ getHeight()

Uint16 DiOverlayPlane::getHeight | ( |  | ) | const
| inline

get height of overlay plane

Returns
  height of overlay plane

## ◆ getLabel()

const char* DiOverlayPlane::getLabel | ( |  | ) | const
| inline

get label of overlay plane

Returns
  label if successful, NULL otherwise

## ◆ getLeft()

Sint16 DiOverlayPlane::getLeft | ( | const Sint32 | left_pos = `0` | ) | const
| inline

get x-coordinate of overlay plane origin

Parameters

  left_pos | offset to be subtracted from the actual value (optional)

Returns
  x-coordinate of overlay plane origin

## ◆ getMode()

EM_Overlay DiOverlayPlane::getMode | ( |  | ) | const
| inline

get overlay plane mode

Returns
  overlay plane mode

## ◆ getNextBit()

int DiOverlayPlane::getNextBit | ( |  | ) |
| inline

get value of the current overlay plane bit and move 'cursor' to the next position

Returns
  true if plane bit is set, false otherwise

References BitPos, BitPosition, BitsAllocated, Ptr, and StartPtr.

## ◆ getNumberOfFrames()

unsigned long DiOverlayPlane::getNumberOfFrames | ( |  | ) | const
| inline

get number of frames

Returns
  number of frames

## ◆ getPValue()

Uint16 DiOverlayPlane::getPValue | ( |  | ) | const
| inline

get p-value of the plane.

Only valid for bitmap shutters.

Returns
  p-value (0..65535)

## ◆ getRight()

Uint16 DiOverlayPlane::getRight | ( | const Sint32 | left_pos = `0` | ) | const
| inline

get right border of overlay plane origin

Parameters

  left_pos | offset to be subtracted from the actual value (optional).

Returns
  right border of overlay plane origin. Negative values are set to 0.

## ◆ getThreshold()

double DiOverlayPlane::getThreshold | ( |  | ) | const
| inline

get threshold value of the plane

Returns
  threshold value (in percent: 0.0-1.0)

## ◆ getTop()

Sint16 DiOverlayPlane::getTop | ( | const Sint32 | top_pos = `0` | ) | const
| inline

get y-coordinate of overlay plane origin

Parameters

  top_pos | offset to be subtracted from the actual value (optional)

Returns
  y-coordinate of overlay plane origin

## ◆ getWidth()

Uint16 DiOverlayPlane::getWidth | ( |  | ) | const
| inline

get width of overlay plane

Returns
  width of overlay plane

## ◆ isEmbedded()

int DiOverlayPlane::isEmbedded | ( |  | ) | const
| inline

check whether overlay plane is embedded in the pixel data

Returns
  true if plane is embedded, false otherwise

## ◆ isMultiframe()

int DiOverlayPlane::isMultiframe | ( |  | ) | const
| inline

check whether overlay plane is a multi-frame overlay.

(see DICOM PS3.3 for definition of "Multi-frame Overlay")

Returns
  true if plane is a multi-frame overlay, false otherwise

## ◆ isValid()

int DiOverlayPlane::isValid | ( |  | ) | const
| inline

check whether overlay plane is valid

Returns
  true if plane is valid, false otherwise

## ◆ isVisible()

int DiOverlayPlane::isVisible | ( |  | ) | const
| inline

check whether overlay plane is visible

Returns
  true if plane is visible, false otherwise

## ◆ place()

void DiOverlayPlane::place | ( | const signed int | left_pos,
|  | const signed int | top_pos
| ) |  |

move overlay plane to a new place

Parameters

  left_pos | x-coordinate of the new plane origin (maybe negative)
  top_pos | y-coordinate of the new plane origin (maybe negative)

## ◆ reset()

int DiOverlayPlane::reset | ( | const unsigned long | frame | ) |
| inline

reset internal 'cursor' to the beginning of the specified frame

Parameters

  frame | number of current frame

Returns
  status, true if successful, false otherwise

References Data, MultiframeOverlay, and Valid.

## ◆ setFlipping()

void DiOverlayPlane::setFlipping | ( | const int | horz,
|  | const int | vert,
|  | const signed long | columns,
|  | const signed long | rows
| ) |  |

set flipping

Parameters

  horz | flip horizontally if true
  vert | flip vertically if true
  columns | width of surrounding image (incl. origin offset)
  rows | height of surrounding image (incl. origin offset)

## ◆ setRotation()

void DiOverlayPlane::setRotation | ( | const int | degree,
|  | const signed long | left_pos,
|  | const signed long | top_pos,
|  | const Uint16 | columns,
|  | const Uint16 | rows
| ) |  |

set rotation

Parameters

  degree | angle by which the plane should be rotated
  left_pos | x-coordinate of the origin for all overlay planes
  top_pos | y-coordinate of the origin for all overlay planes
  columns | width of surrounding image (already rotated)
  rows | height of surrounding image (already rotated)

## ◆ setScaling()

void DiOverlayPlane::setScaling | ( | const double | xfactor,
|  | const double | yfactor
| ) |  |

set scaling factor in x- and y-direction

Parameters

  xfactor | scaling factor in x-direction
  yfactor | scaling factor in y-direction

## ◆ setStart()

void DiOverlayPlane::setStart | ( | const Uint16 | x,
|  | const Uint16 | y,
|  | const OFBool | useOrigin = `OFTrue`
| ) |  |
| inline

set internal 'cursor' to a specific position

Parameters

  x | new x-coordinate to start from
  y | new y-coordinate to start from
  useOrigin | use overlay plane's origin for calculating the start position if true (default), ignore it otherwise

References BitsAllocated, Ptr, and StartPtr.

## ◆ show() [1/2]

void DiOverlayPlane::show | ( | const double | fore,
|  | const double | thresh,
|  | const EM_Overlay | mode
| ) |  |

make overlay plane visible and set parameters

Parameters

  fore | foreground color of the plane (in percent: 0.0-1.0)
  thresh | threshold value for 'threshold replace' (0.0-1.0)
  mode | new overlay plane mode (EMO_Default for stored mode)

## ◆ show() [2/2]

int DiOverlayPlane::show | ( | const Uint16 | pvalue | ) |

make overlay plane visible and set p-value.

Only applicable for bitmap shutters.

Parameters

  pvalue | p-value to be used for the overlay plane (0..65535)

Returns
  status, true if successful, false otherwise

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

- dcmimgle/include/dcmtk/dcmimgle/diovpln.h

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