Frame-level Deflate codec implementation (Supplement 244). More...

#include <frame_deflate_codec.h>

Inheritance diagram for kcenon::pacs::encoding::compression::frame_deflate_codec:

Collaboration diagram for kcenon::pacs::encoding::compression::frame_deflate_codec:

Public Member Functions
	frame_deflate_codec (int compression_level=kDefaultCompressionLevel)
	Constructs a Frame Deflate codec instance.

	~frame_deflate_codec () override

	frame_deflate_codec (const frame_deflate_codec &)=delete

frame_deflate_codec &	operator= (const frame_deflate_codec &)=delete

	frame_deflate_codec (frame_deflate_codec &&) noexcept

frame_deflate_codec &	operator= (frame_deflate_codec &&) noexcept

Codec Information
std::string_view	transfer_syntax_uid () const noexcept override
	Returns the Transfer Syntax UID supported by this codec.

std::string_view	name () const noexcept override
	Returns a human-readable name for the codec.

bool	is_lossy () const noexcept override
	Checks if this codec produces lossy compression.

bool	can_encode (const image_params &params) const noexcept override
	Checks if this codec supports the given image parameters.

bool	can_decode (const image_params &params) const noexcept override
	Checks if this codec can decode data with given parameters.

Configuration
int	compression_level () const noexcept
	Gets the current zlib compression level.

Compression Operations
codec_result	encode (std::span< const uint8_t > pixel_data, const image_params &params, const compression_options &options={}) const override
	Compresses pixel data using zlib deflate.

codec_result	decode (std::span< const uint8_t > compressed_data, const image_params &params) const override
	Decompresses deflate-compressed pixel data.

Public Member Functions inherited from kcenon::pacs::encoding::compression::compression_codec
virtual	~compression_codec ()=default

Static Public Attributes
static constexpr std::string_view	kTransferSyntaxUID
	DICOM Transfer Syntax UID for Frame Deflate.

static constexpr int	kDefaultCompressionLevel = 6
	Default zlib compression level (6 = balanced speed/ratio)

static constexpr int	kMinCompressionLevel = 1
	Minimum zlib compression level (fastest)

static constexpr int	kMaxCompressionLevel = 9
	Maximum zlib compression level (best compression)

Private Attributes
int	compression_level_

Additional Inherited Members
Protected Member Functions inherited from kcenon::pacs::encoding::compression::compression_codec
	compression_codec ()=default

	compression_codec (const compression_codec &)=default

compression_codec &	operator= (const compression_codec &)=default

	compression_codec (compression_codec &&)=default

compression_codec &	operator= (compression_codec &&)=default

Detailed Description

Frame-level Deflate codec implementation (Supplement 244).

Implements DICOM Transfer Syntax 1.2.840.10008.1.2.11 defined in Supplement 244. Applies zlib deflate compression on a per-frame basis, specifically optimized for single-bit binary segmentation masks generated by AI algorithms.

Key Properties:

Always lossless (deflate is a lossless compression algorithm)
Per-frame compression enables random access to individual frames
Highest compression ratio for single-bit binary data compared to RLE
Encapsulated pixel data format (like JPEG, RLE, etc.)

Supported Features:

1-bit binary segmentation masks (optimal use case)
8-bit grayscale images
16-bit grayscale images
Single-sample (grayscale) images
Multi-frame images (via external frame-by-frame processing)

Limitations:

Color images (samples_per_pixel > 1) are not supported
Maximum image size: 65535 x 65535 pixels

Thread Safety:

This class is NOT thread-safe
Create separate instances per thread for concurrent operations

Note: Actual encode/decode operations require zlib library integration. Without zlib, encode/decode return an error.

See also: DICOM Supplement 244 – Frame Deflate Transfer Syntax; RFC 1950 (zlib), RFC 1951 (DEFLATE)

Definition at line 53 of file frame_deflate_codec.h.

Constructor & Destructor Documentation

◆ frame_deflate_codec() [1/3]

kcenon::pacs::encoding::compression::frame_deflate_codec::frame_deflate_codec ( int compression_level = kDefaultCompressionLevel )

explicit

Constructs a Frame Deflate codec instance.

Parameters

compression_level zlib compression level (1-9). 1 = fastest, 9 = best compression, 6 = default balanced.

Definition at line 17 of file frame_deflate_codec.cpp.

    : compression_level_(
          std::clamp(compression_level,
                     kMinCompressionLevel,
                     kMaxCompressionLevel)) {}

◆ ~frame_deflate_codec()

kcenon::pacs::encoding::compression::frame_deflate_codec::~frame_deflate_codec ( )

overridedefault

◆ frame_deflate_codec() [2/3]

kcenon::pacs::encoding::compression::frame_deflate_codec::frame_deflate_codec ( const frame_deflate_codec & )

delete

◆ frame_deflate_codec() [3/3]

kcenon::pacs::encoding::compression::frame_deflate_codec::frame_deflate_codec ( frame_deflate_codec && )

defaultnoexcept

Member Function Documentation

◆ can_decode()

bool kcenon::pacs::encoding::compression::frame_deflate_codec::can_decode ( const image_params & params ) const

nodiscardoverridevirtualnoexcept

Checks if this codec can decode data with given parameters.

Parameters

params The image parameters

Returns: true if decoding is supported

Implements kcenon::pacs::encoding::compression::compression_codec.

Definition at line 58 of file frame_deflate_codec.cpp.

                                                                              {
    return can_encode(params);
}

◆ can_encode()

bool kcenon::pacs::encoding::compression::frame_deflate_codec::can_encode ( const image_params & params ) const

nodiscardoverridevirtualnoexcept

Checks if this codec supports the given image parameters.

Parameters

params The image parameters to check

Returns: true if the codec can handle these parameters

Implements kcenon::pacs::encoding::compression::compression_codec.

Definition at line 40 of file frame_deflate_codec.cpp.

                                                                              {
    if (params.width == 0 || params.height == 0) {
        return false;
    }
 
    // Frame Deflate supports grayscale only (optimized for segmentation masks)
    if (params.samples_per_pixel != 1) {
        return false;
    }
 
    // Support 1-bit through 16-bit
    if (params.bits_stored < 1 || params.bits_stored > 16) {
        return false;
    }
 
    return true;
}

◆ compression_level()

int kcenon::pacs::encoding::compression::frame_deflate_codec::compression_level ( ) const

nodiscardnoexcept

Gets the current zlib compression level.

Returns: Compression level (1-9)

Definition at line 62 of file frame_deflate_codec.cpp.

                                                          {
    return compression_level_;
}

References compression_level_.

◆ decode()

codec_result kcenon::pacs::encoding::compression::frame_deflate_codec::decode	(	std::span< const uint8_t >	compressed_data,
		const image_params &	params ) const

nodiscardoverridevirtual

Decompresses deflate-compressed pixel data.

Parameters

compressed_data	Deflate compressed data (single frame)
params	Image parameters (width, height, samples_per_pixel)

Returns: Decompressed pixel data or error

Implements kcenon::pacs::encoding::compression::compression_codec.

Definition at line 166 of file frame_deflate_codec.cpp.

                                                       {
    return kcenon::pacs::pacs_error<compression_result>(
        kcenon::pacs::error_codes::decompression_error,
        "Frame Deflate codec not available: zlib library not found at build time");
}

References kcenon::pacs::error_codes::decompression_error, and kcenon::pacs::pacs_error().

Here is the call graph for this function:

◆ encode()

codec_result kcenon::pacs::encoding::compression::frame_deflate_codec::encode	(	std::span< const uint8_t >	pixel_data,
		const image_params &	params,
		const compression_options &	options = {} ) const

nodiscardoverridevirtual

Compresses pixel data using zlib deflate.

Parameters

pixel_data	Uncompressed pixel data (single frame)
params	Image parameters describing the pixel data
options	Compression options (lossless flag is ignored, always lossless)

Returns: Compressed deflate data or error

For binary segmentation masks (1-bit), achieves very high compression ratios due to the repetitive nature of single-bit data.

Implements kcenon::pacs::encoding::compression::compression_codec.

Definition at line 157 of file frame_deflate_codec.cpp.

                                                               {
    return kcenon::pacs::pacs_error<compression_result>(
        kcenon::pacs::error_codes::compression_error,
        "Frame Deflate codec not available: zlib library not found at build time");
}

References kcenon::pacs::error_codes::compression_error, and kcenon::pacs::pacs_error().

Here is the call graph for this function:

◆ is_lossy()

bool kcenon::pacs::encoding::compression::frame_deflate_codec::is_lossy ( ) const

nodiscardoverridevirtualnoexcept

Checks if this codec produces lossy compression.

Returns: true if lossy, false if lossless

Implements kcenon::pacs::encoding::compression::compression_codec.

Definition at line 36 of file frame_deflate_codec.cpp.

                                                  {
    return false;
}

◆ name()

std::string_view kcenon::pacs::encoding::compression::frame_deflate_codec::name ( ) const

nodiscardoverridevirtualnoexcept

Returns a human-readable name for the codec.

Returns: The codec name (e.g., "JPEG Baseline")

Implements kcenon::pacs::encoding::compression::compression_codec.

Definition at line 32 of file frame_deflate_codec.cpp.

                                                        {
    return "Frame Deflate";
}

◆ operator=() [1/2]

frame_deflate_codec & kcenon::pacs::encoding::compression::frame_deflate_codec::operator= ( const frame_deflate_codec & )

delete

◆ operator=() [2/2]

frame_deflate_codec & kcenon::pacs::encoding::compression::frame_deflate_codec::operator= ( frame_deflate_codec && )

defaultnoexcept

◆ transfer_syntax_uid()

std::string_view kcenon::pacs::encoding::compression::frame_deflate_codec::transfer_syntax_uid ( ) const

nodiscardoverridevirtualnoexcept

Returns the Transfer Syntax UID supported by this codec.

Returns: The DICOM Transfer Syntax UID

Implements kcenon::pacs::encoding::compression::compression_codec.

Definition at line 28 of file frame_deflate_codec.cpp.

                                                                       {
    return kTransferSyntaxUID;
}

Member Data Documentation

◆ compression_level_

int kcenon::pacs::encoding::compression::frame_deflate_codec::compression_level_

private

Definition at line 140 of file frame_deflate_codec.h.

Referenced by compression_level().

◆ kDefaultCompressionLevel

int kcenon::pacs::encoding::compression::frame_deflate_codec::kDefaultCompressionLevel = 6

staticconstexpr

Default zlib compression level (6 = balanced speed/ratio)

Definition at line 60 of file frame_deflate_codec.h.

◆ kMaxCompressionLevel

int kcenon::pacs::encoding::compression::frame_deflate_codec::kMaxCompressionLevel = 9

staticconstexpr

Maximum zlib compression level (best compression)

Definition at line 66 of file frame_deflate_codec.h.

◆ kMinCompressionLevel

int kcenon::pacs::encoding::compression::frame_deflate_codec::kMinCompressionLevel = 1

staticconstexpr

Minimum zlib compression level (fastest)

Definition at line 63 of file frame_deflate_codec.h.

◆ kTransferSyntaxUID

std::string_view kcenon::pacs::encoding::compression::frame_deflate_codec::kTransferSyntaxUID

staticconstexpr

Initial value:

=

"1.2.840.10008.1.2.11"

DICOM Transfer Syntax UID for Frame Deflate.

Definition at line 56 of file frame_deflate_codec.h.

Referenced by kcenon::pacs::encoding::compression::codec_factory::create().

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

include/kcenon/pacs/encoding/compression/frame_deflate_codec.h
src/encoding/compression/frame_deflate_codec.cpp

Public Member Functions

Static Public Attributes

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ frame_deflate_codec() [1/3]

◆ ~frame_deflate_codec()

◆ frame_deflate_codec() [2/3]

◆ frame_deflate_codec() [3/3]

Member Function Documentation

◆ can_decode()

◆ can_encode()

◆ compression_level()

◆ decode()

◆ encode()

◆ is_lossy()

◆ name()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ transfer_syntax_uid()

Member Data Documentation

◆ compression_level_

◆ kDefaultCompressionLevel

◆ kMaxCompressionLevel

◆ kMinCompressionLevel

◆ kTransferSyntaxUID