Class to manage a 3D set of handles describing frames or volumes to be composed to a higher dimensional volume where the frames are located in z, t, and u dimension. More...

#include <mlZTUFileNameSet.h>

Public Types
typedef std::vector< std::vector< std::vector< DICOMCachedIOFileHandle > > >	FileNameSet
	Vector array to manage a 3D set of (frame) file names the volume is composed of.

typedef std::map< DICOMTagTools::ZTUIndex, DCMTree::Const_TagPtr >	TagsWithPositionMap
	Map of pairs of ZTU frame position with associated tag pointer.

Public Member Functions
	ZTUFileNameSet ()
	Constructor.

	ZTUFileNameSet (const ZTUFileNameSet &otherObject)
	Copy constructor.

	~ZTUFileNameSet ()
	Destructor.

ZTUFileNameSet &	operator= (const ZTUFileNameSet &otherObj)
	Assign members without cacheProxies.

bool	operator== (const ZTUFileNameSet &otherObj) const
	Returns true if the passed FileNameSets equals this, otherwise false.

bool	operator!= (const ZTUFileNameSet &otherObj) const
	Returns false if the passed FileNameSets equals this, otherwise true.

bool	hasEmptyPagesFileName () const
	Returns true if any page file name is an empty string, otherwise false..

bool	hasMultiFrameHandle () const
	Returns true if any page file name is an enhanced multi-frame handle, otherwise false.

bool	hasNormalFrameHandle () const
	Returns true if any page file name is non-enhanced-multi-frame handle, otherwise false.

bool	allHandlesExistAsFile (bool allowEmpty) const
	Returns true if all handles can be found as files on disk, otherwise false; Multi-frame handles are handled as existing if the files they come from exist.

void	resizePageFileNamesToVolumeSize (size_t newZExt, size_t newTExt, size_t newUExt)
	Assures that array of pageFileNames has sufficient extent for the current frames the volume is composed of; the new dimensions are taken from newZExt, newTExt, and newUExt.

void	clearPageFileNames ()
	Resets the file name set to extent 0 in all dimensions.

const FileNameSet &	getConstPageFileNameSet () const
	Returns the entire set of file names as constant.

FileNameSet &	getModifiablePageFileNameSet ()
	Returns the entire set of file names as modifiable object.

void	setPageFileNames (const FileNameSet &pFNames)
	Set entire set of file names at once.

size_t	getZExtent () const
	Returns the extent of the file set in Z-dimension.

size_t	getTExtentAt (size_t z=0) const
	Returns the extent of the file set in T-dimension at the position z if it exists, otherwise 0 is returned.

size_t	getTExtent () const
	Returns the maximum extent of the file set in T-dimension in all z entries.

size_t	getUExtentAt (size_t z=0, size_t t=0) const
	Returns the extent of the file set in T-dimension at the position (z,t) if it exists, otherwise 0 is returned.

size_t	getUExtent () const
	Returns the maximum extent of the file set in U-dimension in all z and u entries.

size_t	getNumFrames () const
	Returns the entire number of file names in set.

bool	isValidPosition (size_t z, size_t t, size_t u) const
	Returns true if (z,t,u) addresses an existing (perhaps empty) entry in the ZTUFileNameSet, otherwise false.

const DICOMCachedIOFileHandle &	getPageFileName (size_t z, size_t t, size_t u=0) const
	Returns a reference to the file name fName for the DICOM frame at position (z,t).

void	setPageFileName (size_t z, size_t t, size_t u, const std::string fName)
	Set the file name fName for the DICOM frame at position (z,t,u) as pageFileName.

void	appendFileName (const std::string &fileName, bool appendToZ)
	Append a file name to the z-dimension if appendToZ is true (there the extents in t and u are set to 1), otherwise append the file name to the t dimension at z-position 0.

void	appendFileNameToZ (const std::string &fileName)
	Append a file name to the z-dimension (there the extents in t and u are set to 1).

void	appendFileNameToT (const std::string &fileName)
	Append the file name to the t dimension at z-position 0.

void	appendFileNameToU (const std::string &fileName)
	Append a file name to the u-dimension at z/t-position 0.

std::string	getFileNameSetAsInfoString (bool fileNamesOnly=false) const
	Returns all z and time positions and the corresponding file names as string.

DICOMCachedIOFileHandle	getFirstNonEmptyFileName () const
	Returns the first non empty file name when scanning from [0][0][0] starting with u=0, u=1,... then continuing with t or an empty string if all file names are empty.

DICOMCachedIOFileHandle	getOriginalFrameHandle () const
	Returns an empty string if there are two handles which have not the same original file, otherwise the original handle for all frames is returned.

std::vector< DICOMCachedIOFileHandle >	getAllFileHandles (const DICOMTagTools::ZTUVector &suppressedHandles=DICOMTagTools::ZTUVector()) const
	Get all non-empty file handles as a one dimensional vector of files.

std::string	getStateAsString (const std::string &lineEndStr, const std::string &cacheFileRootDirPath, bool useRelativePaths) const
	Return current content of class as string whose lines are separated by lineEndStr.

MLErrorCode	setStateFromString (const std::string &state, size_t tExt, size_t uExt, const std::string &cacheDirPath, size_t &readPos)
	Set the object content from the passed state string; the state string is reduced by the parsed content.

bool	searchFrameWithSOPInstanceUID (const std::string &sopInstanceUID, DICOMCachedIOFileHandle &foundHandle, DICOMTagTools::ZTUIndex &ztuPosition, bool forceSearchInEnhancedHandles, DicomMessageCollector &dcmMsgCollector) const
	Returns position and file handle of the first frame with the given SOPInstanceUID.

bool	searchFrameWithValueInTag (unsigned int tagId, const std::string &tagValue, DICOMCachedIOFileHandle &foundHandle, DICOMTagTools::ZTUIndex &ztuPosition, bool forceSearchInEnhancedHandles, DicomMessageCollector &dcmMsgCollector) const
	Returns file handle and position of the first frame with a given tagValue in a tag with id tagId.

TagsWithPositionMap	getTagFromAllFrames (unsigned int tagId, bool forceSearchInEnhancedHandles, bool doStringToValue, DicomMessageCollector &dcmMsgCollector, bool createNullTagEntries=false, const std::string &nullEntryTagValue="", bool createNotConvertibleTagEntries=false, const std::string &nonConvertibleTagValue="") const
	Returns a map with pairs with (DICOMTagTools::ZTUIndex, DCMTree::Const_TagPtr) pairs of first tags in all found DIOCM frames of the given tag id.

bool	needsNewSOPInstanceUID (bool allowOneToOneEnhancedFrameRecomposition, DicomMessageCollector &dcmMsgCollector) const
	Checks all frame handles in fileNameSet whether a new SOPInstanceUID should be generated.

Detailed Description

Class to manage a 3D set of handles describing frames or volumes to be composed to a higher dimensional volume where the frames are located in z, t, and u dimension.

Definition at line 34 of file mlZTUFileNameSet.h.

Member Typedef Documentation

◆ FileNameSet

typedef std::vector< std::vector< std::vector<DICOMCachedIOFileHandle > > > ml::ZTUFileNameSet::FileNameSet

Vector array to manage a 3D set of (frame) file names the volume is composed of.

And access to FileNameSet[p][t][u] returns the frame name at z position p, time position t, and u position u.

Definition at line 48 of file mlZTUFileNameSet.h.

◆ TagsWithPositionMap

typedef std::map<DICOMTagTools::ZTUIndex, DCMTree::Const_TagPtr> ml::ZTUFileNameSet::TagsWithPositionMap

Map of pairs of ZTU frame position with associated tag pointer.

Definition at line 251 of file mlZTUFileNameSet.h.

Constructor & Destructor Documentation

◆ ZTUFileNameSet() [1/2]

ml::ZTUFileNameSet::ZTUFileNameSet ( )

Constructor.

◆ ZTUFileNameSet() [2/2]

ml::ZTUFileNameSet::ZTUFileNameSet ( const ZTUFileNameSet & otherObject )

Copy constructor.

◆ ~ZTUFileNameSet()

ml::ZTUFileNameSet::~ZTUFileNameSet ( )

Destructor.

Member Function Documentation

◆ allHandlesExistAsFile()

bool ml::ZTUFileNameSet::allHandlesExistAsFile ( bool allowEmpty ) const

Returns true if all handles can be found as files on disk, otherwise false; Multi-frame handles are handled as existing if the files they come from exist.

Parameters

allowEmpty If true then empty file names are considered as existing files, otherwise not.

Returns: True if all file handles exist, or the fileNameSet is empty, and false if any existing handle has corresponding existing file.

◆ appendFileName()

void ml::ZTUFileNameSet::appendFileName	(	const std::string &	fileName,
		bool	appendToZ )

Append a file name to the z-dimension if appendToZ is true (there the extents in t and u are set to 1), otherwise append the file name to the t dimension at z-position 0.

◆ appendFileNameToT()

void ml::ZTUFileNameSet::appendFileNameToT ( const std::string & fileName )

Append the file name to the t dimension at z-position 0.

◆ appendFileNameToU()

void ml::ZTUFileNameSet::appendFileNameToU ( const std::string & fileName )

Append a file name to the u-dimension at z/t-position 0.

◆ appendFileNameToZ()

void ml::ZTUFileNameSet::appendFileNameToZ ( const std::string & fileName )

Append a file name to the z-dimension (there the extents in t and u are set to 1).

◆ clearPageFileNames()

void ml::ZTUFileNameSet::clearPageFileNames ( )

inline

Resets the file name set to extent 0 in all dimensions.

Definition at line 95 of file mlZTUFileNameSet.h.

◆ getAllFileHandles()

std::vector< DICOMCachedIOFileHandle > ml::ZTUFileNameSet::getAllFileHandles ( const DICOMTagTools::ZTUVector & suppressedHandles = DICOMTagTools::ZTUVector() ) const

Get all non-empty file handles as a one dimensional vector of files.

Parameters

suppressedHandles A list of indexes to handles which shall not be returned; default is empty.

Returns: A std::vector of all not suppressed handles.

◆ getConstPageFileNameSet()

const FileNameSet & ml::ZTUFileNameSet::getConstPageFileNameSet ( ) const

inline

Returns the entire set of file names as constant.

Definition at line 100 of file mlZTUFileNameSet.h.

◆ getFileNameSetAsInfoString()

std::string ml::ZTUFileNameSet::getFileNameSetAsInfoString ( bool fileNamesOnly = false ) const

Returns all z and time positions and the corresponding file names as string.

useful for information dumps. The default (fileNamesOnly=false) is that the 3D-index position in the array is prefixed to the file names, otherwise only the "\n" separated file names are returned.

◆ getFirstNonEmptyFileName()

DICOMCachedIOFileHandle ml::ZTUFileNameSet::getFirstNonEmptyFileName ( ) const

Returns the first non empty file name when scanning from [0][0][0] starting with u=0, u=1,... then continuing with t or an empty string if all file names are empty.

◆ getModifiablePageFileNameSet()

FileNameSet & ml::ZTUFileNameSet::getModifiablePageFileNameSet ( )

inline

Returns the entire set of file names as modifiable object.

Definition at line 105 of file mlZTUFileNameSet.h.

◆ getNumFrames()

size_t ml::ZTUFileNameSet::getNumFrames ( ) const

Returns the entire number of file names in set.

◆ getOriginalFrameHandle()

DICOMCachedIOFileHandle ml::ZTUFileNameSet::getOriginalFrameHandle ( ) const

Returns an empty string if there are two handles which have not the same original file, otherwise the original handle for all frames is returned.

◆ getPageFileName()

const DICOMCachedIOFileHandle & ml::ZTUFileNameSet::getPageFileName	(	size_t	z,
		size_t	t,
		size_t	u = 0 ) const

Returns a reference to the file name fName for the DICOM frame at position (z,t).

(z,t) must be in valid extent, otherwise a fatal error will be posted.

◆ getStateAsString()

std::string ml::ZTUFileNameSet::getStateAsString	(	const std::string &	lineEndStr,
		const std::string &	cacheFileRootDirPath,
		bool	useRelativePaths ) const

Return current content of class as string whose lines are separated by lineEndStr.

Parameters

lineEndStr	The string appended to each line (usually used as line-end terminator).
cacheFileRootDirPath	Paths of file names or descriptors are stored relative to cacheFileRootDirPath if it is passed as non empty string and if it part of the begin of the file name paths.
useRelativePaths	If false then all file names stored in the returned string are stored with absolute paths. If true and if all referenced and stored files are located in cacheDirPath then all files are stored relative to cacheFileRootDirPath. Files which are not in that path are stored with absolute paths.

◆ getTagFromAllFrames()

TagsWithPositionMap ml::ZTUFileNameSet::getTagFromAllFrames	(	unsigned int	tagId,
		bool	forceSearchInEnhancedHandles,
		bool	doStringToValue,
		DicomMessageCollector &	dcmMsgCollector,
		bool	createNullTagEntries = false,
		const std::string &	nullEntryTagValue = "",
		bool	createNotConvertibleTagEntries = false,
		const std::string &	nonConvertibleTagValue = "" ) const

Returns a map with pairs with (DICOMTagTools::ZTUIndex, DCMTree::Const_TagPtr) pairs of first tags in all found DIOCM frames of the given tag id.

Parameters

tagId	Input parameter: The id of the tag to be searched.
forceSearchInEnhancedHandles	Input parameter: If true then in enhanced frame handles is always searched; if false then only if the frames are available or if it is a normal frame handle.
doStringToValue	Input parameter: If true then the tagValue is converted to string and assigned to the value of the ZTUPosition. If conversion excepts the map entry is not created.
dcmMsgCollector	I/O parameter: Collects error, info and issue messages (typically related to a handle).
createNullTagEntries	Input parameter: If true then pairs with not found tags are created for each frame if the abd tag value is set to nullEntryTagValue, otherwise for nullptr tags no pair entries are created.
nullEntryTagValue	Input parameter: see createNotConvertibleTagEntries.
createNotConvertibleTagEntries	Input parameter: If true then pairs with tags not directly convertible to string are created for each frame and value is set to nonConvertibleTagValue, otherwise for nullptr tags no pair entries are created.
nonConvertibleTagValue	Input parameter: see createNotConvertibleTagEntries.

Returns: (pair,tagPointer) map of all found (first) tags in handles; for non-found tags in returned map no entries are created.

◆ getTExtent()

size_t ml::ZTUFileNameSet::getTExtent ( ) const

Returns the maximum extent of the file set in T-dimension in all z entries.

◆ getTExtentAt()

size_t ml::ZTUFileNameSet::getTExtentAt ( size_t z = 0 ) const

Returns the extent of the file set in T-dimension at the position z if it exists, otherwise 0 is returned.

◆ getUExtent()

size_t ml::ZTUFileNameSet::getUExtent ( ) const

Returns the maximum extent of the file set in U-dimension in all z and u entries.

◆ getUExtentAt()

size_t ml::ZTUFileNameSet::getUExtentAt	(	size_t	z = 0,
		size_t	t = 0 ) const

Returns the extent of the file set in T-dimension at the position (z,t) if it exists, otherwise 0 is returned.

◆ getZExtent()

size_t ml::ZTUFileNameSet::getZExtent ( ) const

Returns the extent of the file set in Z-dimension.

◆ hasEmptyPagesFileName()

bool ml::ZTUFileNameSet::hasEmptyPagesFileName ( ) const

Returns true if any page file name is an empty string, otherwise false..

◆ hasMultiFrameHandle()

bool ml::ZTUFileNameSet::hasMultiFrameHandle ( ) const

Returns true if any page file name is an enhanced multi-frame handle, otherwise false.

◆ hasNormalFrameHandle()

bool ml::ZTUFileNameSet::hasNormalFrameHandle ( ) const

Returns true if any page file name is non-enhanced-multi-frame handle, otherwise false.

Empty or non-DICOM handles are also considered as normal handles.

◆ isValidPosition()

bool ml::ZTUFileNameSet::isValidPosition	(	size_t	z,
		size_t	t,
		size_t	u ) const

Returns true if (z,t,u) addresses an existing (perhaps empty) entry in the ZTUFileNameSet, otherwise false.

◆ needsNewSOPInstanceUID()

bool ml::ZTUFileNameSet::needsNewSOPInstanceUID	(	bool	allowOneToOneEnhancedFrameRecomposition,
		DicomMessageCollector &	dcmMsgCollector ) const

Checks all frame handles in fileNameSet whether a new SOPInstanceUID should be generated.

Parameters

allowOneToOneEnhancedFrameRecomposition	If false then all compositions of more than one (enhanced or normal) frame require a new SOPInstanceUID on top level. If true then it is allowed that the original SOPInstanceUID of the source file can be reused if exactly all (no more and no less) frames of the original enhanced multi-frame file are in the ZTUFileNameSet and no other or empty frames are part of it.
dcmMsgCollector	Collects error, info and issue messages (typically related to a handle).

Returns: true is a new SOPInstanceUID has to be set in the SMFTree created for the fileNameSet, otherwise false.

◆ operator!=()

bool ml::ZTUFileNameSet::operator!= ( const ZTUFileNameSet & otherObj ) const

inline

Returns false if the passed FileNameSets equals this, otherwise true.

Definition at line 67 of file mlZTUFileNameSet.h.

References mlrange_cast(), and ml::operator==().

◆ operator=()

ZTUFileNameSet & ml::ZTUFileNameSet::operator= ( const ZTUFileNameSet & otherObj )

inline

Assign members without cacheProxies.

Definition at line 51 of file mlZTUFileNameSet.h.

References mlrange_cast().

◆ operator==()

bool ml::ZTUFileNameSet::operator== ( const ZTUFileNameSet & otherObj ) const

inline

Returns true if the passed FileNameSets equals this, otherwise false.

Definition at line 61 of file mlZTUFileNameSet.h.

References mlrange_cast().

◆ resizePageFileNamesToVolumeSize()

void ml::ZTUFileNameSet::resizePageFileNamesToVolumeSize	(	size_t	newZExt,
		size_t	newTExt,
		size_t	newUExt )

Assures that array of pageFileNames has sufficient extent for the current frames the volume is composed of; the new dimensions are taken from newZExt, newTExt, and newUExt.

◆ searchFrameWithSOPInstanceUID()

bool ml::ZTUFileNameSet::searchFrameWithSOPInstanceUID	(	const std::string &	sopInstanceUID,
		DICOMCachedIOFileHandle &	foundHandle,
		DICOMTagTools::ZTUIndex &	ztuPosition,
		bool	forceSearchInEnhancedHandles,
		DicomMessageCollector &	dcmMsgCollector ) const

Returns position and file handle of the first frame with the given SOPInstanceUID.

Parameters

sopInstanceUID	Input parameter: The SOPInstanceUID to be searched in the frames.
foundHandle	Output parameter: The file handle of the frame with the given SOPInstanceUID; will be empty if not found.
ztuPosition	Output parameter: Will be set with z, t, and u indexes of the frame in the FileNameSet which has the given SOPInstanceUID; z, t, and u will be set to 0 if no frame with the given SOPInstanceUID is not found.
forceSearchInEnhancedHandles	Input parameter: If true then in enhanced frame handles is always searched; if false then only if the frames are available or if it is a normal frame handle.
dcmMsgCollector	I/O parameter: Collects error, info and issue messages (typically related to a handle).

Returns: true if a frame with the given SOPInstanceUID is found, otherwise false.

◆ searchFrameWithValueInTag()

bool ml::ZTUFileNameSet::searchFrameWithValueInTag	(	unsigned int	tagId,
		const std::string &	tagValue,
		DICOMCachedIOFileHandle &	foundHandle,
		DICOMTagTools::ZTUIndex &	ztuPosition,
		bool	forceSearchInEnhancedHandles,
		DicomMessageCollector &	dcmMsgCollector ) const

Returns file handle and position of the first frame with a given tagValue in a tag with id tagId.

Parameters

tagId	Input parameter: The id of the tag to be searched.
tagValue	Input parameter: The tagValue to be searched in the frames.
foundHandle	Output parameter: The file handle of the frame with the given tagValue in a tag with id tagId will be empty if not found.
ztuPosition	Output parameter: Will be set with z, t, and u indexes of the frame in the FileNameSet which has the given tagValue; z, t, and u will be set to 0 if no frame with the given tagValue is not found.
forceSearchInEnhancedHandles	Input parameter: If true then in enhanced frame handles is always searched; if false then only if the frames are available or if it is a normal frame handle.
dcmMsgCollector	I/O parameter: Collects error, info and issue messages (typically related to a handle).

Returns: true if a frame with the given tagValue in a tag with id tagId is found, otherwise false.

◆ setPageFileName()

void ml::ZTUFileNameSet::setPageFileName	(	size_t	z,
		size_t	t,
		size_t	u,
		const std::string	fName )

Set the file name fName for the DICOM frame at position (z,t,u) as pageFileName.

The set of pageFileNames must have been resized appropriately before to assure that the extent is sufficient, otherwise a fatal error will be posted.

◆ setPageFileNames()

void ml::ZTUFileNameSet::setPageFileNames ( const FileNameSet & pFNames )

inline

Set entire set of file names at once.

Definition at line 110 of file mlZTUFileNameSet.h.

References mlrange_cast().

◆ setStateFromString()

MLErrorCode ml::ZTUFileNameSet::setStateFromString	(	const std::string &	state,
		size_t	tExt,
		size_t	uExt,
		const std::string &	cacheDirPath,
		size_t &	readPos )

Set the object content from the passed state string; the state string is reduced by the parsed content.

tExt, and uExt are passed for security checks and must contain the extent of the volume to be parsed from the state string.

Parameters

state	The string the filenames are read from.
tExt	The extent in the t-dimension of the file name set stored in the file.
uExt	The extent in the u-dimension of the file name set stored in the file.
cacheDirPath	The directory path where the cache file is located which contains state.
readPos	The position in state where reading shall start from; will be incremented to the position after data set during read.

Returns: On success ML_RESULT_OK is returned, otherwise an error code describing the problem. In case of non-ML_RESULT_OK returns the value of state remains undefined.

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

FMEstable/ReleaseMeVis/Projects/DICOM/MLMLToDicomTools/Sources/mlZTUFileNameSet.h

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ FileNameSet

◆ TagsWithPositionMap

Constructor & Destructor Documentation

◆ ZTUFileNameSet() [1/2]

◆ ZTUFileNameSet() [2/2]

◆ ~ZTUFileNameSet()

Member Function Documentation

◆ allHandlesExistAsFile()

◆ appendFileName()

◆ appendFileNameToT()

◆ appendFileNameToU()

◆ appendFileNameToZ()

◆ clearPageFileNames()

◆ getAllFileHandles()

◆ getConstPageFileNameSet()

◆ getFileNameSetAsInfoString()

◆ getFirstNonEmptyFileName()

◆ getModifiablePageFileNameSet()

◆ getNumFrames()

◆ getOriginalFrameHandle()

◆ getPageFileName()

◆ getStateAsString()

◆ getTagFromAllFrames()

◆ getTExtent()

◆ getTExtentAt()

◆ getUExtent()

◆ getUExtentAt()

◆ getZExtent()

◆ hasEmptyPagesFileName()

◆ hasMultiFrameHandle()

◆ hasNormalFrameHandle()

◆ isValidPosition()

◆ needsNewSOPInstanceUID()

◆ operator!=()

◆ operator=()

◆ operator==()

◆ resizePageFileNamesToVolumeSize()

◆ searchFrameWithSOPInstanceUID()

◆ searchFrameWithValueInTag()

◆ setPageFileName()

◆ setPageFileNames()

◆ setStateFromString()