# psd_tools.compression

Image compression utilities for PSD channel data.

This subpackage provides compression and decompression codecs for raw pixel data in PSD files. Adobe Photoshop supports multiple compression methods for channel data to reduce file size.

Supported compression methods:

- RAW (`Compression.RAW`): Uncompressed raw pixel data

- RLE (`Compression.RLE`): Apple PackBits run-length encoding

- ZIP (`Compression.ZIP`): ZIP/Deflate compression without prediction

- ZIP_WITH_PREDICTION (`Compression.ZIP_WITH_PREDICTION`): ZIP with delta encoding

The RLE codec includes both a pure Python implementation and a Cython-optimized version (`_rle.pyx`) that provides significant performance improvements. The Cython version is used automatically when available, with graceful fallback to pure Python.

Key functions:

- `compress()`: Compress raw pixel data using specified method

- `decompress()`: Decompress pixel data back to raw bytes

- `encode_rle()`: RLE encoding for a single channel

- `decode_rle()`: RLE decoding for a single channel

Example usage:

    from psd_tools.compression import compress, decompress
    from psd_tools.constants import Compression

    # Compress raw channel data
    compressed = compress(
        data=raw_pixels,
        compression=Compression.RLE,
        width=100,
        height=100,
        depth=8,
        version=1
    )

    # Decompress back to raw data
    raw_pixels = decompress(
        data=compressed,
        compression=Compression.RLE,
        width=100,
        height=100,
        depth=8,
        version=1
    )

Performance notes:

- RLE is most effective for images with large uniform areas

- ZIP with prediction works well for continuous-tone images

- The Cython RLE codec can be 10-100x faster than pure Python

- Compression method is chosen per-channel when saving PSD files

The compression module handles various bit depths (8, 16, 32-bit per channel) and implements delta encoding for improved compression ratios on certain image types.

This module provides compression and decompression codecs for PSD channel data.

## Compression Functions

psd_tools.compression.compress(data: bytes, compression: Compression, width: int, height: int, depth: int, version: int = 1) → bytes

  Compress raw data.

  Parameters:

    - data – raw data bytes to write.

    - compression – compression type, see `Compression`.

    - width – width.

    - height – height.

    - depth – bit depth of the pixel.

    - version – psd file version.

  Returns:

    compressed data bytes.

psd_tools.compression.decompress(data: bytes, compression: Compression, width: int, height: int, depth: int, version: int = 1) → bytes

  Decompress raw data.

  Parameters:

    - data – compressed data bytes.

    - compression – compression type, see `Compression`.

    - width – width in pixels; must be in [1, 300000].

    - height – height in pixels; must be in [1, 300000].

    - depth – bit depth of the pixel; must be one of 1, 8, 16, 32.

    - version – psd file version.

  Returns:

    decompressed data bytes.

  Raises:

    ValueError – if width, height, or depth are out of range.

## RLE Codec

psd_tools.compression.encode_rle(data: bytes, width: int, height: int, depth: int, version: int) → bytes

psd_tools.compression.decode_rle(data: bytes, width: int, height: int, depth: int, version: int) → bytes

The RLE (Run-Length Encoding) codec implements Apple PackBits compression. A Cython-optimized version (`_rle.pyx`) is used when available, providing 10-100x performance improvement over the pure Python fallback.

## Prediction Encoding

psd_tools.compression.encode_prediction(data: bytes | bytearray, w: int, h: int, depth: int) → bytes

psd_tools.compression.decode_prediction(data: bytes, w: int, h: int, depth: int) → bytes

Prediction encoding applies delta compression before ZIP compression, improving compression ratios for continuous-tone images. Supports 8, 16, and 32-bit depths.