kaira.models.image.compressors.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)

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

__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)

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]]

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)

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)

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)

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]

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]

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]