Metadata-Version: 2.4
Name: pycineform
Version: 0.1.0
Summary: Educational Python implementation of CineForm wavelet compression - for learning, not performance
Project-URL: Homepage, https://github.com/ChipLukes/pycineform
Project-URL: Repository, https://github.com/ChipLukes/pycineform
Project-URL: Issues, https://github.com/ChipLukes/pycineform/issues
Author: Anthony Lukes
License: MIT License
        
        Copyright (c) 2025-2026 Anthony Lukes
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        ---
        
        ## Third-Party Code
        
        ### GoPro CineForm SDK
        
        The `cineform-sdk/` directory contains the GoPro CineForm SDK source code,
        which is dual-licensed under Apache License 2.0 OR MIT License (at your option).
        
        Copyright 2017 GoPro, Inc.
        
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at
        
            http://www.apache.org/licenses/LICENSE-2.0
        
        Unless required by applicable law or agreed to in writing, software
        distributed under the License is distributed on an "AS IS" BASIS,
        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        See the License for the specific language governing permissions and
        limitations under the License.
        
        Alternatively, you may use the GoPro CineForm SDK under the MIT License.
        See `cineform-sdk/LICENSE.txt` for the full license text.
        
        ### Algorithm Reference
        
        The PyCineForm implementation was developed by studying the GoPro CineForm SDK
        source code to understand the codec algorithms, bitstream format, and quantization
        tables. The SDK served as the authoritative reference for achieving compatibility.
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Classifier: Topic :: Multimedia :: Video :: Conversion
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.9
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pillow>=10.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.4.2; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://github.com/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:**

![Wavelet Pyramid](examples/walkthrough_outputs/step2c_wavelet_pyramid.png)

**Full Encode/Decode Roundtrip with Quality Metrics:**

![Full Roundtrip](examples/walkthrough_outputs/step6_full_roundtrip.png)

## Quick Start

```bash
# 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/](src/pycineform/) | Main Python implementation |
| [notes/](notes/) | Technical documentation and notes |
| [cross_codec/](cross_codec/) | SDK comparison and validation tools |
| [examples/](examples/) | Usage examples and demos |
| [tests/](tests/) | Test suite |
| [cineform-sdk/](cineform-sdk/) | GoPro SDK source (for reference/building DLL) |
| [diagnostics/](diagnostics/) | Visualization and debugging tools |

## Documentation

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

## Basic Usage

```python
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):

```bash
# 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:**
```powershell
cd cineform-sdk/build
.\build_stock.bat
# Creates cineform-sdk/build/Release/CFHDCodec.dll
```

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

**macOS:**
```bash
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](notes/compression_overview.md) - High-level algorithm overview
2. [src/pycineform/core/wavelet.py](src/pycineform/core/wavelet.py) - Wavelet transform implementation
3. [src/pycineform/core/quantization.py](src/pycineform/core/quantization.py) - Quantization tables
4. [src/pycineform/core/vlc_encoder.py](src/pycineform/core/vlc_encoder.py) - Entropy coding
5. [diagnostics/wavelet_diag.py](diagnostics/wavelet_diag.py) - Visualize wavelet behavior

## References

- [GoPro CineForm SDK](https://github.com/gopro/cineform-sdk) - Official implementation (Apache 2.0 / MIT)
- [SMPTE VC-5](https://ieeexplore.ieee.org/document/7438667) - The standard CineForm is based on

## License

This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.

Copyright (c) 2025-2026 Anthony Lukes

The `cineform-sdk/` directory contains the [GoPro CineForm SDK](https://github.com/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.

