ColorMatch_LUTGen

A Python toolbox for color space conversion, 3D LUT generation, and LUT-based color matching / training. It supports GPU acceleration (CuPy) with a CPU fallback (NumPy), and provides a lightweight operator-based pipeline that lets you chain decode / matrix / tone mapping / roll-off operators.

Note: this repo contains both (1) “generate a LUT from JSON color space definitions” utilities and (2) “fit/optimize a LUT from paired images” training code. Which path you use depends on the entry script you run.

Features

• Generate 3D LUTs (.cube) from JSON color space descriptions
• Color conversion + operator pipeline (decode/encode, matrices, white adaptation, roll-off, tone mapping, etc.)
• LUT training/optimization from paired images (example entry script included)
• Simple GUI (PyQt5 / PyOpenGL)

Installation

Python 3.10+ is recommended.

1) Install dependencies

pip install -r requirements.txt

2) CuPy (optional, GPU acceleration)

requirements.txt includes cupy>=12.0.0. If you don’t have CUDA properly installed, CuPy installation may fail or the package may be unusable.

• CPU-only workflow: comment out/remove cupy, or install a CuPy build that matches your CUDA environment.
• GPU workflow: make sure your CUDA driver/toolkit matches the selected CuPy version.

Quickstart

1) Training entry (LUT fitting/optimization)

The repo provides a training entry script: run_train.py.

python run_train.py

Most training knobs live in config.py. You can visualize the latest loss curve with plot_latest_loss.py.

2) LUT generation / validation demos

There are multiple demos you can use as references for “how to build a pipeline” and “how to export a .cube”:

• demo_aces_ap1_to_709.py: generate an ACES AP1 (ACEScg linear) → Rec.709 LUT
• demo_slog3_to_709_minimal.py / demo_slog3_to_709_midgray_rgb_rolloff.py: S-Log3 → 709 variants
• gen_logc3_to_709_simple.py: a simplified LogC3 → 709 LUT generator

Generate a 3D LUT from JSON (ColorSpaceUtils)

ColorSpaceUtils/ provides a JSON-driven LUT generation workflow:

• ColorSpaceUtils/Bin/: color space JSON definitions
• ColorSpaceUtils/CSTLUTGen.py: LUT generation core (create identity grid + run a pipeline)

Example: generate a LUT (CLI)

python -m ColorSpaceUtils.CSTLUTGen --src ColorSpaceUtils/Bin/bt709_display.json --dst ColorSpaceUtils/Bin/slog3sgmt3c_camera.json --precision 33 --output Rec709_to_SLog3.cube

Mid-gray alignment (if enabled)

If both JSON files include a mid_gray field, the converter may apply an automatic scaling to align mid-gray luminance (e.g. 18% reflectance). To disable it, there is typically an option like auto_mid_gray_align=False (see the code for the exact API).

GUI

GUI entry script: gui_main.py (requires PyQt5, PyOpenGL, pyqtgraph).

python gui_main.py

If OpenGL is not available (driver issues / remote desktop), validate the workflow using the scripts first.

Repo layout (common folders)

• run_train.py: training entry
• config.py: training/experiment config
• requirements.txt: dependencies
• plot_latest_loss.py: plot the latest loss curve
• ImgObj/: image objects, I/O, dataset containers (e.g. image.py, pictpool.py)
• LUTObj/: LUT data structures and processing
• LossObj/: loss functions and related logic
• ColorSpaceUtils/: color space definitions, pipelines, and LUT generation
• CSTLutGen_Demo/: small LUT-generation demos
• checkpoint/: training checkpoint images

ACES AP1 → Rec.709 demo

The ACES AP1 → Rec.709 workflow is documented in ACES_AP1_TO_709_README.md. The corresponding script is demo_aces_ap1_to_709.py, and an example output LUT is aces_ap1_to_709.cube.

Notes / safety

• Transfer expressions in JSON are evaluated in a “restricted expression” style implementation. Don’t run untrusted JSON definitions.
• When building pipelines, keep units consistent (encoded vs linear vs absolute nits).

Trademarks

All trademarks and product names mentioned in this repository are the property of their respective owners.

License

Unless otherwise noted, the contents of this repository are licensed under Creative Commons Attribution-NonCommercial 3.0 China (CC BY-NC 3.0 CN).

• You may share and adapt the material for non-commercial purposes, as long as you provide appropriate attribution.
• For commercial licensing, please contact the author.

See LICENSE for the full license text.

Third-party dependencies and assets (including but not limited to Python packages, sample images, and datasets) remain under their respective licenses/terms.