README.md

---
license: cc-by-nc-sa-4.0
library_name: onnxruntime
tags:
  - onnx
  - torch-tensorrt
  - mlx
  - image-segmentation
  - matting
  - keying
  - vfx
  - green-screen
  - blue-screen
  - corridorkey
pipeline_tag: image-segmentation
---

# CorridorKey — model variants

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

Training checkpoints (`.pth`, base `.safetensors`) are not republished
here; fetch them from the original repos:

| Variant | Upstream |
|---|---|
| Green | [`nikopueringer/CorridorKey_v1.0`](https://huggingface.co/nikopueringer/CorridorKey_v1.0) |
| Blue | [`nikopueringer/CorridorKeyBlue_1.0`](https://huggingface.co/nikopueringer/CorridorKeyBlue_1.0) |

Everything in this repo is derived from those checkpoints.

## ONNX FP16

Static-shape models for ONNX Runtime (TensorRT, DirectML, CUDA, CPU EPs).

| 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

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 | 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

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 | 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

Pre-compiled TorchScript engines (Torch-TensorRT 2.8.0 + TensorRT 10.12,
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 | 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

Same toolchain as green, dedicated to the CorridorKeyBlue 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 | Size |
|---|---|---|---|
| `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 | _not yet published_ |

## MLX — Apple Silicon

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 | Size |
|---|---|---|
| `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 |

## Hint trackers

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.

| File | Size |
|---|---|
| `hint/mobilesam_image_encoder_fp16.onnx` | ~14 MB |
| `hint/mobilesam_prompt_decoder_fp16.onnx` | ~8 MB |
| `hint/cutie_feature_extractor_fp16.onnx` | ~18 MB |
| `hint/cutie_init_memory_fp16.onnx` | ~1 MB |
| `hint/cutie_tracking_memory_fp16.onnx` | ~1 MB |

## Releases

`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 file
hf download alexandrealvaro/CorridorKey onnx/fp16/corridorkey_fp16_1024.onnx

# All ONNX FP16
hf download alexandrealvaro/CorridorKey --include "onnx/fp16/*.onnx"

# All Torch-TensorRT (green + blue)
hf download alexandrealvaro/CorridorKey --include "torchtrt/**/*.ts"

# Direct HTTP
# https://huggingface.co/alexandrealvaro/CorridorKey/resolve/main/<path>
```