docs: rewrite README as spec (drop devlog narrative, focus on what each variant is)

README.md

@@ -15,122 +15,116 @@ tags:
 pipeline_tag: image-segmentation
 ---
 
-# CorridorKey — runtime model variants
+# CorridorKey — model variants
 
-Pre-compiled inference variants of the **CorridorKey** chroma-keying network,
-re-exported from the upstream training checkpoints to the formats the
-[CorridorKey Runtime](https://github.com/alexandremendoncaalvaro/CorridorKey-Runtime)
-loads at runtime (ONNX for TensorRT-RTX EP / DirectML, Torch-TensorRT
-TorchScript engines for the in-process Windows blue path, MLX for Apple
-Silicon, plus the auxiliary tracker fixtures).
+Ready-to-load inference variants of the CorridorKey chroma-keying network
+in the formats common runtimes consume: ONNX (FP16 + INT8), Torch-TensorRT
+TorchScript engines, and MLX safetensors + bridges for Apple Silicon.
+
+License: **CC BY-NC-SA 4.0**.
 
 ## Upstream sources
 
-The training checkpoints (`.pth`, base `.safetensors`) are not duplicated
-here — they live at the canonical locations published by the model author:
+Training checkpoints (`.pth`, base `.safetensors`) are not republished
+here; fetch them from the original repos:
 
-| Variant | Upstream repo |
+| Variant | Upstream |
 |---|---|
-| Green (CorridorKey v1.0) | [`nikopueringer/CorridorKey_v1.0`](https://huggingface.co/nikopueringer/CorridorKey_v1.0) |
-| Blue (CorridorKeyBlue 1.0) | [`nikopueringer/CorridorKeyBlue_1.0`](https://huggingface.co/nikopueringer/CorridorKeyBlue_1.0) |
+| Green | [`nikopueringer/CorridorKey_v1.0`](https://huggingface.co/nikopueringer/CorridorKey_v1.0) |
+| Blue | [`nikopueringer/CorridorKeyBlue_1.0`](https://huggingface.co/nikopueringer/CorridorKeyBlue_1.0) |
 
-License (both upstreams + this repo): **CC BY-NC-SA 4.0**.
+Everything in this repo is derived from those checkpoints.
 
-## What this repo publishes
+## ONNX FP16
 
-Everything below is generated from the upstream checkpoints by the
-CorridorKey Runtime build pipeline. Re-exports are deterministic; if
-upstream re-trains, regenerate the artefacts and bump the runtime
-version that consumes them.
+Static-shape models for ONNX Runtime (TensorRT, DirectML, CUDA, CPU EPs).
 
-### ONNX FP16 — green ladder (Windows / Linux GPU via TensorRT-RTX EP, DirectML)
-
-| File | Resolution | Approx size |
+| File | Resolution | Size |
 |---|---|---|
 | `onnx/fp16/corridorkey_fp16_512.onnx` | 512 × 512 | ~145 MB |
 | `onnx/fp16/corridorkey_fp16_1024.onnx` | 1024 × 1024 | ~156 MB |
 | `onnx/fp16/corridorkey_fp16_1536.onnx` | 1536 × 1536 | ~174 MB |
 | `onnx/fp16/corridorkey_fp16_2048.onnx` | 2048 × 2048 | ~200 MB |
 
-### ONNX FP16 context cache — TensorRT-RTX EP pre-compiled
+## ONNX FP16 context cache
 
-Optional companion artefacts paired by resolution. Shipping these lets
-the runtime skip first-launch TensorRT compile (10–30 s on RTX 4090) and
-go straight to a warm session.
+Companion `_ctx.onnx` files for ONNX Runtime's TensorRT EP. When paired
+with the matching FP16 model, the EP loads a pre-built TensorRT engine
+instead of compiling on first run. Pair by resolution.
 
-| File | Resolution | Approx size |
+| File | Resolution | Size |
 |---|---|---|
 | `onnx/fp16_ctx/corridorkey_fp16_512_ctx.onnx` | 512 × 512 | ~167 MB |
 | `onnx/fp16_ctx/corridorkey_fp16_1024_ctx.onnx` | 1024 × 1024 | ~178 MB |
 | `onnx/fp16_ctx/corridorkey_fp16_1536_ctx.onnx` | 1536 × 1536 | ~197 MB |
 | `onnx/fp16_ctx/corridorkey_fp16_2048_ctx.onnx` | 2048 × 2048 | ~223 MB |
 
-### ONNX INT8 — research / browser experiment only
+## ONNX INT8
 
-Quantised models retained for the browser-based demo. **Not used by the
-production OFX plugin**; the Windows RTX render path uses FP16 + TRT-RTX
-EP exclusively.
+Quantised FP16 → INT8 models. Lower memory footprint, lower precision
+than FP16; useful where GPU memory or model size matters more than
+edge fidelity (browsers, lower-tier hardware).
 
-| File | Resolution | Approx size |
+| File | Resolution | Size |
 |---|---|---|
 | `onnx/int8/corridorkey_int8_512.onnx` | 512 × 512 | ~79 MB |
 | `onnx/int8/corridorkey_int8_768.onnx` | 768 × 768 | ~88 MB |
 | `onnx/int8/corridorkey_int8_1024.onnx` | 1024 × 1024 | ~101 MB |
 
-### Torch-TensorRT — green ladder (Windows blue-pack runtime, in-process)
+## Torch-TensorRT — green
 
 Pre-compiled TorchScript engines (Torch-TensorRT 2.8.0 + TensorRT 10.12,
-CUDA 12.8). Loaded by the runtime via `torch::jit::load` when the
-session is bound to `Backend::TorchTRT` and the curated TorchTRT runtime
-DLLs (libtorch + nvinfer + cuDNN) are resident next to the install.
+CUDA 12.8 toolchain). Loaded via `torch::jit::load`. The runtime
+process must have the matching `torch_tensorrt` runtime DLLs reachable
+to the OS loader.
 
-| File | Resolution | Precision | Approx size |
+| File | Resolution | Precision | Size |
 |---|---|---|---|
 | `torchtrt/fp16/corridorkey_torchtrt_fp16_512.ts` | 512 × 512 | FP16 | ~408 MB |
 | `torchtrt/fp16/corridorkey_torchtrt_fp16_1024.ts` | 1024 × 1024 | FP16 | ~430 MB |
 | `torchtrt/fp16/corridorkey_torchtrt_fp16_1536.ts` | 1536 × 1536 | FP16 | ~502 MB |
 | `torchtrt/fp16/corridorkey_torchtrt_fp16_2048.ts` | 2048 × 2048 | FP16 | ~558 MB |
 
-### Torch-TensorRT — blue ladder (CorridorKeyBlue, dedicated)
+## Torch-TensorRT — blue
+
+Same toolchain as green, dedicated to the CorridorKeyBlue checkpoint.
 
-Sprint 1 added a dedicated path for blue-screen plates so the runtime
-no longer relies on the green-domain canonicalisation workaround. The
-1536 / 2048 rungs use FP32 because Sprint 0 measured FP16 NaNs at those
-graph sizes for the blue checkpoint.
+**Precision split:** FP16 for 512 / 1024, FP32 for 1536 / 2048. The
+blue checkpoint produces NaN activations at higher resolutions when
+compiled at FP16; FP32 above 1024 is the workaround until the
+checkpoint is retrained.
 
-| File | Resolution | Precision | Approx size |
+| File | Resolution | Precision | Size |
 |---|---|---|---|
-| `torchtrt/fp16-blue/corridorkey_blue_torchtrt_fp16_512.ts` | 512 × 512 | FP16 | _pending compile_ |
+| `torchtrt/fp16-blue/corridorkey_blue_torchtrt_fp16_512.ts` | 512 × 512 | FP16 | _not yet published_ |
 | `torchtrt/fp16-blue/corridorkey_blue_torchtrt_fp16_1024.ts` | 1024 × 1024 | FP16 | ~258 MB |
 | `torchtrt/fp32-blue/corridorkey_blue_torchtrt_fp32_1536.ts` | 1536 × 1536 | FP32 | ~488 MB |
-| `torchtrt/fp32-blue/corridorkey_blue_torchtrt_fp32_2048.ts` | 2048 × 2048 | FP32 | _pending compile_ |
+| `torchtrt/fp32-blue/corridorkey_blue_torchtrt_fp32_2048.ts` | 2048 × 2048 | FP32 | _not yet published_ |
 
-### MLX — Apple Silicon
+## MLX — Apple Silicon
 
-Native Apple Silicon weights and per-resolution pre-compiled bridges,
-loaded by the runtime when `Backend::MLX` is selected on macOS.
+Safetensors weights for the MLX framework plus per-resolution
+pre-compiled bridges. The `.safetensors` here is re-exported for the
+MLX layout and differs byte-wise from the upstream
+`CorridorKey_v1.0.safetensors`; use it together with the bridges below.
 
-| File | Description | Approx size |
+| File | Description | Size |
 |---|---|---|
-| `mlx/corridorkey_mlx.safetensors` | Re-exported base weights for MLX layout | ~399 MB |
+| `mlx/corridorkey_mlx.safetensors` | Re-exported base weights | ~399 MB |
 | `mlx/corridorkey_mlx_bridge_512.mlxfn` | 512 × 512 bridge | ~289 MB |
 | `mlx/corridorkey_mlx_bridge_768.mlxfn` | 768 × 768 bridge | ~298 MB |
 | `mlx/corridorkey_mlx_bridge_1024.mlxfn` | 1024 × 1024 bridge | ~311 MB |
 | `mlx/corridorkey_mlx_bridge_1536.mlxfn` | 1536 × 1536 bridge | ~348 MB |
 | `mlx/corridorkey_mlx_bridge_2048.mlxfn` | 2048 × 2048 bridge | ~399 MB |
 
-The `.safetensors` here is **re-exported** for the MLX framework's
-expected layout — it differs byte-wise from the upstream
-`nikopueringer/CorridorKey_v1.0.safetensors` and is required by the MLX
-bridges below it.
+## Hint trackers
 
-### Hint trackers — auxiliary fixtures
+Auxiliary models used by alpha-hint generation pipelines (interactive
+matte refinement, segment-then-track flows). Exported from
+[MobileSAM](https://github.com/ChaoningZhang/MobileSAM) and
+[Cutie](https://github.com/hkchengrex/Cutie) under their own licences.
 
-Tracker models the runtime calls during alpha-hint generation. Exported
-from the upstream MobileSAM and Cutie projects under their own licences
-(see model cards on Hugging Face).
-
-| File | Approx size |
+| File | Size |
 |---|---|
 | `hint/mobilesam_image_encoder_fp16.onnx` | ~14 MB |
 | `hint/mobilesam_prompt_decoder_fp16.onnx` | ~8 MB |
@@ -138,52 +132,25 @@ from the upstream MobileSAM and Cutie projects under their own licences
 | `hint/cutie_init_memory_fp16.onnx` | ~1 MB |
 | `hint/cutie_tracking_memory_fp16.onnx` | ~1 MB |
 
-### Releases
-
-Standalone CorridorKey Runtime installer artefacts (Windows OFX plugin
-bundle for DaVinci Resolve / Foundry Nuke). Each subdirectory under
-`releases/` is a single tagged build of the
-[CorridorKey-Runtime repo](https://github.com/alexandremendoncaalvaro/CorridorKey-Runtime).
-
-## What this repo deliberately does NOT publish
+## Releases
 
-- **Training checkpoints (`.pth`, base `.safetensors`)** — fetch directly
-  from the `nikopueringer/*` upstream repos linked above. Removing these
-  duplicates avoids drift if the author republishes a checkpoint.
-- **Curated runtime DLL bundles** (libtorch / nvinfer / cuDNN for the
-  Windows blue pack) — those ship inside the OFX installer artefact,
-  not as a model file.
+`releases/v*/` contains tagged builds of the
+[CorridorKey Runtime](https://github.com/alexandremendoncaalvaro/CorridorKey-Runtime)
+OFX plugin and CLI for Windows, packaged with the model subset each
+build expects.
 
 ## Usage
 
 ```bash
-# Single artefact
+# Single file
 hf download alexandrealvaro/CorridorKey onnx/fp16/corridorkey_fp16_1024.onnx
 
-# All ONNX FP16 green
+# All ONNX FP16
 hf download alexandrealvaro/CorridorKey --include "onnx/fp16/*.onnx"
 
-# All Torch-TRT (green + blue)
+# All Torch-TensorRT (green + blue)
 hf download alexandrealvaro/CorridorKey --include "torchtrt/**/*.ts"
 
 # Direct HTTP
-# https://huggingface.co/alexandrealvaro/CorridorKey/resolve/main/onnx/fp16/corridorkey_fp16_1024.onnx
+# https://huggingface.co/alexandrealvaro/CorridorKey/resolve/main/<path>
 ```
-
-The CorridorKey Runtime ships a wrapper that pulls the right subset for
-each platform: `scripts/fetch_models.ps1 -Profile windows-rtx`,
-`-Profile windows-rtx-blue`, `-Profile apple`, etc.
-
-## Runtime
-
-Models above are consumed by
-[CorridorKey Runtime](https://github.com/alexandremendoncaalvaro/CorridorKey-Runtime),
-shipped as:
-
-- OFX plugin for DaVinci Resolve and Foundry Nuke (Windows RTX, macOS Apple Silicon)
-- CLI for offline batch processing
-- Browser demo (uses the INT8 ONNX rung above)
-
-## License
-
-CC BY-NC-SA 4.0 (matches upstream).