...
- 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
...
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
| Code Block | ||
|---|---|---|
|
...
<role> (<color space>) |
Roles included in menus should ideally be put under a hierarchical “Roles” menu consistent with family-based color space menu organization:
| Code Block | ||
|---|---|---|
| ||
<family>/ |
...
<color space> |
...
<color space> |
...
Roles/ |
...
<role> |
...
<role> |
If nested menus are not supported, roles should be separated from color spaces with a visual separator:
| Code Block | ||
|---|---|---|
| ||
<color space> |
...
<color space> |
...
------------- |
...
<role> |
...
<role> |
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:
| Code Block | ||
|---|---|---|
| ||
<app name>_<use/task> (e.g. “mari_blending”) |
...
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 a given an expected role, it is an indication to the application that it may ask the user to select one of the a color spaces from the config. Typically a A config authored by a facility color scientist for a specific show project will typically chose a specific role, but generic configs (e.g. those produced by the OCIO config working group) may omit the roles in cases where there is more than one viable solution reasonable choice, depending on the details of a 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 app application is saving a scene, role color space 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 could 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.
Mockups (optional)
...