DCMTK Version 3.7.0 OFFIS DICOM Toolkit

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

Class implementing the image2dcm engine. More...

## Public Member Functions
| Image2Dcm ()
| Constructor, initializes command line options.
virtual | ~Image2Dcm ()
| Destructor, frees plugin memory.
OFCondition | convertFirstFrame (I2DImgSource *inputPlug, I2DOutputPlug *outPlug, size_t numberOfFrames, DcmDataset *&resultDset, E_TransferSyntax &proposedTS)
| Start the conversion. More...
OFCondition | convertNextFrame (I2DImgSource *inputPlug, size_t frameNumber)
| Start the conversion. More...
virtual OFCondition | adjustByteOrder (size_t numberOfFrames)
| Adjust byte order of the pixel data to local byte order for the OW VR. More...
OFCondition | updateOffsetTable ()
| Update the offset table in the case of an encapsulated image. More...
OFCondition | updateLossyCompressionInfo (I2DImgSource *inputPlug, size_t numberOfFrames, DcmDataset *dset)
| Finalizes the conversion after the last call to convertNextFrame() by writing the attributes related to lossy image compression. More...
void | setTemplateFile (const OFString &file)
| Sets a file that should serve as a template for the resulting DICOM object. More...
void | setTemplateFileIsXML (OFBool isXML)
| Sets the format of the template file. More...
void | setXMLvalidation (OFBool enabled)
| activates or deactivates XML validation More...
void | setXMLnamespaceCheck (OFBool enabled)
| activates or deactivates an XML namespace check More...
void | setSeriesFrom (const OFString &file)
| Set file from which patient/study/series data should be imported from. More...
void | setStudyFrom (const OFString &file)
| Set file from which patient/study/series data should be imported from. More...
void | setIncrementInstanceNumber (OFBool incInstNo)
| Enables/Disables incrementing instance number taken over from DICOM file. More...
void | setConversionFlags (size_t conversionFlags)
| Sets the conversion flags for character set conversion of the study/series file. More...
void | setOverrideKeys (const OFList< OFString > &ovkeys)
| Specifies some attributes that should be inserted after conversion. More...
void | setValidityChecking (OFBool doChecks, OFBool insertMissingType2=OFTrue, OFBool inventMissingType1=OFTrue)
| Enable/Disable basic validity checks for output dataset. More...

## Protected Member Functions
void | cleanupTemplate (DcmDataset *targetDset)
| Cleans up template for future insertion of pixel data information, ie generally removes attributes from image pixel module. More...
OFCondition | applyStudyOrSeriesFromFile (DcmDataset *targetDset)
| Parses patient/study/series level attributes from file as defined on command line and fills internal attributes accordingly. More...
OFCondition | incrementInstanceNumber (DcmDataset *targetDset)
| Increments instance number in given dataset. More...
OFCondition | generateUIDs (DcmDataset *dset)
| Generates and inserts missing UIDs, ie UIDs not taken over from –dataset-from –study from and –series-from options. More...
OFCondition | readAndInsertPixelDataFirstFrame (I2DImgSource *imageSource, I2DOutputPlug *outPlug, size_t numberOfFrames, DcmDataset *dset, E_TransferSyntax &outputTS, double &compressionRatio)
| Reads pixel data and corresponding attributes like rows etc. More...
OFCondition | readAndInsertPixelDataNextFrame (I2DImgSource *imageSource, size_t frameNumber)
| Reads pixel data and corresponding attributes like rows etc. More...
OFString | isValid (DcmDataset &dataset) const
| Do some completeness / validity checks. More...
OFCondition | applyOverrideKeys (DcmDataset *outputDset)
| Copy override keys over existing keys in given dataset. More...
OFCondition | insertLatin1 (DcmDataset *outputDset)
| Inserts "ISO_IR100" in the attribute "Specific Character Set". More...
OFString | checkAndInventType1Attrib (const DcmTagKey &key, DcmDataset *targetDset, const OFString &defaultValue="") const
| Check whether given type 1 attribute is present and has a length > 0. More...
OFString | checkAndInventType2Attrib (const DcmTagKey &key, DcmDataset *targetDset) const
| Inserts an empty element with the given tag into a dataset. More...

## Private Member Functions
OFCondition | insertEncapsulatedPixelDataFirstFrame (DcmDataset *dset, char *pixData, Uint32 length, E_TransferSyntax outputTS)
| Inserts encapsulated pixel data for the first frame. More...
OFCondition | insertEncapsulatedPixelDataNextFrame (char *pixData, Uint32 length)
| Inserts encapsulated pixel data for another frame. More...

## Private Attributes
OFList< OFString > | m_overrideKeys
| These attributes are applied to the dataset after conversion (and are not checked by the isValid() function)
OFString | m_templateFile
| If not empty, the DICOM or XML file specified in this variable is used as a base for the DICOM image file to be created, ie. More...
OFBool | m_templateFileIsXML
| if true, the template file is in XML format, otherwise DICOM
OFBool | m_XMLvalidation
| if true, an XML validation will be performed while parsing
OFBool | m_XMLnamespaceCheck
| if true, an XML namespace check will be performed while parsing
OFBool | m_readStudyLevel
| If true, patient and study data is read from file.
OFBool | m_readSeriesLevel
| If true, patient, study and series data is read from file.
OFString | m_studySeriesFile
| File to read study and series from.
OFBool | m_incInstNoFromFile
| If true, Instance Number is read from file and incremented by 1.
OFBool | m_disableAttribChecks
| If true, some simple attribute checks (missing type 2 attributes or missing type 1 values) are omitted.
OFBool | m_inventMissingType2Attribs
| If true, missing type 2 elements are inserted automatically (empty value). More...
OFBool | m_inventMissingType1Attribs
| If true, missing type 1 elements are inserted automatically with a predefined value, if possible. More...
OFBool | m_insertLatin1
| If enabled, ISO_IR100 (ISO Latin 1) is inserted as a standard value for attribute "Specific Character Set". More...
Uint16 | m_rows
| number of rows
Uint16 | m_cols
| number of columns
Uint16 | m_samplesPerPixel
| samples per pixel
Uint16 | m_bitsAllocated
| bits allocated
Uint16 | m_bitsStored
| bits stored
Uint16 | m_highBit
| high bit
Uint16 | m_pixelRepresentation
| pixel representation
Uint16 | m_planarConfiguration
| planar configuration
Uint16 | m_pixelAspectRatioH
| pixel aspect ratio, horizontal
Uint16 | m_pixelAspectRatioV
| pixel aspect ratio, vertical
Uint32 | m_frameLength
| frame length in bytes
OFString | m_photometricInterpretation
| photometric interpretation
double | m_compressionRatio
| compression ratio per frame accumulated in this variable
size_t | m_conversionFlags
| flags for character set conversion
char * | m_output_buffer
| buffer into which uncompressed pixel data is written
DcmOffsetList | m_offsetList
| offset list object used for the creation of encapsulated datasets
DcmPixelSequence * | m_pixelSequence
| pixel sequence object used for the creation of encapsulated datasets
DcmPixelItem * | m_offsetTable
| offset table object used for the creation of encapsulated datasets

## Detailed Description

Class implementing the image2dcm engine.

Conversion takes place by combining an input plugin reading a general purpose image format and output plugins for conversion to specific DICOM SOP class(es)

## Member Function Documentation

## ◆ adjustByteOrder()

virtual OFCondition Image2Dcm::adjustByteOrder | ( | size_t | numberOfFrames | ) |
| virtual

Adjust byte order of the pixel data to local byte order for the OW VR.

Parameters

  numberOfFrames | - [in] The number of frames to be written

Returns
  EC_Normal, if successful, error otherwise

## ◆ applyOverrideKeys()

OFCondition Image2Dcm::applyOverrideKeys | ( | DcmDataset * | outputDset | ) |
| protected

Copy override keys over existing keys in given dataset.

Parameters

  outputDset | - [out] dataset to which the override keys are copied

Returns
  Error code if error occurs, EC_Normal otherwise

## ◆ applyStudyOrSeriesFromFile()

OFCondition Image2Dcm::applyStudyOrSeriesFromFile | ( | DcmDataset * | targetDset | ) |
| protected

Parses patient/study/series level attributes from file as defined on command line and fills internal attributes accordingly.

Parameters

  targetDset | - [out] The dataset to write the attributes to

Returns
  EC_Normal, if successful, error otherwise

## ◆ checkAndInventType1Attrib()

OFString Image2Dcm::checkAndInventType1Attrib | ( | const DcmTagKey & | key,
|  | DcmDataset * | targetDset,
|  | const OFString & | defaultValue = `""`
| ) |  | const
| protected

Check whether given type 1 attribute is present and has a length > 0.

Parameters

  key | - [in] The attribute tag check
  targetDset | - [out] targetDset
  defaultValue | - [in] value to be inserted if attribute is missing (needs invent option for type 1 attributes enabled)

Returns
  A string with an error message if attribute is not present or has length of 0

## ◆ checkAndInventType2Attrib()

OFString Image2Dcm::checkAndInventType2Attrib | ( | const DcmTagKey & | key,
|  | DcmDataset * | targetDset
| ) |  | const
| protected

Inserts an empty element with the given tag into a dataset.

Parameters

  key | - [in] The attribute tag to check
  targetDset | - [out] targetDset

Returns
  A string with an error message if attribute is not present nor gets inserted automatically (see m_inventMissingType2Attribs)

## ◆ cleanupTemplate()

void Image2Dcm::cleanupTemplate | ( | DcmDataset * | targetDset | ) |
| protected

Cleans up template for future insertion of pixel data information, ie generally removes attributes from image pixel module.

Parameters

  targetDset | - [out] The dataset that should be cleaned up

## ◆ convertFirstFrame()

OFCondition Image2Dcm::convertFirstFrame | ( | I2DImgSource * | inputPlug,
|  | I2DOutputPlug * | outPlug,
|  | size_t | numberOfFrames,
|  | DcmDataset *& | resultDset,
|  | E_TransferSyntax & | proposedTS
| ) |  |

Start the conversion.

Needs a fully configured input plugin and a fully configured output plugin to operate. Returns a dataset with the resulting DICOM object.

Parameters

  inputPlug | - [in] The input plugin to read pixel data
  outPlug | - [in] The output plugin for specific SOP class output
  numberOfFrames | - [in] The number of frames to be written
  resultDset | - [out] The DICOM object resulting from the conversion The dataset is allocated in this method and must be freed by the caller.
  proposedTS | - [out] The proposed transfer syntax (needed e. g. by JPEG input plugin)

Returns
  EC_Normal, if successful, error otherwise

## ◆ convertNextFrame()

OFCondition Image2Dcm::convertNextFrame | ( | I2DImgSource * | inputPlug,
|  | size_t | frameNumber
| ) |  |

Start the conversion.

Needs a fully configured input plugin to operate. Updates the pixel data element created by convertFirstFrame().

Parameters

  inputPlug | - [in] The input plugin to read pixel data
  frameNumber | - [in] The number of the current frame, must be larger than 1 and smaller or equal to the numberOfFrames value passed to convertFirstFrame().

Returns
  EC_Normal, if successful, error otherwise

## ◆ generateUIDs()

OFCondition Image2Dcm::generateUIDs | ( | DcmDataset * | dset | ) |
| protected

Generates and inserts missing UIDs, ie UIDs not taken over from –dataset-from –study from and –series-from options.

Parameters

  dset | - [in] The dataset to write the UIDs to

Returns
  EC_Normal, if successful, error otherwise

## ◆ incrementInstanceNumber()

OFCondition Image2Dcm::incrementInstanceNumber | ( | DcmDataset * | targetDset | ) |
| protected

Increments instance number in given dataset.

Parameters

  targetDset | - [in/out] Dataset to increment instance number in

Returns
  EC_Normal, if successful, error otherwise

## ◆ insertEncapsulatedPixelDataFirstFrame()

OFCondition Image2Dcm::insertEncapsulatedPixelDataFirstFrame | ( | DcmDataset * | dset,
|  | char * | pixData,
|  | Uint32 | length,
|  | E_TransferSyntax | outputTS
| ) |  |
| private

Inserts encapsulated pixel data for the first frame.

Parameters

  dset | [in] - The dataset to which we should add this.
  pixData | [in] - The data to add.
  length | [in] - The length of pixData.
  outputTS | [in] - The output transfer syntax to be used

Returns
  EC_Normal, if successful, error otherwise.

## ◆ insertEncapsulatedPixelDataNextFrame()

OFCondition Image2Dcm::insertEncapsulatedPixelDataNextFrame | ( | char * | pixData,
|  | Uint32 | length
| ) |  |
| private

Inserts encapsulated pixel data for another frame.

Parameters

  pixData | [in] - The data to add.
  length | [in] - The length of pixData.

Returns
  EC_Normal, if successful, error otherwise.

## ◆ insertLatin1()

OFCondition Image2Dcm::insertLatin1 | ( | DcmDataset * | outputDset | ) |
| protected

Inserts "ISO_IR100" in the attribute "Specific Character Set".

Overwrites any existing value.

Parameters

  outputDset | - [out] The dataset to write to

Returns
  EC_Normal if insertion is successful, error code otherwise

## ◆ isValid()

OFString Image2Dcm::isValid | ( | DcmDataset & | dataset | ) | const
| protected

Do some completeness / validity checks.

Should be called when dataset is completed and is about to be saved.

Parameters

  dataset | - [in] The dataset to check

Returns
  Error string if error occurs, empty string otherwise

## ◆ readAndInsertPixelDataFirstFrame()

OFCondition Image2Dcm::readAndInsertPixelDataFirstFrame | ( | I2DImgSource * | imageSource,
|  | I2DOutputPlug * | outPlug,
|  | size_t | numberOfFrames,
|  | DcmDataset * | dset,
|  | E_TransferSyntax & | outputTS,
|  | double & | compressionRatio
| ) |  |
| protected

Reads pixel data and corresponding attributes like rows etc.

from image file and inserts them into dataset.

Parameters

  imageSource | - [in] The input plugin that actually reads the pixel data
  outPlug | - [in] The output plugin for specific SOP class output
  numberOfFrames | - [in] The number of frames to be written
  dset | - [out] The dataset to export the pixel data attributes to
  outputTS | - [out] The proposed transfex syntax of the dataset
  compressionRatio | - [out] compression ratio of the pixel data, 1.0 for uncompressed

Returns
  EC_Normal, if successful, error otherwise

## ◆ readAndInsertPixelDataNextFrame()

OFCondition Image2Dcm::readAndInsertPixelDataNextFrame | ( | I2DImgSource * | imageSource,
|  | size_t | frameNumber
| ) |  |
| protected

Reads pixel data and corresponding attributes like rows etc.

from image file and inserts them into dataset as an additional frame.

Parameters

  imageSource | - [in] The input plugin that actually reads the pixel data
  frameNumber | - [in] The number of the current frame, must be larger than 1 and smaller or equal to the numberOfFrames value passed to convertFirstFrame().

Returns
  EC_Normal, if successful, error otherwise

## ◆ setConversionFlags()

void Image2Dcm::setConversionFlags | ( | size_t | conversionFlags | ) |

Sets the conversion flags for character set conversion of the study/series file.

Parameters

  conversionFlags | - [in] conversion flags

## ◆ setIncrementInstanceNumber()

void Image2Dcm::setIncrementInstanceNumber | ( | OFBool | incInstNo | ) |

Enables/Disables incrementing instance number taken over from DICOM file.

This can either be a the study/series file or the template file provided.

Parameters

  incInstNo | - [in] If true, the instance number will be incremented

## ◆ setOverrideKeys()

void Image2Dcm::setOverrideKeys | ( | const OFList< OFString > & | ovkeys | ) |

Specifies some attributes that should be inserted after conversion.

They will override any identical attributes already existing in the converted result DICOM object. The override keys are applied at the very end of the conversion and do not undergoe any validity checking.

Parameters

  ovkeys | [in] override keys that can be tags, dictionary names and paths (see DcmPath for syntax). Also it is permitted to set a value if appropriate, e. g. "PatientName=Doe^John" would be a valid override key.

## ◆ setSeriesFrom()

void Image2Dcm::setSeriesFrom | ( | const OFString & | file | ) |

Set file from which patient/study/series data should be imported from.

Parameters

  file | - [in] The DICOM file to read from

## ◆ setStudyFrom()

void Image2Dcm::setStudyFrom | ( | const OFString & | file | ) |

Set file from which patient/study/series data should be imported from.

Parameters

  file | - [in] The DICOM file to read from

## ◆ setTemplateFile()

void Image2Dcm::setTemplateFile | ( | const OFString & | file | ) |

Sets a file that should serve as a template for the resulting DICOM object.

Only the dataset of the given file is imported.

Parameters

  file | - [in] The filename of the template file, which is either in DICOM or XML format.

## ◆ setTemplateFileIsXML()

void Image2Dcm::setTemplateFileIsXML | ( | OFBool | isXML | ) |

Sets the format of the template file.

Parameters

  isXML | - [in] true for XML, false for DICOM format

## ◆ setValidityChecking()

void Image2Dcm::setValidityChecking | ( | OFBool | doChecks,
|  | OFBool | insertMissingType2 = `OFTrue`,
|  | OFBool | inventMissingType1 = `OFTrue`
| ) |  |

Enable/Disable basic validity checks for output dataset.

Parameters

  doChecks | - [in] OFTrue enables checking, OFFalse turns it off.
  insertMissingType2 | - [in] If true (default), missing type 2 attributes are inserted automatically
  inventMissingType1 | - [in] If true , missing type 1 attributes are inserted automatically with a predefined value (if possible). An existing empty type 1 attribute is assigned a value, too.

## ◆ setXMLnamespaceCheck()

void Image2Dcm::setXMLnamespaceCheck | ( | OFBool | enabled | ) |

activates or deactivates an XML namespace check

Parameters

  enabled | - [in] true to enable namespace check

## ◆ setXMLvalidation()

void Image2Dcm::setXMLvalidation | ( | OFBool | enabled | ) |

activates or deactivates XML validation

Parameters

  enabled | - [in] true to enable validation

## ◆ updateLossyCompressionInfo()

OFCondition Image2Dcm::updateLossyCompressionInfo | ( | I2DImgSource * | inputPlug,
|  | size_t | numberOfFrames,
|  | DcmDataset * | dset
| ) |  |

Finalizes the conversion after the last call to convertNextFrame() by writing the attributes related to lossy image compression.

Parameters

  inputPlug | - [in] The input plugin to read pixel data
  numberOfFrames | - [in] The number of frames to be written
  dset | - [in/out] The DICOM object resulting from the conversion

Returns
  EC_Normal, if successful, error otherwise

## ◆ updateOffsetTable()

OFCondition Image2Dcm::updateOffsetTable | ( |  | ) |

Update the offset table in the case of an encapsulated image.

Returns
  EC_Normal if offset table could be updated, error code otherwise

## Member Data Documentation

## ◆ m_insertLatin1

OFBool Image2Dcm::m_insertLatin1
| private

If enabled, ISO_IR100 (ISO Latin 1) is inserted as a standard value for attribute "Specific Character Set".

Insertion takes place after loading (optional) template file.

## ◆ m_inventMissingType1Attribs

OFBool Image2Dcm::m_inventMissingType1Attribs
| private

If true, missing type 1 elements are inserted automatically with a predefined value, if possible.

Disabled per default.

## ◆ m_inventMissingType2Attribs

OFBool Image2Dcm::m_inventMissingType2Attribs
| private

If true, missing type 2 elements are inserted automatically (empty value).

Enabled per default.

## ◆ m_templateFile

OFString Image2Dcm::m_templateFile
| private

If not empty, the DICOM or XML file specified in this variable is used as a base for the DICOM image file to be created, ie.

all attributes are taken over from this template file

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

- dcmdata/include/dcmtk/dcmdata/libi2d/i2d.h

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