Skip to content

Add the color interop ID recommendation #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
doug-walker wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add the color interop ID recommendation #11

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 150 additions & 0 deletions Recommendations/03_ColorInteropID/ColorInteropID.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
# An ID for Color Interop

**ASWF Color Interop Forum Recommendation**

*2026-01-26 v1.0.0*


### Introduction

During its lifecycle, a professionally produced image may travel through dozens of software tools, graphics APIs, and file formats, each with their own method for identifying color spaces. One of the goals of the Color Interop Forum is to help people translate between these different tagging methods by providing reference materials that may serve as a kind of "Rosetta Stone". In some cases, the tagging methods are hard-coded (e.g., a set of enumerated types in a graphics API), but in other cases a text string is used. This document provides guidance for how to set a color space name string for good interoperability, the result is called a ***color interop ID***.


### Color Space Name Strings

Unfortunately, it has been difficult to get the industry to coalesce around standard names for color spaces. The ACES project made the most concerted attempt at trying to make this happen but, despite their best efforts, even standard ACES color spaces are often referred to by a variety of different names (e.g., "ACES2065-1" vs. "lin\_ap0"). Often, VFX/animation studios or applications have long-standing practices concerning how to name color spaces and it is very difficult to make changes.

Part of the success of OpenColorIO is that it allows studios to name color spaces according to their own conventions and provides a configuration format to facilitate getting those names to show up in application software menus for artists. However, an OCIO color space name only has meaning within the self-contained universe of the configuration file in which it is defined and may be unrecognized by another config file.

The Color Interop Forum has worked on developing a set of standardized names for common color spaces, but the challenges of reaching consensus required having two recommended strings:

1. A recommended user-facing name. This is what should be used in end-user menus, but it is only a recommendation, with the understanding that studios or applications may need to customize it to meet their own conventions.
2. An "interop" ID string which is mandatory but not user-facing (i.e., it should only be used inside file formats and should never show up in end-user application menus). This is intended to be a fixed, permanent name.

In order to keep the string compact, and because the user-facing name is just a recommendation that may be overridden, only the interop ID is designed to be stored in file formats.

However, the Color Interop Forum only develops recommendations for the most common color spaces and there is a need to be able to generate a name string for any possible color space. To avoid the problem of different groups trying to use the same string for different color spaces, the proposal is that a "namespace" be used along with the color space name. That way, people may generate IDs for unique color spaces with minimal risk of colliding with IDs generated by others.

Rather than requiring two separate attributes in various file formats, the namespace and color space name are combined into one string.


### The Color Interop ID

Therefore, the color interop ID is structured as a namespace string and a color space string, separated by a colon:
`<NAMESPACE>:<COLOR SPACE>`

For example:
`my-vfx-studio:custom_cinema_camera_a123`

If the color space string is one of the Color Interop Forum IDs, the namespace and colon are not used. For example: `lin_rec709_scene`. This reduces the length of the ID for the common color spaces that represent the vast majority of use-cases. For other color spaces, the namespace is mandatory.

For maximum portability and robustness, the following restrictions are placed on the Interop ID:

1. It may only use lower-case ASCII characters: 0-9, a-z, and the following characters (no spaces):
`. - _ ~ / * # % ^ + ( ) [ ] |`
2. The colon may only be used as the separator (not in the namespace or color space).
3. If the color space is not on a Color Interop Forum list, the namespace must be present.

#### Uniqueness of the Interop ID

A color interop ID is intended to be an unambiguous identifier that may be used to match up color spaces that are functionally equivalent. It is not a "unique ID" in the sense that it is not intended to be unique to a specific color space implementation, for example, in a specific OCIO config. If color spaces in two configs share an interop ID, it does not imply that a hash function such as a config or processor ID of the two would also be identical. In the case of OCIO color spaces, for example, the bit-depth or other attributes may differ, a different reference space may be used, one may use an analytic log or exponent transform and the other may use a LUT, or other such differences may be present.

In addition, the ID is not necessarily intended to capture every detail of how colors arrive in a given color space. For example, as long as colors are intended to be viewed on a Rec.709 monitor, it is likely correct to assign the g24\_rec709\_display ID, regardless of what look or view transform was used in the conversion. However, it is always possible to generate a new ID to capture certain details, if it is felt essential to do so.

#### Avoiding Naming Collisions

When generating interop IDs, it is essential to avoid using the same string that may be used by others. Here are a few things to avoid:

* To avoid confusion, it is illegal to use any of the Color Interop Forum IDs with a custom namespace.
* The namespaces consisting of "ocio", or any string beginning with "ocio", are reserved for use by the OCIO project maintainers.

A registry is being set up on the Color Interop Forum website to allow entities to reserve namespaces or IDs to avoid collisions with other users. Please see Annex A for more information about the interop ID registry.


### Using the Color Interop ID in Color Management Systems

The Color Interop Forum recommendations provide essential information about common color spaces along with the color interop ID string. This includes references to source documents, clarification of confusing topics, and an OpenColorIO config implementation. Since OCIO is open source, the config may be used to understand the exact math involved in implementing a given color space and connecting it to other color spaces. It is therefore hoped that these recommendations will be useful and enable good interoperability for the associated IDs, regardless of whether OCIO is used in a given implementation.


### Using the Color Interop ID with OpenColorIO

As of OCIO 2.5, released in September 2025, there is an `interop_id` attribute available for use on ColorSpace objects in an OCIO config file. This allows config authors to set the appropriate interop ID on their color spaces. This section covers various aspects of how to use the associated OCIO functions.

#### The Interop ID and Config Files

##### Getting and Setting the Interop ID

Applications may use the `ColorSpace` class member functions `getInteropID` and `setInteropID`.

##### Inferring a Missing Interop ID

If the `interop_id` attribute on the color space object is missing, an application could use heuristics to infer an ID. For example, it could look at the aliases present on a color space and compare them to the name and alias strings used in the [built-in ACES configs](https://opencolorio.readthedocs.io/en/latest/configurations/aces_studio.html), which include interop IDs for all color spaces as of OCIO 2.5. Another approach would be to compare the transforms in the color space to the transforms used for the color spaces in one of the built-in ACES configs.

##### Generating an Interop ID

If an application is unable to find or infer an ID, it may need to generate an ID for a color space. If `Config::getName` returns a non-empty string, that could be used for the namespace, otherwise, the application would need to invent some other string. For the color space portion, the application could use the methods on the `ColorSpace` class to check the name and aliases and choose one (one of the aliases is often less likely to use illegal characters than the name). Here is an example of doing this on one of the ACES configs (the dashes and underscores are what is found in the built-in config but there is no official structure other than that the colon separates the string into two parts):

`studio-config-v3.0.0_aces-v2.0_ocio-v2.4:arri_logc3_ei800`

The tentative ID string must then be sanitized to remove or replace any characters that are not allowed.

##### Obtaining the User-Facing Name from the Interop ID

The interop ID should not be shown in the user interface, for example in color space menus. The ID should be used to find a `ColorSpace` object, then call `getName` on the object for the string that should be used in the UI.

##### Storing the Interop ID in Config Files Earlier than OCIO v2.5

Using OCIO v2.5 or later, it is acceptable to write the interop ID for config files going back to version 2.0.

##### Reading the Interop ID Using a Library Version Earlier than OCIO v2.5

The interop ID is only accessible from the OCIO library v2.5 or later.

#### Finding a Color Space for an Interop ID

##### Searching a Config for an Interop ID

Search for an interop ID the same way you would search for a color space name or alias – use the `getColorSpace` method of the `Config` class.

Unlike the strings used for color space names and aliases, an interop ID may appear more than once in a config. This is because configs sometimes contain color spaces that are essentially identical but that may, for example, include different look or color balance adjustments. Therefore, when searching for an interop ID, it is the color space names and aliases that must be searched, rather than looking for the `interop_id` attribute itself. That way, the config author decides how to resolve which color space takes precedence if several share the same ID.

It is thus essential that config authors set the interop ID string as a color space name or (more typically) an alias, in addition to the interop ID attribute itself. The config validation process will fail if this is not done.

##### Fallback Methods to Search for an ID in Other Configs

Ideally, `getColorSpace` will return a result within the designated config being used for a given project. However, it is possible to search in other configs as well. The simplest approach is to use the [Studio config for ACES](https://opencolorio.readthedocs.io/en/latest/configurations/aces_studio.html) that is built into the OCIO library itself. The most recent version of this config (`ocio://studio-config-latest`) will return a color space for all of the Color Interop Forum names (that were current when the library was released) as well as many other commonly used color space name aliases.

##### Using a Color Space from Another Config

If the color space is located in a different config from the main one being used, there are various methods for leveraging that:

* The function `Config::GetProcessorFromConfigs` may be used to convert an image into one of the color spaces in the user's config (e.g., a working color space or a display color space).
* The function `Config::IdentifyBuiltinColorSpace` may be used to see if there is an equivalent color space in the user's config that simply uses a different name (e.g., it's named "lin_ap0" rather than "ACES2065-1", but it's the same mathematical transform).
* The merge functionality (available starting in OCIO 2.5) may be used to merge the color space into the user's config. Generally, this should only be done to the in-memory version of the config rather than actually updating the user's config file on disk.


### General References

Color Interop Forum Recommendation ["Identifying the Color Space of OpenEXR Files"](https://docs.google.com/document/d/1MTH1bq2L67ifvdDf64Amhzg4AbkIM5LG6yPHrB96Vwo/edit?usp=sharing)

OpenEXR Standard Attribute [colorInteropID](https://openexr.com/en/latest/StandardAttributes.html#anticipated-use-in-pipeline)

Color Interop Forum Recommendation ["Color Space Encodings for Texture Assets and CG Rendering"](https://github.com/AcademySoftwareFoundation/ColorInterop/blob/main/Recommendations/01_TextureAssetColorSpaces/TextureAssetColorSpaces.md)

Color Interop Forum Recommendation ["Color Space Encodings for Displays"](https://docs.google.com/document/d/1MmBG4a3Dr6S6EO781WjK-xZW7QdHpuo-zd7wtMvG1Rs/edit?usp=sharing)

[ACES Technical Documentation](https://docs.acescentral.com/)

[OpenColorIO](https://opencolorio.org/)



## Annexes

### Annex A: Registering Interop IDs

A Wiki has been created on the Color Interop Forum's GitHub repo to allow people to register interop IDs they generate and namespaces. This is intended to help avoid conflicts by providing visibility into how others are using the system.

The Wiki page is available at this [URL](https://github.com/AcademySoftwareFoundation/ColorInterop/wiki/Registered-Color-Interop-IDs).

Not everyone will have write access to the Wiki. To have something added to the registry, please post a request on the ASWF Slack in the \#color-interop-forum channel, create an Issue on GitHub or send a message to one of the Color Interop Forum leaders.