DCMTK  Version 3.6.7
OFFIS DICOM Toolkit
Classes | Public Types | Public Member Functions | Protected Member Functions | Private Attributes | List of all members
ConcatenationLoader Class Reference

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< FailureTScanFailures
 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. More...
 
virtual OFCondition scan (const OFList< OFFilename > &files)
 Scan given list of files for Concatenations. More...
 
virtual OFCondition scan (const OFFilename &directory, const OFFilename &pattern="*", OFBool recursive=OFTrue)
 Scan given directory for Concatenations. More...
 
virtual const TScanResultgetInfo ()
 Get successful results of scan() operation. More...
 
virtual const TScanFailuresgetFailedFiles ()
 Get failed files of scan() operation. More...
 
virtual OFCondition load (const OFString &concatenationUID, DcmDataset *dataset, OFVector< DcmIODTypes::Frame * > &frames)
 Load Concatenation and merge it into "original" source dataset. More...
 

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. More...
 
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. More...
 
virtual OFBool zeroOrEqual (const size_t num1, const size_t num2)
 Check whether two numbers equal to 0 or empty. More...
 
virtual OFBool emptyOrEqual (const OFString &str1, const OFString &str2)
 Check whether two strings are equal or one of them is empty. More...
 
template<typename T >
getNotZero (const T num1, const T num2)
 Get that number from both which is not 0. More...
 
virtual OFCondition doScanFinalChecks ()
 Perform consistency checks on the Concatenations found. More...
 
virtual OFCondition prepareTemplate (Info &firstInstance)
 Prepare template (dataset) that is used to represent the final result dataset. More...
 
virtual OFCondition extractFrames (DcmItem &item, Info &info, Uint32 numFrames)
 Extract frames from given item. More...
 
virtual OFCondition extractBinaryFrames (DcmItem &item, Info &info, Uint32 numFrames)
 Extract binary frames (Bits Allocated = 1) from given item. More...
 
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. More...
 
virtual OFCondition movePerFrameItems (DcmItem &item)
 Moves all Per-Frame Functional Group items found in given item to result instance. More...
 
virtual OFCondition insertDestinationAttributes ()
 Insert/adapt attributes that are required with the merged result instance. More...
 

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.
 
DcmDatasetm_Result
 The dataset that will contain the final merged SOP instance produced by the load() method. More...
 
OFVector< DcmIODTypes::Frame * > m_Frames
 The frames that will contain all the frames of the merged SOP instance produced by the load() method. More...
 

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:

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
infoInformation for this Concatenation
instInstance information that should be added to the Concatenation
errorError, 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
itemThe 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
str1The first string
str2The 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
itemThe item to read Pixel Data attribute from
infoConcatenation information providing pixel meta data like Rows and Columns
numFramesThe 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
itemThe item to read Pixel Data attribute from
infoConcatenation information providing pixel meta data like Rows and Columns
numFramesThe 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
num1The first number
num2The 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
fileThe file to process
infoThe 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
concatenationUIDThe Concatenation UID of the Concatenation to be loaded
datasetThe 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.
framesThe 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
itemThe 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
firstInstanceThe 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
directoryThe directory to scan
patternThe search pattern (* per default)
recursiveIf 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
filesThe 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
ignoreIf 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
num1The first number
num2The 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:


Generated on Thu Apr 28 2022 for DCMTK Version 3.6.7 by Doxygen 1.9.1