kaira.models.image.compressors.PNGCompressor

Inheritance diagram for PNGCompressor

class kaira.models.image.compressors.PNGCompressor(max_bits_per_image: int | None = None, quality: int | None = None, compress_level: int | None = None, optimize: bool = True, collect_stats: bool = False, return_bits: bool = True, return_compressed_data: bool = False, *args: Any, **kwargs: Any)

Bases: BaseImageCompressor

PNG image compressor using libpng via PIL/Pillow.

This class provides PNG compression with configurable compression levels and optimization. PNG is a lossless compression format that provides good compression for images with limited colors, text, or sharp edges.

The compress_level parameter ranges from 0 (no compression, fastest) to 9 (best compression, slowest). Higher compression levels result in smaller file sizes but take more time to process.

Note: Since PNG is lossless, the “quality” parameter in bit-constrained mode actually refers to the compression level, which affects file size but not image quality.

Example

# Fixed compression level compressor = PNGCompressor(quality=6) # quality here means compression level compressed_images = compressor(image_batch)

# Bit-constrained compression compressor = PNGCompressor(max_bits_per_image=50000) compressed_images, bits_used = compressor(image_batch)

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

Methods

__init__	Initialize the PNG compressor.
compress	Compress a PIL Image to PNG bytes.
decompress	Decompress PNG 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.PNGCompressor

Image Compressors Comparison

Image Compressors Comparison

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

Initialize the PNG compressor.

Parameters:

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

• quality – PNG compression level (0-9, higher = better compression, smaller file size). This is an alias for compress_level to maintain API consistency.

• compress_level – PNG compression level (0-9, higher = better compression). If both quality and compress_level are provided, compress_level takes precedence.

• optimize – Enable PNG optimization for better compression

• 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, compress_level: int | None = None) → bytes

Compress a PIL Image to PNG bytes.

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

Parameters:

• image – PIL Image to compress

• compress_level – PNG compression level (uses instance quality if not provided)

Returns:

Compressed PNG data as bytes

decompress(data: bytes) → Image

Decompress PNG bytes to PIL Image.

This is a convenience method for direct decompression.

Parameters:

data – Compressed PNG 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