kaira.models.image.compressors.BPGCompressor

Inheritance diagram of BPGCompressor

Inheritance diagram for BPGCompressor

class kaira.models.image.compressors.BPGCompressor(max_bits_per_image: int | None = None, quality: int | None = None, bpg_encoder_path: str = 'bpgenc', bpg_decoder_path: str = 'bpgdec', n_jobs: int | None = None, collect_stats: bool = False, return_bits: bool = True, return_compressed_data: bool = False, *args: Any, **kwargs: Any)[source]

Bases: BaseModel

BPG (Better Portable Graphics) image compression based on bpgenc and bpgdec.

This class provides BPG-based compression using external BPG tools. It can operate in two modes: 1. Fixed quality mode: directly uses the specified quality level 2. Bit-constrained mode: finds the highest quality that stays under a bit budget

BPG (Better Portable Graphics) is a lossy image compression format based on HEVC (High Efficiency Video Coding) that provides superior compression efficiency compared to JPEG while maintaining good visual quality.

Installation:

The BPG tools (bpgenc and bpgdec) must be installed separately on your system. For installation instructions, see: https://kaira.readthedocs.io/en/latest/installation.html#bpg-image-compression-support

Example

# Fixed quality compression compressor = BPGCompressor(quality=30) compressed_images = compressor(image_batch)

# Bit-constrained compression compressor = BPGCompressor(max_bits_per_image=5000) compressed_images, bits_used = compressor(image_batch)

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

Note

This class requires external BPG tools to be installed and available in PATH or specified via bpg_encoder_path and bpg_decoder_path parameters.

Methods

__init__

Initialize the BPG Compressor.

compress_with_quality

Compress image with a specific quality level.

compress_with_target_size

Find highest quality that produces file size below target_bits using binary search.

forward

Process a batch of images through BPG 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_bits_per_image

Compress images and return only the bit counts per image.

get_stats

Return compression statistics if collect_stats=True was set.

parallel_forward_bpg

Process a single image with BPG compression.

Examples using kaira.models.image.compressors.BPGCompressor

Image Compressors Comparison

Image Compressors Comparison
__init__(max_bits_per_image: int | None = None, quality: int | None = None, bpg_encoder_path: str = 'bpgenc', bpg_decoder_path: str = 'bpgdec', n_jobs: int | None = None, collect_stats: bool = False, return_bits: bool = True, return_compressed_data: bool = False, *args: Any, **kwargs: Any)[source]

Initialize the BPG 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 – Fixed quality level for BPG compression (0-51, lower is better). If provided, this exact quality will be used regardless of resulting file size.

  • bpg_encoder_path – Path to the BPG encoder executable

  • bpg_decoder_path – Path to the BPG decoder executable

  • n_jobs – Number of parallel jobs to use (default: CPU count // 2)

  • 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.

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

Process a batch of images through BPG compression.

The compression method depends on initialization parameters: - If quality was provided, that fixed quality is used - If max_bits_per_image was provided, the highest quality meeting the bit constraint is found

Parameters:

  • x – Tensor of shape [batch_size, channels, height, width]

  • *args – Additional positional arguments (passed to internal methods).

  • **kwargs – Additional keyword arguments (passed to internal methods).

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

parallel_forward_bpg(idx: int, img: Tensor, return_info: bool = False, *args: Any, **kwargs: Any)[source]

Process a single image with BPG compression.

Parameters:

  • idx – Image index

  • img – Image tensor of shape [channels, height, width]

  • return_info – Whether to return compression information

  • *args – Additional positional arguments (passed to compression methods).

  • **kwargs – Additional keyword arguments (passed to compression methods).

Returns:

Processed image tensor If return_info=True: Tuple of (tensor, info_dict)

Return type:

If return_info=False

compress_with_quality(idx: int, x: Tensor, quality: int, return_info: bool = False, *args: Any, **kwargs: Any)[source]

Compress image with a specific quality level.

Parameters:

  • idx – Image index for generating unique filenames

  • x – Image tensor

  • quality – BPG quality level (0-51)

  • return_info – Whether to return compression information

  • *args – Additional positional arguments (unused in this method).

  • **kwargs – Additional keyword arguments (unused in this method).

Returns:

Compressed-decompressed image tensor If return_info=True: Tuple of (tensor, info_dict)

Return type:

If return_info=False

compress_with_target_size(idx: int, x: Tensor, target_bits: int, return_info: bool = False, *args: Any, **kwargs: Any)[source]

Find highest quality that produces file size below target_bits using binary search.

Parameters:

  • idx – Image index for generating unique filenames

  • x – Image tensor

  • target_bits – Maximum bits for the compressed image

  • return_info – Whether to return compression information

  • *args – Additional positional arguments (unused in this method).

  • **kwargs – Additional keyword arguments (unused in this method).

Returns:

Compressed-decompressed image tensor If return_info=True: Tuple of (tensor, info_dict)

Return type:

If return_info=False

get_stats() → Dict[str, Any][source]

Return compression statistics if collect_stats=True was set.

Returns detailed compression statistics collected during the forward pass, including total bits, average quality, bits per pixel, compression ratios, and processing time.

Returns:

  • total_bits: Total bits used for all images

  • avg_quality: Average BPG quality level used

  • avg_bpp: Average bits per pixel across all images

  • avg_compression_ratio: Average compression ratio (original/compressed)

  • processing_time: Time taken for compression

  • img_stats: List of per-image statistics

Return type:

Dict containing compression statistics

Note

Returns empty dict if collect_stats=False was set during initialization.

get_bits_per_image(x: Tensor, *args: Any, **kwargs: Any) → List[int][source]

Compress images and return only the bit counts per image.

The compression method depends on whether quality or max_bits_per_image was provided during initialization.

Parameters:

  • x – Tensor of shape [batch_size, channels, height, width]

  • *args – Additional positional arguments passed to forward.

  • **kwargs – Additional keyword arguments passed to forward.

Returns:

Number of bits used for each compressed image

Return type:

List[int]

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