Support for structured multi-frame (SMF) DICOM objects. More...

#include <DCMTree_StructuredMF.h>

Public Types
enum	{ privateGroupId = 0x0041 , dimensionsOffset = 1 , dimensionSequenceOffset = 2 , frameIndexOffset = 3 }

typedef std::vector< unsigned int >	IndexVector
	Index vector type, ordered as (z, t, u1, u2, ...) More...

Public Member Functions
	StructuredMF (Const_TreePtr tree)
	Constructor. More...

	StructuredMF (TreePtr tree)
	Constructor. More...

	StructuredMF (TreePtr sharedTagTree, const IndexVector &gridExtent)
	Constructor. More...

	StructuredMF (TreePtr sharedTagTree, unsigned int depth, unsigned int timePoints=0, unsigned int u1Size=0)

Const_TreePtr	tagTree () const
	Returns a const pointer to the contained tag tree. More...

TreePtr	tagTree ()
	Returns a pointer to the contained tag tree. More...

void	setSharedTags (TreePtr tree, bool handleFuncGroups=true)
	Adds/replaces shared tags with the given tag tree (no copy). More...

Access shared tags
TagPtr	sharedTag_rw (TagId tagId)
	Returns a writable pointer to the specified shared tag. More...

Const_TagPtr	sharedTag (TagId tagId) const
	Returns a const pointer to the specified shared tag. More...

Const_TagPtr	sharedTag (TagId tagId, const std::string &privateCreatorArg, Vr privateVr=UN) const
	Returns a const pointer to the specified shared tag with the given private creator and VR. More...

TreePtr	extractSharedTagTree () const
	Extracts all DICOM tags valid for all frames (deep copy). More...

Relation between logical grid and DICOM multi-frame structure
boost::uint32_t	getGridDimension () const
	Returns the dimension of the logical grid (i.e., the number of dimensions). More...

const IndexVector &	getGridExtent () const
	Returns the extents of the logical grid (i.e., the size in each dimension). More...

unsigned int	getNumberOfFrames () const
	Returns total number of frames. More...

bool	frameExists (const IndexVector &position) const
	Returns `true` if frame at a given grid position exists. More...

void	getEmptyFrames (std::vector< IndexVector > &positions) const
	Fills `positions` vector with unoccupied logical grid positions, i.e., positions for which no frame data has been set. More...

TreePtr	gridPositionTagTree (IndexVector gridPosition)
	Returns a pointer to a specific dimension index tree. More...

Activates support for reading native enhanced multi-frame tags.
This requires that a native frame index is set (with setFrameIndexForGridPosition) in the per-frame data of the StructuredMF.
void	setAlsoRegardEnhancedMultiFrameTags (bool flag)

bool	alsoRegardEnhancedMultiFrameTags () const

bool	privateTagsAreSet () const
	Returns `true` if the internal private tags have been initialized. More...

Static Public Attributes
static std::string	privateCreator
	Private creator string used for storing the StructuredMF information. More...

Access all tags valid for a given grid position
enum	ExtractMode { ExtractSharedAndSpecific , ExtractSpecific , ExtractSpecificWithSharedParent }
	Constants for extracting DICOM tags for a given index vector. More...

Const_TagPtr	tagForGridPosition (TagId tagId, IndexVector gridPosition) const
	Returns a pointer to the specified tag for a given grid position. More...

Const_TagPtr	tagForGridPosition (TagId tagId, unsigned int z, unsigned int t=0, unsigned int u1=0) const

Const_TagPtr	tagForGridPosition (TagId tagId, IndexVector gridPosition, const std::string &privateCreatorArg, Vr privateVr=UN) const
	Returns a pointer to the specified tag for a given index vector or grid position. More...

Const_TagPtr	tagForGridPosition (TagId tagId, const std::string &privateCreatorArg, Vr privateVr, unsigned int z, unsigned int t=0, unsigned int u1=0) const

int	frameIndexForGridPosition (const IndexVector &gridPosition) const
	Returns the frame index of the original image for a given grid position. More...

int	frameIndexForGridPosition (unsigned int z, unsigned int t=0, unsigned int u1=0) const

TreePtr	extractTagTreeForGridPosition (IndexVector gridPosition, ExtractMode mode=ExtractSharedAndSpecific) const
	Extract all DICOM tags for a given index vector (deep copy). More...

TreePtr	extractTagTreeForGridPosition (unsigned int z, unsigned int t=0, unsigned int u1=0, ExtractMode mode=ExtractSharedAndSpecific) const

void	setTagForGridPosition (TagPtr tag, const IndexVector &gridPosition, const std::string &privateCreatorArg="", bool skipInvalidPrivateTags=true)
	Adds/replaces specified tag for a given grid position (no copy); if skipInvalidPrivateTags is `false`, then private tags without creator will throw exceptions; otherwise, (in `true` case) they will be skipped without exception. More...

void	setTagForGridPosition (TagPtr tag, unsigned int z, unsigned int t=0, unsigned int u1=0, const std::string &privateCreatorArg="")

void	setGridPositionSpecificTags (TreePtr tree, const IndexVector &gridPosition, bool skipInvalidPrivateTags=true)
	Adds/replaces specific tags for a given grid position (no copy); if skipInvalidPrivateTags is `false`, then private tags without creator will throw exceptions; otherwise, (in `true` case) they will be skipped without exception. More...

void	setGridPositionSpecificTags (TreePtr tree, unsigned int z, unsigned int t=0, unsigned int u1=0)

void	setFrameIndexForGridPosition (unsigned int frameIndex, const IndexVector &gridPosition)
	Sets frame index of original image (for MF data only). More...

void	setFrameIndexForGridPosition (unsigned int frameIndex, unsigned int z, unsigned int t=0, unsigned int u1=0)

Checks validity of SMF object.
enum	StatusCode { OK = 0 , NO_PER_FRAME_TAGS , AMBIGUOUS_TAG , INCONSISTENT_PER_FRAME_TAGS , NUM_STATUS_CODES }
	Status code constants. More...

void	normalizeTagStructure (double tolerance=0.0, bool compress=true)
	Makes sure all grid position specific tags are consistent: each tag shall exist either for each grid position or as shared tag if `compress` is `true`, per frame tags that have the same value for all frames will be replaced by a shared tag. More...

Detailed Description

Support for structured multi-frame (SMF) DICOM objects.

An SMF object contains DICOM tags of multiple images that are organized in a multi-dimensional grid (dimensions are depth, time points, and an arbitrary number of user-defined dimensions). The grid is represented by hierarchical sequences (one level for each dimension), the highest dimension being at the root level.

Example: 4D image with 2 time points and 3 slices per time point

Shared tag 1 ... Shared tag N Dimension info tag = 3 \ 2 Dimension sequence -> item 1 - time point 1 specific tags

dimension sequence -> item 1 - slice/time spec. tags item 2 - slice/time spec. tags item 3 - slice/time spec. tags item 2 - time point 2 specific tags
dimension sequence -> item 1 - slice/time spec. tags item 2 - slice/time spec. tags item 3 - slice/time spec. tags

Definition at line 49 of file DCMTree_StructuredMF.h.

Member Typedef Documentation

◆ IndexVector

typedef std::vector<unsigned int> DCMTree::StructuredMF::IndexVector

Index vector type, ordered as (z, t, u1, u2, ...)

Definition at line 54 of file DCMTree_StructuredMF.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Enumerator
privateGroupId	The (fixed) private group in which the StructuredMF info is stored.
dimensionsOffset	Element offset for number of dimensions.
dimensionSequenceOffset	Element offset for dimension sequence.
frameIndexOffset	Element offset for frame index.

Definition at line 60 of file DCMTree_StructuredMF.h.

◆ ExtractMode

enum DCMTree::StructuredMF::ExtractMode

Constants for extracting DICOM tags for a given index vector.

Enumerator
ExtractSharedAndSpecific	Shared and frame-specific tags are copied to new tree.
ExtractSpecific	Only frame-specific tags are copied to new tree.
ExtractSpecificWithSharedParent	Frame-specific tags are copied to new tree, shared tags are inherited.

Definition at line 131 of file DCMTree_StructuredMF.h.

◆ StatusCode

enum DCMTree::StructuredMF::StatusCode

Status code constants.

Enumerator
OK	Object valid.
NO_PER_FRAME_TAGS	A per-frame tag list is empty.
AMBIGUOUS_TAG	A per-frame tag list contains a tag already defined by the shared tag list.
INCONSISTENT_PER_FRAME_TAGS	The per-frame tag lists define different sets of tags.
NUM_STATUS_CODES

Definition at line 167 of file DCMTree_StructuredMF.h.

Constructor & Destructor Documentation

◆ StructuredMF() [1/4]

DCMTree::StructuredMF::StructuredMF ( Const_TreePtr tree )

Constructor.

It receives the tree of the DICOM tags for the SMF. Use this constructor to access an existing SMF object. Make sure that the DICOM tags defining the SMF structure are not modified during the lifetime of this object.

◆ StructuredMF() [2/4]

DCMTree::StructuredMF::StructuredMF ( TreePtr tree )

Constructor.

It receives the tree of the DICOM tags for the SMF. Use this constructor to access an existing writable SMF object The DICOM tags in the new object can be freely modified

◆ StructuredMF() [3/4]

DCMTree::StructuredMF::StructuredMF	(	TreePtr	sharedTagTree,
		const IndexVector &	gridExtent
	)

Constructor.

It creates a DICOM SMF object from the tree of common tags, the extent of the logical grid, and the tag IDs associated with the individual grid dimensions.

◆ StructuredMF() [4/4]

DCMTree::StructuredMF::StructuredMF	(	TreePtr	sharedTagTree,
		unsigned int	depth,
		unsigned int	timePoints = `0`,
		unsigned int	u1Size = `0`
	)

Member Function Documentation

◆ alsoRegardEnhancedMultiFrameTags()

bool DCMTree::StructuredMF::alsoRegardEnhancedMultiFrameTags ( ) const

inline

Definition at line 222 of file DCMTree_StructuredMF.h.

◆ extractSharedTagTree()

TreePtr DCMTree::StructuredMF::extractSharedTagTree ( ) const

Extracts all DICOM tags valid for all frames (deep copy).

◆ extractTagTreeForGridPosition() [1/2]

TreePtr DCMTree::StructuredMF::extractTagTreeForGridPosition	(	IndexVector	gridPosition,
		ExtractMode	mode = `ExtractSharedAndSpecific`
	)		const

Extract all DICOM tags for a given index vector (deep copy).

Returns a null pointer if the grid position is out of bounds.

◆ extractTagTreeForGridPosition() [2/2]

TreePtr DCMTree::StructuredMF::extractTagTreeForGridPosition	(	unsigned int	z,
		unsigned int	t = `0`,
		unsigned int	u1 = `0`,
		ExtractMode	mode = `ExtractSharedAndSpecific`
	)		const

◆ frameExists()

bool DCMTree::StructuredMF::frameExists ( const IndexVector & position ) const

Returns true if frame at a given grid position exists.

◆ frameIndexForGridPosition() [1/2]

int DCMTree::StructuredMF::frameIndexForGridPosition ( const IndexVector & gridPosition ) const

Returns the frame index of the original image for a given grid position.

Returns -1 if the slice does not belong to a multi-frame or if the grid position is out of bounds.

◆ frameIndexForGridPosition() [2/2]

int DCMTree::StructuredMF::frameIndexForGridPosition	(	unsigned int	z,
		unsigned int	t = `0`,
		unsigned int	u1 = `0`
	)		const

◆ getEmptyFrames()

void DCMTree::StructuredMF::getEmptyFrames ( std::vector< IndexVector > & positions ) const

Fills positions vector with unoccupied logical grid positions, i.e., positions for which no frame data has been set.

◆ getGridDimension()

boost::uint32_t DCMTree::StructuredMF::getGridDimension ( ) const

Returns the dimension of the logical grid (i.e., the number of dimensions).

All frames in a structured multi-frame (SMF) object are located at different positions in a logical, multi-dimensional grid. By convention, this grid has a spatial dimension (z), a time dimension (t), and optionally additional user dimensions (u1, u2, ...).

Referenced by ml::DicomToMLTools::FrameSpecificTag::setUpFrameSpecificTagInfos().

◆ getGridExtent()

const IndexVector& DCMTree::StructuredMF::getGridExtent ( ) const

Returns the extents of the logical grid (i.e., the size in each dimension).

Referenced by ml::DicomToMLTools::FrameSpecificTag::setUpFrameSpecificTagInfos().

◆ getNumberOfFrames()

unsigned int DCMTree::StructuredMF::getNumberOfFrames ( ) const

Returns total number of frames.

◆ gridPositionTagTree()

TreePtr DCMTree::StructuredMF::gridPositionTagTree ( IndexVector gridPosition )

Returns a pointer to a specific dimension index tree.

Creates the tree with basic sequence structures if it does not exist but it does not copy tags.

◆ normalizeTagStructure()

void DCMTree::StructuredMF::normalizeTagStructure	(	double	tolerance = `0.0`,
		bool	compress = `true`
	)

Makes sure all grid position specific tags are consistent: each tag shall exist either for each grid position or as shared tag if compress is true, per frame tags that have the same value for all frames will be replaced by a shared tag.

◆ privateTagsAreSet()

bool DCMTree::StructuredMF::privateTagsAreSet ( ) const

Returns true if the internal private tags have been initialized.

◆ setAlsoRegardEnhancedMultiFrameTags()

void DCMTree::StructuredMF::setAlsoRegardEnhancedMultiFrameTags ( bool flag )

inline

Definition at line 221 of file DCMTree_StructuredMF.h.

◆ setFrameIndexForGridPosition() [1/2]

void DCMTree::StructuredMF::setFrameIndexForGridPosition	(	unsigned int	frameIndex,
		const IndexVector &	gridPosition
	)

Sets frame index of original image (for MF data only).

Exceptions

DCMTree::Exception if the grid position is out of bounds.

◆ setFrameIndexForGridPosition() [2/2]

void DCMTree::StructuredMF::setFrameIndexForGridPosition	(	unsigned int	frameIndex,
		unsigned int	z,
		unsigned int	t = `0`,
		unsigned int	u1 = `0`
	)

◆ setGridPositionSpecificTags() [1/2]

void DCMTree::StructuredMF::setGridPositionSpecificTags	(	TreePtr	tree,
		const IndexVector &	gridPosition,
		bool	skipInvalidPrivateTags = `true`
	)

Adds/replaces specific tags for a given grid position (no copy); if skipInvalidPrivateTags is false, then private tags without creator will throw exceptions; otherwise, (in true case) they will be skipped without exception.

Exceptions

DCMTree::Exception if the grid position is out of bounds.

◆ setGridPositionSpecificTags() [2/2]

void DCMTree::StructuredMF::setGridPositionSpecificTags	(	TreePtr	tree,
		unsigned int	z,
		unsigned int	t = `0`,
		unsigned int	u1 = `0`
	)

◆ setSharedTags()

void DCMTree::StructuredMF::setSharedTags	(	TreePtr	tree,
		bool	handleFuncGroups = `true`
	)

Adds/replaces shared tags with the given tag tree (no copy).

◆ setTagForGridPosition() [1/2]

void DCMTree::StructuredMF::setTagForGridPosition	(	TagPtr	tag,
		const IndexVector &	gridPosition,
		const std::string &	privateCreatorArg = `""`,
		bool	skipInvalidPrivateTags = `true`
	)

Adds/replaces specified tag for a given grid position (no copy); if skipInvalidPrivateTags is false, then private tags without creator will throw exceptions; otherwise, (in true case) they will be skipped without exception.

If the private creator for the private tag does not exist yet, it will also be set.

Exceptions

DCMTree::Exception if the grid position is out of bounds.

◆ setTagForGridPosition() [2/2]

void DCMTree::StructuredMF::setTagForGridPosition	(	TagPtr	tag,
		unsigned int	z,
		unsigned int	t = `0`,
		unsigned int	u1 = `0`,
		const std::string &	privateCreatorArg = `""`
	)

◆ sharedTag() [1/2]

Const_TagPtr DCMTree::StructuredMF::sharedTag ( TagId tagId ) const

Returns a const pointer to the specified shared tag.

◆ sharedTag() [2/2]

Const_TagPtr DCMTree::StructuredMF::sharedTag	(	TagId	tagId,
		const std::string &	privateCreatorArg,
		Vr	privateVr = `UN`
	)		const

Returns a const pointer to the specified shared tag with the given private creator and VR.

◆ sharedTag_rw()

TagPtr DCMTree::StructuredMF::sharedTag_rw ( TagId tagId )

Returns a writable pointer to the specified shared tag.

Returns only tags that are found by using the TagSelector "Owned". Parent tags are omitted.

◆ tagForGridPosition() [1/4]

Const_TagPtr DCMTree::StructuredMF::tagForGridPosition	(	TagId	tagId,
		const std::string &	privateCreatorArg,
		Vr	privateVr,
		unsigned int	z,
		unsigned int	t = `0`,
		unsigned int	u1 = `0`
	)		const

◆ tagForGridPosition() [2/4]

Const_TagPtr DCMTree::StructuredMF::tagForGridPosition	(	TagId	tagId,
		IndexVector	gridPosition
	)		const

Returns a pointer to the specified tag for a given grid position.

Returns a null pointer if no tag is found or the grid position is out of bounds.

Referenced by ml::DicomToMLTools::FrameSpecificTag::setUpFrameSpecificTagInfos().

◆ tagForGridPosition() [3/4]

Const_TagPtr DCMTree::StructuredMF::tagForGridPosition	(	TagId	tagId,
		IndexVector	gridPosition,
		const std::string &	privateCreatorArg,
		Vr	privateVr = `UN`
	)		const

Returns a pointer to the specified tag for a given index vector or grid position.

If the tag is a private tag, the private creator is used for the lookup, and the VR is set if not known. Returns a null pointer if no tag is found or the grid position is out of bounds.

◆ tagForGridPosition() [4/4]

Const_TagPtr DCMTree::StructuredMF::tagForGridPosition	(	TagId	tagId,
		unsigned int	z,
		unsigned int	t = `0`,
		unsigned int	u1 = `0`
	)		const

◆ tagTree() [1/2]

TreePtr DCMTree::StructuredMF::tagTree ( )

Returns a pointer to the contained tag tree.

◆ tagTree() [2/2]

Const_TreePtr DCMTree::StructuredMF::tagTree ( ) const

Returns a const pointer to the contained tag tree.

Referenced by ml::DicomToMLTools::FrameSpecificTag::setUpFrameSpecificTagInfos().

Member Data Documentation

◆ privateCreator

std::string DCMTree::StructuredMF::privateCreator

static

Private creator string used for storing the StructuredMF information.

Definition at line 57 of file DCMTree_StructuredMF.h.

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

MeVis/Foundation/Sources/DicomTree/MLDicomTree/DCMTree_StructuredMF.h

Public Types

Public Member Functions

Static Public Attributes

Access all tags valid for a given grid position

Checks validity of SMF object.

Detailed Description

Example: 4D image with 2 time points and 3 slices per time point

Member Typedef Documentation

◆ IndexVector

Member Enumeration Documentation

◆ anonymous enum

◆ ExtractMode

◆ StatusCode

Constructor & Destructor Documentation

◆ StructuredMF() [1/4]

◆ StructuredMF() [2/4]

◆ StructuredMF() [3/4]

◆ StructuredMF() [4/4]

Member Function Documentation

◆ alsoRegardEnhancedMultiFrameTags()

◆ extractSharedTagTree()

◆ extractTagTreeForGridPosition() [1/2]

◆ extractTagTreeForGridPosition() [2/2]

◆ frameExists()

◆ frameIndexForGridPosition() [1/2]

◆ frameIndexForGridPosition() [2/2]

◆ getEmptyFrames()

◆ getGridDimension()

◆ getGridExtent()

◆ getNumberOfFrames()

◆ gridPositionTagTree()

◆ normalizeTagStructure()

◆ privateTagsAreSet()

◆ setAlsoRegardEnhancedMultiFrameTags()

◆ setFrameIndexForGridPosition() [1/2]

◆ setFrameIndexForGridPosition() [2/2]

◆ setGridPositionSpecificTags() [1/2]

◆ setGridPositionSpecificTags() [2/2]

◆ setSharedTags()

◆ setTagForGridPosition() [1/2]

◆ setTagForGridPosition() [2/2]

◆ sharedTag() [1/2]

◆ sharedTag() [2/2]

◆ sharedTag_rw()

◆ tagForGridPosition() [1/4]

◆ tagForGridPosition() [2/4]

◆ tagForGridPosition() [3/4]

◆ tagForGridPosition() [4/4]

◆ tagTree() [1/2]

◆ tagTree() [2/2]

Member Data Documentation

◆ privateCreator