DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | Private Attributes | List of all members
OverlapUtil Class Reference

Class that analyzes the frame-based segment structures of a given segmentation object. More...

## Classes
struct | ComparePositions
| Implements comparision operator to be used for sorting of frame positions, making the sorting order depend on the coordinate given in the constructor. More...
struct | FramePositionAndNumber
| Physical Frame number with its respective position. More...
struct | SegNumAndFrameNum
| Represents a segment number and a logical frame number it is found at. More...

## Public Types
typedef OFVector< Float64 > | ImagePosition
| Image Position Patient tuple (x,y,z)
typedef OFVector< FramePositionAndNumber > | FramePositions
| Physical Frame number with its respective position.
typedef OFVector< Uint32 > | LogicalFrame
| Logical Frame, represented and defined by various physical frames (numbers) at the same position.
typedef OFVector< LogicalFrame > | DistinctFramePositions
| All distinct positions and for each position the physical frame numbers that can be found at it.
typedef OFVector< OFVector< Uint32 > > | FramesForSegment
| Lists frames for each segment where segment with index i is represented by the vector at index i, and index 0 is unused. More...
typedef OFVector< OFVector< Sint8 > > | OverlapMatrix
| Matrix of N x N segment numbers, where N is the number of segments. More...
typedef OFVector< OFVector< Uint32 > > | SegmentGroups
| Group of non-overlapping segments (each represented by its segment number)
typedef OFVector< OFVector< SegNumAndFrameNum > > | SegmentsByPosition
| Segments and their phyiscal frame number (inner set), grouped by their respective logical frame number (outer vector) .The inner vector is not.

## Public Member Functions
| OverlapUtil ()
| Constructor. More...
| ~OverlapUtil ()
| Destructor.
void | setSegmentationObject (DcmSegmentation *seg)
| Set the segmentation object to work with and clears all old data. More...
void | clear ()
| Clears all internal data (except segmentation object reference). More...
OFCondition | getFramesByPosition (DistinctFramePositions &result)
| Get all distinct frame positions and the physical frame numbers at this position. More...
OFCondition | getSegmentsByPosition (SegmentsByPosition &result)
| Get all segments and their physical frame number, grouped by their respective logical frame number. More...
OFCondition | getFramesForSegment (const Uint32 segmentNumber, OFVector< Uint32 > &frames)
| Get phyiscal frames for a specific segment by its segment number. More...
OFCondition | getOverlapMatrix (OverlapMatrix &matrix)
| Returns computed overlap matrix. More...
OFCondition | getNonOverlappingSegments (SegmentGroups &segmentGroups)
| Returns segments grouped together in a way, that no two overlapping segments will be in the same group. More...
void | printSegmentsByPosition (OFStringStream &ss)
| Prints segments by their position in space. More...
void | printOverlapMatrix (OFStringStream &ss)
| Prints segment overlap matrix to given stream. More...
void | printNonOverlappingSegments (OFStringStream &ss)
| Prints groups of non-overlapping segments (identified by their numbers) to given stream. More...
OFBool | hasOverlappingSegments ()
| Return whether there are at least two segments, that overlap each other. More...

## Static Public Member Functions
static Float64 | fabs (const Float64 value)
| Returns the absolute value of a floating-point number. More...

## Protected Member Functions
OFCondition | groupFramesByLogicalPosition ()
| Group physical frame positions into logical positions. More...
OFCondition | buildOverlapMatrix ()
| Builds the overlap matrix, if not already done. More...
OFCondition | ensureFramesAreParallel ()
| Checks if frames are parallel, i.e. More...
OFCondition | groupFramesByPosition ()
| Groups all physical frames by their position. More...
OFCondition | checkFramesOverlap (const Uint32 &f1, const Uint32 &f2, OFBool &overlap)
| Checks whether the given two frames overlap. More...

## Static Protected Member Functions
static OFCondition | checkFramesOverlapBinary (const Uint32 &f1, const Uint32 &f2, const DcmIODTypes::Frame< Uint8 > *f1_data, const DcmIODTypes::Frame< Uint8 > *f2_data, const Uint16 &, const Uint16 &, OFBool &overlap)
| Checks whether the given two frames overlap by using comparing their pixel data by bitwise "and". More...
static OFCondition | checkFramesOverlapUnpacked (const Uint32 &f1, const Uint32 &f2, const DcmIODTypes::Frame< Uint8 > *f1_data, const DcmIODTypes::Frame< Uint8 > *f2_data, const Uint16 &rows, const Uint16 cols, OFBool &overlap)
| Checks whether the given two frames overlap by using comparing their pixel data after unpacking, i.e. More...
static Uint8 | identifyChangingCoordinate (const OFVector< Float64 > &imageOrientation)
| Return the most relevant (changing) coordinate, computed by multiplying x and y vectors of the image orientation and selecting the coordinate with the largest absolute value. More...

## Private Attributes
OFVector< Float64 > | m_imageOrientation
| Image Orientation Patient.
FramePositions | m_framePositions
| Phyiscal frames with their respective positions (IPP)
FramesForSegment | m_framesForSegment
| Outer vector with one entry per segment. More...
DistinctFramePositions | m_logicalFramePositions
| Logical frames, ie. More...
SegmentsByPosition | m_segmentsByPosition
| Stores for each logical frame a collection of (paired) segment and physical frame number, that exists at that position.
OverlapMatrix | m_segmentOverlapMatrix
| Matrix that stores for each segment pair whether they overlap or not. More...
DcmSegmentation * | m_seg
| Reference to segmentation object to work with Must be freed outside this class.

## Detailed Description

Class that analyzes the frame-based segment structures of a given segmentation object.

It provides the following main functionality:

- Grouping of "physical" frames by their position in space (called "logical frames"), i.e. frames that are at the same position in space are grouped together.
- For every logical frame (i.e. position in space), it lists the segments found at this position together with their respective physical frame number
- Return physical frame numbers for a given segment number
- Building an overlap matrix that stores for each arbitrary segment pair whether they overlap or not.
- Return groups of segments, that no two overlapping segments will be in the same group. This will not necessarily return the optimal solution, but a solution that should be good enough. For the method used see getNonOverlappingSegments().

## Member Typedef Documentation

## ◆ FramesForSegment

typedef OFVector<OFVector<Uint32> > OverlapUtil::FramesForSegment

Lists frames for each segment where segment with index i is represented by the vector at index i, and index 0 is unused.

I.e. index i is segment number, value is vector of physical frame numbers.

## ◆ OverlapMatrix

typedef OFVector<OFVector<Sint8> > OverlapUtil::OverlapMatrix

Matrix of N x N segment numbers, where N is the number of segments.

Value is 1 at x,y if x and y overlap, 0 if they don't overlap, and -1 if not initialized.

## Constructor & Destructor Documentation

## ◆ OverlapUtil()

OverlapUtil::OverlapUtil | ( |  | ) |

Constructor.

Use setSegmentationObject() to set the segmentation object to work with.

## Member Function Documentation

## ◆ buildOverlapMatrix()

OFCondition OverlapUtil::buildOverlapMatrix | ( |  | ) |
| protected

Builds the overlap matrix, if not already done.

Returns
  EC_Normal if successful or already existant, error otherwise

## ◆ checkFramesOverlap()

OFCondition OverlapUtil::checkFramesOverlap | ( | const Uint32 & | f1,
|  | const Uint32 & | f2,
|  | OFBool & | overlap
| ) |  |
| protected

Checks whether the given two frames overlap.

Parameters

  f1 | Frame 1, provided by its physical frame number
  f2 | Frame 2, provided by its physical frame number
  overlap | Resulting overlap (overlaps if OFTrue, otherwise not)

Returns
  EC_Normal if successful, error otherwise

## ◆ checkFramesOverlapBinary()

static OFCondition OverlapUtil::checkFramesOverlapBinary | ( | const Uint32 & | f1,
|  | const Uint32 & | f2,
|  | const DcmIODTypes::Frame< Uint8 > * | f1_data,
|  | const DcmIODTypes::Frame< Uint8 > * | f2_data,
|  | const Uint16 & | ,
|  | const Uint16 & | ,
|  | OFBool & | overlap
| ) |  |
| static protected

Checks whether the given two frames overlap by using comparing their pixel data by bitwise "and".

This is very efficient, however, only works and is called (right now), if row*cols % 8 = 0, so we can easily extract frames as binary bitsets without unpacking them. TODO: Check whether this can be easily extended to other cases as well.

Parameters

  f1 | Frame 1, provided by its physical frame number
  f2 | Frame 2, provided by its physical frame number
  f1_data | Pixel data of frame 1
  f2_data | Pixel data of frame 2
  rows | Number of rows of the frame(s), not used right now
  cols | Number of columns of the frame(s), not used right now
  overlap | Resulting overlap (overlaps if OFTrue, otherwise not)

Returns
  EC_Normal if successful, error otherwise

## ◆ checkFramesOverlapUnpacked()

static OFCondition OverlapUtil::checkFramesOverlapUnpacked | ( | const Uint32 & | f1,
|  | const Uint32 & | f2,
|  | const DcmIODTypes::Frame< Uint8 > * | f1_data,
|  | const DcmIODTypes::Frame< Uint8 > * | f2_data,
|  | const Uint16 & | rows,
|  | const Uint16 | cols,
|  | OFBool & | overlap
| ) |  |
| static protected

Checks whether the given two frames overlap by using comparing their pixel data after unpacking, i.e.

expanding every bit to a byte, and then comparing whether the two related bytes of each frame are both non-zero. This is less efficient than checkFramesOverlapBinary(),

Parameters

  f1 | Frame 1, provided by its physical frame number
  f2 | Frame 2, provided by its physical frame number
  f1_data | Pixel data of frame 1
  f2_data | Pixel data of frame 2
  rows | Number of rows of the frame(s)
  cols | Number of columns of the frame(s)
  overlap | Resulting overlap (overlaps if OFTrue, otherwise not)

Returns
  EC_Normal if successful, error otherwise

## ◆ clear()

void OverlapUtil::clear | ( |  | ) |

Clears all internal data (except segmentation object reference).

This should be called whenever the input data (i.e. the underlying) DICOM segmentation object changes, before calling any other method.

## ◆ ensureFramesAreParallel()

OFCondition OverlapUtil::ensureFramesAreParallel | ( |  | ) |
| protected

Checks if frames are parallel, i.e.

if DICOM Image Position Patient is present and all frames are parallel to each other (i.e. found in the shared functional group)

Returns
  EC_Normal if parallel, SG_EC_FramesNotParallel if image orientation is not shared, error otherwise

## ◆ fabs()

static Float64 OverlapUtil::fabs | ( | const Float64 | value | ) |
| static

Returns the absolute value of a floating-point number.

Parameters

  value | The input value

Returns
  The absolute value of the input

## ◆ getFramesByPosition()

OFCondition OverlapUtil::getFramesByPosition | ( | DistinctFramePositions & | result | ) |

Get all distinct frame positions and the physical frame numbers at this position.

Parameters

  result | Resulting vector of distinct frame positions

Returns
  EC_Normal if successful, error otherwise

## ◆ getFramesForSegment()

OFCondition OverlapUtil::getFramesForSegment | ( | const Uint32 | segmentNumber,
|  | OFVector< Uint32 > & | frames
| ) |  |

Get phyiscal frames for a specific segment by its segment number.

Parameters

  segmentNumber | Segment number to get frames for (1..n)
  frames | Resulting vector of physical frame numbers (first frame is frame 0)

Returns
  EC_Normal if successful, error otherwise

## ◆ getNonOverlappingSegments()

OFCondition OverlapUtil::getNonOverlappingSegments | ( | SegmentGroups & | segmentGroups | ) |

Returns segments grouped together in a way, that no two overlapping segments will be in the same group.

This method does not necessarily returns the optimal solution, but a solution that should be good enough. It is guaranteed, that segments in the same group don't overlap.

It is based on the idea of a greedy algorithm that creates a first group containing the first segment. Then it goes to the next segment, checks whether it fits into the first group with no overlaps (easily checked in overlap matrix) and inserts it into that group if no overlaps exists. Otherwise, it creates a new group and continues with the next segment (trying to insert it into the first group, then second group, otherwise creates third group, and so on).

Parameters

  segmentGroups | Resulting vector of segment groups, each listing the segment numbers that are in that group

Returns
  EC_Normal if successful, error otherwise

## ◆ getOverlapMatrix()

OFCondition OverlapUtil::getOverlapMatrix | ( | OverlapMatrix & | matrix | ) |

Returns computed overlap matrix.

Parameters

  matrix | Resulting overlap matrix

Returns
  EC_Normal if successful, error otherwise

## ◆ getSegmentsByPosition()

OFCondition OverlapUtil::getSegmentsByPosition | ( | SegmentsByPosition & | result | ) |

Get all segments and their physical frame number, grouped by their respective logical frame number.

Parameters

  result | Resulting vector of segments grouped by logical frame number

Returns
  EC_Normal if successful, error otherwise

## ◆ groupFramesByLogicalPosition()

OFCondition OverlapUtil::groupFramesByLogicalPosition | ( |  | ) |
| protected

Group physical frame positions into logical positions.

This is done by sorting frames after that position coordinate that in its mean position difference is larger than slice thickness * 0.9. Then those frames that are close enough to each other (i.e. distance is smaller than slice thickness * 0.01), end up at the same logical position (considered a "logical frame") TODO: This should probably not use mean values for the coordinates since in some cases, the mean difference in a slice coordinate might be close to 0 if many frames are at the same position. Instead, the maximum difference, variance or something else could be used?

Returns
  EC_Normal if successful, error otherwise

## ◆ groupFramesByPosition()

OFCondition OverlapUtil::groupFramesByPosition | ( |  | ) |
| protected

Groups all physical frames by their position.

This also works if the physical frames have slightly different positions, i.e. if they are not exactly the same and are only "close enough" to be considered the same. Right now, the maximum distance treated equal is if distance is smaller than slice thickness * 0.01 (i.e. 1% of slice thickness). Only performs the computation, if not done before.

Returns
  EC_Normal if successful, error otherwise

## ◆ hasOverlappingSegments()

OFBool OverlapUtil::hasOverlappingSegments | ( |  | ) |

Return whether there are at least two segments, that overlap each other.

The overlap matrix is used (and computed if not already done) for this purpose.

Returns
  True if overlapping segments exist, false otherwise

## ◆ identifyChangingCoordinate()

static Uint8 OverlapUtil::identifyChangingCoordinate | ( | const OFVector< Float64 > & | imageOrientation | ) |
| static protected

Return the most relevant (changing) coordinate, computed by multiplying x and y vectors of the image orientation and selecting the coordinate with the largest absolute value.

Parameters

  imageOrientation | Image orientation patient (3 coordinates for x vector, 3 coordinates for y vector )

Returns
  0 if x, 1 if y, 2 if z, 3 if not determinable

## ◆ printNonOverlappingSegments()

void OverlapUtil::printNonOverlappingSegments | ( | OFStringStream & | ss | ) |

Prints groups of non-overlapping segments (identified by their numbers) to given stream.

Parameters

  ss | The stream to dump to

## ◆ printOverlapMatrix()

void OverlapUtil::printOverlapMatrix | ( | OFStringStream & | ss | ) |

Prints segment overlap matrix to given stream.

Parameters

  ss | The stream to dump to

## ◆ printSegmentsByPosition()

void OverlapUtil::printSegmentsByPosition | ( | OFStringStream & | ss | ) |

Prints segments by their position in space.

Parameters

  ss | The stream to dump to

## ◆ setSegmentationObject()

void OverlapUtil::setSegmentationObject | ( | DcmSegmentation * | seg | ) |

Set the segmentation object to work with and clears all old data.

Parameters

  seg | The segmentation object to work with (not owned by this class)

## Member Data Documentation

## ◆ m_framesForSegment

FramesForSegment OverlapUtil::m_framesForSegment
| private

Outer vector with one entry per segment.

Index is the DICOM segment number where segment 1 goes to index 0, segment 2 to index 1, and so on. Inner vector contains the physical frame numbers that represent the segment.

## ◆ m_logicalFramePositions

DistinctFramePositions OverlapUtil::m_logicalFramePositions
| private

Logical frames, ie.

physical frames with the same position are grouped together to a logical frame. For every logical frame, we store the related physical frame numbers. The logical frame number is implicitly given by the index in the vector.

## ◆ m_segmentOverlapMatrix

OverlapMatrix OverlapUtil::m_segmentOverlapMatrix
| private

Matrix that stores for each segment pair whether they overlap or not.

I.e. Matrix has size N x N, where N is the number of segments. The diagonal is always 0 (no overlap), i.e. a segment never overlaps with itself. If there is an overlap, the value is 1. If the field is not initialized, the value is -1.

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

- dcmseg/include/dcmtk/dcmseg/overlaputil.h

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