OCIO Context Variables

OCIO context variables allow you to change the behaviour of a config file on a per-shot or per-show basis. This opens up very powerful workflows, but is also a complex feature. In order to make use of context variables, the OCIO config author must build them into the config. To help illustrate the concept, a preset is provided named "Context Var. Example". Creating a project using that OCIO config will allow you to explore how context variables work.

Using Context Variables in a Config

You may want to open the "Context Var. Example" preset in a text editor. The file is installed here: /opt/Autodesk/colour_mgmt/configs/flame_configs/2026.0/context_example_config/config.ocio.

You will notice at the top of the file is an environment section that lists the context variables used in the config, along with a default value for each.

OpenColorIO allows context variables to be used in the following places in a config:

• In the search_path.
• In a FileTransform to define the source file name.
• In the cccid attribute of a FileTransform to identify which specific transform to use from a CDL or CCC file.
• In a ColorSpaceTransform to define the source or destination colour space name.

The "Context Var. Example" config has examples of each of these techniques.

Usage as a FileTransform

In an OCIO config, a FileTransform is the way external colour transform files or LUTs are used. The CCC_FILE and CCC_ID context variables are used on line 1660 in the "CCC CDL" Look, using a FileTransform:

transform: !<FileTransform> {src: ./$CCC_FILE, cccid: $CCC_ID}

Using the default values of the context variables, this would expand to:

transform: !<FileTransform> {src: ./ccc_example.ccc, cccid: 0001}

There is a "ccc_example.ccc" in the "luts" directory adjacent to the config.ocio file. That file has several CDLs in it and changing the cccid to "0002", or "0003", etc. will change the look that gets applied. The "CCC CDL" view is available for use in viewports with any clip tagged with a scene-linear or log colour space.

Usage in the Search Path

In an OCIO config, the search_path is a list of directories of where to search when trying to load FileTransforms. In the previous example, the FileTransform used the relative path "./ccc_example.ccc". Since the search_path contains "luts", OCIO will be able to find that file. You could use this mechanism to point OCIO at different locations based on the shot being worked on.

The "context file" colour space uses "./$CONTEXT_FILE" as the FileTransform path, and this relies on having "./$CONTEXT_PATH" in the search_path. With the default values of these two context variables, the path will be expanded to point to a specific file in the "syncolor_ctfs" directory.

Usage in a Colour Space Transform

In an OCIO config, a ColorSpaceTransform is a transform that converts between two named colour spaces. The "colorspace src to dst" colour space has the following on line 3865 of the config:

to_scene_reference: !<ColorSpaceTransform> {src: $CS_SRC, dst: $CS_DST}

Using the default values of the context variables, this would expand to:

to_scene_reference: !<ColorSpaceTransform> {src: ACEScg, dst: ACES2065-1}

The "CS_SRC" could be changed to point to a different colour space. (In this example, since it is a "to_scene_reference" transform, the destination should be left unchanged since nothing else would be appropriate for this config.)

Show/Seq/Shot CDL Look Example

The "Shot Based CC" Look is used to define the "Shot Based CC" view, which is available on all displays for any clips tagged with a video colour space. It contains the following on line 1654:

transform: !<FileTransform> {src: ./$SHOW/$SEQ/$SHOT/look.cc}

In the "luts" directory there is a "MyShow" directory, which contains a sequence directory named "001", which contains shot directories named "0001" through "0004", that each contain a "look.cc" file. The default values of the context variables would expand that path as:

transform: !<FileTransform> {src: ./MyShow/001/0001/look.cc}

You can imagine how this could be used to swap in different looks based on the show, sequence, and shot.

Show LUT Example

In some cases, rather than having a different look transform per shot, you may have an entire view transform or "show LUT". On line 1975 you will find an example of how to define a ViewTransform that uses a show LUT that will be swapped in using the context variables "./$SHOW/$SHOW_LUT" as the source for a FileTransform:

- !<ColorSpaceTransform> {src: ACES2065-1, dst: Log film scan (ADX10)}
- !<FileTransform> {src: ./$SHOW/$SHOW_LUT}
- !<ColorSpaceTransform> {src: Rec.709 video, dst: CIE-XYZ}

In this config, the view transforms expect "ACES2065-1" values going in and producing "CIE-XYZ" values coming out. For this example, the assumption is that all the show LUTs will expect "Log film scan (ADX10)" going in and producing "Rec.709 video" coming out. So the LUT is accompanied on either side by a ColorSpaceTransform to fit it into the expectations of this config. Once this is done, the LUT may be applied to a clip in any colour space in the application and sent to any display device. OCIO will automatically insert any additional necessary conversions to make that happen.

This print-film emulation from the Lustre Colour collection is available as the "Show LUT" view on any display and any clip tagged with a scene-linear or log colour space.

Setting Context Variables

When you create a project, the context variables and their default values from the environment section of the config are copied into the project. From that point on, any changes you make to the default values in the source config file are ignored unless you go into the Colour Management Preferences and either use the Reset Context button or the Reload config button. If you reload the config, click "Yes" in the dialog box asking if you want to reset the project context variables.

The application keeps this copy of the current context variables so that it is able to communicate them to shared services such as Burn.

Every time you launch the application, if you have environment variables defined with the same name as your context variables, those will be copied into the project and become the new current values.

Setting Values in the Colour Management Preferences

In the Context Variables tab of the Colour Management Preferences, you will see the context variables for the config and their current values. Every time you launch the application, the content of this table may be different since the environment variables defined at launch will override the previous values.

If you click on a row in the Value column you may update a context variable to a new value. (The Name may not be changed, only the context variable names defined in the environment section of the config file may be used.) You may click the Reset Context button to reset the table to the values in the source config.

The values defined in the Preferences are the global values that apply everywhere in the application that does not specifically allow you to override them. The following locations only use the current values from the Preferences:

• Viewports
• Look node in Batch or Timeline FX
• Colour Mgmt settings in MediaHub and Export
• Action
• Colour Mgmt Matchbox

Setting Values in the Colour Mgmt Tool

In the Colour Mgmt node in Batch and the Colour Mgmt Timeline FX, there is a Context tab that allows you to override the global context variables from the Preferences.

If you go into the Context tab, you will see a table of Name/Value pairs. They start out initialized to whatever the current value in the Preferences is. If you turn off the From Project toggle, you will be able to edit the values. Edited values that are different from the Preferences will be shown in a light blue colour. To temporarily revert to the values from the Preferences, you may enable the From Project toggle button.

You may click on the blue "LED" on the Context tab as a quick alternative to using the toggle button. It also shows you if an override is in effect without having to go into the Context tab.

The context variable overrides are copied with the Colour Mgmt setup, for example, if you duplicate a Batch node or use Shift+T+click to copy from one Batch node to another. In addition, they are automatically communicated to any external services such as Burn.

The values will be persisted if you save a Batch setup. If you load the setup into another project that uses a different OCIO config, those context values may, or may not, be relevant. However, any context variables not present in the current config will be ignored.

When the context variables in the Preferences are updated, Colour Mgmt tools that are in From Project mode are notified and updated. If you don't want this to happen, make sure to disable From Project mode in the relevant Colour Mgmt nodes or Timeline FX.

Setting Values via the Python API

The Python API allows you to create "Colour Mgmt" nodes in Batch or in Timeline FX. These have a set_context_variable function available to set Name/Value pairs. The context_variables_from_project attribute may be set to False to toggle From Project mode off and allow overrides.

Using Python, one could create Colour Mgmt Timeline FX on each shot in a timeline and set the appropriate context variables to apply any shot-specific processing, either on input or output. Creating a gap effect using Colour Mgmt View Transforms would allow you to apply custom view transforms on each shot without needing to bake them in.

Please see the sample code in the Python API examples.