The illustrated guide

How the parts work together

This guide walks the whole design demonstrated by this repository: how a color interop ID travels through read, resolution, identification, conversion, and write — and how the pieces feed each other. Everything described here runs live in the numbered marimo notebooks, in pure Python against PyOpenColorIO, modeling the behavior proposed for OpenImageIO.

The chapters

1. The highway model	The metaphor that makes the two-lane design intuitive: lanes, on-ramps, a merge rule, and lane discipline.
2. Color interop IDs in 60 seconds	What an ID is, the two rules that make it robust, and the ELI5.
3. Anatomy of the system	One picture of who feeds whom — the surface pipeline and the engine behind it.
4. The parts, one by one
4.1 The ID grammar	What an ID is as a string: base IDs, namespaces, the config-local form, utility tokens.
4.2 The registry and the cache	The built-in interop identities, and the content-addressed memoization contract everything rides on.
4.3 Read-side reconciliation	One centrally defined priority list adjudicating contradictory file signals.
4.4 Transform-comparison identification	Recognizing a space by what its transforms actually do.
4.5 The write side and derived IDs	Write, derive, omit, or suppress — every outgoing attribute decided, with a reason.
4.6 Cross-config conversion	The ID’s core promise: the name works even if your config never heard of it.
4.7 The metadata harness	Keeping what the metadata says in step with what the pixels mean.
4.8 The inspection machinery	The same engine made queryable — internal, surfaced through experimental `oiiotool` diagnostics.
5. Compatibility	Delegation and backfill, stability guarantees, and why config adoption is optional.
6. What belongs where	The generous, non-territorial map of which project naturally owns what.

Reading it as a book

Every chapter has previous/next links at the foot of the page, so the guide reads front to back — or jump straight to a part from the sidebar.