DEPLOYMENT.md

# Colorizer deployment

Use the release's inference wrapper or its ONNX graph to obtain the complete
improvement. The `.safetensors` file contains the learned colorizer; guided
decoding is implemented by `spatial.py` and is included in the ONNX graph.

## Python / PyTorch

Run from the extracted release directory:

```bash
python -m pip install -r requirements.txt
python inference.py --model . --output-dir colorized photo.jpg
```

The default guided radius is 8 at the model's input resolution. Use
`--guided-radius 0` for raw predictions or `--guided-radius 16` for stronger
smoothing. Stronger smoothing can remove legitimate small color details.
`--flip-tta --guided-radius 4` is an optional two-pass mode. The released
ONNX graph is the single-pass radius-8 mode.

```python
from PIL import Image
from model import load_model
from inference import colorize

model = load_model('.')
result = colorize(model, Image.open('photo.jpg'))
result.save('colorized.png')
```

The wrapper handles EXIF orientation, preserves aspect ratio, bounds the
longest network-input side to 256 pixels, upsamples chroma to the original
oriented image dimensions and combines it with the original Lab luminance.
Final RGB conversion can clip colors outside the display gamut. Very large
inputs still require memory for full-resolution color conversion. There is
no video temporal-consistency guarantee.

## ONNX without PyTorch

```bash
python -m pip install -r requirements-onnx.txt
python colorize_onnx.py --model colorizer.onnx --output-dir colorized photo.jpg
```

Input name: `luminance`, float32, shape `N x 1 x H x W`, values `L*/50 - 1`.
Output name: `chroma`, float32, shape `N x 2 x H x W`, Lab a and b values.
Height and width must each be at least 8. Dynamic shapes and batches are
supported. Prefer a longest input side of 256 to match the evaluated
operating point. Ordinary RGB values are not valid graph inputs.

The graph includes temperature-0.38 decoding and radius-8 guided filtering
with epsilon 0.001. It does not include file loading, EXIF handling, Lab
conversion, aspect-ratio resizing or final chroma upsampling; these are
implemented in `colorize_onnx.py`. The ONNX wrapper uses Pillow resizing,
whereas the PyTorch wrapper uses PyTorch interpolation. Their image-level
comparison is recorded in the release checks.

## Publish to main

Authenticate normally on your own computer with repository write access:

```bash
hf auth login
python upload_main.py --folder . --repo User-2468/mini-unet-colorizer
```

This performs one upload to `main` with an optimistic-concurrency guard.
It also verifies that `stable` retains its pre-upload revision. The app can
keep using `stable` until you choose to switch it to the tested release.
The current chat connection has Jobs/read access but no repository write
scope; the downloadable release is the publication fallback.

## Deployment limits

This is a measured app-testing candidate. Semantic color mistakes remain,
and smoothing cannot infer an object's unknown original color. Review the
included failure examples on your app's real input photos before describing
it as generally production-ready. Browser/mobile performance and real-time
video have not been validated.