DCMTK Version 3.7.0 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< 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. 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 TScanResult & | getInfo ()
| Get successful results of scan() operation. More...
virtual const TScanFailures & | getFailedFiles ()
| Get failed files of scan() operation. More...
virtual OFCondition | load (const OFString &concatenationUID, DcmDataset *dataset, OFVector< DcmIODTypes::FrameBase * > &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 >
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...
virtual OFCondition | computeBytesPerFrame (const Uint16 rows, const Uint16 cols, const Uint16 bitsAlloc, size_t &bytes_per_frame)
| Compute bytes per frame based on Rows, Columns and Bits Allocated. 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.
DcmDataset * | m_Result
| The dataset that will contain the final merged SOP instance produced by the load() method. More...
OFVector< DcmIODTypes::FrameBase * > | 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:

- 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
| ) |  |
| protected virtual

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.

## ◆ computeBytesPerFrame()

virtual OFCondition ConcatenationLoader::computeBytesPerFrame | ( | const Uint16 | rows,
|  | const Uint16 | cols,
|  | const Uint16 | bitsAlloc,
|  | size_t & | bytes_per_frame
| ) |  |
| protected virtual

Compute bytes per frame based on Rows, Columns and Bits Allocated.

Parameters

  rows | The number of Rows
  cols | The number of Columns
  bitsAlloc | The Bits Allocated value (only 1, 8 or 16 supported)
  bytes_per_frame | The resulting number of bytes per frame

Returns
  EC_Normal if successful, error otherwise.

## ◆ deleteConcatAttributes()

virtual OFCondition ConcatenationLoader::deleteConcatAttributes | ( | DcmItem & | item | ) |
| protected virtual

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 | ( |  | ) |
| protected virtual

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
| ) |  |
| protected virtual

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
| ) |  |
| protected virtual

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
| ) |  |
| protected virtual

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
| ) |  |
| protected virtual

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 | ( |  | ) |
| protected virtual

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::FrameBase * > & | 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 | ) |
| protected virtual

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 | ) |
| protected virtual

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
| ) |  |
| protected virtual

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::FrameBase*> 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

Generated on Mon Dec 15 2025 for DCMTK Version 3.7.0 by Doxygen 1.9.1