WORK IN PROGRESS

Background

Roles provide both config authors and application developers with a mechanism for task-specific color space classification, without awareness of an OCIO config's design. A config author will define the scene_linear role in each of their configs pointing to their desired scene-referred linear color space, which applications can then confidently use as a default linear working space, without knowledge of its implementation. Similarly an application can advertise support for an app-specific role for config authors to implement to customize an aspect of color management unaccounted for by OCIO's standard roles.

OCIO's standard roles are represented by string constants in the API, which reflect common tasks utilized within a VFX or animation color pipeline. Some of these roles have gained widespread use and standardization among applications with OCIO support, while others have largely been topics of confusion and ambiguity. The reference role for example has been interpreted by some as pointing to the config's implicit "reference" color space (what color spaces define transforms relative to and from), and by others as a color space for reference images. These two interpretations result in drastically different use cases which make it hard for this role to be of much use outside of a strictly managed color pipeline.

OCIO v2 introduced several new standard roles, as well as a second display-referred implicit reference space, which have created new opportunities for applications to utilize roles even more. These guidelines provide insight on the recommended use of roles both for internal implementation within an application, as well as for user facing interfaces which may opt to expose roles and their underlying color space.

Resources

• Authoring Configurations: Roles

• API: Role Constants

Use Cases

• A config author defines standard OCIO roles and studio-specific custom roles for each config so that pipeline software can provide consistent behavior across projects without awareness of how they differ in their underlying color management choices.

• An application provides several app-specific roles allowing a config author to tune the application's color management preferences per config without code or user intervention.

• A studio uses clearly named roles to guide artists in an application toward color spaces for specific tasks without needing an understanding of color science terminology.

• A studio uses an interchange role to convert images from a past project to a new project without concern for color pipeline differences between them.

• An application uses an interchange role to map color between a proprietary camera SDK and their OCIO implementation without knowledge of the config's contents.

Guidelines

App Developers

Color Space Menus

By default, roles should not be included in color space menus. If config authors want to guarantee inclusion of a specific role in a color space menu they can create a color space of the same name.

Applications can optionally include a localized or global preference for users to opt-in to having roles included in color space menus. When including roles in menus or UI components, the “canonical” color space name should be indicated beside the role name, formatted like

Roles included in menus should ideally be put under a hierarchical “Roles” menu consistent with family-based color space menu organization:

If nested menus are not supported, roles should be separated from color spaces with a visual separator:

Application-specific Roles

Applications should use standard roles for appropriate color space assignment when possible. If a role for a specific use case in the app doesn’t exist, the app should support an app-specific custom role. App-specific roles should adhere to the naming convention:

App-specific roles should default to inheriting their color space from a standard role. This default should be clearly documented in a role table. A well documented example of app-specific role implementation is Foundry Mari.

Undefined Roles

If a config does not define an expected role, an application may ask the user to select a color spaces from the config. A config authored by a facility color scientist for a project will typically chose a specific role, but generic configs (e.g. those produced by the OCIO config working group) may omit roles in cases where there is more than one reasonable choice, depending on the details of the specific workflow.

Standard Roles

Standard roles should be used in the following way:

default

When using color space rules to determine a default color space, OCIO will use this role if no other color space can be determined. It does not need to be referenced by an application directly.

reference

This role has had multiple interpreted meanings over the years and is a common point of confusion. It is kept in OCIO for backwards compatibility, but the recommendation is that it is not used by applications.

data

A no-op color space which bypasses any color management. This should be the default for utility image data (normals, position, displacement, alpha, etc.).

color_picking

This role has been another point of confusion, used in various ways historically. The recommendation is that it be used to define the gamut of colors that can be picked (limiting, but not necessarily clamping), but that the picked colors themselves are represented and stored in the application’s working space (e.g. scene_linear). It is also recommended that color picker gradients and swatches support the option to be viewed through the current display and view (output transform), allowing artists to target display colors in addition to scene colors.

scene_linear

The default linear working space. Apps should generally do all internal processing of linear image data in this space. This may or may not match the reference role. For example, the reference role may point to ACES2065-1 while scene_linear points to ACEScg. Or they could both point to ACES2065-1.

compositing_log

Color space to use for compositing operations which operate on logarithmically encoded image data (e.g. rolloff or filters with negative lobes). This can also be used with the scene_linear role for default log-to-lin and lin-to-log conversion when the specific spaces are less critical than their general characteristics.

color_timing

Color space for logarithmic color grading operations, also commonly used to define the working space for look application, matching on-set grading pipelines.

texture_paint

Working color space for texture painting, which may be a display-referred space like sRGB or a linear space like ACEScg. This is highly dependent on the pipeline, but is commonly used for diffuse (albedo) textures so in many cases is limited to a [0.0, 1.0] domain.

matte_paint

Working color space for matte painting, which may be a display-referred space like sRGB or a logarithmic space for utilizing high dynamic range data in applications which operate in unsigned integer data types.

rendering

This color space will typically match scene_linear, but may differ for color pipelines that are rendering in a studio-defined linear color space while compositing in a different client-defined linear color space. For example, a studio may adhere to ACES, but finish shots in ALEXA wide gamut if they are being delivered in that gamut to clients.

aces_interchange

If defined this will always refer to a color space implementing ACES2065-1, used exclusively for interchange between two different OCIO configs (between scene-referred spaces). This is internally used by OCIO so does not need to be referenced by an application directly, however may also be used by an app to interchange OCIO color processing with another color managed library where both are capable of transforming to and from ACES2065-1.

cie_xyz_d65_interchange

If defined this will always refer to a color space implementing CIE XYZ with a D65 white point, used exclusively for interchange between two different OCIO configs (between display-referred spaces). This is internally used by OCIO so does not need to be referenced by an app directly, however may also be used by an app to interchange OCIO color processing with another color managed library where both are capable of transforming to and from CIE XYZ D65.

Scene Save Behavior

When an application is saving a scene, role selections should be saved to the scene file as the color space they point to (their “canonical” color space name) instead of the role name. If the role then changes there will be no visual impact when loading the scene later. The exception to this rule is when storing global color space preferences with no direct impact on visual results of the scene. For example, an app may have a preference that defines a role or color space to use when importing new images into the scene. That should be saved as a role name so that the desired behavior is consistent after an OCIO config change. However, if an already imported image has been assigned a color space with a role name, it should be saved as the color space name, so that an OCIO config change will not alter the scene’s rendered result.