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

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

Return compression statistics if collect_stats=True was set.

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]