OverlapUtil Class Reference

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

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

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

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

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".
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.
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.

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.
DistinctFramePositions	m_logicalFramePositions
	Logical frames, ie.
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.
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()

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 )

staticprotected

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()

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 )

staticprotected

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()

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()

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

staticprotected

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