---
library_name: pytorch
pipeline_tag: image-to-image
license: apache-2.0
tags:
  - image-to-image
  - color-grading
  - 3d-lut
  - computer-vision
  - pytorch
---

# Nolanizer V1

Nolanizer V1 is a scene-adaptive image-to-image model for cinematic global
color grading. It preserves the input composition and predicts a color
transformation designed to produce a restrained, large-format cinematic look
associated with Christopher Nolan-inspired visual language.

The model analyzes each image, predicts a mixture of eight learned `33³` 3D LUT
bases, and applies bounded exposure, contrast, saturation, temperature, and tint
adjustments. A single intensity control blends continuously between the
original image and the full grade.

> Nolanizer is an independent research project. It is not affiliated with,
> endorsed by, or an official product of Christopher Nolan, any
> cinematographer, colorist, or film studio. The output is an algorithmic
> interpretation of a cinematic visual style, not a claim about how a specific
> person would grade an image.

## Model details

| Property | Value |
| --- | --- |
| Task | Scene-adaptive global image color grading |
| Framework | PyTorch |
| Architecture | CNN condition encoder with a learnable 3D LUT mixture |
| LUT basis | 8 learned LUTs, each `33 × 33 × 33` |
| Global controls | Exposure, contrast, saturation, temperature, and tint |
| Effect range | `0.0` to `1.0` |
| Recommended weights | EMA |
| Release checkpoint | Epoch 7 |

The transformation is global: every output pixel is produced from its input
color and the scene-conditioned grade. Spatial structure, objects, and
composition are therefore left unchanged.

## Files

| File | Purpose |
| --- | --- |
| `nolanizer_v1.pt` | Frozen epoch-7 checkpoint; use EMA weights |
| `config.json` | Architecture and inference contract |
| `training_config.yaml` | Resolved optimization configuration |
| `checkpoint_manifest.json` | Checkpoint checksum and release metrics |
| `requirements.txt` | Runtime Python dependencies |


## Usage

The checkpoint requires the Nolanizer Python package or a Nolanizer source
checkout. Install the project, then run:

```bash
python -m pip install -e .

python -m nolanizer.inference \
  --checkpoint huggingface/nolanizer-v1/nolanizer_v1.pt \
  --input path/to/input.jpg \
  --output path/to/output.jpg \
  --intensity 0.8 \
  --weights ema
```

Supported inputs include standard RGB images such as JPEG, PNG, and WebP.

### Intensity

- `0.0`: exact identity output
- `0.6–0.9`: recommended range for most images
- `1.0`: full predicted grade

The inference command saves the graded image and can also expose the predicted
LUT mixture and global adjustment parameters for inspection.

## Evaluation

The release checkpoint passed the project's frozen color, content-preservation,
clipping, LUT-basis health, and exact-identity gates.

| Metric | Value |
| --- | ---: |
| CIEDE2000 | `5.7666` |
| Lab MAE | `3.6339` |
| Luminance SSIM | `0.8617` |
| Edge correlation | `0.9837` |
| Clipped-pixel ratio | `0.0017` |

These are internal release metrics rather than a perceptual preference score.
They should not be interpreted as a guarantee of equivalent performance on
every image domain.

## Intended use

- Interactive grading of photographs and still images
- Research and education in global cinematic color grading
- Analysis of scene-conditioned LUT mixtures
- Non-destructive look exploration through the intensity control

## Limitations

- The renderer applies global color and tone transformations only; it does not
  perform local masking or selective relighting.
- It cannot change geometry, composition, production design, lens
  characteristics, film grain, bloom, or halation.
- Extremely clipped highlights, near-black images, unusual color spaces, and
  heavily compressed inputs may produce unstable or subtle results.
- Skin-tone behavior has not been assessed with a dedicated demographic
  benchmark.
- Output quality is subjective and depends on exposure, white balance, scene
  content, and the selected intensity.

## Responsible use

Use the model only with images you have the right to process. Do not present
generated results as an official Christopher Nolan look, endorsement, or
creative decision. Keep the original image when provenance or faithful color
reproduction matters.