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)
	ctor - gets the tree of the DICOM tags for the SMF Use this constructor to access an existing SMF object. More...

	StructuredMF (TreePtr tree)
	ctor - gets 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 More...

	StructuredMF (TreePtr sharedTagTree, const IndexVector &gridExtent)
	ctor - create a DICOM SMF object from the tree of common tags, the extent of the logical grid and the tag id's associated with the individual grid dimensions. More...

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

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

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

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

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

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

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

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

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

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

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

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

void	getEmptyFrames (std::vector< IndexVector > &positions) const
	Fill positions vector with unoccupied logical grid positions, i.e. More...

TreePtr	gridPositionTagTree (IndexVector gridPosition)
	Get a pointer to a specific dimension index tree Create the tree with basic sequence structures if it does not exist but it does not copy tags. More...

Activate 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
	Return 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 info. 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
	Get 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
	Get 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
	Get 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. 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) Returns a null pointer if the grid position is out of bounds. 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)
	Add/replace 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)
	Add/replace 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)
	Set 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)

Check 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)
	Make 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 )

ctor - gets 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 )

ctor - gets 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
	)

ctor - create a DICOM SMF object from the tree of common tags, the extent of the logical grid and the tag id's 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

Extract 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

Return true if frame at a given grid position exists.

◆ frameIndexForGridPosition() [1/2]

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

Get 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

Fill 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

Get 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

Get 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

Get total number of frames.

◆ gridPositionTagTree()

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

Get a pointer to a specific dimension index tree Create 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`
	)

Make 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

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

Set 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`
	)

Add/replace 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`
	)

Add/replace 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`
	)

Add/replace 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

Get 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

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

◆ sharedTag_rw()

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

Get a writable pointer to the specified shared tag.

Returns only tags which 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

Get 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

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

Return a pointer to the contained tag tree.

◆ tagTree() [2/2]

Const_TreePtr DCMTree::StructuredMF::tagTree ( ) const

Return 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 info.

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

Check 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