DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Public Member Functions | Protected Member Functions | Private Attributes | Static Private Attributes | List of all members
ConcatenationCreator Class Reference

Class for creating Concatenations from existing SOP Instances. More...

## Public Member Functions
| ConcatenationCreator ()
| Constructor.
virtual | ~ConcatenationCreator ()
| Virtual destructor.
virtual OFCondition | setCfgInput (DcmItem *srcDataset, OFBool transferOwnership)
| Set input dataset that should be split into a number of concatenation instances. More...
virtual OFCondition | setCfgInput (DcmItem *srcDataset, Uint8 *pixelData, size_t pixelDataLength, OFBool transferOwnership)
| Set input dataset with separate pixel data that should be split into a number of concatenation instances. More...
virtual OFCondition | setCfgInput (DcmItem *srcDataset, Uint16 *pixelData, size_t pixelDataLength, OFBool transferOwnership)
| Set input dataset with separate pixel data that should be split into a number of concatenation instances. More...
virtual OFCondition | setCfgFramesPerInstance (Uint32 numFramesPerInstance)
| Set number of frames that should go into a single concatenation instance produced. More...
virtual OFBool | setCfgInstanceNumber (const OFString &instanceNumber)
| Set the Instance Number that should be used in the concatenation instances produced. More...
virtual OFCondition | writeNextInstance (DcmItem &dstDataset)
| Write first/next concatenation instance. More...
virtual OFCondition | writeNextInstance (const OFFilename &fn)
| Write first/next concatenation instance to given filename. More...
virtual size_t | getNumInstances ()
| Get number of concatenation instances that will be produced. More...

## Protected Member Functions
virtual OFBool | checkSOPClass (DcmItem &srcDataset)
| Check whether SOP Class of given dataset does allow Concatenation. More...
virtual OFBool | checkColorModel (DcmItem &srcDataset)
| Check whether color model (Photometric Interpretation) and planar configuration are acceptable. More...
virtual OFCondition | setConcatenationAttributes (DcmItem &dstDataset, Uint32 numFramesCurrentInstance)
| Insert Concatenation attributes into destination dataset. More...
virtual OFCondition | goToNextFrame ()
| Advance internal counters to next frame. More...
virtual Uint32 | numFramesCurrentDstInstance ()
| Return number of frames that must be written into current instance. More...
virtual OFCondition | configureCommon ()
| Configure class based on input/configuration settings, i.e. More...
virtual OFCondition | initSrcPixelData (DcmItem *srcDataset, OFBool transferOwnership)
| Prepare source pixel data (m_srcPixelData) according to the pixel data existing in the source dataset. More...

## Private Attributes
OFBool | m_configured
| Flag denoting whether class is configured (i.e. More...
OFBool | m_cfgTransferOwnership
| Flag denoting whether source data (dataset and/with frame data) should be deleted by this class (OFTrue) or not (OFFalse). More...
Uint32 | m_cfgNumFramesPerInstance
| Number of instances each concatenation instance should contain (last may differ) as configured by the user using setCfgFramesPerInstance(). More...
size_t | m_numBitsFrame
| Number of bits used for each frame (same in source instance and concatenation instances).
DcmItem * | m_srcDataset
| Pointer to source dataset; will be modified during conversion (but content is restored before the call to this class returns). More...
OFString | m_srcSOPInstanceUID
| SOP Instance UID of source instance provided in setCfgInput()
DcmIODTypes::FrameBase * | m_srcPixelData
| Pointer to source pixel data; will be modified during conversion (but content is restored before the call to this class returns). More...
DcmEVR | m_VRPixelData
| VR of pixel data extracted/derived from source dataset. More...
DcmSequenceOfItems * | m_srcPerFrameFG
| Pointer to Per-Frame Functional Group Sequence of source dataset. More...
Uint32 | m_srcNumFrames
| Number of frames in source instance.
Uint16 | m_dstNumInstances
| Number of instances to be produced for Concatenation. More...
Uint32 | m_dstNumFramesPerInstance
| Number of Frames per instance (cached) to be produced for all frames (last frame may differ)
Uint32 | m_dstNumFramesLastInstance
| Number of Frames per instance (cached) to be produced for last frame.
OFString | m_dstConcatenationUID
| Concatenation UID to be used in the concatenation instances. More...
OFString | m_dstInstanceNumber
| Instance Number to be used in concatenation instances produced. More...
Uint16 | m_currentSrcFrame
| Source frame that is used next in conversion.
DcmItem * | m_currentPerFrameItem
| Per frame FG item that is used next in conversion.
Uint16 | m_currentInstanceNum
| Next instance number that is about to be produced.

## Static Private Attributes
static Uint16 const | m_MAX_INSTANCES_PER_CONCATENATION
| Maximum number of instances that make up a Concatenation (=2^16-1=65535), derived from attributes In-concatentation Number and In-concatenation Total Number that only store 16 bit values (VR US).
static Uint32 const | m_MAX_PIXEL_DATA_LENGTH
| Maximum number of bytes for uncompressed pixel data (=2^32-2), derived from 32 bit length field of Pixel Data attribute with even length being required.

## Detailed Description

Class for creating Concatenations from existing SOP Instances.

As input, a user can either provide a full SOP Instance with Pixel Data attribute, or a SOP Instance plus separate pixel data as a vector of frame data. The input file is uncompressed if necessary and possible, and the resulting concatenation instances will also contain uncompressed pixel data. During conversion, the original source pixel data is held into memory and additionally one of the concatenation instances the moment it is being produced when calling writeNextInstance() (see below). The following workflow must be used to create a Concatenation:

- Call to one of the setCfgInput() methods in order to set the concatenation source data, i.e. the SOP Instance that should be split into a number of concatenation instances.
- Call to other setCfg...() calls in order to set conversion options. For example the number of frames per concatenation instance produced can be configured by calling setCfgFramesPerInstance(). Per default, 25 frames per instance are being used.
- Call to one of the writeNextInstance() methods in order to write the next concatenation instance.
- 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

## ◆ checkColorModel()

virtual OFBool ConcatenationCreator::checkColorModel | ( | DcmItem & | srcDataset | ) |
| protected virtual

Check whether color model (Photometric Interpretation) and planar configuration are acceptable.

Right now this class supports the following color models:

- RGB
- YBR_FULL
- MONOCHROME1
- MONOCHROME2

Also, only Planar Configuration=0 is supported (or empty value implicating the same plane configuration).

Parameters

  srcDataset | The dataset to check

Returns
  OFTrue if color model and planar configuration is permitted, OFFalse otherwise

## ◆ checkSOPClass()

virtual OFBool ConcatenationCreator::checkSOPClass | ( | DcmItem & | srcDataset | ) |
| protected virtual

Check whether SOP Class of given dataset does allow Concatenation.

Right now the Standard forbids Concatenations for:

- Ophthalmic Tomography Image Storage
- Ophthalmic Optical Coherence Tomography B-scan Volume Analysis Storage

Parameters

  srcDataset | The dataset to check SOP Class for

Returns
  OFTrue if Concatenation is permitted, OFFalse otherwise

## ◆ configureCommon()

virtual OFCondition ConcatenationCreator::configureCommon | ( |  | ) |
| protected virtual

Configure class based on input/configuration settings, i.e.

prepare for concatenation writing.

Returns
  EC_Normal if successful, error otherwise

## ◆ getNumInstances()

virtual size_t ConcatenationCreator::getNumInstances | ( |  | ) |
| virtual

Get number of concatenation instances that will be produced.

This can only be used after setCfgInput() was successful; otherwise it will always return 0.

Returns
  The number of instances that will be produced

## ◆ goToNextFrame()

virtual OFCondition ConcatenationCreator::goToNextFrame | ( |  | ) |
| protected virtual

Advance internal counters to next frame.

Returns
  EC_Normal if there is a next frame, error otherwise

## ◆ initSrcPixelData()

virtual OFCondition ConcatenationCreator::initSrcPixelData | ( | DcmItem * | srcDataset,
|  | OFBool | transferOwnership
| ) |  |
| protected virtual

Prepare source pixel data (m_srcPixelData) according to the pixel data existing in the source dataset.

Parameters

  srcDataset | The source dataset to read from
  transferOwnership | If OFTrue, this class (m_srcPixelData) takes ownership of the pixel data, i.e. frees memory on destruction.

Returns
  EC_Normal if successful, error otherwise

## ◆ numFramesCurrentDstInstance()

virtual Uint32 ConcatenationCreator::numFramesCurrentDstInstance | ( |  | ) |
| protected virtual

Return number of frames that must be written into current instance.

Will be the same for each instance except (potentially) the last one.

Returns
  Number of frames

## ◆ setCfgFramesPerInstance()

virtual OFCondition ConcatenationCreator::setCfgFramesPerInstance | ( | Uint32 | numFramesPerInstance | ) |
| virtual

Set number of frames that should go into a single concatenation instance produced.

The last concatenation instance might have less frames. This setting also directly determines the number of instances produced for a specific input.

Parameters

  numFramesPerInstance | The number of frames to be used for each instance (last instance may differ)

Returns
  EC_Normal if setting is ok, error otherwise

## ◆ setCfgInput() [1/3]

virtual OFCondition ConcatenationCreator::setCfgInput | ( | DcmItem * | srcDataset,
|  | OFBool | transferOwnership
| ) |  |
| virtual

Set input dataset that should be split into a number of concatenation instances.

Parameters

  srcDataset | The dataset to read from (must not be NULL)
  transferOwnership | If OFTrue, the ConcatenationCreator class will free memory of the srcDataset after processing.

Returns
  EC_Normal if input is considered valid (up to now), error otherwise

## ◆ setCfgInput() [2/3]

virtual OFCondition ConcatenationCreator::setCfgInput | ( | DcmItem * | srcDataset,
|  | Uint16 * | pixelData,
|  | size_t | pixelDataLength,
|  | OFBool | transferOwnership
| ) |  |
| virtual

Set input dataset with separate pixel data that should be split into a number of concatenation instances.

Parameters

  srcDataset | The dataset to read from (must not be NULL and not contain the Pixel Data attribute (on main level)
  pixelData | Raw buffer of source pixel data
  pixelDataLength | Length of pixelData buffer in bytes
  transferOwnership | If OFTrue, the ConcatenationCreator class will free memory of the srcDataset and pixelData after processing.

Returns
  EC_Normal if input is considered valid (up to now), error otherwise

## ◆ setCfgInput() [3/3]

virtual OFCondition ConcatenationCreator::setCfgInput | ( | DcmItem * | srcDataset,
|  | Uint8 * | pixelData,
|  | size_t | pixelDataLength,
|  | OFBool | transferOwnership
| ) |  |
| virtual

Set input dataset with separate pixel data that should be split into a number of concatenation instances.

Parameters

  srcDataset | The dataset to read from (must not be NULL and not contain the Pixel Data attribute (on main level)
  pixelData | Raw buffer of source pixel data
  pixelDataLength | Length of pixelData buffer in bytes
  transferOwnership | If OFTrue, the ConcatenationCreator class will free memory of the srcDataset and pixelData after processing.

Returns
  EC_Normal if input is considered valid (up to now), error otherwise

## ◆ setCfgInstanceNumber()

virtual OFBool ConcatenationCreator::setCfgInstanceNumber | ( | const OFString & | instanceNumber | ) |
| virtual

Set the Instance Number that should be used in the concatenation instances produced.

Parameters

  instanceNumber | The Instance Number to be used

Returns
  OFTrue if Instance Number is acceptable, OFFalse otherwise

## ◆ setConcatenationAttributes()

virtual OFCondition ConcatenationCreator::setConcatenationAttributes | ( | DcmItem & | dstDataset,
|  | Uint32 | numFramesCurrentInstance
| ) |  |
| protected virtual

Insert Concatenation attributes into destination dataset.

Parameters

  dstDataset | The destination dataset to write to
  numFramesCurrentInstance | The number of frames that will go into the dataset

Returns
  EC_Normal if setting worked, error otherwise

## ◆ writeNextInstance() [1/2]

virtual OFCondition ConcatenationCreator::writeNextInstance | ( | const OFFilename & | fn | ) |
| virtual

Write first/next concatenation instance to given filename.

Parameters

  fn | The filename to write to

Returns
  EC_Normal if instance could be written, FG_EC_ConcatenationComplete error code if the last instance has already been written, other error otherwise.

## ◆ writeNextInstance() [2/2]

virtual OFCondition ConcatenationCreator::writeNextInstance | ( | DcmItem & | dstDataset | ) |
| virtual

Write first/next concatenation instance.

Parameters

  dstDataset | The dataset to write to

Returns
  EC_Normal if instance could be written, FG_EC_ConcatenationComplete error code if the last instance has already been written, other error otherwise.

## Member Data Documentation

## ◆ m_cfgNumFramesPerInstance

Uint32 ConcatenationCreator::m_cfgNumFramesPerInstance
| private

Number of instances each concatenation instance should contain (last may differ) as configured by the user using setCfgFramesPerInstance().

Default is 25.

## ◆ m_cfgTransferOwnership

OFBool ConcatenationCreator::m_cfgTransferOwnership
| private

Flag denoting whether source data (dataset and/with frame data) should be deleted by this class (OFTrue) or not (OFFalse).

Value is initially OFFalse but a value must be provided in any case in setCfgInput().

## ◆ m_configured

OFBool ConcatenationCreator::m_configured
| private

Flag denoting whether class is configured (i.e.

configureCommon() has been called) and ready for concatenation writing.

## ◆ m_dstConcatenationUID

OFString ConcatenationCreator::m_dstConcatenationUID
| private

Concatenation UID to be used in the concatenation instances.

Automatically created during conversion.

## ◆ m_dstInstanceNumber

OFString ConcatenationCreator::m_dstInstanceNumber
| private

Instance Number to be used in concatenation instances produced.

Can be configured using setCfgInstanceNumber().

## ◆ m_dstNumInstances

Uint16 ConcatenationCreator::m_dstNumInstances
| private

Number of instances to be produced for Concatenation.

This is limited to 16 bit since the attributes In-concatentation Number and In-concatenation Total Number only stores 16 bit values (VR US).

## ◆ m_srcDataset

DcmItem* ConcatenationCreator::m_srcDataset
| private

Pointer to source dataset; will be modified during conversion (but content is restored before the call to this class returns).

Once the ConcatenationCreator creator class goes out of scope or reset() is being called, it is set to NULL. If m_cfgTransferOwnership is OFTrue, memory is freed by this class, too.

## ◆ m_srcPerFrameFG

DcmSequenceOfItems* ConcatenationCreator::m_srcPerFrameFG
| private

Pointer to Per-Frame Functional Group Sequence of source dataset.

Use to copy per-frame items to concatenation instances as needed.

## ◆ m_srcPixelData

DcmIODTypes::FrameBase* ConcatenationCreator::m_srcPixelData
| private

Pointer to source pixel data; will be modified during conversion (but content is restored before the call to this class returns).

Once the ConcatenationCreator creator class goes out of scope or reset() is being called, it is set to NULL. If m_cfgTransferOwnership is OFTrue, memory is freed by this class, too.

## ◆ m_VRPixelData

DcmEVR ConcatenationCreator::m_VRPixelData
| private

VR of pixel data extracted/derived from source dataset.

EVR_OB and EVR_OW are supported. Initially set to EVR_Unknown.

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

- dcmfg/include/dcmtk/dcmfg/concatenationcreator.h

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