pycineform 0.1.0

Educational Python implementation of CineForm wavelet compression - for learning, not performance

PyCineForm

A pure Python implementation of the CineForm/VC-5 wavelet codec, built for learning and understanding.

⚠️ Important: This is an educational project. For production use, please use the GoPro CineForm SDK which is optimized for performance.

Purpose

This project exists to help understand how CineForm compression works by implementing it from scratch in Python. It prioritizes clarity and readability over performance - the goal is well-documented code that can be stepped through, visualized, and experimented with.

Why Python?

• Easy-to-follow code with clear algorithm implementations
• Excellent debugging and visualization tools
• NumPy for clean array operations without hiding the math
• No low-level optimizations obscuring the algorithms

What this is NOT:

• A high-performance encoder/decoder
• A drop-in replacement for the CineForm SDK
• Optimized for real-time video processing

Cross-codec testing was used to verify that this Python implementation matches the CineForm SDK output (at least to the extent of the testing done so far).

What's Implemented

• 2-6 Integer Wavelet Transform - SDK-compatible forward/inverse transforms
• Multi-level Decomposition - 3-level wavelet pyramid
• Quantization - SDK-compatible subband quantization tables
• VLC Encoding - Variable-length coding with SDK codebooks
• SDK Bitstream Format - Produces bitstreams the SDK can decode
• Color Support - RGB 4:4:4, YUV 4:2:2, grayscale (uses one of the RGB channels)
• Cross-codec Validation - Compare PyCineForm against the real SDK

Visualizations

The educational walkthrough (examples/encoder_decoder_walkthrough.py) generates visualizations to help understand the compression pipeline:

3-Level Wavelet Pyramid Decomposition:

Full Encode/Decode Roundtrip with Quality Metrics:

Quick Start

# Install dependencies and project
uv sync

# Run tests
uv run pytest

# Try the educational walkthrough (recommended!)
uv run python examples/encoder_decoder_walkthrough.py

# Or basic encode/decode demo
uv run python examples/basic_usage.py

NOTE: Some tests/examples rely on the SDK DLL being built. See below for instructions.

Project Structure

Folder	Purpose
src/pycineform/	Main Python implementation
notes/	Technical documentation and notes
cross_codec/	SDK comparison and validation tools
examples/	Usage examples and demos
tests/	Test suite
cineform-sdk/	GoPro SDK source (for reference/building DLL)
diagnostics/	Visualization and debugging tools

Documentation

Document	Description
notes/compression_overview.md	How CineForm compression works
notes/bitstream.md	Bitstream format documentation
notes/python_overview.md	Python codebase structure
notes/sdk_overview.md	SDK architecture notes
cross_codec/README.md	SDK validation tools
examples/README.md	Example scripts

Basic Usage

from pycineform import encode_color, decode_color, SDKQuality
import numpy as np

# Create or load an RGB image (H, W, 3), uint8
image = np.random.randint(0, 256, (256, 256, 3), dtype=np.uint8)

# Encode
result = encode_color(image, quality=SDKQuality.FILMSCAN1)
print(f"Compressed to {len(result.bitstream)} bytes ({result.compression_ratio:.1f}:1)")

# Decode
decoded = decode_color(result.bitstream, output_bit_depth=8)

SDK Validation

The cross-codec tests verify PyCineForm produces bitstreams the SDK can decode (and vice versa):

# Run cross-codec validation
uv run pytest tests/test_sdk_reference.py -v -k "cross_codec"

Building the CineForm SDK Library

The cross-codec validation requires the CineForm SDK shared library.

Windows:

cd cineform-sdk/build
.\build_stock.bat
# Creates cineform-sdk/build/Release/CFHDCodec.dll

Linux:

cd cineform-sdk && mkdir -p build && cd build
cmake .. && make -j$(nproc)
# Creates cineform-sdk/build/libCFHDCodec.so

macOS:

cd cineform-sdk && mkdir -p build && cd build
cmake .. && make -j$(sysctl -n hw.ncpu)
# Creates cineform-sdk/build/libCFHDCodec.dylib

Current status:

• ✅ PyCineForm encode → SDK decode (8, 10, 12-bit RGB and Bayer RAW)
• ✅ SDK encode → PyCineForm decode (8-bit RGB)
• 🔄 Higher bit-depth decoder support in progress
• ⚠️ Image dimensions must be multiples of 16 (use crop_to_multiple() or pad_to_multiple() from pycineform.utils)

Learning Resources

To understand the compression pipeline, start with:

1. notes/compression_overview.md - High-level algorithm overview
2. src/pycineform/core/wavelet.py - Wavelet transform implementation
3. src/pycineform/core/quantization.py - Quantization tables
4. src/pycineform/core/vlc_encoder.py - Entropy coding
5. diagnostics/wavelet_diag.py - Visualize wavelet behavior

References

• GoPro CineForm SDK - Official implementation (Apache 2.0 / MIT)
• SMPTE VC-5 - The standard CineForm is based on

License

This project is licensed under the MIT License - see LICENSE for details.

Copyright (c) 2025-2026 Anthony Lukes

The cineform-sdk/ directory contains the GoPro CineForm SDK, which is separately licensed under Apache 2.0 OR MIT (at your option). See cineform-sdk/LICENSE.txt.

Acknowledgments

This project would not be possible without the GoPro team's decision to open-source the CineForm SDK. The SDK source code served as the authoritative reference for understanding the codec's algorithms, bitstream format, and quantization tables.