OCIO 2.2 Release¶
OpenColorIO 2.2 was delivered in October 2022 and is in the VFX Reference Platform for calendar year 2023.
New Feature Guide¶
The OCIO Configs Working Group has put a lot of effort into building new ACES configs that take advantage of the features of OCIO v2 and that are informed by the learnings from the previous ACES configs. The new configs are available from the project’s GitHub repo: OpenColorIO-Config-ACES
To make them easily accessible, they are built in to the library itself and may be accessed directly from within applications that incorporate the OCIO 2.2 library.
Wherever you are able to provide a file path to a config, you may now provide a URI-type string to instead use one of the built-in configs. For example, you may use these strings for the OCIO environment variable.
- To use the ACES CG Config, use this string for the config path::
- To use the ACES Studio Config, use this string for the config path::
- This string will give you the current default config, which is currently the ACES CG Config::
In future releases, it is expected that updated versions of these configs will be added, each with a unique name string. However, the previous strings will continue to be supported for backwards compatibility.
The new URI-type strings may be passed into the existing APIs such as
CreateFromFile. There is also a new
CreateFromBuiltinConfig. No changes
should be needed, but please test that users of your application may use a path containing
a URI-type string rather than a path to a config.ocio file.
If you’d like to offer the built-in configs from your user interface, there is an API to
access them through the new
BuiltinConfigRegistry. Here is basic Python code to
access the registry and print the strings to present in a UI:
registry = ocio.BuiltinConfigRegistry().getBuiltinConfigs() for item in registry: # The short_name is the URI-style name. # The ui_name is the name to use in a user interface. short_name, ui_name, isRecommended, isDefault = item # Don't present built-in configs to users if they are no longer recommended. if isRecommended: print(ui_name)
Academy Color Encoding System - CG Config [COLORSPACES v1.0.0] [ACES v1.3] [OCIO v2.1]
Academy Color Encoding System - Studio Config [COLORSPACES v1.0.0] [ACES v1.3] [OCIO v2.1]
If your application saves the path to a config and the user enters
is recommended that you don’t save that as is. Instead, call
getDefaultBuiltinConfigName to get the name of the current default. This is
guaranteed to give the same results, whereas the default config could change somewhat
between releases. Prepend
ocio:// in order to save it as a valid config path. Here’s
the Python code:
"ocio://" + ocio.BuiltinConfigRegistry().getDefaultBuiltinConfigName()
An OCIO config, including its external LUT files, may now be packaged into a single file.
This makes it easier to distribute configs and may slightly discourage tampering with the
contents. An archived config may be created with the new
tool and is stored in a file with the extension
.ocioz. It is basically a compressed
ZIP archive of the config and its LUTs.
To be archivable, the external LUT files must be contained within (or below) the config’s working directory. (In OCIO terminology, the “working directory” is the directory that contains the config.ocio file.)
A config is not archivable if any of the following are true:
It contains FileTransforms with a src outside the working directory
The search path contains paths outside the working directory
The search path contains paths that start with a context variable
The working directory is not set (if archiving a Config object)
Context variables are allowed but the intent is that they may only resolve to paths that are within or below the working directory. This is because the archiving function will only archive files that are within the working directory in order to ensure that if it is later expanded, that it will not create any files outside this directory.
For example, a context variable on the search path intended to contain the name of a
sub-directory under the working directory must have the form
./$DIR_NAME rather than
$DIR_NAME to be considered archivable. This is imperfect since there is no way to
prevent the context variable from creating a path outside the working dir, but it should
at least draw attention to the fact that the archive would fail if used with context vars
that try to abuse the intended functionality.
All files within or below the working directory that end with an extension corresponding to a LUT type supported by OCIO are added to the archive. This approach was taken since the goal was for the archive to work with any combination of context variables that the original config works with. Files with other extensions or no extension are not archived.
Wherever you are able to provide a file path to a config, you may now provide a path to a .ocioz file. For example, you may use this for the OCIO environment variable.
ocioarchive command-line tool will allow you to archive a config or to expand an
existing archive. It will also allow you to list the contents of an archived config. Run
ocioarchive --help to get a print-out of the various options.
The print out from the
ociocheck command-line tool now includes a new line-item
indicating whether the config is archivable.
The new .ocioz files may be passed into the existing APIs such as
CreateFromFile. No changes should be needed, but please test that users of your
application may use a path containing a .ocioz file rather than a path to a config.ocio
The Config class has new
archive methods. There is also an
Abstracting the Source of External LUT Files¶
The new ConfigIOProxy class allows the calling program to supply the config and any associated LUT files directly, without relying on the standard file system. This opens the door to expanded ways in which OCIO may be used.
The new config archiving feature was implemented using this mechanism.
Please refer to the
ConfigIOProxy class. By implementing the
getFastLutFileHash methods, you have control over how the
config is provided to OCIO. No file system access to a config is required.
CreateFromConfigIOProxy factory allows for the creation of a Config object from a
Converting To or From a Known Color Space¶
An OCIO config defines its own self-contained universe of color spaces. But there are not any requirements for color spaces which must always be included or how they must be named. This poses difficulties for many applications which need to convert to or from certain known standard color spaces. For example, a renderer might have a physical sun and sky model which produces colors in a CIE space and it needs to convert those into the rendering space defined by a user’s custom OCIO config. Or an application may use an SDK to debayer images from a digital cinema camera. The SDK produces images in a specific color space which then needs to be processed into something viewable through a user’s custom OCIO config.
OCIO v2 introduced the Interchange Roles to help address this problem but these had previously been optional and are unlikely to be included in OCIO v1 configs (although it would be perfectly legal to add them).
OCIO 2.2 introduces the new functions
GetProcessorFromBuiltinColorSpace that will allow you to convert to or from any of the
color spaces in the built-in Default config (this is currently the ACES CG config
described above). This built-in config includes common spaces such as “Linear Rec.709
(sRGB)”, “sRGB - Texture”, “ACEScg”, and “ACES2065-1”.
If the source config defines the necessary Interchange Role (typically
aces_interchange), then the conversion will be well-defined and equivalent to calling
GetProcessorFromConfigs with the source config and the Built-in config
However, if the Interchange Roles are not present, heuristics will be used to try and identify a common color space in the source config that may be used to allow the conversion to proceed. If the heuristics fail to find a suitable space, an exception is thrown. The heuristics may evolve, so the results returned by this function for a given source config and color space may change in future releases of the library. However, the Interchange Roles are required in config versions 2.2 and higher, so it is hoped that the need for the heuristics will decrease over time.
The current heuristics should work on any config (including an OCIO v1 config) that was generated by editing one of the ACES configs or any config that uses one of the following as its reference space:
Scene-linear Rec.709 (sRGB)
And that has a color space either for any of the above spaces or for an sRGB texture space that has “sRGB” (case-insensitive) in its color space name or one of its aliases.
Note that the heuristics create a Processor and evaluate color values that must match within a certain tolerance. No color space is selected purely based on its name alone. If the heuristics fail to find a recognized color space, an exception is thrown.
Making the interchange roles required for config versions 2.2 or higher¶
Users were surveyed during the OCIO 2.2 development process as to whether the Interchange Roles should become mandatory. The response was overwhelmingly in favor of doing this, largely because it allows robust interchange of color spaces between configs or to external known standard color spaces.
Therefore, as described in the previous section, for config files of version 2.2 or
higher, it is mandatory to define the
aces_interchange role. If the config includes
display color spaces, the
cie_xyz_d65_interchange role is also required.
Note that the
cie_xyz_d65_interchange is only used in connection with display color
spaces (that is, with the display-referred connection space). It is not used for
scene-referred color spaces, and indeed it is an error if a scene-referred space is
assigned to that role.
ociocheck command-line tool has been updated to make these checks. In addition,
its reporting on other roles has been modified to be more lenient regarding roles which
are no longer considered essential.
The Config::validate method will log an error if the Config object does not meet these
requirements. Note that an exception is not thrown since it was felt that the Config’s
upgradeToLatestVersion method must always produce a valid config.
Determining if a Color Space is Linear¶
There have been many requests from developers that would like a standard way to determine
if a color space is linear, since this impacts what sort of processing is suitable. OCIO
v2 introduced a new
encoding attribute for color spaces which contains this
information. However, this is optional and may not be set by all config authors. And it
won’t be present in OCIO v1 configs, which are still widely used.
OCIO 2.2 adds a new
isColorSpaceLinear method to the Config class which may be used
for this purpose.
Note that since OCIO has both a scene-referred and a display-referred reference space, the
method also takes a ReferenceSpaceType enum to indicate which reference space the
linearity determination is with respect to. Typically developers will set this to
The following algorithm is used to make the determination:
If the color space
isdataattribute is true, return false.
If the reference space type of the color space differs from the requested reference
space type, return false.
* If the color space’s encoding attribute is present, return true if it matches the
expected reference space type (i.e., “scene-linear” for
REFERENCE_SPACE_DISPLAY) and false otherwise.
* If the color space has no
from_reference transform, return true.
* Evaluate several points through the color space’s transform and check if the output only
differs by a scale factor (which may be different per channel, e.g. allowing an arbitrary
matrix transform, with no offset).
Note that the last step is a heuristic that may or may not be accurate. However, note
encoding attribute takes precedence and so config authors have the ultimate
control over the linearity determination.
Getting a Processor for a NamedTransform¶
A new config object was introduced in OCIO v2 called Named Transforms. These are used when there is a need to apply a mathematical function which is not a conversion between two specific color spaces. The most common example is applying a transfer function curve to convert linear data to non-linear, or vice-versa.
The new ACES configs include Named Transforms, so it is important for application developers to start supporting this type of config object. The preferred method for doing so is to add a new tool, similar to FileTransform that applies a Named Transform.
What is new in OCIO 2.2 is that the code for applying these is now simpler with the introduction of several new getProcessor methods on the Config class that will return a Processor directly from a NamedTransform object.
In addition, the NamedTransform class has a GetTransform method that returns a (regular) Transform object for a given direction. It will create the transform from the inverse direction if the transform for the requested direction is missing.
Circular OCIO / OIIO Build Dependency Solution¶
A long-standing complaint has been regarding the circular build dependency between OCIO
and OpenImageIO. This is due to the fact that OIIO wants to use OCIO for color management
and OCIO wants to use OIIO in its command-line tools
ociodisplay for reading and writing image files. These tools will not be built if
OIIO is not available when configuring the build.
Furthermore, some package installers will not install these command-line tools due to the dependency on OIIO.
By default, OCIO will now build these tools with OpenEXR rather than relying on OIIO.
If you have a version of OCIO that was not compiled with tools such as
you want to use OCIO to process images, you could try using OpenImageIO’s
(Although note that
ocioconvert has a few features that are not in
as GPU processing support.) Similarly if you have
ocioconvert, but it is compiled
with OpenEXR rather than OpenImageIO, you may use
oiiotool to convert other image file
formats to/from OpenEXR.
If you want to use
oiiotool but it does not support a particular type of conversion,
you may be able to use
ociowrite to export a CTF file and then use that with the
--ociofiletransform option in
In OCIO 2.2, by default, the build will now use OpenEXR rather than OpenImageIO for the
command-line tools that read or write images. This will limit the functionality of the
aforementioned command-line tools to only working with OpenEXR files. If you want support
for more file formats in these tools, you will still need to have OIIO available when
building OCIO and set the CMake variable
Here are some other improvements in OCIO 2.2:
Support for more types of ICC Monitor Profiles – All of the parametric curve types are
New hash function for calculating cache IDs – The md5 algorithm has been replaced with
xxhash, which provides a considerable speed-up for various operations. The APIs that return cache ID strings will obviously return different strings now, but please note that these are not guaranteed to be unchanged across releases. (The 128-bit version of xxhash was used, which is the same length as for md5.)
The command-line tools
using an inverse DisplayViewTransform.
Add DisplayViewTransform and NamedTransform support to Baker.
Several new Built-in Transforms are available for version 2.2 config files, including
Preliminary support for ACES Metadata File (AMF) – A prototype Python tool has been
pyocioamf that converts an AMF file into the OCIO native transform format
CTF. It uses a prototype ACES Reference config file that is serving as a database of ACES
Transform IDs for interpreting the AMF file.
Support for PyPI installation from source rather than pre-built binaries.
For more detail, please see the GitHub release pages: