Class for scanning files for concatenations and if desired, load one of them. More...

Classes
struct	Failure
	structure representing error information about a failed file More...

struct	Info
	Structure representing information about a Concatenation, consisting of its instances and common data. More...

Public Types
typedef OFMap< OFString, ConcatenationLoader::Info * >	TScanResult
	Result type of scan()

typedef OFMap< OFString, ConcatenationLoader::Info * >::iterator	ScanResultIt
	Iterator type for iterating over scan() results.

typedef OFList< Failure >	TScanFailures
	Result type for the failures reported by scan()

Public Member Functions
typedef	OFListIterator (Failure) TScanFailureIt
	Result type for iterating the failures reported by scan()

	ConcatenationLoader ()
	Constructor.

virtual	~ConcatenationLoader ()
	Virtual destructor.

virtual void	setIgnoreMissingSourceUID (const OFBool ignore)
	Ignore missing SOP Instance UID of Concatenation Source.

virtual OFCondition	scan (const OFList< OFFilename > &files)
	Scan given list of files for Concatenations.

virtual OFCondition	scan (const OFFilename &directory, const OFFilename &pattern="*", OFBool recursive=OFTrue)
	Scan given directory for Concatenations.

virtual const TScanResult &	getInfo ()
	Get successful results of scan() operation.

virtual const TScanFailures &	getFailedFiles ()
	Get failed files of scan() operation.

virtual OFCondition	load (const OFString &concatenationUID, DcmDataset dataset, OFVector< DcmIODTypes::Frame > &frames)
	Load Concatenation and merge it into "original" source dataset.

Protected Member Functions
virtual void	handleFile (const OFFilename &file, ConcatenationLoader::Info &info)
	Handles single file of a Concatenation and extracts structure for later access by the user.

virtual void	checkAndInsertInfo (const ConcatenationLoader::Info &info, const ConcatenationLoader::Info::Instance &inst, OFString &error)
	Checks an current file's information whether it fits to the rest of the Concatenation instances already read.

virtual OFBool	zeroOrEqual (const size_t num1, const size_t num2)
	Check whether two numbers equal to 0 or empty.

virtual OFBool	emptyOrEqual (const OFString &str1, const OFString &str2)
	Check whether two strings are equal or one of them is empty.

template<typename T >
T	getNotZero (const T num1, const T num2)
	Get that number from both which is not 0.

virtual OFCondition	doScanFinalChecks ()
	Perform consistency checks on the Concatenations found.

virtual OFCondition	prepareTemplate (Info &firstInstance)
	Prepare template (dataset) that is used to represent the final result dataset.

virtual OFCondition	extractFrames (DcmItem &item, Info &info, Uint32 numFrames)
	Extract frames from given item.

virtual OFCondition	extractBinaryFrames (DcmItem &item, Info &info, Uint32 numFrames)
	Extract binary frames (Bits Allocated = 1) from given item.

virtual OFCondition	deleteConcatAttributes (DcmItem &item)
	Deletes those concatenation attributes from given item that are not used or get a different value in the resulting merged dataset.

virtual OFCondition	movePerFrameItems (DcmItem &item)
	Moves all Per-Frame Functional Group items found in given item to result instance.

virtual OFCondition	insertDestinationAttributes ()
	Insert/adapt attributes that are required with the merged result instance.

Private Attributes
TScanResult	m_Concats
	Map with entries consisting each of ConcatenationUID and related Concatenation information.

TScanFailures	m_FailedFiles
	List with failed files, each entry consisting of filename, error text and SOP Instance UID (latter might be empty).

OFBool	m_ignoreMissingSourceUID
	If OFTrue, the missing of attribute SOP Instance UID of Concatenation Source is ignored and will not lead to an error.

DcmDataset *	m_Result
	The dataset that will contain the final merged SOP instance produced by the load() method.

OFVector< DcmIODTypes::Frame * >	m_Frames
	The frames that will contain all the frames of the merged SOP instance produced by the load() method.

Detailed Description

Class for scanning files for concatenations and if desired, load one of them.

If successful, loading produces the merged SOP Instance as a single dataset plus its frames in a separate data structure. The following workflow must be used:

Call to one of the scan() methods.
If scanning was successful, call getInfo() to get information about the concatenations found by scan(). getFailedFiles() will return those files who could not be read, do not provide Concatenation information or had other errors.
Call to the load() method in order to load of the the Concatenations found during scan(). Selection is done via the Concatenations Concatenation UID. The result is made available as a single, merged dataset without Pixel Data attribute and a vector containing all frames of the merged instance.

Member Function Documentation

◆ checkAndInsertInfo()

virtual void ConcatenationLoader::checkAndInsertInfo	(	const ConcatenationLoader::Info &	info,
		const ConcatenationLoader::Info::Instance &	inst,
		OFString &	error
	)

protectedvirtual

Checks an current file's information whether it fits to the rest of the Concatenation instances already read.

If this is the case, the instance's information is added to the results.

Parameters

info	Information for this Concatenation
inst	Instance information that should be added to the Concatenation
error	Error, if instance cannot be processed/added, otherwise empty.

◆ deleteConcatAttributes()

virtual OFCondition ConcatenationLoader::deleteConcatAttributes ( DcmItem & item )

protectedvirtual

Deletes those concatenation attributes from given item that are not used or get a different value in the resulting merged dataset.

Parameters

item	The item to delete from

Returns: EC_Normal if successful, error otherwise

◆ doScanFinalChecks()

virtual OFCondition ConcatenationLoader::doScanFinalChecks ( )

protectedvirtual

Perform consistency checks on the Concatenations found.

Returns: EC_Normal if successful, failure otherwise

◆ emptyOrEqual()

virtual OFBool ConcatenationLoader::emptyOrEqual	(	const OFString &	str1,
		const OFString &	str2
	)

protectedvirtual

Check whether two strings are equal or one of them is empty.

Parameters

str1	The first string
str2	The second string

Returns: OFTrue if both strings are equal or one of them is empty, OFFalse otherwise.

◆ extractBinaryFrames()

virtual OFCondition ConcatenationLoader::extractBinaryFrames	(	DcmItem &	item,
		Info &	info,
		Uint32	numFrames
	)

protectedvirtual

Extract binary frames (Bits Allocated = 1) from given item.

The resulting frames are stored in member variable.

Parameters

item	The item to read Pixel Data attribute from
info	Concatenation information providing pixel meta data like Rows and Columns
numFrames	The number of frames to extract from item's Pixel Data attribute

Returns: EC_Normal if extraction was successful, error otherwise.

◆ extractFrames()

virtual OFCondition ConcatenationLoader::extractFrames	(	DcmItem &	item,
		Info &	info,
		Uint32	numFrames
	)

protectedvirtual

Extract frames from given item.

Works for Bits Allocated = 8 and Bits Allocated = 16. Resulting frames are stored in member variable.

Parameters

item	The item to read Pixel Data attribute from
info	Concatenation information providing pixel meta data like Rows and Columns
numFrames	The number of frames to extract from item's Pixel Data attribute

Returns: EC_Normal if extraction was successful, error otherwise.

◆ getFailedFiles()

virtual const TScanFailures & ConcatenationLoader::getFailedFiles ( )

virtual

Get failed files of scan() operation.

Returns empty result set is scan() has not been called before (may be empty otherwise).

Returns: The failed files of the scan() operation

◆ getInfo()

virtual const TScanResult & ConcatenationLoader::getInfo ( )

virtual

Get successful results of scan() operation.

Returns empty result set is scan() has not been called before.

Returns: The results of the scan() operation

◆ getNotZero()

template<typename T >

T ConcatenationLoader::getNotZero	(	const T	num1,
		const T	num2
	)

protected

Get that number from both which is not 0.

Parameters

num1	The first number
num2	The second number

Returns: num1 if num 1 is not zero, num 2 otherwise.

◆ handleFile()

virtual void ConcatenationLoader::handleFile	(	const OFFilename &	file,
		ConcatenationLoader::Info &	info
	)

protectedvirtual

Handles single file of a Concatenation and extracts structure for later access by the user.

Parameters

file	The file to process
info	The concatenation information structure to store results to

◆ insertDestinationAttributes()

virtual OFCondition ConcatenationLoader::insertDestinationAttributes ( )

protectedvirtual

Insert/adapt attributes that are required with the merged result instance.

Returns: EC_Normal if successful, failure otherwise

◆ load()

virtual OFCondition ConcatenationLoader::load	(	const OFString &	concatenationUID,
		DcmDataset *	dataset,
		OFVector< DcmIODTypes::Frame * > &	frames
	)

virtual

Load Concatenation and merge it into "original" source dataset.

The Concatenation to be loaded is selected by its Concatenation UID. Frames are not written to the dataset's Pixel Data attribute but instead reside in a frame structure provided by the caller (since they could exceed the uncompressed maximum of 4 GB allowed in a single dataset).

Parameters

concatenationUID	The Concatenation UID of the Concatenation to be loaded
dataset	The result dataset. The caller must hand in a pointer to a valid dataset, i.e. memory allocation must be done by the caller. During loading, the dataset must not be freed outside this class. However, the caller stays responsible to delete the dataset after usage.
frames	The resulting frames. Vector should provided empty by the user. The user is responsible for deleting frames after successful operation. If load() fails, this parameter should return an empty vector.

Returns: EC_Normal if loading Concatenation worked, error otherwise.

◆ movePerFrameItems()

virtual OFCondition ConcatenationLoader::movePerFrameItems ( DcmItem & item )

protectedvirtual

Moves all Per-Frame Functional Group items found in given item to result instance.

Parameters

item	The item to delete from

Returns: EC_Normal if deletion was successful, error otherwise

◆ prepareTemplate()

virtual OFCondition ConcatenationLoader::prepareTemplate ( Info & firstInstance )

protectedvirtual

Prepare template (dataset) that is used to represent the final result dataset.

Parameters

firstInstance The first (or any instance) of the concatenation instances that will be used to create the result dataset.

Returns: EC_Normal if successful, failure otherwise

◆ scan() [1/2]

virtual OFCondition ConcatenationLoader::scan	(	const OFFilename &	directory,
		const OFFilename &	pattern = `"*"`,
		OFBool	recursive = `OFTrue`
	)

virtual

Scan given directory for Concatenations.

If successful, a results can be accessed by calling getInfo() which contains an overview of the Concatenations found (and files that failed during reading).

Parameters

directory	The directory to scan
pattern	The search pattern (* per default)
recursive	If OFTrue, sub directories are scanned, too (default: OFTrue)

Returns: EC_Normal if scanning was successful, i.e. at least one Concatenation could be discovered successfully.

◆ scan() [2/2]

virtual OFCondition ConcatenationLoader::scan ( const OFList< OFFilename > & files )

virtual

Scan given list of files for Concatenations.

If successful, a results can be accessed by calling getInfo() which contains an overview of the Concatenations found (and files that failed during reading).

Parameters

files The files to scan

Returns: EC_Normal if scanning was successful, i.e. at least one Concatenation could be discovered successfully.

◆ setIgnoreMissingSourceUID()

virtual void ConcatenationLoader::setIgnoreMissingSourceUID ( const OFBool ignore )

virtual

Ignore missing SOP Instance UID of Concatenation Source.

Parameters

ignore If OFTrue, missing or empty SOP Instance UID of Concatenation Source tag is ignored and operation continues.

◆ zeroOrEqual()

virtual OFBool ConcatenationLoader::zeroOrEqual	(	const size_t	num1,
		const size_t	num2
	)

protectedvirtual

Check whether two numbers equal to 0 or empty.

Parameters

num1	The first number
num2	The second number

Returns: OFTrue if both number are equal or one of them is 0, OFFalse otherwise.

Member Data Documentation

◆ m_Frames

OFVector<DcmIODTypes::Frame*> ConcatenationLoader::m_Frames

private

The frames that will contain all the frames of the merged SOP instance produced by the load() method.

Once a merged instance is provided to the caller, as a result of load(), the caller is responsible for deleting the related memory.

◆ m_Result

DcmDataset* ConcatenationLoader::m_Result

private

The dataset that will contain the final merged SOP instance produced by the load() method.

Once a merged instance is provided to the caller, as a result of load(), the caller is responsible for deleting the related memory.

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

dcmfg/include/dcmtk/dcmfg/concatenationloader.h

Classes

Public Types

Public Member Functions

Protected Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ checkAndInsertInfo()

◆ deleteConcatAttributes()

◆ doScanFinalChecks()

◆ emptyOrEqual()

◆ extractBinaryFrames()

◆ extractFrames()

◆ getFailedFiles()

◆ getInfo()

◆ getNotZero()

◆ handleFile()

◆ insertDestinationAttributes()

◆ load()

◆ movePerFrameItems()

◆ prepareTemplate()

◆ scan() [1/2]

◆ scan() [2/2]

◆ setIgnoreMissingSourceUID()

◆ zeroOrEqual()

Member Data Documentation

◆ m_Frames

◆ m_Result