DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Public Member Functions | Static Public Member Functions | List of all members
DcmCodec Class Referenceabstract

abstract base class for a codec object that can be registered in dcmdata and performs transfer syntax transformation (i.e. More...

Inheritance diagram for DcmCodec:

## Public Member Functions
| DcmCodec ()
| default constructor
virtual | ~DcmCodec ()
| destructor
virtual OFCondition | decode (const DcmRepresentationParameter *fromRepParam, DcmPixelSequence *pixSeq, DcmPolymorphOBOW &uncompressedPixelData, const DcmCodecParameter *cp, const DcmStack &objStack, OFBool &removeOldRep) const =0
| decompresses the given pixel sequence and stores the result in the given uncompressedPixelData element. More...
virtual OFCondition | decodeFrame (const DcmRepresentationParameter *fromParam, DcmPixelSequence *fromPixSeq, const DcmCodecParameter *cp, DcmItem *dataset, Uint32 frameNo, Uint32 &startFragment, void *buffer, Uint32 bufSize, OFString &decompressedColorModel) const =0
| decompresses a single frame from the given pixel sequence and stores the result in the given buffer. More...
virtual OFCondition | encode (const Uint16 *pixelData, const Uint32 length, const DcmRepresentationParameter *toRepParam, DcmPixelSequence *&pixSeq, const DcmCodecParameter *cp, DcmStack &objStack, OFBool &removeOldRep) const =0
| compresses the given uncompressed DICOM image and stores the result in the given pixSeq element. More...
virtual OFCondition | encode (const E_TransferSyntax fromRepType, const DcmRepresentationParameter *fromRepParam, DcmPixelSequence *fromPixSeq, const DcmRepresentationParameter *toRepParam, DcmPixelSequence *&toPixSeq, const DcmCodecParameter *cp, DcmStack &objStack, OFBool &removeOldRep) const =0
| transcodes (re-compresses) the given compressed DICOM image and stores the result in the given toPixSeq element. More...
virtual OFBool | canChangeCoding (const E_TransferSyntax oldRepType, const E_TransferSyntax newRepType) const =0
| checks if this codec is able to convert from the given current transfer syntax to the given new transfer syntax More...
virtual Uint16 | decodedBitsAllocated (Uint16 bitsAllocated, Uint16 bitsStored) const =0
| determines the effective value of BitsAllocated that a dataset will have after decompression of an image with the given values for bitsAllocated and bitsStored. More...
virtual OFCondition | determineDecompressedColorModel (const DcmRepresentationParameter *fromParam, DcmPixelSequence *fromPixSeq, const DcmCodecParameter *cp, DcmItem *dataset, OFString &decompressedColorModel) const =0
| determine color model of the decompressed image More...

## Static Public Member Functions
static OFCondition | insertStringIfMissing (DcmItem *dataset, const DcmTagKey &tag, const char *val)
| helper function that inserts a string attribute with a given value into a dataset if missing in the dataset. More...
static OFCondition | convertToSecondaryCapture (DcmItem *dataset)
| helper function that converts a dataset containing a DICOM image into a valid (standard extended) Secondary Capture object by inserting all attributes that are type 1/2 in Secondary Capture and missing in the source dataset. More...
static OFCondition | newInstance (DcmItem *dataset, const char *purposeOfReferenceCodingScheme=NULL, const char *purposeOfReferenceCodeValue=NULL, const char *purposeOfReferenceCodeMeaning=NULL)
| create new SOP Instance UID and Source Image Sequence referencing the old SOP instance (if present) More...
static OFCondition | updateImageType (DcmItem *dataset)
| update value of the Image Type element (if needed). More...
static OFCondition | insertCodeSequence (DcmItem *dataset, const DcmTagKey &tagKey, const char *codingSchemeDesignator, const char *codeValue, const char *codeMeaning)
| insert code sequence into the given dataset More...
static OFCondition | determineStartFragment (Uint32 frameNo, Sint32 numberOfFrames, DcmPixelSequence *fromPixSeq, Uint32 &currentItem)
| determine the index number (starting with zero) of the compressed pixel data fragment corresponding to the given frame (also starting with zero) More...

## Detailed Description

abstract base class for a codec object that can be registered in dcmdata and performs transfer syntax transformation (i.e.

compressing, decompressing or transcoding between different compressed transfer syntaxes). When dcmdata is requested to write a transfer syntax that differs from the current one (i.e. the one in which the object was read), dcmdata dynamically searches for a DcmCodec object that is able to create the desired transfer syntax. If no suitable codec is found, the write operation fails.

## Member Function Documentation

## ◆ canChangeCoding()

virtual OFBool DcmCodec::canChangeCoding | ( | const E_TransferSyntax | oldRepType,
|  | const E_TransferSyntax | newRepType
| ) |  | const
| pure virtual

checks if this codec is able to convert from the given current transfer syntax to the given new transfer syntax

Parameters

  oldRepType | current transfer syntax
  newRepType | desired new transfer syntax

Returns
  true if transformation is supported by this codec, false otherwise.

Implemented in DJLSEncoderBase, DJLSDecoderBase, DJCodecEncoder, DJCodecDecoder, DcmRLECodecEncoder, and DcmRLECodecDecoder.

## ◆ convertToSecondaryCapture()

static OFCondition DcmCodec::convertToSecondaryCapture | ( | DcmItem * | dataset | ) |
| static

helper function that converts a dataset containing a DICOM image into a valid (standard extended) Secondary Capture object by inserting all attributes that are type 1/2 in Secondary Capture and missing in the source dataset.

Replaces SOP Class UID by Secondary Capture. It does not, however, change an existing SOP Instance UID.

Parameters

  dataset | dataset to insert to, must not be NULL.

Returns
  EC_Normal if successful, an error code otherwise

## ◆ decode()

virtual OFCondition DcmCodec::decode | ( | const DcmRepresentationParameter * | fromRepParam,
|  | DcmPixelSequence * | pixSeq,
|  | DcmPolymorphOBOW & | uncompressedPixelData,
|  | const DcmCodecParameter * | cp,
|  | const DcmStack & | objStack,
|  | OFBool & | removeOldRep
| ) |  | const
| pure virtual

decompresses the given pixel sequence and stores the result in the given uncompressedPixelData element.

Parameters

  fromRepParam | current representation parameter of compressed data, may be NULL
  pixSeq | compressed pixel sequence
  uncompressedPixelData | uncompressed pixel data stored in this element
  cp | codec parameters for this codec
  objStack | stack pointing to the location of the pixel data element in the current dataset.
  removeOldRep | boolean flag that should be set to false before this method call and will be set to true if the codec modifies the DICOM dataset such that the pixel data of the original representation may not be usable anymore.

Returns
  EC_Normal if successful, an error code otherwise.

Implemented in DJLSEncoderBase, DJLSDecoderBase, DJCodecEncoder, DJCodecDecoder, DcmRLECodecEncoder, and DcmRLECodecDecoder.

## ◆ decodedBitsAllocated()

virtual Uint16 DcmCodec::decodedBitsAllocated | ( | Uint16 | bitsAllocated,
|  | Uint16 | bitsStored
| ) |  | const
| pure virtual

determines the effective value of BitsAllocated that a dataset will have after decompression of an image with the given values for bitsAllocated and bitsStored.

This may differ from the bitsAllocated parameter for example if that value is not a multiple of 8. Returns zero if an image with the given parameters cannot be decoded with this codec.

Parameters

  bitsAllocated | current value of Bits Allocated
  bitsStored | current value of Bits Stored

Returns
  value of BitsAllocated after decompression, 0 if no decompression possible

Implemented in DJLSEncoderBase, DJLSDecoderBase, DJCodecEncoder, DJCodecDecoder, DcmRLECodecEncoder, and DcmRLECodecDecoder.

## ◆ decodeFrame()

virtual OFCondition DcmCodec::decodeFrame | ( | const DcmRepresentationParameter * | fromParam,
|  | DcmPixelSequence * | fromPixSeq,
|  | const DcmCodecParameter * | cp,
|  | DcmItem * | dataset,
|  | Uint32 | frameNo,
|  | Uint32 & | startFragment,
|  | void * | buffer,
|  | Uint32 | bufSize,
|  | OFString & | decompressedColorModel
| ) |  | const
| pure virtual

decompresses a single frame from the given pixel sequence and stores the result in the given buffer.

Parameters

  fromParam | representation parameter of current compressed representation, may be NULL.
  fromPixSeq | compressed pixel sequence
  cp | codec parameters for this codec
  dataset | pointer to dataset in which pixel data element is contained
  frameNo | number of frame, starting with 0 for the first frame
  startFragment | index of the compressed fragment that contains all or the first part of the compressed bitstream for the given frameNo. Upon successful return this parameter is updated to contain the index of the first compressed fragment of the next frame. When unknown, zero should be passed. In this case the decompression algorithm will try to determine the index by itself, which will always work if frames are decompressed in increasing order from first to last, but may fail if frames are decompressed in random order, multiple fragments per frame and multiple frames are present in the dataset, and the offset table is empty.
  buffer | pointer to buffer where frame is to be stored
  bufSize | size of buffer in bytes
  decompressedColorModel | upon successful return, the color model of the decompressed image (which may be different from the one used in the compressed images) is returned in this parameter.

Returns
  EC_Normal if successful, an error code otherwise.

Implemented in DJLSEncoderBase, DJLSDecoderBase, DJCodecEncoder, DJCodecDecoder, DcmRLECodecEncoder, and DcmRLECodecDecoder.

## ◆ determineDecompressedColorModel()

virtual OFCondition DcmCodec::determineDecompressedColorModel | ( | const DcmRepresentationParameter * | fromParam,
|  | DcmPixelSequence * | fromPixSeq,
|  | const DcmCodecParameter * | cp,
|  | DcmItem * | dataset,
|  | OFString & | decompressedColorModel
| ) |  | const
| pure virtual

determine color model of the decompressed image

Parameters

  fromParam | representation parameter of current compressed representation, may be NULL
  fromPixSeq | compressed pixel sequence
  cp | codec parameters for this codec
  dataset | pointer to dataset in which pixel data element is contained
  dataset | pointer to DICOM dataset in which this pixel data object is located. Used to access photometric interpretation.
  decompressedColorModel | upon successful return, the color model of the decompressed image (which may be different from the one used in the compressed images) is returned in this parameter

Returns
  EC_Normal if successful, an error code otherwise

Implemented in DJLSEncoderBase, DJLSDecoderBase, DJCodecEncoder, DJCodecDecoder, DcmRLECodecEncoder, and DcmRLECodecDecoder.

## ◆ determineStartFragment()

static OFCondition DcmCodec::determineStartFragment | ( | Uint32 | frameNo,
|  | Sint32 | numberOfFrames,
|  | DcmPixelSequence * | fromPixSeq,
|  | Uint32 & | currentItem
| ) |  |
| static

determine the index number (starting with zero) of the compressed pixel data fragment corresponding to the given frame (also starting with zero)

Parameters

  frameNo | frame number
  numberOfFrames | number of frames of this image
  fromPixSeq | compressed pixel sequence
  currentItem | index of compressed pixel data fragment returned in this parameter on success

Returns
  EC_Normal if successful, an error code otherwise

## ◆ encode() [1/2]

virtual OFCondition DcmCodec::encode | ( | const E_TransferSyntax | fromRepType,
|  | const DcmRepresentationParameter * | fromRepParam,
|  | DcmPixelSequence * | fromPixSeq,
|  | const DcmRepresentationParameter * | toRepParam,
|  | DcmPixelSequence *& | toPixSeq,
|  | const DcmCodecParameter * | cp,
|  | DcmStack & | objStack,
|  | OFBool & | removeOldRep
| ) |  | const
| pure virtual

transcodes (re-compresses) the given compressed DICOM image and stores the result in the given toPixSeq element.

Parameters

  fromRepType | current transfer syntax of the compressed image
  fromRepParam | current representation parameter of compressed data, may be NULL
  fromPixSeq | compressed pixel sequence
  toRepParam | representation parameter describing the desired new compressed representation (e.g. JPEG quality)
  toPixSeq | compressed pixel sequence (pointer to new DcmPixelSequence object allocated on heap) returned in this parameter upon success.
  cp | codec parameters for this codec
  objStack | stack pointing to the location of the pixel data element in the current dataset.
  removeOldRep | boolean flag that should be set to false before this method call and will be set to true if the codec modifies the DICOM dataset such that the pixel data of the original representation may not be usable anymore.

Returns
  EC_Normal if successful, an error code otherwise.

Implemented in DJLSEncoderBase, DJLSDecoderBase, DJCodecEncoder, DJCodecDecoder, DcmRLECodecEncoder, and DcmRLECodecDecoder.

## ◆ encode() [2/2]

virtual OFCondition DcmCodec::encode | ( | const Uint16 * | pixelData,
|  | const Uint32 | length,
|  | const DcmRepresentationParameter * | toRepParam,
|  | DcmPixelSequence *& | pixSeq,
|  | const DcmCodecParameter * | cp,
|  | DcmStack & | objStack,
|  | OFBool & | removeOldRep
| ) |  | const
| pure virtual

compresses the given uncompressed DICOM image and stores the result in the given pixSeq element.

Parameters

  pixelData | pointer to the uncompressed image data in OW format and local byte order
  length | of the pixel data field in bytes
  toRepParam | representation parameter describing the desired compressed representation (e.g. JPEG quality)
  pixSeq | compressed pixel sequence (pointer to new DcmPixelSequence object allocated on heap) returned in this parameter upon success.
  cp | codec parameters for this codec
  objStack | stack pointing to the location of the pixel data element in the current dataset.
  removeOldRep | boolean flag that should be set to false before this method call and will be set to true if the codec modifies the DICOM dataset such that the pixel data of the original representation may not be usable anymore.

Returns
  EC_Normal if successful, an error code otherwise.

Implemented in DJLSEncoderBase, DJLSDecoderBase, DJCodecEncoder, DJCodecDecoder, DcmRLECodecEncoder, and DcmRLECodecDecoder.

## ◆ insertCodeSequence()

static OFCondition DcmCodec::insertCodeSequence | ( | DcmItem * | dataset,
|  | const DcmTagKey & | tagKey,
|  | const char * | codingSchemeDesignator,
|  | const char * | codeValue,
|  | const char * | codeMeaning
| ) |  |
| static

insert code sequence into the given dataset

Parameters

  dataset | dataset to insert into
  tagKey | tag of the code sequence
  codingSchemeDesignator | coding scheme designator for the sequence item
  codeValue | code value for the sequence item
  codeMeaning | code meaning for the sequence item

Returns
  EC_Normal if successful, an error code otherwise

## ◆ insertStringIfMissing()

static OFCondition DcmCodec::insertStringIfMissing | ( | DcmItem * | dataset,
|  | const DcmTagKey & | tag,
|  | const char * | val
| ) |  |
| static

helper function that inserts a string attribute with a given value into a dataset if missing in the dataset.

Parameters

  dataset | dataset to insert to, must not be NULL.
  tag | tag key of attribute to check/insert
  val | string value, may be NULL.

Returns
  EC_Normal if successful, an error code otherwise

## ◆ newInstance()

static OFCondition DcmCodec::newInstance | ( | DcmItem * | dataset,
|  | const char * | purposeOfReferenceCodingScheme = `NULL`,
|  | const char * | purposeOfReferenceCodeValue = `NULL`,
|  | const char * | purposeOfReferenceCodeMeaning = `NULL`
| ) |  |
| static

create new SOP Instance UID and Source Image Sequence referencing the old SOP instance (if present)

Parameters

  dataset | dataset to be modified
  purposeOfReferenceCodingScheme | coding scheme designator for purpose of reference code sequence
  purposeOfReferenceCodeValue | code value for purpose of reference code sequence
  purposeOfReferenceCodeMeaning | code meaning for purpose of reference code sequence

Returns
  EC_Normal if successful, an error code otherwise

## ◆ updateImageType()

static OFCondition DcmCodec::updateImageType | ( | DcmItem * | dataset | ) |
| static

update value of the Image Type element (if needed).

Three cases are handled by this method:

1. The Image Type element is not present or has an empty value.
2. The Image Type element is present and has a single value only.
3. The Image Type element is present and has two or more values.

For case 1, nothing is done. An empty value means "unknown" for Type 2.
For case 2, the value "DERIVED\SECONDARY" is used (VM is 2-n).
For case 3, the first value is replaced by the string "DERIVED".

Parameters

  dataset | dataset to be modified

Returns
  EC_Normal if successful, an error code otherwise

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

- dcmdata/include/dcmtk/dcmdata/dccodec.h

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