impossible-lut

Open-source LUT generation toolkit from Impossible Labs.

Generate film-look LUTs from text descriptions or classic film stock presets. The project combines a high-performance C++ LUT engine, a deterministic Python recipe generator, and a TypeScript orchestration layer for demos and tooling.

Highlights

• Cross-language architecture: C++ + Python + TypeScript
• Deterministic "AI-assisted" text-to-look mapping (no external APIs)
• Native-quality interpolation: trilinear and tetrahedral
• Film stock preset library (10 stocks)
• End-to-end demo and benchmark tooling

Quick Start

npm install
npm run build
npm run demo

Generate a stock LUT directly:

python3 python/generate_lut.py --stock "Kodak Portra 400" --size 33 --output luts/portra400.cube

Generate from description:

python3 python/generate_lut.py --stock custom --description "warm sunset, faded shadows, teal highlights" --size 33 --output luts/custom.cube

List presets:

python3 python/generate_lut.py --list

Architecture

Python recipes/text parser -> .cube LUT -> C++ native LUT core -> N-API addon -> TypeScript engine/demo

• C++ core (native/lut_engine):
  • .cube parse/write
  • LUT transforms (curves, hue/sat, contrast, LGG)
  • Interpolation (trilinear + tetrahedral)
  • Image test buffer + PPM output
• Python (python/):
  • Film stock recipe library
  • Deterministic description keyword rule engine
  • LUT generation CLI + optional visualizer
• TypeScript (packages/):
  • Native addon wrapper
  • Preset/description orchestration
  • Demo + benchmark scripts

More detail: docs/ARCHITECTURE.md.

.cube Format Support

The parser supports:

• TITLE
• DOMAIN_MIN
• DOMAIN_MAX
• LUT_3D_SIZE
• RGB data rows

Parser implementation: native/lut_engine/src/lut/cube.cpp.

Film Stock Gallery

Available presets (python/film_stocks.py):

• Kodak Portra 400
• Kodak Ektar 100
• Fuji Pro 400H
• Fuji Velvia 50
• Kodak Tri-X 400
• Ilford HP5 Plus
• CineStill 800T
• Kodak Vision3 500T
• Agfa Vista 200
• Lomography Color Negative 400

Demo

Run:

npm run demo

Outputs:

• output/demo/*.cube
• output/demo/*_trilinear.ppm
• output/demo/*_tetrahedral.ppm

Benchmark

Run:

npm run bench

Sample output shape:

LUT size 33 loaded (Kodak Portra 400)
image 256x256 -> trilinear 5.12 ms | tetrahedral 7.08 ms
image 512x512 -> trilinear 20.44 ms | tetrahedral 28.76 ms
image 1024x1024 -> trilinear 81.32 ms | tetrahedral 116.41 ms

Testing

npm test

• C++ tests: tests/cpp/test_main.cpp
• Python tests: tests/python/test_stocks.py
• TypeScript tests: tests/ts/lut.test.ts

Repository Layout

native/lut_engine/    # C++ LUT core + N-API addon
python/               # stock recipes, generator, visualizer
packages/lut_ts/      # TypeScript wrapper API
packages/demo/        # demo + benchmark scripts
tests/                # cpp/py/ts tests
docs/                 # architecture + film science notes
luts/                 # pre-generated LUTs

License

MIT (LICENSE)