High-Throughput JPEG 2000 (HTJ2K) codec implementation. More...

#include <htj2k_codec.h>

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

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

Public Member Functions
	htj2k_codec (bool lossless=true, bool use_rpcl=false, float compression_ratio=kDefaultCompressionRatio, int resolution_levels=kDefaultResolutionLevels)
	Constructs an HTJ2K codec instance.

	~htj2k_codec () override

	htj2k_codec (const htj2k_codec &)=delete

htj2k_codec &	operator= (const htj2k_codec &)=delete

	htj2k_codec (htj2k_codec &&) noexcept

htj2k_codec &	operator= (htj2k_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
bool	is_lossless_mode () const noexcept
	Checks if this codec is configured for lossless mode.

bool	is_rpcl_mode () const noexcept
	Checks if RPCL progression order is enabled.

float	compression_ratio () const noexcept
	Gets the current compression ratio setting.

int	resolution_levels () const noexcept
	Gets the number of DWT resolution levels.

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 to HTJ2K format.

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

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

Static Public Attributes
static constexpr std::string_view	kTransferSyntaxUIDLossless
	DICOM Transfer Syntax UID for HTJ2K Lossless Only.

static constexpr std::string_view	kTransferSyntaxUIDRPCL
	DICOM Transfer Syntax UID for HTJ2K with RPCL Options (Lossless Only)

static constexpr std::string_view	kTransferSyntaxUIDLossy
	DICOM Transfer Syntax UID for HTJ2K (Lossy)

static constexpr float	kDefaultCompressionRatio = 20.0f
	Default compression ratio for lossy mode (20:1)

static constexpr int	kDefaultResolutionLevels = 6
	Default number of resolution levels.

Private Attributes
bool	lossless_

bool	use_rpcl_

float	compression_ratio_

int	resolution_levels_

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

High-Throughput JPEG 2000 (HTJ2K) codec implementation.

Implements DICOM Transfer Syntaxes defined in Supplement 235:

1.2.840.10008.1.2.4.201 (HTJ2K Lossless Only)
1.2.840.10008.1.2.4.202 (HTJ2K with RPCL Options - Lossless Only)
1.2.840.10008.1.2.4.203 (HTJ2K - Lossless or Lossy)

HTJ2K provides 10-50x faster decoding than legacy JPEG 2000 while maintaining comparable compression ratios. Uses the Part 15 (HTJ2K) block coder which enables highly parallelizable decoding.

Supported Features:

8-bit, 12-bit, 16-bit grayscale images
8-bit color images (RGB, YCbCr)
Lossless mode (reversible 5/3 wavelet transform with HT block coder)
Lossy mode (irreversible 9/7 wavelet transform with HT block coder)
RPCL progression order for streaming/progressive decoding

Thread Safety:

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

Note: Actual encode/decode operations require OpenJPH library integration (see issue #785). Without OpenJPH, encode/decode return an error.

See also: DICOM Supplement 235 - HTJ2K Transfer Syntaxes; ISO/IEC 15444-15 (JPEG 2000 Part 15 - High-Throughput block coder)

Definition at line 47 of file htj2k_codec.h.

Constructor & Destructor Documentation

◆ htj2k_codec() [1/3]

kcenon::pacs::encoding::compression::htj2k_codec::htj2k_codec	(	bool	lossless = true,
		bool	use_rpcl = false,
		float	compression_ratio = kDefaultCompressionRatio,
		int	resolution_levels = kDefaultResolutionLevels )

explicit

Constructs an HTJ2K codec instance.

Parameters

lossless	If true, use lossless mode (Transfer Syntax .201 or .202). If false, use lossy mode (Transfer Syntax .203).
use_rpcl	If true, use RPCL progression order (Transfer Syntax .202). Only meaningful in lossless mode. Enables progressive resolution decoding for streaming use cases.
compression_ratio	Target compression ratio for lossy mode (ignored in lossless). Higher values = smaller files but lower quality.
resolution_levels	Number of DWT resolution levels (1-32, default: 6).

Definition at line 20 of file htj2k_codec.cpp.

    : lossless_(lossless),
      use_rpcl_(use_rpcl),
      compression_ratio_(compression_ratio),
      resolution_levels_(resolution_levels) {}

◆ ~htj2k_codec()

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

overridedefault

◆ htj2k_codec() [2/3]

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

delete

◆ htj2k_codec() [3/3]

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

defaultnoexcept

Member Function Documentation

◆ can_decode()

bool kcenon::pacs::encoding::compression::htj2k_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 68 of file htj2k_codec.cpp.

                                                                      {
    return can_encode(params);
}

◆ can_encode()

bool kcenon::pacs::encoding::compression::htj2k_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 52 of file htj2k_codec.cpp.

                                                                      {
    if (params.width == 0 || params.height == 0) {
        return false;
    }
 
    if (params.samples_per_pixel != 1 && params.samples_per_pixel != 3) {
        return false;
    }
 
    if (params.bits_stored < 1 || params.bits_stored > 16) {
        return false;
    }
 
    return true;
}

◆ compression_ratio()

float kcenon::pacs::encoding::compression::htj2k_codec::compression_ratio ( ) const

nodiscardnoexcept

Gets the current compression ratio setting.

Returns: Compression ratio (only meaningful for lossy mode)

Definition at line 80 of file htj2k_codec.cpp.

                                                    {
    return compression_ratio_;
}

References compression_ratio_.

◆ decode()

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

nodiscardoverridevirtual

Decompresses HTJ2K data.

Parameters

compressed_data	HTJ2K compressed data
params	Image parameters (width/height for validation)

Returns: Decompressed pixel data or error

Note: Currently returns an error indicating OpenJPH is not integrated. Full implementation will be added in issue #785.

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

Definition at line 427 of file htj2k_codec.cpp.

                                                       {
    return kcenon::pacs::pacs_error<compression_result>(
        kcenon::pacs::error_codes::decompression_error,
        "HTJ2K codec not available: OpenJPH 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::htj2k_codec::encode	(	std::span< const uint8_t >	pixel_data,
		const image_params &	params,
		const compression_options &	options = {} ) const

nodiscardoverridevirtual

Compresses pixel data to HTJ2K format.

Parameters

pixel_data	Uncompressed pixel data (8/12/16-bit, grayscale or color)
params	Image parameters
options	Compression options

Returns: Compressed HTJ2K codestream or error

Note: Currently returns an error indicating OpenJPH is not integrated. Full implementation will be added in issue #785.

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

Definition at line 418 of file htj2k_codec.cpp.

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

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

Referenced by kcenon::pacs::web::dicomweb::render_dicom_image().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ is_lossless_mode()

bool kcenon::pacs::encoding::compression::htj2k_codec::is_lossless_mode ( ) const

nodiscardnoexcept

Checks if this codec is configured for lossless mode.

Returns: true if lossless, false if lossy

Definition at line 72 of file htj2k_codec.cpp.

                                                  {
    return lossless_;
}

References lossless_.

◆ is_lossy()

bool kcenon::pacs::encoding::compression::htj2k_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 48 of file htj2k_codec.cpp.

                                          {
    return !lossless_;
}

References lossless_.

◆ is_rpcl_mode()

bool kcenon::pacs::encoding::compression::htj2k_codec::is_rpcl_mode ( ) const

nodiscardnoexcept

Checks if RPCL progression order is enabled.

Returns: true if RPCL mode is active

Definition at line 76 of file htj2k_codec.cpp.

                                              {
    return use_rpcl_;
}

References use_rpcl_.

◆ name()

std::string_view kcenon::pacs::encoding::compression::htj2k_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 41 of file htj2k_codec.cpp.

                                                {
    if (lossless_) {
        return use_rpcl_ ? "HTJ2K with RPCL (Lossless)" : "HTJ2K (Lossless)";
    }
    return "HTJ2K (Lossy)";
}

References lossless_, and use_rpcl_.

◆ operator=() [1/2]

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

delete

◆ operator=() [2/2]

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

defaultnoexcept

◆ resolution_levels()

int kcenon::pacs::encoding::compression::htj2k_codec::resolution_levels ( ) const

nodiscardnoexcept

Gets the number of DWT resolution levels.

Returns: Resolution levels (1-32)

Definition at line 84 of file htj2k_codec.cpp.

                                                  {
    return resolution_levels_;
}

References resolution_levels_.

◆ transfer_syntax_uid()

std::string_view kcenon::pacs::encoding::compression::htj2k_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 34 of file htj2k_codec.cpp.

                                                               {
    if (lossless_) {
        return use_rpcl_ ? kTransferSyntaxUIDRPCL : kTransferSyntaxUIDLossless;
    }
    return kTransferSyntaxUIDLossy;
}

Member Data Documentation

◆ compression_ratio_

float kcenon::pacs::encoding::compression::htj2k_codec::compression_ratio_

private

Definition at line 170 of file htj2k_codec.h.

Referenced by compression_ratio().

◆ kDefaultCompressionRatio

float kcenon::pacs::encoding::compression::htj2k_codec::kDefaultCompressionRatio = 20.0f

staticconstexpr

Default compression ratio for lossy mode (20:1)

Definition at line 62 of file htj2k_codec.h.

◆ kDefaultResolutionLevels

int kcenon::pacs::encoding::compression::htj2k_codec::kDefaultResolutionLevels = 6

staticconstexpr

Default number of resolution levels.

Definition at line 65 of file htj2k_codec.h.

◆ kTransferSyntaxUIDLossless

std::string_view kcenon::pacs::encoding::compression::htj2k_codec::kTransferSyntaxUIDLossless

staticconstexpr

Initial value:

=

"1.2.840.10008.1.2.4.201"

DICOM Transfer Syntax UID for HTJ2K Lossless Only.

Definition at line 50 of file htj2k_codec.h.

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

◆ kTransferSyntaxUIDLossy

std::string_view kcenon::pacs::encoding::compression::htj2k_codec::kTransferSyntaxUIDLossy

staticconstexpr

Initial value:

=

"1.2.840.10008.1.2.4.203"

DICOM Transfer Syntax UID for HTJ2K (Lossy)

Definition at line 58 of file htj2k_codec.h.

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

◆ kTransferSyntaxUIDRPCL

std::string_view kcenon::pacs::encoding::compression::htj2k_codec::kTransferSyntaxUIDRPCL

staticconstexpr

Initial value:

=

"1.2.840.10008.1.2.4.202"

DICOM Transfer Syntax UID for HTJ2K with RPCL Options (Lossless Only)

Definition at line 54 of file htj2k_codec.h.

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

◆ lossless_

bool kcenon::pacs::encoding::compression::htj2k_codec::lossless_

private

Definition at line 168 of file htj2k_codec.h.

Referenced by is_lossless_mode(), is_lossy(), and name().

◆ resolution_levels_

int kcenon::pacs::encoding::compression::htj2k_codec::resolution_levels_

private

Definition at line 171 of file htj2k_codec.h.

Referenced by resolution_levels().

◆ use_rpcl_

bool kcenon::pacs::encoding::compression::htj2k_codec::use_rpcl_

private

Definition at line 169 of file htj2k_codec.h.

Referenced by is_rpcl_mode(), and name().

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

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

Public Member Functions

Static Public Attributes

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ htj2k_codec() [1/3]

◆ ~htj2k_codec()

◆ htj2k_codec() [2/3]

◆ htj2k_codec() [3/3]

Member Function Documentation

◆ can_decode()

◆ can_encode()

◆ compression_ratio()

◆ decode()

◆ encode()

◆ is_lossless_mode()

◆ is_lossy()

◆ is_rpcl_mode()

◆ name()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ resolution_levels()

◆ transfer_syntax_uid()

Member Data Documentation

◆ compression_ratio_

◆ kDefaultCompressionRatio

◆ kDefaultResolutionLevels

◆ kTransferSyntaxUIDLossless

◆ kTransferSyntaxUIDLossy

◆ kTransferSyntaxUIDRPCL

◆ lossless_

◆ resolution_levels_

◆ use_rpcl_