Colopresso Python Bindings

Python bindings for the colopresso image compression library. Encode PNG images to WebP, AVIF, or optimized PNG (PNGX) formats.

Table of Contents

• Requirements
• Installation
• Quick Start
• API Reference
  • Encoding Functions
  • Config Class
  • PngxLossyType Enum
  • Configuration Parameters
  • Utility Functions
  • Exception Classes
• Examples
• Building Wheels

Requirements

[!IMPORTANT] AVX2 instruction set support is required on x86_64 (amd64) platforms. Intel Haswell (2013) or later, or AMD Excavator or later processors are required.

Installation

From PyPI

pip install "colopresso"

From source (requires CMake, Rust, and C compiler)

cd python
pip install .

Development installation

cd python
pip install -e ".[dev]"

Quick Start

import colopresso

# Read PNG file
with open("input.png", "rb") as f:
    png_data = f.read()

# Convert to WebP
webp_data = colopresso.encode_webp(png_data)
with open("output.webp", "wb") as f:
    f.write(webp_data)

# Convert to AVIF
avif_data = colopresso.encode_avif(png_data)
with open("output.avif", "wb") as f:
    f.write(avif_data)

# Optimize PNG
optimized_png = colopresso.encode_pngx(png_data)
with open("output.png", "wb") as f:
    f.write(optimized_png)

API Reference

Encoding Functions

encode_webp(png_data, config=None) -> bytes

Encode PNG data to WebP format.

Parameters:

• png_data (bytes): Raw PNG file data
• config (Config, optional): Encoding configuration. Uses defaults if not provided.

Returns:

• bytes: WebP encoded data

Raises:

• ColopressoError: If encoding fails

Example:

import colopresso

with open("input.png", "rb") as f:
    png_data = f.read()

# Default settings
webp_data = colopresso.encode_webp(png_data)

# Custom quality
config = colopresso.Config(webp_quality=90.0)
webp_data = colopresso.encode_webp(png_data, config)

encode_avif(png_data, config=None) -> bytes

Encode PNG data to AVIF format.

Parameters:

• png_data (bytes): Raw PNG file data
• config (Config, optional): Encoding configuration. Uses defaults if not provided.

Returns:

• bytes: AVIF encoded data

Raises:

• ColopressoError: If encoding fails (including when output is larger than input)

Example:

import colopresso

with open("input.png", "rb") as f:
    png_data = f.read()

config = colopresso.Config(avif_quality=70.0, avif_speed=4)
avif_data = colopresso.encode_avif(png_data, config)

encode_pngx(png_data, config=None) -> bytes

Optimize PNG data using the PNGX encoder. Supports both lossless and lossy compression.

Parameters:

• png_data (bytes): Raw PNG file data
• config (Config, optional): Encoding configuration. Uses defaults if not provided.

Returns:

• bytes: Optimized PNG data

Raises:

• ColopressoError: If encoding fails

Example:

import colopresso

with open("input.png", "rb") as f:
    png_data = f.read()

# 256-color palette optimization
config = colopresso.Config(
    pngx_lossy_enable=True,
    pngx_lossy_type=colopresso.PngxLossyType.PALETTE256,
    pngx_lossy_max_colors=256
)
optimized = colopresso.encode_pngx(png_data, config)

Config Class

The Config dataclass holds all encoder settings.

@dataclass
class Config:
    # WebP settings
    webp_quality: float = 80.0
    webp_lossless: bool = False
    webp_method: int = 6
    
    # AVIF settings
    avif_quality: float = 50.0
    avif_alpha_quality: int = 100
    avif_lossless: bool = False
    avif_speed: int = 6
    avif_threads: int = 1
    
    # PNGX settings
    pngx_level: int = 5
    pngx_strip_safe: bool = True
    pngx_optimize_alpha: bool = True
    pngx_lossy_enable: bool = True
    pngx_lossy_type: PngxLossyType = PngxLossyType.PALETTE256
    pngx_lossy_max_colors: int = 256
    pngx_lossy_quality_min: int = 80
    pngx_lossy_quality_max: int = 95
    pngx_lossy_speed: int = 3
    pngx_lossy_dither_level: float = 0.6
    pngx_threads: int = 1

PngxLossyType Enum

Specifies the type of lossy compression for PNGX.

class PngxLossyType(IntEnum):
    PALETTE256 = 0          # 256-color indexed palette
    LIMITED_RGBA4444 = 1    # RGBA4444 limited (16-bit color)
    REDUCED_RGBA32 = 2      # Reduced color RGBA32

Configuration Parameters

WebP Settings

Advanced WebP Parameters:

AVIF Settings

Recommended Settings:

PNGX Settings

Basic Settings

Lossy Compression Settings

PALETTE256 Mode Settings

LIMITED_RGBA4444 Mode Settings

Utility Functions

Version Information

def get_version() -> int

Get the colopresso version number.

def get_libwebp_version() -> int

Get the libwebp version number (e.g., 67072 = 1.4.0).

def get_libpng_version() -> int

Get the libpng version number.

def get_libavif_version() -> int

Get the libavif version number.

def get_pngx_oxipng_version() -> int

Get the oxipng version number.

def get_pngx_libimagequant_version() -> int

Get the libimagequant version number.

Build Information

def get_buildtime() -> int

Get the build timestamp (Unix time).

def get_compiler_version_string() -> str

Get the C compiler version string.

def get_rust_version_string() -> str

Get the Rust compiler version string.

Thread Information

def is_threads_enabled() -> bool

Check if multithreading is enabled.

def get_default_thread_count() -> int

Get the default number of threads.

def get_max_thread_count() -> int

Get the maximum available thread count.

Exception Classes

ColopressoError

class ColopressoError(Exception):
    code: int       # Error code
    message: str    # Error message

Error Codes:

Example:

import colopresso

try:
    result = colopresso.encode_avif(png_data)
except colopresso.ColopressoError as e:
    if e.code == 9:
        print("AVIF compression was not effective. Using original PNG.")
    else:
        print(f"Error: {e.message}")

Examples

WebP Conversion with Quality Settings

import colopresso

with open("photo.png", "rb") as f:
    png_data = f.read()

# High quality WebP
config = colopresso.Config(
    webp_quality=95.0,
    webp_method=6,
    webp_use_sharp_yuv=True
)
high_quality = colopresso.encode_webp(png_data, config)

# High compression WebP
config = colopresso.Config(
    webp_quality=60.0,
    webp_method=6
)
compressed = colopresso.encode_webp(png_data, config)

# Lossless WebP
config = colopresso.Config(webp_lossless=True)
lossless = colopresso.encode_webp(png_data, config)

AVIF with Multithreading

import colopresso

with open("large_image.png", "rb") as f:
    png_data = f.read()

# Multithreaded high-speed encoding
config = colopresso.Config(
    avif_quality=70.0,
    avif_speed=6,
    avif_threads=4
)
avif_data = colopresso.encode_avif(png_data, config)

PNG Optimization (256-Color Palette)

import colopresso

with open("icon.png", "rb") as f:
    png_data = f.read()

config = colopresso.Config(
    pngx_lossy_enable=True,
    pngx_lossy_type=colopresso.PngxLossyType.PALETTE256,
    pngx_lossy_max_colors=256,
    pngx_lossy_quality_min=85,
    pngx_lossy_quality_max=100,
    pngx_lossy_dither_level=0.8
)
optimized = colopresso.encode_pngx(png_data, config)

print(f"Original: {len(png_data)} bytes")
print(f"Optimized: {len(optimized)} bytes")
print(f"Reduction: {(1 - len(optimized)/len(png_data))*100:.1f}%")

PNG Lossless Optimization

import colopresso

with open("screenshot.png", "rb") as f:
    png_data = f.read()

config = colopresso.Config(
    pngx_lossy_enable=False,  # Disable lossy compression
    pngx_level=6,             # Maximum compression level
    pngx_strip_safe=True,     # Remove metadata
    pngx_optimize_alpha=True  # Optimize alpha
)
optimized = colopresso.encode_pngx(png_data, config)

Game Texture PNG (RGBA4444)

import colopresso

with open("texture.png", "rb") as f:
    png_data = f.read()

# RGBA4444 format (16-bit color)
config = colopresso.Config(
    pngx_lossy_enable=True,
    pngx_lossy_type=colopresso.PngxLossyType.LIMITED_RGBA4444,
    pngx_lossy_reduced_bits_rgb=4,
    pngx_lossy_reduced_alpha_bits=4
)
optimized = colopresso.encode_pngx(png_data, config)

Batch Processing

import colopresso
from pathlib import Path
from concurrent.futures import ThreadPoolExecutor

def convert_to_webp(png_path: Path) -> tuple[Path, int, int]:
    """Convert PNG to WebP and return size info"""
    with open(png_path, "rb") as f:
        png_data = f.read()
    
    config = colopresso.Config(webp_quality=80.0)
    webp_data = colopresso.encode_webp(png_data, config)
    
    webp_path = png_path.with_suffix(".webp")
    with open(webp_path, "wb") as f:
        f.write(webp_data)
    
    return webp_path, len(png_data), len(webp_data)

# Parallel conversion
png_files = list(Path("images").glob("*.png"))
with ThreadPoolExecutor(max_workers=4) as executor:
    results = list(executor.map(convert_to_webp, png_files))

for path, original, converted in results:
    print(f"{path.name}: {original} -> {converted} ({(1-converted/original)*100:.1f}% reduction)")

Error Handling

import colopresso

def safe_encode(png_data: bytes, format: str = "webp") -> bytes | None:
    """Encode with error handling"""
    config = colopresso.Config()
    
    try:
        if format == "webp":
            return colopresso.encode_webp(png_data, config)
        elif format == "avif":
            return colopresso.encode_avif(png_data, config)
        elif format == "pngx":
            return colopresso.encode_pngx(png_data, config)
        else:
            raise ValueError(f"Unknown format: {format}")
            
    except colopresso.ColopressoError as e:
        if e.code == 2:
            print("Error: Input is not a valid PNG")
        elif e.code == 9:
            print(f"{format.upper()} compression was not effective")
            return png_data  # Return original data
        else:
            print(f"Encoding error: {e.message}")
        return None

# Usage
with open("input.png", "rb") as f:
    png_data = f.read()

result = safe_encode(png_data, "avif")
if result:
    with open("output.avif", "wb") as f:
        f.write(result)

Building Wheels

cd python
pip install build
python -m build --wheel

The wheel will be created in python/dist/.

License

colopresso is licensed under GPL-3.0-or-later.

Copyright (C) 2026 COLOPL, Inc.