Enumerations
enum	{ NumLosslessTransferSyntaxes = 8 }
	Number of supported lossless compression transfer syntax modes. More...

Functions
MLDICOMCachedIO_EXPORT void	pushMessageCollecting ()
	Takes current message handles of DCMTree library and uses redirectStream() to push current handler and message states on a stack and sets up own handlers to collect all messages from that handler and from std::cerr stream; needs to be restored with popMessageCollecting();.

MLDICOMCachedIO_EXPORT void	popMessageCollecting (DicomMessageCollector &dcmMsgCollector, const std::string &callersMessage, size_t outStrMaxSize=std::string::npos, bool addClampInfo=true)
	Restores states which must have been saved before with pushMessageCollecting() and sends collected (and possibly processed) messages to dcmMsgCollector for further processing.

MLDICOMCachedIO_EXPORT void	redirectStream (std::ostream &outputStream, std::streambuf &tempBuf, std::stringbuf &stringBuffer)
	Redirect outputs to outputStream into the temporary buffer tmpBuf.

MLDICOMCachedIO_EXPORT std::string	unRedirectStream (std::ostream &outputStream, std::streambuf &tmpBuf, std::stringbuf &stringBuffer, size_t outStrMaxSize=std::string::npos, bool addClampInfo=true)
	Undo the redirected output of outputStream into the temporary buffer tmpBuf.

MLDICOMCachedIO_EXPORT void	makeWarningsWarningsAndErrorsErrors (std::string &messageString)
	Some messages for example from DCMTree(_OFFIS) are not marked with "error" or "warnings" and cannot be filtered correctly therefore in DicomMessageFilters.

MLDICOMCachedIO_EXPORT void	logFileCheckInfos (const std::string &fileName, DicomMessageCollector &dcmMsgCollector, bool pedantic=true, bool doWarnEmpty=false, bool doWarnFullPathLonger254=false, bool doWarnSpaces=false, bool doWarnUntypicalChars=false, bool warnBaseNamesLonger31=false)
	Logs nothing into dcmMsgCollector if fileName is okay according to selected checks, for example whether it has a length lower problematic limits and does not contain any non-typical characters spaces; otherwise it appends warnings! about possible reasons of a for an IO error; this function is intended to be called whenever a file IO problem occurred on fileName and the user shall be informed about and problems which could be related to the length or content of the file name (path).

MLDICOMCachedIO_EXPORT std::string	logFileCheckInfosIntoString (const std::string &fileName, const std::string &prependMessage=" ", bool pedantic=true, bool doWarnEmpty=false, bool doWarnFullPathLonger254=false, bool doWarnSpaces=false, bool doWarnUntypicalChars=false, bool warnBaseNamesLonger31=false)
	Same as DICOMCachedIO::logFileCheckInfos() but it return the result information as std::string.

MLDICOMCachedIO_EXPORT DCMTree::TreePtr	getDirectDCMTree (const std::string &fName, DicomMessageCollector &dcmMsgCollector, bool loadPixelData=false)
	Tries to open a file directly by reading it with the DCMTree interfaces and returns a non constant TreePtr pointer on success or a nullptr TreePtr on failure.

MLDICOMCachedIO_EXPORT MLErrorCode	getDCMTreeFromDICOMFile (const std::string &dcmFileName, DCMTree::Const_TreePtr &treePtr, size_t &numVols, DicomMessageCollector &dcmMsgCollector)
	Loads a Const_TreePtr from a valid DICOM given by the absolute file path fileName if possible.

MLDICOMCachedIO_EXPORT MLErrorCode	getDCMTreeFromDCMTiffFilePair (const std::string &dcmTiffFileName, DCMTree::Const_TreePtr &treePtr, size_t &numVols, DicomMessageCollector &dcmMsgCollector)
	Loads a Const_TreePtr from a any of both filename components of DCM/TIFF file pair if possible.

MLDICOMCachedIO_EXPORT void	getDCMTreeFromPagedImage (PagedImage *inImg, DCMTree::Const_TreePtr &treePtr, size_t &numVols)
	Returns a Const_TreePtr from the given PagedImage if possible.

MLDICOMCachedIO_EXPORT void	getDCMTreeFromDicomTreeBasePtr (Base *basePtr, DCMTree::Const_TreePtr &treePtr, size_t &numVols)
	Returns a Const_TreePtr from a DicomTree pointer given as Base pointer if possible.

MLDICOMCachedIO_EXPORT DCMTree::TransferSyntax	getLosslessStorageTransferSyntax (DCMTree::Const_TreePtr dcmTree)
	If dcmTree has a TransferSyntaxUID tag matching one form LosslessTransferSyntaxUIDs then the corresponding DCMTree::TransferSyntax is returned, otherwise DCMTree::EXPLICIT_LITTLE_ENDIAN is returned.

MLDICOMCachedIO_EXPORT DCMTree::Const_TagPtr	getPrivateTag (const std::string &privateCreatorString, unsigned short groupId, DCMTree::RawTagId lowerEightBitOfElementId, DCMTree::Const_TreePtr dcmTree)
	If a private creator tag with value privateCreatorString in a private slot with groupId and a tag with element id lowerEightBitOfElementId is found then the private tag is returned; in all other cases nullptr is returned.

MLDICOMCachedIO_EXPORT bool	isPhilips3D (DCMTree::Const_TreePtr dcmTree, MLint *spatialExtent=nullptr)
	Looks for Philips3D format and if there is an extra spatial extent then it is returned in spatialExtent (if non-nullptr) and true is returned, in all other cases false is returned and spatialExtent is unchanged.

MLDICOMCachedIO_EXPORT unsigned int	getNumberOfFrames (DCMTree::Const_TreePtr dcmTree, unsigned int *fromTagOnly=nullptr)
	Returns the number of real frames in the data set from Number of Frames tag if possible including a possible private extensions such as Philips 3D; if the number of frames cannot be determined for any reason then 0 is returned; if fromTagOnly is not nullptr then the value of the Number Of Frames tag is returned or 0 if not possible.

MLDICOMCachedIO_EXPORT DCMTree::PixelData	getPixelDataPtrFromTree (DCMTree::Const_TreePtr treePtr, size_t *valSizeInBytes, DicomMessageCollector &dcmMsgCollector)
	Returns the pointer to the pixel data tag value.

MLDICOMCachedIO_EXPORT void	removeAssociatedCacheEntries (const DICOMCachedIOFileHandle &fileHandle)
	Flush all cached entries related to the given file handle.

MLDICOMCachedIO_EXPORT void	clearDICOMCaches ()
	Clears all cached DICOM date including tags, trees, pixel frames and decomposed multi-frame trees.

Variables
MLDICOMCachedIO_EXPORT const char *const	LosslessTransferSyntaxUIDs [NumLosslessTransferSyntaxes]
	Supported lossless compression transfer syntax UIDs.

MLDICOMCachedIO_EXPORT const char *const	LosslessTransferSyntaxNames [NumLosslessTransferSyntaxes]
	Supported lossless compression transfer syntax names.

MLDICOMCachedIO_EXPORT DCMTree::TransferSyntax	LosslessTransferSyntaxCodes [NumLosslessTransferSyntaxes]
	DCMTree::TransferSyntax enums for supported lossless compression transfer syntax.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Number of supported lossless compression transfer syntax modes.

Enumerator
NumLosslessTransferSyntaxes

Definition at line 209 of file mlDICOMCachedIOTools.h.

Function Documentation

◆ clearDICOMCaches()

MLDICOMCachedIO_EXPORT void ml::DICOMCachedIOTools::clearDICOMCaches ( )

Clears all cached DICOM date including tags, trees, pixel frames and decomposed multi-frame trees.

References clearDICOMCaches().

Referenced by clearDICOMCaches().

◆ getDCMTreeFromDCMTiffFilePair()

MLDICOMCachedIO_EXPORT MLErrorCode ml::DICOMCachedIOTools::getDCMTreeFromDCMTiffFilePair	(	const std::string &	dcmTiffFileName,
		DCMTree::Const_TreePtr &	treePtr,
		size_t &	numVols,
		DicomMessageCollector &	dcmMsgCollector
	)

Loads a Const_TreePtr from a any of both filename components of DCM/TIFF file pair if possible.

Parameters

dcmTiffFileName	The absolute file name path to the any of the file name components of the DCM/TIFF file pair from which the DCMTree shall be loaded.
treePtr	Returns the loaded DCMTree on success, nullptr on failure.
numVols	Will return 1 on successful DCMTree load, otherwise 0.
dcmMsgCollector	Collects error, info and issue messages (typically related to a handle).

Returns: ML_RESULT_OK on successful load, or ML_OBJECT_OR_FILE_DOES_NOT_EXIST if it is not a valid DCM/TIFF file pair or another error code describing the problem. Any issues get also reported as non empty issue in dcmMessageCollector.

References getDCMTreeFromDCMTiffFilePair().

Referenced by getDCMTreeFromDCMTiffFilePair().

◆ getDCMTreeFromDICOMFile()

MLDICOMCachedIO_EXPORT MLErrorCode ml::DICOMCachedIOTools::getDCMTreeFromDICOMFile	(	const std::string &	dcmFileName,
		DCMTree::Const_TreePtr &	treePtr,
		size_t &	numVols,
		DicomMessageCollector &	dcmMsgCollector
	)

Loads a Const_TreePtr from a valid DICOM given by the absolute file path fileName if possible.

Parameters

dcmFileName	The absolute file name path to the DICOM file from which the DCMTree shall be loaded.
treePtr	Returns the loaded DCMTree on success, nullptr on failure.
numVols	Will return 1 on successful DCMTree load, otherwise 0.
dcmMsgCollector	Collects error, info and issue messages (typically related to a handle).

Returns: ML_RESULT_OK on successful load, otherwise an error code describing the problem.

References getDCMTreeFromDICOMFile().

Referenced by getDCMTreeFromDICOMFile().

◆ getDCMTreeFromDicomTreeBasePtr()

MLDICOMCachedIO_EXPORT void ml::DICOMCachedIOTools::getDCMTreeFromDicomTreeBasePtr	(	Base *	basePtr,
		DCMTree::Const_TreePtr &	treePtr,
		size_t &	numVols
	)

Returns a Const_TreePtr from a DicomTree pointer given as Base pointer if possible.

Parameters

basePtr	The Base pointer pointing to a DicomTree (allowed to be nullptr or pointing to another Base type).
treePtr	Returns the DCMTree on successful retrieval, nullptr otherwise or unavailability.
numVols	Will return 1 on successful DCMTree retrieval, otherwise 0.

References getDCMTreeFromDicomTreeBasePtr().

Referenced by getDCMTreeFromDicomTreeBasePtr().

◆ getDCMTreeFromPagedImage()

MLDICOMCachedIO_EXPORT void ml::DICOMCachedIOTools::getDCMTreeFromPagedImage	(	PagedImage *	inImg,
		DCMTree::Const_TreePtr &	treePtr,
		size_t &	numVols
	)

Returns a Const_TreePtr from the given PagedImage if possible.

Parameters

inImg	The PagedImage from which the DCMTree shall be retrieved (allowed to be nullptr).
treePtr	Returns the DCMTree on success, nullptr on failure or unavailability.
numVols	Will return 1 on successful DCMTree retrieval, otherwise 0.

References getDCMTreeFromPagedImage().

Referenced by getDCMTreeFromPagedImage().

◆ getDirectDCMTree()

MLDICOMCachedIO_EXPORT DCMTree::TreePtr ml::DICOMCachedIOTools::getDirectDCMTree	(	const std::string &	fName,
		DicomMessageCollector &	dcmMsgCollector,
		bool	loadPixelData = `false`
	)

Tries to open a file directly by reading it with the DCMTree interfaces and returns a non constant TreePtr pointer on success or a nullptr TreePtr on failure.

In contrast to the DICOMCachedIOTreeCache interfaces this tree is not cached. issues is set to the amount of fatal and non fatal issues. Note that there also may be non fatal messages in issues while a non nullptr tree is returned. This function is not thread-safe and not reentrant.

Parameters

fName	File name from which the DCMTree is to be read.
dcmMsgCollector	Collects error, info and issue messages (typically related to a handle).
loadPixelData	If false (the default) then do not load pixel data, (usually for performance reasons), otherwise load it.

Returns: a non constant TreePtr pointer on success or a nullptr TreePtr on failure.

References getDirectDCMTree().

Referenced by getDirectDCMTree().

◆ getLosslessStorageTransferSyntax()

MLDICOMCachedIO_EXPORT DCMTree::TransferSyntax ml::DICOMCachedIOTools::getLosslessStorageTransferSyntax ( DCMTree::Const_TreePtr dcmTree )

If dcmTree has a TransferSyntaxUID tag matching one form LosslessTransferSyntaxUIDs then the corresponding DCMTree::TransferSyntax is returned, otherwise DCMTree::EXPLICIT_LITTLE_ENDIAN is returned.

References getLosslessStorageTransferSyntax().

Referenced by getLosslessStorageTransferSyntax().

◆ getNumberOfFrames()

MLDICOMCachedIO_EXPORT unsigned int ml::DICOMCachedIOTools::getNumberOfFrames	(	DCMTree::Const_TreePtr	dcmTree,
		unsigned int *	fromTagOnly = `nullptr`
	)

Returns the number of real frames in the data set from Number of Frames tag if possible including a possible private extensions such as Philips 3D; if the number of frames cannot be determined for any reason then 0 is returned; if fromTagOnly is not nullptr then the value of the Number Of Frames tag is returned or 0 if not possible.

References getNumberOfFrames().

Referenced by getNumberOfFrames().

◆ getPixelDataPtrFromTree()

MLDICOMCachedIO_EXPORT DCMTree::PixelData ml::DICOMCachedIOTools::getPixelDataPtrFromTree	(	DCMTree::Const_TreePtr	treePtr,
		size_t *	valSizeInBytes,
		DicomMessageCollector &	dcmMsgCollector
	)

Returns the pointer to the pixel data tag value.

If data is not found then nullptr is returned. This function does not handle multi-frame pixel tags, nullptr is returned in that case, however, the expected size of pixel data is returned anyway if valSizeInBytes if provided non-nullptr. Only top level tags with ids DCMTree_PixelData, DCMTree_FloatPixelData, and DCMTree_DoubleFloatPixelData are checked.

Parameters

treePtr	The DicomTree from whose pixelDataTag the pixelData shall be read.
valSizeInBytes	If valSizeInBytes is non nullptr then *valSizeInBytes is set to the size of the pixel data chunk in bytes, otherwise it is ignored.
dcmMsgCollector	Collects error, info and issue messages (typically related to a handle).

References getPixelDataPtrFromTree().

Referenced by getPixelDataPtrFromTree().

◆ getPrivateTag()

MLDICOMCachedIO_EXPORT DCMTree::Const_TagPtr ml::DICOMCachedIOTools::getPrivateTag	(	const std::string &	privateCreatorString,
		unsigned short	groupId,
		DCMTree::RawTagId	lowerEightBitOfElementId,
		DCMTree::Const_TreePtr	dcmTree
	)

If a private creator tag with value privateCreatorString in a private slot with groupId and a tag with element id lowerEightBitOfElementId is found then the private tag is returned; in all other cases nullptr is returned.

References getPrivateTag().

Referenced by getPrivateTag().

◆ isPhilips3D()

MLDICOMCachedIO_EXPORT bool ml::DICOMCachedIOTools::isPhilips3D	(	DCMTree::Const_TreePtr	dcmTree,
		MLint *	spatialExtent = `nullptr`
	)

Looks for Philips3D format and if there is an extra spatial extent then it is returned in spatialExtent (if non-nullptr) and true is returned, in all other cases false is returned and spatialExtent is unchanged.

References isPhilips3D().

Referenced by isPhilips3D().

◆ logFileCheckInfos()

MLDICOMCachedIO_EXPORT void ml::DICOMCachedIOTools::logFileCheckInfos	(	const std::string &	fileName,
		DicomMessageCollector &	dcmMsgCollector,
		bool	pedantic = `true`,
		bool	doWarnEmpty = `false`,
		bool	doWarnFullPathLonger254 = `false`,
		bool	doWarnSpaces = `false`,
		bool	doWarnUntypicalChars = `false`,
		bool	warnBaseNamesLonger31 = `false`
	)

Logs nothing into dcmMsgCollector if fileName is okay according to selected checks, for example whether it has a length lower problematic limits and does not contain any non-typical characters spaces; otherwise it appends warnings! about possible reasons of a for an IO error; this function is intended to be called whenever a file IO problem occurred on fileName and the user shall be informed about and problems which could be related to the length or content of the file name (path).

Future versions may also check for other things such as permissions, non-standard characters or so, which, however, are still not implemented.

Parameters

fileName	The file path/name to be checked.
dcmMsgCollector	The DicomMessageCollector in which to log the messages.
pedantic	If true then all subsequent do-named checks are implicitly set true (e.g. doWarnSpaces, doWarnBaseNamesLonger31 and possible future ones).
doWarnEmpty	If enabled then empty paths will be warned, otherwise only if pedantic is true.
doWarnFullPathLonger254	If enabled then path lengths > 254 characters will be warned, otherwise only if pedantic is true.
doWarnSpaces	If enabled then spaces in the path will be warned, otherwise only if pedantic is true.
doWarnUntypicalChars	If enabled then non-typical characters which are forbidden undesired or problematic in some circumstances such non-printables, ASCII values not in "A B C D E F G H I J K L M N O P Q R S T U V W X Y Z a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8 9 . _ - / \ "
warnBaseNamesLonger31	If enabled then basenames longer than 31 characters will be warned, otherwise not. This check is not included in pedantic checks since it happens in too many files related to MeVisLab operations.

References logFileCheckInfos().

Referenced by logFileCheckInfos().

◆ logFileCheckInfosIntoString()

MLDICOMCachedIO_EXPORT std::string ml::DICOMCachedIOTools::logFileCheckInfosIntoString	(	const std::string &	fileName,
		const std::string &	prependMessage = `" "`,
		bool	pedantic = `true`,
		bool	doWarnEmpty = `false`,
		bool	doWarnFullPathLonger254 = `false`,
		bool	doWarnSpaces = `false`,
		bool	doWarnUntypicalChars = `false`,
		bool	warnBaseNamesLonger31 = `false`
	)

Same as DICOMCachedIO::logFileCheckInfos() but it return the result information as std::string.

prependMessage is ignored if no message is generated, otherwise it is added at begin of the returned string which is useful for separation from other messages logged before.

References logFileCheckInfosIntoString().

Referenced by logFileCheckInfosIntoString().

◆ makeWarningsWarningsAndErrorsErrors()

MLDICOMCachedIO_EXPORT void ml::DICOMCachedIOTools::makeWarningsWarningsAndErrorsErrors ( std::string & messageString )

Some messages for example from DCMTree(_OFFIS) are not marked with "error" or "warnings" and cannot be filtered correctly therefore in DicomMessageFilters.

Those ones we know we mark appropriately here by inserting "warning" or "error" at the correct places.

References makeWarningsWarningsAndErrorsErrors().

Referenced by makeWarningsWarningsAndErrorsErrors().

◆ popMessageCollecting()

MLDICOMCachedIO_EXPORT void ml::DICOMCachedIOTools::popMessageCollecting	(	DicomMessageCollector &	dcmMsgCollector,
		const std::string &	callersMessage,
		size_t	outStrMaxSize = `std::string::npos`,
		bool	addClampInfo = `true`
	)

Restores states which must have been saved before with pushMessageCollecting() and sends collected (and possibly processed) messages to dcmMsgCollector for further processing.

callersMessage may contain additional information about the caller, its position etc for enhance message understanding.

Parameters

dcmMsgCollector	The message collector into which the received messages are forwarded.
callersMessage	The message added before the messages forwarded to the dcmMsgCollector.
outStrMaxSize	Passed unchanged to the internally used unRedirectStream.
addClampInfo	Passed unchanged to the internally used unRedirectStream.

References popMessageCollecting().

Referenced by popMessageCollecting().

◆ pushMessageCollecting()

MLDICOMCachedIO_EXPORT void ml::DICOMCachedIOTools::pushMessageCollecting ( )

Takes current message handles of DCMTree library and uses redirectStream() to push current handler and message states on a stack and sets up own handlers to collect all messages from that handler and from std::cerr stream; needs to be restored with popMessageCollecting();.

References pushMessageCollecting().

Referenced by pushMessageCollecting().

◆ redirectStream()

MLDICOMCachedIO_EXPORT void ml::DICOMCachedIOTools::redirectStream	(	std::ostream &	outputStream,
		std::streambuf *&	tempBuf,
		std::stringbuf *&	stringBuffer
	)

Redirect outputs to outputStream into the temporary buffer tmpBuf.

Parameters

outputStream	The stream which to be redirected until unRedirectStream is called.
tempBuf	The buffer used to store the streambuf used outputStream, must be passed unchanged to unredirectStream later. Previous content will be overwritten.
stringBuffer	The buffer used to collect the stream outputs between the call to redirectStream and unRedirectStream, must be passed unchanged to unredirectStream later. Previous content will be overwritten.

References redirectStream().

Referenced by redirectStream().

◆ removeAssociatedCacheEntries()

MLDICOMCachedIO_EXPORT void ml::DICOMCachedIOTools::removeAssociatedCacheEntries ( const DICOMCachedIOFileHandle & fileHandle )

Flush all cached entries related to the given file handle.

References removeAssociatedCacheEntries().

Referenced by removeAssociatedCacheEntries().

◆ unRedirectStream()

MLDICOMCachedIO_EXPORT std::string ml::DICOMCachedIOTools::unRedirectStream	(	std::ostream &	outputStream,
		std::streambuf *&	tmpBuf,
		std::stringbuf *&	stringBuffer,
		size_t	outStrMaxSize = `std::string::npos`,
		bool	addClampInfo = `true`
	)

Undo the redirected output of outputStream into the temporary buffer tmpBuf.

Parameters

outputStream	The stream which was redirected with redirectStream.
tmpBuf	The buffer used to store the previous streambuf used by outputStream, must be one passed to redirectStream.
stringBuffer	The buffer used to collect the stream outputs between the call to redirectStream and unRedirectStream.
outStrMaxSize	The size to which the collected information will be clamped.
addClampInfo	If the collected stream information was clamped then an information message will be added to inform the user about the clamping.

Returns: An empty string if nothing was collected between the calls to redirectStream and unRedirectStream and passed parameters were valid. Otherwise a string describing the parameter errors or the composed message of collected and/or clamped message possibly with a clamping information.

References unRedirectStream().

Referenced by unRedirectStream().

Variable Documentation

◆ LosslessTransferSyntaxCodes

MLDICOMCachedIO_EXPORT DCMTree::TransferSyntax ml::DICOMCachedIOTools::LosslessTransferSyntaxCodes[NumLosslessTransferSyntaxes]

extern

DCMTree::TransferSyntax enums for supported lossless compression transfer syntax.

◆ LosslessTransferSyntaxNames

MLDICOMCachedIO_EXPORT const char* const ml::DICOMCachedIOTools::LosslessTransferSyntaxNames[NumLosslessTransferSyntaxes]

extern

Supported lossless compression transfer syntax names.

◆ LosslessTransferSyntaxUIDs

MLDICOMCachedIO_EXPORT const char* const ml::DICOMCachedIOTools::LosslessTransferSyntaxUIDs[NumLosslessTransferSyntaxes]

extern

Supported lossless compression transfer syntax UIDs.

Enumerations

Functions

Variables

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ clearDICOMCaches()

◆ getDCMTreeFromDCMTiffFilePair()

◆ getDCMTreeFromDICOMFile()

◆ getDCMTreeFromDicomTreeBasePtr()

◆ getDCMTreeFromPagedImage()

◆ getDirectDCMTree()

◆ getLosslessStorageTransferSyntax()

◆ getNumberOfFrames()

◆ getPixelDataPtrFromTree()

◆ getPrivateTag()

◆ isPhilips3D()

◆ logFileCheckInfos()

◆ logFileCheckInfosIntoString()

◆ makeWarningsWarningsAndErrorsErrors()

◆ popMessageCollecting()

◆ pushMessageCollecting()

◆ redirectStream()

◆ removeAssociatedCacheEntries()

◆ unRedirectStream()

Variable Documentation

◆ LosslessTransferSyntaxCodes

◆ LosslessTransferSyntaxNames

◆ LosslessTransferSyntaxUIDs