kaira.models.image.compressors.JPEGXLCompressor

Inheritance diagram for JPEGXLCompressor

class kaira.models.image.compressors.JPEGXLCompressor(max_bits_per_image: int | None = None, quality: int | None = None, effort: int = 7, lossless: bool = False, collect_stats: bool = False, return_bits: bool = True, return_compressed_data: bool = False, *args: Any, **kwargs: Any)

Bases: BaseImageCompressor

JPEG XL image compressor using JPEG XL via PIL/Pillow.

This class provides JPEG XL compression with configurable quality settings and advanced features. JPEG XL is a modern image compression format that provides superior compression efficiency compared to traditional JPEG while maintaining excellent visual quality. It supports both lossy and lossless compression modes.

The quality parameter ranges from 1 (worst quality, highest compression) to 100 (best quality, lowest compression). JPEG XL also supports a special lossless mode when quality is set to 100.

Example

# Fixed quality compression compressor = JPEGXLCompressor(quality=85) compressed_images = compressor(image_batch)

# Bit-constrained compression compressor = JPEGXLCompressor(max_bits_per_image=3000) compressed_images, bits_used = compressor(image_batch)

# Lossless compression compressor = JPEGXLCompressor(quality=100) compressed_images = compressor(image_batch)

# With compression statistics compressor = JPEGXLCompressor(quality=90, collect_stats=True, return_bits=True) compressed_images, bits_per_image = compressor(image_batch) stats = compressor.get_stats()

Methods

__init__	Initialize the JPEG XL compressor.
compress	Compress a PIL Image to JPEG XL bytes.
decompress	Decompress JPEG XL bytes to PIL Image.
forward	Process a batch of images through compression.
from_config	Create model instance from configuration.
from_hydra_config	Create model from Hydra DictConfig.
from_pretrained_config	Create model from Hugging Face PretrainedConfig.
get_compression_ratio	Calculate compression ratio.
get_stats	Get compression statistics from the last forward pass.

Examples using kaira.models.image.compressors.JPEGXLCompressor

Image Compressors Comparison

Image Compressors Comparison

__init__(max_bits_per_image: int | None = None, quality: int | None = None, effort: int = 7, lossless: bool = False, collect_stats: bool = False, return_bits: bool = True, return_compressed_data: bool = False, *args: Any, **kwargs: Any)

Initialize the JPEG XL compressor.

Parameters:

• max_bits_per_image – Maximum bits allowed per compressed image. If provided without quality, the compressor will find the highest quality that produces files smaller than this limit.

• quality – JPEG XL quality level (1-100, higher = better quality, larger file size). If provided, this exact quality will be used regardless of resulting file size. Quality 100 enables lossless mode unless lossless=False is explicitly set.

• effort – Encoding effort (1-9, higher = slower but potentially better compression). Default is 7 for good balance of speed and compression.

• lossless – Force lossless mode regardless of quality setting.

• collect_stats – Whether to collect and return compression statistics

• return_bits – Whether to return bits per image in forward pass

• return_compressed_data – Whether to return the compressed binary data

• *args – Variable positional arguments passed to the base class.

• **kwargs – Variable keyword arguments passed to the base class.

compress(image: Image, quality: int | None = None) → bytes

Compress a PIL Image to JPEG XL bytes.

This is a convenience method for direct compression without the full forward pass.

Parameters:

• image – PIL Image to compress

• quality – JPEG XL quality level (uses instance quality if not provided)

Returns:

Compressed JPEG XL data as bytes

decompress(data: bytes) → Image

Decompress JPEG XL bytes to PIL Image.

This is a convenience method for direct decompression.

Parameters:

data – Compressed JPEG XL data as bytes

Returns:

Reconstructed PIL Image

forward(x: Tensor, *args: Any, **kwargs: Any) → Tensor | Tuple[Tensor, List[int]] | Tuple[Tensor, List[bytes]] | Tuple[Tensor, List[int], List[bytes]]

Process a batch of images through compression.

Parameters:

• x – Tensor of shape [batch_size, channels, height, width] with values in [0, 1]

• *args – Additional positional arguments

• **kwargs – Additional keyword arguments

Returns:

Just the reconstructed image tensor If return_bits=True: Tuple of (tensor, bits per image) If return_compressed_data=True: Tuple of (tensor, compressed binary data) If both are True: Tuple of (tensor, bits per image, compressed binary data)

Return type:

If no additional returns

classmethod from_config(config, **kwargs)

Create model instance from configuration.

Parameters:

• config – Configuration object (PretrainedConfig, DictConfig, or dict)

• **kwargs – Additional parameters to override config

Returns:

Model instance

classmethod from_hydra_config(config: DictConfig, **kwargs)

Create model from Hydra DictConfig.

Parameters:

• config – Hydra configuration

• **kwargs – Additional parameters

Returns:

Model instance

classmethod from_pretrained_config(config: PretrainedConfig, **kwargs)

Create model from Hugging Face PretrainedConfig.

Parameters:

• config – PretrainedConfig instance

• **kwargs – Additional parameters

Returns:

Model instance

get_compression_ratio(original_size: int, compressed_size: int) → float

Calculate compression ratio.

Parameters:

• original_size – Size of original data in bits

• compressed_size – Size of compressed data in bits

Returns:

Compression ratio (original_size / compressed_size)

get_stats() → Dict[str, Any]

Get compression statistics from the last forward pass.

Returns:

Dictionary containing compression statistics