Color interop IDs, demonstrated

A small, self-contained proof of concept — the illustrated guide, the deck, and a notebook for every part of the design

A color interop ID is a short, standardized string — lin_ap1_scene, srgb_rec709_display — published by the ASWF Color Interop Forum, that names a color space by what it is rather than by what some config happens to call it. Files carry it (OpenEXR has the colorInteropID attribute); configs answer to it (as an alias, or on OpenColorIO 2.5+ as a declared interop_id).

Two rules make it robust: IDs may be namespaced (vendor: prefixes, with a defined fallback that strips the leftmost namespace), and an ID that can’t be honored resolves to nothing rather than to a guess.

How config authors command behavior: one line — the aces_interchange role — anchors every space in a config for exact conversion and identification. Aliases matching the published IDs opt spaces into name-tier resolution on every OpenColorIO version. On 2.5+, a declared interop_id: wins outright.

The real thing lives in OpenImageIO: the combined working branch behind the upcoming PR series is up as draft PR #5392 — everything demonstrated here, running end to end against the full CI matrix.

ELI5 — what do we get out of this?

Every picture gets a name tag for its colors that every program reads the same way. Today, programs guess — and when they guess wrong, pictures come out washed out, too dark, or double-corrected, and nobody knows which program broke them. After this: read the tag if it’s there, figure it out from evidence if it isn’t (colors can be recognized by how they behave, so even ten-year-old projects get correct tags), never invent an answer that can’t be backed up, and write the tag so the next program doesn’t have to guess either. Old files work. Old configs work. New pipelines stop breaking at tool boundaries.

Start anywhere

The illustrated guide	How every part works together — the highway model, the anatomy of the system, each part in its own chapter, and the compatibility posture. Start here.
The deck	The accompanying presentation (reveal.js — arrow keys advance, `f` for full screen).
The notebooks	Interactive marimo notebooks — a master presentation, one notebook per part of the design, and the standalone demo. Most run straight from GitHub with nothing cloned.
Resolution as a service	The same resolver behind three HTTP endpoints, in a single file.

Try it without downloading anything

The demo notebook runs straight from GitHub, no clone required — it fetches its sibling helper module itself on first run:

uvx marimo run --sandbox https://raw.githubusercontent.com/zachlewis/color_interop_demo/main/color_interop_demo.py

From a checkout, every notebook is a PEP 723 script — dependencies are declared inline, so there is nothing to install first:

uvx marimo run  --sandbox color_interop_demo.py   # present (app view)
uvx marimo edit --sandbox color_interop_demo.py   # author/edit

The helper runs its own assert-based self-check standalone:

uv run --with opencolorio python color_interop_helper.py
# PyOpenColorIO 2.5.2
# self-check OK

All dependencies ship binary wheels — no compilation. Requirements: Python ≥ 3.10 and PyOpenColorIO ≥ 2.2. The helper feature-detects native OpenColorIO functions (getInteropID is 2.5+, IdentifyBuiltinColorSpace is 2.3+) and backfills the recommendation’s semantics in pure Python where the linked version doesn’t provide them.

What’s in the repository

`color_interop_helper.py`	A single-file, plain-function reference implementation of the recommendation’s application-side function set, on PyOpenColorIO alone. Assert-based self-check included.
`color_interop_oiio.py`	A pure-Python model of the color behavior proposed for OpenImageIO — `ImageSpec`, `ColorConfig`, read reconciliation, write planning, the metadata harness. Its functions also accept a real `OpenImageIO.ImageSpec` directly (duck-typed), so real file metadata feeds straight in.
`color_interop_demo.py`	The interactive notebook driving the helper live.
`notebooks/`	The full set — see the notebook index.
`tools/serve.py`	Resolution as a service.

The recommendation

Everything here implements (or demonstrates) the ASWF Color Interop Forum recommendation “An ID for Color Interop”:

https://github.com/AcademySoftwareFoundation/ColorInterop/blob/main/Recommendations/03_ColorInteropID/ColorInteropID.md

Where this proof of concept simplifies the recommendation, the module docstring in color_interop_helper.py says so explicitly.

This repository accompanies a proposed contribution series to OpenImageIO. It is a proof of concept and a presentation aid — not a released library, and not an official Forum or OpenImageIO artifact.

Drafted with AI assistance; authored, reviewed, and posted by Zach Lewis.