Using OCIO

Environment Variables

The following environment variables may be used with OpenColorIO:

OCIO

Specifies the file path of the config file to be used. (This is necessary for some of the command-line tools but most applications provide a way of setting this from the user interface.)

OCIO_ACTIVE_DISPLAYS

Overrides the active_displays list from the config file and reorders them. Colon-separated list of displays, e.g sRGB:P3

OCIO_ACTIVE_VIEWS

Overrides the active_views list from the config file and reorders them. Colon-separated list of view names, e.g internal:client:DI

OCIO_INACTIVE_COLORSPACES

Overrides the inactive_colorspaces list from the config file. Colon-separated list of color spaces, e.g previousColorSpace:tempSpace

OCIO_LOGGING_LEVEL

Configures OCIO’s internal logging level. Valid values are none, warning, info, or debug (or their respective numeric values 0, 1, 2, or 3 can be used)

Logging output is sent to STDERR output by default.

OCIO_OPTIMIZATION_FLAGS

Overrides the optimization settings being used by an application, for troubleshooting purposes. The complete list of flags is in OpenColorTypes.h.

Tool overview

The following command-line tools are provided with OpenColorIO. Note that compilation of the tools requires additional components such as OpenImageIO and OpenGL.

The –help argument may be provided for info about the arguments and most tools use the -v argument for more verbose output.

Many of the tools require you to first set the OCIO environment variable to point to the config file you want to use.

ociocheck

This is a command-line tool which shows an overview of an OCIO config file, and checks for obvious errors.

For example, the following shows the output of a config with a typo - the colorspace used for compositing_log is not incorrect:

$ ociocheck --iconfig example.ocio

OpenColorIO Library Version: 0.8.3
OpenColorIO Library VersionHex: 525056
Loading example.ocio

** General **
Search Path: luts
Working Dir: /tmp

Default Display: sRGB
Default View: Film

** Roles **
ncf (default)
lnf (scene_linear)
NOT DEFINED (compositing_log)

** ColorSpaces **
lnf
lgf
ncf
srgb8 -- output only

ERROR: Config failed validation. The role 'compositing_log' refers to a colorspace, 'lgff', which is not defined.

Tests complete.

It cannot verify the defined color transforms are “correct”, only that the config file can be loaded by OCIO without error. Some of the problems it will detect are:

  • Duplicate colorspace names

  • References to undefined colorspaces

  • Required roles being undefined

  • At least one display device is defined

  • No v2 features are used in a v1 config

As with all the OCIO command-line tools, you can use the –help argument to read a description and see the other arguments accepted:

$ ociocheck --help
ociocheck -- validate an OpenColorIO configuration

usage:  ociocheck [options]

    --help        Print help message
    --iconfig %s  Input .ocio configuration file (default: $OCIO)
    --oconfig %s  Output .ocio file

ociochecklut

The ociochecklut tool will load any LUT type supported by OCIO and print any errors or warnings encountered. An RGB or RGBA value may be provided and will be evaluated through the LUT and the result printed to the console. Alternatively, the -t option will send a predefined set of test RGB values through the LUT:

$  ociochecklut -v acescct_to_rec709.clf  0.18 0.18 0.18

OCIO Version: 2.0.0dev

Input  [R G B]: [      0.18      0.18       0.18]
Output [R G B]: [0.05868321 0.0586832 0.05868318]

The –gpu argument may be used to evaluate using the GPU renderer rather than the CPU renderer.

ociobakelut

A command-line tool which bakes a color transform into various color lookup file formats (“a LUT”)

This is intended for applications that have not directly integrated OCIO, but can load LUT files

If we want to create a lnf to srgb8 viewer LUT for Houdini’s MPlay:

$ ociobakelut --inputspace scene_linear --shaperspace lg10 --outputspace srgb8 --format houdini houdini__lnf_to_lg10_to_srgb8.lut

The --inputspace and -outputspace options specify the colorspace of the input image, and the displayed image.

Since a 3D LUT can only practically operate on 0-1 (e.g a Log image), the --shaperspace option is specified. This uses the Houdini LUT’s 1D “pretransform” LUT to do “lnf” to “lg10”, then the 3D LUT part to go from “lg10” to “srgb8” (basically creating a single file containing a 1D linear-to-log LUT, and a 3D log-to-sRGB LUT)

To make a legacy log to sRGB LUT in 3dl format, the usage is similar, except the shaperspace option is omitted, as the input colorspace does not have values outside 0.0-1.0 (being a Log space):

$ ociobakelut --inputspace lg10 --outputspace srgb8 --format flame flame__lg10_to_srgb.3dl

See the Supported LUT Formats section for a list of formats that support baking

The ociobakelut command supports many arguments, use the –help argument for a summary. For more information on baking LUT’s, see Baking LUT’s

ocioconvert

Loads an image, applies a color transform, and saves it to a new file.

OpenImageIO is used to open and save the file, so a wide range of formats are supported.

ociodisplay

A basic image viewer. Uses OpenImageIO to load images, and displays them using OCIO and typical viewer controls (scene-linear exposure control and a post-display gamma control)

May be useful to users to quickly check colorspace configuration, but primarily a demonstration of the OCIO API

ociolutimage

Convert a 3D LUT to or from an image.

ociomakeclf

The ociomakeclf tool converts a LUT into Academy/ASC Common LUT Format (CLF):

$ ociomakeclf lut_file.cube lut_file.clf

The –csc argument may be used to convert the LUT into an ACES compliant Look Modification Transform (LMT) that may be referenced from an ACES Metadata File. An ACES LMT requires ACES2065-1 color space values on input and output. The –csc argument is used to specify the standard color space that the Look LUT expects on input and output and the tool will prepend a transform from ACES2065-1 to the LUT color space and postpend a transform from that color space back to ACES2065-1:

$ ociomakeclf my_ACEScct_look.cube my_LMT.clf --csc ACEScct

The –list argument will print out all of the standard ACES color spaces that are supported as –csc arguments.

ocioperf

The ocioperf tool allows you to benchmark the performance of a given color transformation on your hardware. Please use the –help argument for a description of the options.

ociowrite

The ociowrite tool allows you to serialize a color transformation to an XML file. This is useful for troubleshooting and also to be able to send a complete OCIO color conversion as a single file.

Note that this command does not do any baking of the transform into another format and so should give identical results to the original.

The –colorspaces argument specifies the source and destination color spaces for a ColorSpaceTransform and the –file argument specifies that name of the output file. The OCIO environment variable is used to specify the config file to be used.

The two file formats supported are CTF and CLF and this is selected by the extension you provide to the –file argument. The CTF format is recommended because it is able to represent all OCIO transforms and operators. The CLF format is also allowed since it has wider support in non-OCIO applications but the tool will not write the file if the transformation would require an operator that is not supported by CLF.

Here is an example:

$ export OCIO=/path/to/the/config.ocio
$ ociowrite --colorspaces acescct aces2065-1 --file mytransform.ctf

Supported LUT Formats

Ext

Details

Notes

3dl

Discreet legacy 3D-LUT

Read + Write Support. Supports shaper + 3D-LUT

ccc

ASC CDL ColorCorrectionCollection

Full read support.

cc

ASC CDL ColorCorrection

Full read support.

cdl

ASC CDL ColorCorrection

Full read support.

clf

Academy/ASC Common LUT Format

Full read + write support.

ctf

Autodesk Color Transform Format

Full read + write support. Provides lossless serialization of arbitrary OCIO transforms.

csp

Cinespace (Rising Sun Research) LUT. Spline-based shaper LUT, with either 1D or 3D-LUT.

Read + Write Support. Shaper is resampled into simple 1D-LUT with 2^16 samples.

cub

Truelight format. Shaper Lut + 3D

Full read support.

cube

Iridas format. Either 1D or 3D Lut.

Read support.

cube

Resolve format.

Read support.

lut

Discreet legacy 1D-LUT

Read support.

hdl

Houdini. 1D-LUT, 3D-LUT, 1D shaper Lut

Only ‘C’ type is supported. Need to add R G B A RGB RGBA ALL. No support for Sampling tag. Header fields must be in strict order.

icc/icm/pf

ICC profile format

Read support for basic monitor profiles.

look

IRIDAS .look

Read baked 3D-LUT embedded in file. No mask support.

mga/m3d

Pandora 3D-LUT

Full read support.

spi1d

1D-LUT format. Imageworks native format. HDR friendly, supports arbitrary input and output domains

Full read support.

spi3d

3D-LUT format. Imageworks native format.

Full read support.

spimtx

3x3 matrix + color offset. Imageworks native matrix format.

Full read support.

vf

Inventor 3D-LUT.

Read support for 3D-LUT data and global_transform element

Note

Some LUT formats include a “shaper” before a 3D-LUT intended to help the 3D-LUT work better with input spaces that are not perceptually uniform. These shapers are sometimes not actually LUTs and OCIO needs to convert them into one of the existing operators such as a LUT1D. In some cases this is done with linear interpolation, which does not work well with coarsely sampled shapers. In other cases (such as CSP format) spline interpolation is used, but the resulting LUT1D may not have fine enough sampling in the shadows to adequately represent the original shaper. If you are able to use them, the CLF and CTF formats are recommended since they allow very powerful shaper options that may be converted exactly into OCIO operators.

Compatible Software

The following software all supports OpenColorIO (to varying degrees).

If you are interested in getting OCIO support for an application not listed here, please contact the ocio-dev mailing list.

If you are a developer and would like assistance integrating OCIO into your application, please contact ocio-dev as well.

After Effects

An OpenColorIO plugin is available for use in After Effects.

Website: http://www.adobe.com/products/aftereffects.html

Documentation :

Arnold (Autodesk)

Website : https://www.arnoldrenderer.com/

Documentation :

Blender

Blender has integrated OCIO as part of it’s redesigned color management system.

Website: http://www.blender.org/

Supported Version: >= 2.64

Documentation:

C++

The core OpenColorIO API is available for use in C++. Minimal code examples are also available in the source code distribution.

Website: http://github.com/AcademySoftwareFoundation/OpenColorIO/tree/master/export/OpenColorIO

Examples:

Documentation:

Clarisse (Isotropix)

Website: https://www.isotropix.com/products

Documentation:

CryEngine (CryTek)

CryEngine is a real-time game engine, targeting applications in the motion-picture market. While we don’t know many details about the CryEngine OpenColorIO integration, we’re looking forward to learning more as information becomes available.

Website: https://www.cryengine.com/

Gaffer

Gaffer is a node based application for use in CG and VFX production, with a particular focus on lighting and look development.

Website: http://www.gafferhq.org/

Guerilla Render

Composed of Guerilla Station and Guerilla Render, Guerilla is a Production-Proven Look Development, Assembly, Lighting and Rendering Solution designed for the Animation and VFX industries.

Website: http://guerillarender.com/

Supported version: >= 2.2

Documentation:

Hiero (Foundry)

Hiero ships with native support for OCIO in the display and the equivalent of Nuke’s OCIOColorSpace in the Read nodes. It comes with the “nuke-default” OCIO config by default, so the Hiero viewer matches when sending files to Nuke for rendering.

Website: https://www.foundry.com/products/hiero

Supported version: >= 1.0

Houdini (SideFX)

Website: https://www.sidefx.com

Supported Version: >= 16

Documentation:

Java (Beta)

The OpenColorIO API is available for use in Java. This integration is currently considered a work in progress, and should not be relied upon for critical production work.

Website: https://github.com/AcademySoftwareFoundation/OpenColorIO/tree/master/src/bindings/java

Krita

Krita now support OpenColorIO for image viewing, allowing for the accurate painting of float32/OpenEXR imagery.

Website: http://www.krita.org/

Documentation :

Mari (Foundry)

Website: https://www.foundry.com/products/mari

Supported Version: >= 1.4v1

Documentation:

Maya (Autodesk)

Autodesk Maya is a 3D computer animation, modeling, simulation, and rendering software.

Website: https://www.autodesk.com/products/maya/overview

Supported Version: >= 2016

Documentation:

Mocha Pro (Boris FX)

Website: https://borisfx.com/products/mocha-pro

Supported Version: >= 2020

Documentation:

Modo (Foundry)

Website: https://www.foundry.com/products/modo

Documentation:

mrViewer

mrViewer is a professional flipbook player, hdri viewer and video/audio playback tool. It supports OCIO input color spaces in images as well as display/view color spaces.

Website: https://mrviewer.sourceforge.io

Documentation:

Natron

Website : https://natrongithub.github.io/

Documentation :

Nuke (Foundry)

Nuke ships with native support for OpenColorIO. There is also an available “nuke-default” OCIO config, which matches the built-in Nuke color processing. This profile is useful for those who want to mirror the native Nuke color processing in other applications (the underlying equations are also provided as python code in the config as well).

Website : https://www.foundry.com/products/nuke

Supported Version: >= 6.3v7

Documentation:

OpenImageIO

OIIO’s C++ and Python bindings include several methods for applying color transforms to whole images, notably functions in the ImageBufAlgo namespace including colorconvert(), ociolook(), ociodisplay(), ociofiletransform(). These are also available as part of the oiiotool command line utility (–colorconvert, –ociolook, –ociodisplay, –ociofiletransform) and the maketx utility for preparing textures also supports –colorconvert. From C++, there is additional low-level functionality in the header OpenImageIO/color.h that are wrappers for accessing underlying OCIO color configurations and doing color processing on individual pixel values.

Website : http://openimageio.org

PhotoFlow

PhotoFlow supports OCIO via a dedicated tool that can load a given configuration and apply the available color transforms. So far the tool has been tested it with the Filmic and ACES configs.

Website : https://github.com/aferrero2707/PhotoFlow

Photoshop

OpenColorIO display luts can be exported as ICC profiles for use in photoshop. The core idea is to create an .icc profile, with a valid description, and then to save it to the proper OS icc directory. (On OSX, ~/Library/ColorSync/Profiles/). Upon a Photoshop relaunch, Edit->Assign Profile, and then select your new OCIO lut.

Website : https://www.adobe.com/products/photoshop.html

Python

The OpenColorIO API is available for use in Python.

Website: https://github.com/AcademySoftwareFoundation/OpenColorIO/tree/master/src/bindings/python

Documentation:

RV (Autodesk)

Website : http://www.tweaksoftware.com

Supported Version: >= 4

Documentation :

  • For more details, see the OpenColorIO section of the RV User Manual.

Silhouette (Boris FX)

OCIO is natively integrated in Silhouette. Full support is provided for both image import/export, as well as image display.

Website : https://borisfx.com/products/silhouette/

Supported Version: >= 4.5

Substance Designer (Adobe)

Website: https://www.substance3d.com/products/substance-designer/

Supported version: >= 2019.3

Documentation:

Unreal Engine (Epic Games)

Website : https://unrealengine.com

Supported Version : >= 4.22

Documentation :

Vegas Pro (Magix)

Vegas Pro uses OpenColorIO, supporting workflows such as S-log footage via the ACES colorspace.

Website : http://www.sonycreativesoftware.com/vegaspro

Supported Version: >= 12

V-Ray (Chaos Group)

Website : https://chaosgroup.com

Documentation :

Apps w/icc or luts

flame (.3dl), lustre (.3dl), cinespace (.csp), houdini (.lut), iridas_itx (.itx) photoshop (.icc)

Export capabilities through ociobakelut:

$ ociobakelut -- create a new LUT or icc profile from an OCIO config or lut file(s)
$
$ usage:  ociobakelut [options] <OUTPUTFILE.LUT>
$
$ example:  ociobakelut --inputspace lg10 --outputspace srgb8 --format flame lg_to_srgb.3dl
$ example:  ociobakelut --lut filmlut.3dl --lut calibration.3dl --format flame display.3dl
$ example:  ociobakelut --lut look.3dl --offset 0.01 -0.02 0.03 --lut display.3dl --format flame display_with_look.3dl
$ example:  ociobakelut --inputspace lg10 --outputspace srgb8 --format icc ~/Library/ColorSync/Profiles/test.icc
$ example:  ociobakelut --lut filmlut.3dl --lut calibration.3dl --format icc ~/Library/ColorSync/Profiles/test.icc
$
$
$ Using Existing OCIO Configurations
$     --inputspace %s      Input OCIO ColorSpace (or Role)
$     --outputspace %s     Output OCIO ColorSpace (or Role)
$     --shaperspace %s     the OCIO ColorSpace or Role, for the shaper
$     --iconfig %s         Input .ocio configuration file (default: $OCIO)
$
$ Config-Free LUT Baking
$     (all options can be specified multiple times, each is applied in order)
$     --lut %s             Specify a LUT (forward direction)
$     --invlut %s          Specify a LUT (inverse direction)
$     --slope %f %f %f     slope
$     --offset %f %f %f    offset (float)
$     --offset10 %f %f %f  offset (10-bit)
$     --power %f %f %f     power
$     --sat %f             saturation (ASC-CDL luma coefficients)
$
$ Baking Options
$     --format %s          the lut format to bake: flame (.3dl), lustre (.3dl),
$                          cinespace (.csp), houdini (.lut), iridas_itx (.itx), icc (.icc)
$     --shapersize %d      size of the shaper (default: format specific)
$     --cubesize %d        size of the cube (default: format specific)
$     --stdout             Write to stdout (rather than file)
$     --v                  Verbose
$     --help               Print help message
$
$ ICC Options
$     --whitepoint %d      whitepoint for the profile (default: 6505)
$     --displayicc %s      an icc profile which matches the OCIO profiles target display
$     --description %s     a meaningful description, this will show up in UI like photoshop
$     --copyright %s       a copyright field

See this ocio-dev thread for additional usage discussions.

When exporting an ICC Profile, you will be asked to specify your monitor’s profile (it will be selected for you by default). This is because ICC Profile are not LUTs per se. An ICC Profile describes a color space and then needs a destination profile to calculate the transformation. So if you have an operation working and looking good on the monitor you’re using (and maybe its should choose its profile instead.

FAQ

Can you query a color space by name (like “Rec709”) and get back XYZ coordinates of its primaries and whitepoint?

Not currently.

OCIO is a color configuration ‘playback’ tool that tries to be as flexible as possible; color information such as this is often only needed / relevant at configuration authoring time. Making primaries / whitepoint required would limit the pipeline OCIO could service. In the strictest sense, we would consider OCIO to be a ‘baked’ representation of color processes, similar to how Alembic files do not store animation rig data, but rather only the baked geometry.

Also, remember that not all colorspaces using in visual effects even have strongly defined color space definitions. For example, scanned film negatives, when linearized with 1d transfer curves (the historical norm in vfx), do not have defined primaries/white point. Each rgb value could of course individually be tied to a specific color, but if you were to do a sweep of the pure ‘red channel’, for example, you’d find that it creates a curves in chromaticity space, not a single point. (This is due to the 1d linearization not attempting to undo the subtractive processes that created the pixels in the first place.

But many color spaces in OCIO do have very strongly defined white points/chromaticities. On the display side, for example, we have very precise information on this.

Perhaps OCIO should include optional metadata to tag outputs? We are looking at this as as a OCIO 1.2 feature.

Can you convert XYZ <-> named color space RGB values?

OCIO includes a MatrixTransform, so the processing capability is there. But there is no convenience function to compute this matrix for you. (We do include other Matrix convenience functions though, so it already has a place to be added. See MatrixTransform in export/OpenColorTransforms.h)

There’s talk of extended OCIO 1.2 to have a plugin api where colorspaces could be dynamically added at runtime (such as after reading exr chromaticity header metadata). This would necessitate adding such a feature.

What are the differences between Nuke’s Vectorfield and OCIOFileTransform?

(All tests done with Nuke 6.3)

Ext

Details

Notes

3dl

Matched Results

ccc

n/a

cc

n/a

csp

Difference

Gain error. Believe OCIO is correct, but need to verify.

cub

Matched Results

Note: Nuke’s .cub exporter is broken (gain error)

cube

Matched Results

hdl

n/a

mga/m3d

n/a

spi1d

n/a

spi3d

n/a

spimtx

n/a

vf

Difference

Gain error. Believe OCIO is correct, but need to verify.

All gain differences are due to a common ‘gotcha’ when interpolating 3d luts, related to internal index computation. If you have a 32x32x32 3dlut, when sampling values from (0,1) do you internally scale by 31.0 or 32.0? This is typically well-defined for each format, (in this case the answer is usually 31.0) but when incorrectly handled in an application, you occasionally see gain errors that differ by this amount. (In the case of a 32-sized 3dlut, 32/31 = ~3% error)

What do ColorSpace::setAllocation() and ColorSpace::setAllocationVars() do?

These hints only come into play during LUT baking, and are used to determine proper colorspace allocation handling for 3D LUTs. See this page How to Configure ColorSpace Allocation for further information. Note: OCIO v1 used allocation variables for the GPU renderer, but that is no longer necessary for OCIO v2.