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[source]

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[source]

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[source]

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

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[source]

psd_tools.compression.decode_prediction(data: bytes, w: int, h: int, depth: int) → bytes[source]

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