A tool library with useful functions to detect, analyze, decompose multi-frame DICOM trees. More...

Functions
MLDICOMTags_EXPORT bool	isSingleFrame (DCMTree::Const_TreePtr dcmTree)
	Returns true if dcmTree seems to be a valid dcmTree and no multi-frame file; nullptr trees return false.

MLDICOMTags_EXPORT bool	isEnhanced (DCMTree::Const_TreePtr dcmTree)
	Returns true if dcmTree seems to be a valid dcmTree and and enhanced IOD; nullptr trees return false.

MLDICOMTags_EXPORT void	copyTopLevelTags (DCMTree::Const_TreePtr mfTree, DCMTree::TreePtr dstTree, const DICOMTagTools::TagIdDesc *tagsToCopy, bool alsoCopySequenceTags)
	This routine copies root tags from mfTree to destTree; pixel data and/or sequence tags are possibly skipped according to function arguments.

MLDICOMTags_EXPORT void	addSubSequenceTags (DCMTree::RawTagId sequenceTagId, std::vector< DCMTree::RawTagId > *copyTagIds, DCMTree::Const_TreePtr srcTree, size_t frameIdx, DCMTree::TreePtr &dstTree, DicomMessageCollector &dcmMsgCollector)
	Gets the tag with ID sequenceTagId from the given srcTree, checks whether it is a sequence tag, and if yes, then it copies the tags with ids given by copyTagIds.

MLDICOMTags_EXPORT void	addSequenceContents (DCMTree::Const_TreePtr srcFrameTree, size_t pffgItemIdx, DCMTree::TreePtr dstFramePtr, DicomMessageCollector &dcmMsgCollector)
	Searches all sequences in srcFrameTree and copies the tags in all sequence items flatly to dstFramePtr.

MLDICOMTags_EXPORT bool	extractSingleFramesFromMultiFrameTree (DCMTree::Const_TreePtr dcmMFTree, std::vector< DCMTree::TreePtr > &singleFrameList, const DICOMTagTools::TagIdDesc tagsToCopy, const DICOMTagTools::TagIdDesc tagsToRemove, bool addFullFunctionalGroupSequences, DicomMessageCollector &dcmMsgCollector)
	If possible this routine tries to build a set of DICOM trees (one for each frame) from the multi-frame or enhanced CT DICOM tree and returns them in singleFrameList.

MLDICOMTags_EXPORT bool	doMultiFrameDecomposition (DCMTree::Const_TreePtr mfTree, std::vector< DCMTree::TreePtr > &singleFrameList, const DICOMTagTools::TagIdDesc tagsToCopy, const DICOMTagTools::TagIdDesc tagsToRemove, bool addFullFunctionalGroupSequences, DicomMessageCollector &dcmMsgCollector)
	Decomposes a the multi-frame file given by fileAttributes and adds each frame as a single frame with _addFile.

Variables
MLDICOMTags_EXPORT const DICOMTagTools::TagIdDesc	BaseTagsToRemove []
	A list of tags which should not copied from a top level multi-frame tree to a single frame, because they do not make sense for single frames any more or because they could provide invalid information if the information is not overwritten by specific subframes.

Detailed Description

A tool library with useful functions to detect, analyze, decompose multi-frame DICOM trees.

Function Documentation

◆ addSequenceContents()

MLDICOMTags_EXPORT void ml::MultiFrameTools::addSequenceContents	(	DCMTree::Const_TreePtr	srcFrameTree,
		size_t	pffgItemIdx,
		DCMTree::TreePtr	dstFramePtr,
		DicomMessageCollector &	dcmMsgCollector )

Searches all sequences in srcFrameTree and copies the tags in all sequence items flatly to dstFramePtr.

Does nothing if any of srcFrameTree or dstFramePtr is nullptr.

Parameters

srcFrameTree	The DCMTree in which sequences are searched and whose items are copied to dstFramePtr.
pffgItemIdx	The id of the frame currently analyzed. Only needed for message generation.
dstFramePtr	The frame into which the tags are to be copied.
dcmMsgCollector	Collects error, info and issue messages (typically related to a handle).

References addSequenceContents().

Referenced by addSequenceContents().

◆ addSubSequenceTags()

MLDICOMTags_EXPORT void ml::MultiFrameTools::addSubSequenceTags	(	DCMTree::RawTagId	sequenceTagId,
		std::vector< DCMTree::RawTagId > *	copyTagIds,
		DCMTree::Const_TreePtr	srcTree,
		size_t	frameIdx,
		DCMTree::TreePtr &	dstTree,
		DicomMessageCollector &	dcmMsgCollector )

Gets the tag with ID sequenceTagId from the given srcTree, checks whether it is a sequence tag, and if yes, then it copies the tags with ids given by copyTagIds.

if available - to tree dstTree.

Parameters

sequenceTagId	The tag id of the sequence to be extracted.
copyTagIds	The tag ids of the tags to be copied from the sequence with id sequenceTagId; if nullptr then the entire sequence is copied.
srcTree	The tree from which the sequence tag and the copy tag shall be searched/copied.
frameIdx	The id of the frame currently analyzed. Only needed for message generation.
dstTree	The tree to which the copy of the tag shall be added.
dcmMsgCollector	Collects error, info and issue messages (typically related to a handle).

References addSubSequenceTags().

Referenced by addSubSequenceTags().

◆ copyTopLevelTags()

MLDICOMTags_EXPORT void ml::MultiFrameTools::copyTopLevelTags	(	DCMTree::Const_TreePtr	mfTree,
		DCMTree::TreePtr	dstTree,
		const DICOMTagTools::TagIdDesc *	tagsToCopy,
		bool	alsoCopySequenceTags )

This routine copies root tags from mfTree to destTree; pixel data and/or sequence tags are possibly skipped according to function arguments.

Parameters

mfTree	is the source tree whose tags are to be copied, ignored if nullptr.
dstTree	is the tree into which the tags shall be copied, ignored if nullptr.
tagsToCopy	if nullptr (the default) then all top level tags are copied exclusive pixel data tags(DCMTree_PixelData, DCMTree_FloatPixelData, DCMTree_DoubleFloatPixelData, spectDataTagId1(0x7fe1, 0x1010) and DCMTree::TagId spectDataTagId2(0x5600, 0x0020)) and sequence tags are copied according to alsoCopySequenceTags, if non-nullptr exactly those ones given in tagsToCopy (even with pixel data and/or sequence tags regardless of alsoCopySequenceTags). Non nullptr tagsToCopy must be terminated with {0, ""}.
alsoCopySequenceTags	If true then also top levels sequence tags are copied if tagsToCopy is nullptr.

References copyTopLevelTags().

Referenced by copyTopLevelTags().

◆ doMultiFrameDecomposition()

MLDICOMTags_EXPORT bool ml::MultiFrameTools::doMultiFrameDecomposition	(	DCMTree::Const_TreePtr	mfTree,
		std::vector< DCMTree::TreePtr > &	singleFrameList,
		const DICOMTagTools::TagIdDesc *	tagsToCopy,
		const DICOMTagTools::TagIdDesc *	tagsToRemove,
		bool	addFullFunctionalGroupSequences,
		DicomMessageCollector &	dcmMsgCollector )

Decomposes a the multi-frame file given by fileAttributes and adds each frame as a single frame with _addFile.

If mfTree is no multi-frame tree or the value of the NumberOfFrames tags is <= 1 then no decomposition is performed and return arguments are not modified.

Parameters

mfTree	The DICOM tag tree from which all single frame trees will be extracted.
singleFrameList	Returns a vector containing single frame trees for each frame in mfTree.
tagsToCopy	if nullptr (the default) then all top level non sequence tags exclusive pixel data tags are copied, otherwise those ones given in tagsToCopy. If non nullptr then tagsToCopy must be terminated with {0, ""}.
tagsToRemove	If non nullptr then all tags with the given ids are removed from the top level of the created trees, otherwise this argument is ignored. If non nullptr then tagsToRemove must be terminated with {0, ""}.
addFullFunctionalGroupSequences	Older versions only copied the contents of functional sequences to the top-level of the generated frames, which however, is not sufficient for newer requirements, thus now the entire sequences are also copied if this flag is on. It can be disabled for backwards compatibility.
dcmMsgCollector	Collects error, info and issue messages (typically related to a handle).

Returns: true if at least one PerFrameFunctionalGroupsSequence tag was found which describes that the file should be a decomposable multi-frame file; otherwise always false is returned.

References doMultiFrameDecomposition().

Referenced by doMultiFrameDecomposition().

◆ extractSingleFramesFromMultiFrameTree()

MLDICOMTags_EXPORT bool ml::MultiFrameTools::extractSingleFramesFromMultiFrameTree	(	DCMTree::Const_TreePtr	dcmMFTree,
		std::vector< DCMTree::TreePtr > &	singleFrameList,
		const DICOMTagTools::TagIdDesc *	tagsToCopy,
		const DICOMTagTools::TagIdDesc *	tagsToRemove,
		bool	addFullFunctionalGroupSequences,
		DicomMessageCollector &	dcmMsgCollector )

If possible this routine tries to build a set of DICOM trees (one for each frame) from the multi-frame or enhanced CT DICOM tree and returns them in singleFrameList.

For dcmMFTree not containing enhanced CT or multi-frame structures in PerFrameFunctionalGroupsSequence singleFrameList will be returned empty without warnings or errors. TODO: Currently only a predefined subset of tags is extracted from subtrees. In future this perhaps will be provided as an additional argument to copy all or a user defined subset.

Parameters

dcmMFTree	The DICOM tag tree from which all single frame trees will be extracted.
singleFrameList	Returns a vector containing single frame trees for each frame in dcmMFTree.
tagsToCopy	if nullptr (the default) then all top level non sequence tags exclusive pixel data tags are copied, otherwise those ones given in tagsToCopy. If non nullptr then tagsToCopy must be terminated with {0, ""}.
tagsToRemove	If non nullptr then all tags with the given ids are removed from the top level of the created trees, otherwise this argument is ignored. If non nullptr then tagsToRemove must be terminated with {0, ""}. Note: tags may be added again from shared or per-frame functional entries after removing them from top level or as default tags from other tree generators in DICOM importers to fulfil DICOM standard requirements.
addFullFunctionalGroupSequences	Older versions only copied the contents of functional sequences to the top-level of the generated frames, which however, is not sufficient for newer requirements, thus now the entire sequences are also copied if this flag is on. It can be disabled for backwards compatibility.
dcmMsgCollector	Collects error, info and issue messages (typically related to a handle).

Returns: true if at least one PerFrameFunctionalGroupsSequence tag was found which describes that the file should be a decomposable multi-frame file; otherwise always false is returned.

References extractSingleFramesFromMultiFrameTree().

Referenced by extractSingleFramesFromMultiFrameTree().

◆ isEnhanced()

MLDICOMTags_EXPORT bool ml::MultiFrameTools::isEnhanced ( DCMTree::Const_TreePtr dcmTree )

Returns true if dcmTree seems to be a valid dcmTree and and enhanced IOD; nullptr trees return false.

References isEnhanced().

Referenced by isEnhanced().

◆ isSingleFrame()

MLDICOMTags_EXPORT bool ml::MultiFrameTools::isSingleFrame ( DCMTree::Const_TreePtr dcmTree )

Returns true if dcmTree seems to be a valid dcmTree and no multi-frame file; nullptr trees return false.

References isSingleFrame().

Referenced by isSingleFrame().

Variable Documentation

◆ BaseTagsToRemove

MLDICOMTags_EXPORT const DICOMTagTools::TagIdDesc ml::MultiFrameTools::BaseTagsToRemove[]

extern

A list of tags which should not copied from a top level multi-frame tree to a single frame, because they do not make sense for single frames any more or because they could provide invalid information if the information is not overwritten by specific subframes.

This list is terminated with {0, ""}.

Functions

Variables

Detailed Description

Function Documentation

◆ addSequenceContents()

◆ addSubSequenceTags()

◆ copyTopLevelTags()

◆ doMultiFrameDecomposition()

◆ extractSingleFramesFromMultiFrameTree()

◆ isEnhanced()

◆ isSingleFrame()

Variable Documentation

◆ BaseTagsToRemove