JPEG-LS codec implementation supporting both lossless and near-lossless modes. More...

#include <jpeg_ls_codec.h>

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

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

Classes
class	impl
	PIMPL implementation for jpeg_ls_codec. More...

Public Member Functions
	jpeg_ls_codec (bool lossless=true, int near_value=kAutoNearValue)
	Constructs a JPEG-LS codec instance.

	~jpeg_ls_codec () override

	jpeg_ls_codec (const jpeg_ls_codec &)=delete

jpeg_ls_codec &	operator= (const jpeg_ls_codec &)=delete

	jpeg_ls_codec (jpeg_ls_codec &&) noexcept

jpeg_ls_codec &	operator= (jpeg_ls_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.

int	near_value () const noexcept
	Gets the NEAR parameter value.

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 JPEG-LS format.

codec_result	decode (std::span< const uint8_t > compressed_data, const image_params &params) const override
	Decompresses JPEG-LS 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 JPEG-LS Lossless.

static constexpr std::string_view	kTransferSyntaxUIDNearLossless
	DICOM Transfer Syntax UID for JPEG-LS Near-Lossless (Lossy)

static constexpr int	kAutoNearValue = -1
	Sentinel value indicating "auto-determine NEAR based on mode".

static constexpr int	kLosslessNearValue = 0
	NEAR parameter for lossless mode.

static constexpr int	kDefaultNearLosslessValue = 2
	Default NEAR parameter for near-lossless mode (visually lossless quality)

static constexpr int	kMaxNearValue = 255
	Maximum NEAR parameter value (higher = more compression, more loss)

Private Attributes
std::unique_ptr< impl >	impl_

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

JPEG-LS codec implementation supporting both lossless and near-lossless modes.

Implements DICOM Transfer Syntaxes:

1.2.840.10008.1.2.4.80 (JPEG-LS Lossless Image Compression)
1.2.840.10008.1.2.4.81 (JPEG-LS Lossy (Near-Lossless) Image Compression)

Uses CharLS library for high-performance JPEG-LS encoding/decoding.

Supported Features:

8-bit, 12-bit, 16-bit grayscale images
8-bit color images (RGB, interleaved)
Lossless mode (NEAR=0)
Near-lossless mode with configurable NEAR parameter
Line interleaved and sample interleaved modes for color

Limitations:

Maximum image size: 65535 x 65535 pixels
Requires CharLS 2.0+ for full feature support

Thread Safety:

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

Integration:

Uses thread_system for parallel batch encoding (via thread_pool_adapter)
Logs operations via logger_system (via logger_adapter)
Reports metrics to monitoring_system (via monitoring_adapter)

See also: DICOM PS3.5 Annex A.4.3 - JPEG-LS Image Compression; ISO/IEC 14495-1 (JPEG-LS standard)

Definition at line 50 of file jpeg_ls_codec.h.

Constructor & Destructor Documentation

◆ jpeg_ls_codec() [1/3]

kcenon::pacs::encoding::compression::jpeg_ls_codec::jpeg_ls_codec	(	bool	lossless = true,
		int	near_value = kAutoNearValue )

explicit

Constructs a JPEG-LS codec instance.

Parameters

lossless	If true, use lossless mode (Transfer Syntax 1.2.840.10008.1.2.4.80). If false, use near-lossless mode (Transfer Syntax 1.2.840.10008.1.2.4.81).
near_value	NEAR parameter controlling the maximum absolute error per pixel. -1 = auto (0 for lossless, kDefaultNearLosslessValue for near-lossless) 0 = lossless (overrides lossless flag to true) 1-255 = near-lossless (bounded error, higher = more compression) Typical medical imaging: 1-3 for visually lossless quality.

Definition at line 253 of file jpeg_ls_codec.cpp.

254 : impl_(std::make_unique<impl>(lossless, near_value)) {}

kcenon::pacs::encoding::compression::jpeg_ls_codec::near_value

int near_value() const noexcept

Gets the NEAR parameter value.

Definition jpeg_ls_codec.cpp:317

kcenon::pacs::encoding::compression::jpeg_ls_codec::impl_

std::unique_ptr< impl > impl_

Definition jpeg_ls_codec.h:167

◆ ~jpeg_ls_codec()

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

overridedefault

◆ jpeg_ls_codec() [2/3]

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

delete

◆ jpeg_ls_codec() [3/3]

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

defaultnoexcept

Member Function Documentation

◆ can_decode()

bool kcenon::pacs::encoding::compression::jpeg_ls_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 302 of file jpeg_ls_codec.cpp.

                                                                        {
    // For decoding, we're more lenient as actual parameters come from the bitstream
    // Just validate samples_per_pixel if specified
    if (params.samples_per_pixel != 0 &&
        params.samples_per_pixel != 1 &&
        params.samples_per_pixel != 3) {
        return false;
    }
    return true;
}

◆ can_encode()

bool kcenon::pacs::encoding::compression::jpeg_ls_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 273 of file jpeg_ls_codec.cpp.

                                                                        {
    // JPEG-LS supports 2-16 bit precision per component
    if (params.bits_stored < 2 || params.bits_stored > 16) {
        return false;
    }
 
    // bits_allocated must be 8 or 16
    if (params.bits_allocated != 8 && params.bits_allocated != 16) {
        return false;
    }
 
    // Support grayscale (1) and color (3) images
    if (params.samples_per_pixel != 1 && params.samples_per_pixel != 3) {
        return false;
    }
 
    // Require valid dimensions
    if (params.width == 0 || params.height == 0) {
        return false;
    }
 
    // Maximum dimension check (JPEG-LS limit)
    if (params.width > 65535 || params.height > 65535) {
        return false;
    }
 
    return true;
}

◆ decode()

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

nodiscardoverridevirtual

Decompresses JPEG-LS data.

Parameters

compressed_data	JPEG-LS compressed data
params	Image parameters (width/height for validation)

Returns: Decompressed pixel data or error

Output format matches the original bit depth:

8-bit: single byte per sample
12/16-bit: two bytes per sample (little-endian)

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

Definition at line 327 of file jpeg_ls_codec.cpp.

                                                                      {
    return impl_->decode(compressed_data, params);
}

References kcenon::pacs::encoding::compression::jpeg_ls_codec::impl::decode(), and impl_.

Here is the call graph for this function:

◆ encode()

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

nodiscardoverridevirtual

Compresses pixel data to JPEG-LS format.

Parameters

pixel_data	Uncompressed pixel data (8/12/16-bit, grayscale or color)
params	Image parameters
options	Compression options: quality: 1-100 for near-lossless mode (maps to NEAR parameter) lossless: Override codec's lossless setting

Returns: Compressed JPEG-LS data or error

For lossless mode (NEAR=0):

Output is exactly reconstructible
Typical compression ratio: 2:1 to 4:1 for medical images

For near-lossless mode (NEAR>0):

Maximum pixel error is bounded by NEAR value
Higher NEAR = smaller file but more artifact potential
NEAR=1-3 typically provides visually lossless quality

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

Definition at line 321 of file jpeg_ls_codec.cpp.

                                                                              {
    return impl_->encode(pixel_data, params, options);
}

References kcenon::pacs::encoding::compression::jpeg_ls_codec::impl::encode(), and impl_.

Here is the call graph for this function:

◆ is_lossless_mode()

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

nodiscardnoexcept

Checks if this codec is configured for lossless mode.

Returns: true if lossless, false if near-lossless

Definition at line 313 of file jpeg_ls_codec.cpp.

                                                    {
    return impl_->is_lossless_mode();
}

References impl_, and kcenon::pacs::encoding::compression::jpeg_ls_codec::impl::is_lossless_mode().

Referenced by transfer_syntax_uid().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ is_lossy()

bool kcenon::pacs::encoding::compression::jpeg_ls_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 269 of file jpeg_ls_codec.cpp.

                                            {
    return !impl_->is_lossless_mode();
}

References impl_, and kcenon::pacs::encoding::compression::jpeg_ls_codec::impl::is_lossless_mode().

Here is the call graph for this function:

◆ name()

std::string_view kcenon::pacs::encoding::compression::jpeg_ls_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 265 of file jpeg_ls_codec.cpp.

                                                  {
    return impl_->is_lossless_mode() ? "JPEG-LS Lossless" : "JPEG-LS Near-Lossless";
}

References impl_, and kcenon::pacs::encoding::compression::jpeg_ls_codec::impl::is_lossless_mode().

Here is the call graph for this function:

◆ near_value()

int kcenon::pacs::encoding::compression::jpeg_ls_codec::near_value ( ) const

nodiscardnoexcept

Gets the NEAR parameter value.

Returns: NEAR value (0 for lossless, 1-255 for near-lossless)

Definition at line 317 of file jpeg_ls_codec.cpp.

                                             {
    return impl_->near_value();
}

References impl_, and kcenon::pacs::encoding::compression::jpeg_ls_codec::impl::near_value().

Here is the call graph for this function:

◆ operator=() [1/2]

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

delete

◆ operator=() [2/2]

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

defaultnoexcept

◆ transfer_syntax_uid()

std::string_view kcenon::pacs::encoding::compression::jpeg_ls_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 261 of file jpeg_ls_codec.cpp.

                                                                 {
    return impl_->is_lossless_mode() ? kTransferSyntaxUIDLossless : kTransferSyntaxUIDNearLossless;
}

References is_lossless_mode().

Here is the call graph for this function:

Member Data Documentation

◆ impl_

std::unique_ptr<impl> kcenon::pacs::encoding::compression::jpeg_ls_codec::impl_

private

Definition at line 167 of file jpeg_ls_codec.h.

Referenced by decode(), encode(), is_lossless_mode(), is_lossy(), name(), and near_value().

◆ kAutoNearValue

int kcenon::pacs::encoding::compression::jpeg_ls_codec::kAutoNearValue = -1

staticconstexpr

Sentinel value indicating "auto-determine NEAR based on mode".

Definition at line 61 of file jpeg_ls_codec.h.

Referenced by kcenon::pacs::encoding::compression::jpeg_ls_codec::impl::impl().

◆ kDefaultNearLosslessValue

int kcenon::pacs::encoding::compression::jpeg_ls_codec::kDefaultNearLosslessValue = 2

staticconstexpr

Default NEAR parameter for near-lossless mode (visually lossless quality)

Definition at line 67 of file jpeg_ls_codec.h.

Referenced by kcenon::pacs::encoding::compression::jpeg_ls_codec::impl::impl().

◆ kLosslessNearValue

int kcenon::pacs::encoding::compression::jpeg_ls_codec::kLosslessNearValue = 0

staticconstexpr

NEAR parameter for lossless mode.

Definition at line 64 of file jpeg_ls_codec.h.

Referenced by kcenon::pacs::encoding::compression::jpeg_ls_codec::impl::impl().

◆ kMaxNearValue

int kcenon::pacs::encoding::compression::jpeg_ls_codec::kMaxNearValue = 255

staticconstexpr

Maximum NEAR parameter value (higher = more compression, more loss)

Definition at line 70 of file jpeg_ls_codec.h.

Referenced by kcenon::pacs::encoding::compression::jpeg_ls_codec::impl::encode(), and kcenon::pacs::encoding::compression::jpeg_ls_codec::impl::impl().

◆ kTransferSyntaxUIDLossless

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

staticconstexpr

Initial value:

=

"1.2.840.10008.1.2.4.80"

DICOM Transfer Syntax UID for JPEG-LS Lossless.

Definition at line 53 of file jpeg_ls_codec.h.

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

◆ kTransferSyntaxUIDNearLossless

std::string_view kcenon::pacs::encoding::compression::jpeg_ls_codec::kTransferSyntaxUIDNearLossless

staticconstexpr

Initial value:

=

"1.2.840.10008.1.2.4.81"

DICOM Transfer Syntax UID for JPEG-LS Near-Lossless (Lossy)

Definition at line 57 of file jpeg_ls_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/jpeg_ls_codec.h
src/encoding/compression/jpeg_ls_codec.cpp

Classes

Public Member Functions

Static Public Attributes

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ jpeg_ls_codec() [1/3]

◆ ~jpeg_ls_codec()

◆ jpeg_ls_codec() [2/3]

◆ jpeg_ls_codec() [3/3]

Member Function Documentation

◆ can_decode()

◆ can_encode()

◆ decode()

◆ encode()

◆ is_lossless_mode()

◆ is_lossy()

◆ name()

◆ near_value()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ transfer_syntax_uid()

Member Data Documentation

◆ impl_

◆ kAutoNearValue

◆ kDefaultNearLosslessValue

◆ kLosslessNearValue

◆ kMaxNearValue

◆ kTransferSyntaxUIDLossless

◆ kTransferSyntaxUIDNearLossless