academysoftwarefoundation / opencolorio

A color management framework for visual effects and animation.

OpenColorIO

Introduction

OpenColorIO (OCIO) is a complete color management solution geared towards motion picture production with an emphasis on visual effects and computer animation. OCIO provides a straightforward and consistent user experience across all supporting applications while allowing for sophisticated back-end configuration options suitable for high-end production usage. OCIO is compatible with the Academy Color Encoding Specification (ACES) and is LUT-format agnostic, supporting many popular formats.

OpenColorIO is released as version 2.0 and has been in development since 2003. OCIO represents the culmination of years of production experience earned on such films as SpiderMan 2 (2004), Surf's Up (2007), Cloudy with a Chance of Meatballs (2009), Alice in Wonderland (2010), and many more. OpenColorIO is natively supported in commercial applications like Katana, Mari, Nuke, Maya, Houdini, Silhouette FX, and others.

OpenColorIO is free and open source software (LICENSE), and one of several projects actively sponsored by the ASWF (Academy Software Foundation).

OpenColorIO Project Mission

The OpenColorIO project is committed to providing an industry standard solution for highly precise, performant, and consistent color management across digital content creation applications and pipelines.

OpenColorIO aims to:

• be stable, secure, and thoroughly tested on Linux, macOS, and Windows
• be performant on modern CPUs and GPUs
• be simple, scalable, and well documented
• be compatible with critical color and imaging standards
• provide lossless color processing wherever possible
• maintain config backwards compatibility across major versions
• have every new feature carefully reviewed by leaders from the motion picture, VFX, animation, and video game industries
• have a healthy and active community
• receive wide industry adoption

OpenColorIO Project Governance

OpenColorIO is governed by the Academy Software Foundation (ASWF). See GOVERNANCE.md for detailed information about how the project operates.

Web Resources

• Website: http://opencolorio.org
• Documentation: https://opencolorio.readthedocs.io/en/latest/
• Mailing lists:
  • Developer: [email protected]
  • User: [email protected]
• Slack workspace: https://opencolorio.slack.com
  • New users can join via http://slack.opencolorio.org

Reference Configs

Reference OCIO configuration files and associated LUTs can be found at the Imageworks OpenColorIO-Configs repository.

The following reference implementations are provided:

• SPI: Sony Pictures Imageworks
  • spi-anim
  • spi-vfx
• ACES: Academy Color Encoding System
  • aces_1.0.3
  • aces_1.0.2
  • aces_1.0.1
  • aces_0.7.1
  • aces_0.1.1
• Other
  • nuke-default

Sources for the newer builtin ACES configuration files can be found in the releases section of the OpenColorIO-Config-ACES repository.

Acknowledgements

OpenColorIO represents the generous contributions of many organizations and individuals. The "Contributors to the OpenColorIO Project" copyright statement used throughout the project reflects that the OCIO source is a collaborative effort, often with multiple copyright holders within a single file. Copyright for specific portions of code can be traced to an originating contributor using git commit history.

OpenColorIO was originally developed and made open source by Sony Pictures Imageworks. The core design, and the majority of OCIO 1.0 code was authored by Imageworks, who continue to support and contribute to OCIO 2.0 development.

The design and development of OpenColorIO 2.0 is being led by Autodesk. Autodesk submitted a proposal to revitalize the project in 2017, and have authored the majority of OCIO 2.0 code in the years since.

Significant contributions have also been made by Industrial Light & Magic, DNEG, and many individuals. See Contributors for a complete list.

See THIRD-PARTY.md for license information about portions of OpenColorIO that have been imported from other projects.

---

Images from "Cloudy With A Chance of Meatballs" Copyright 2011 Sony Pictures Inc. All Rights Reserved.

opencolorio's Issues

Add function to clear all internal caches.

We cache info occasionally, such as if a lut file exists, etc. Provide an API function for flushing all caches.

Add binary LUT transforms

Some apps will want to dynamically add ColorSpaces without touching disk. What if they want to specify a 1d or 3d lut? Perhaps an 'in memory' transform will let them do this. How would this work if the profile is not saved? These transforms will likely require explicit serialization calls to write out to known format. Maybe this could utilize an already existing format? Does this relate to the LUT generation code?

getProcessor should fail for ColorSpaces that do not exist

No matter if you have strictparsing enabled or not, config.getProcessor will always succeed even if the specified colorspace is not found. If you request a string which is not a colorspace, and not a role, the getProcessor call should throw an exception.

Add LUT export to API

We would like to export LUTs (1d,3d,shapers,etc) from the API. The 'default' behavior should be something simple, but large configurability will be required for experts. This will have to be rich enough, or provide enough implementation flexibility to allow for writing luts for all otherwise unsupported OCIO clients.

BuildColorSpaceOps does not optimize intermediate colorspace values

BuildColorSpaceOps often walks though one colorspace, on the way to the destination. However, these potential 'early-exit' locations are not tracked. We should refactor this code so the stack traversal history is shared such that early exits based on family names is properly utilized.

Add PyContext

Add Context support to python / config.getProcessor calls.

Remove CineonLogToLin Transform

CineonLogToLin was worth considering, but is probably appropriate to drop. It should not be a 'basic' transform operation that color spaces are built upon. It is too specific to a particular use case, but at the same time not configurable enough to be useful! A more appropriate way to achieve this effect would be to use a math log operator or a 1D lut.

Need GenerateLUT node

OCIO should include a node that handles LUT generation, a la nuke's GenerateLUT node. This would output a new 1D or 3D LUT of any known type. Bit allocation would be handled in a reasonable way, and would include support for shaper luts, etc.

Add config.setOriginalSourceFile(...) / getOriginalSourceFile()

The value for original source file is internally stored and used in relation to the lutpath. In some circumstances (such as testing in a dynamic ocio creation script) it's useful to set this value explicitly.

Add gamma control to Nuke's Display node

Add gamma control to Nuke's Display node. Should emulate the normal control, post display lut.

Wrap all implementation objects Ops, etc. in internal namespace

Would be nice for encapsulation purposes. But, is this needed when we're hiding symbols? Perhaps not...

typo on http://sites.google.com/site/opencolorio/profiles/spi-vfx-profile

"lnf is a full precision (16-bit) floating point colorspace. It is used for rendering and compositing." should be "lnf is a full precision (32-bit) floating point colorspace. It is used for rendering and compositing."

FileTransform interpolation behavior should be clarified with multi-lut files

Some LUT files, such a 3dl, actually contain multiple luts internally. (A simple example would be a 1D shaper lut and a 3D lut). When an interpolation is specified, which LUT does it refer to? Both? This intent needs to be clarified, and then all LUT loaders need to agree with the intent.

Provide rich Transform constructors

Currently, all transforms just have the default constructor and fcns are required to get/set all values. Why not allow for convenience a richer set of constructor functions? Alternatively, a bunch of builder factory functions could also work.

Allow default display device + default transform name to be explicit

Currently in OCIO profiles, the top-most entry for display device is default. This should be configurable.

make install shouldnt install cruft

sudo make_install does:

-- Installing: /usr/local/bin/ocio_core_tests
-- Installing: /usr/local/bin/OpenColorIOTest
-- Installing: /usr/local/bin/scripts/main.py
-- Installing: /usr/local/bin/scripts/ocio_info.py
-- Installing: /usr/local/lib/nuke6.2v1/OCIOColorSpace.so
-- Installing: /usr/local/lib/nuke6.2v1/OCIODisplay.so
-- Installing: /usr/local/lib/nuke6.2v1/OCIOLogConvert.so
-- Installing: /usr/local/lib/nuke6.2v1/OCIOFileTransform.so
-- Installing: /usr/local/share//nuke
-- Installing: /usr/local/share//nuke/init.py
-- Installing: /usr/local/share//nuke/menu.py
-- Installing: /usr/local/lib/python/PyOpenColorIO.so
-- Installing: /usr/local/include/PyOpenColorIO/PyOpenColorIO.h

Python should go in the right place, and we shouldnt litter /usr/local/bin with crap

Add Look support

A look would be a named alias to a transform (group transform, etc)

Update INSTALL with clear installation instructions

Add clear installation instructions for mac / linux, for both a system install and a Nuke install

Allow for non-clamping optimizations to be skipped.

Some performance optimizations (such as identity 1D luts), or ASC_CDLs that do not use gamma, skip clamping to preserve data as much as possible. While this behavior is useful, it's not always strictly correct. Provide an option to defeat this optimization.

See http://groups.google.com/group/ocio-dev/browse_thread/thread/a001177f8346acd2 for the initial discussion on this topic.

Add Config.family API

ColorSpace families are currently not really well support. Flesh out this API. Ideas include config.getHighestColorSpaceInFamily? Maybe allow for family names in getColorSpace?

Luma Channels / Fstop offset bug

On the spi-cg profile, viewing a luma image with filmlook has a visual discontinuity related to the use of fstop offset. At an offset of 0.0, the image has a particular look. At an offset of 0.00001 (which changes the op baking), the appearance changes substantially.

Update const correctness with impl

The impl pattern is defeating const correctness internally. See Context::Impl for an example on how to get this working.

Add .vf (vectorfield) lut format

Must be able to read Nuke's .vf format.

Per-Shot Looks / LUTs

OCIO should provide a workflow where per-shot looks are allowed. For client apps that work on a single 'shot', this workflow should be transparent. For clients that span multiple 'shots', such as an image playback utility, the ability to switch shots on the fly (with high performance) should be allowed.

This may involve search paths, global variables, etc.

Add makfile support for example apps

ociodisplay and ocioconvert should get real makefile support

Allow for display device environment mask

The list of allowed display devices should be filterable based on an envvar, OCIO_DISPLAY_MASK. This would allow for facility specific code to limit the allowed options (opt-in). Thus, on an artist workstation the env could be setup so the DLP tables are not presented to the user. This would also effect default values. If this value is unset, all options will be allowed.

Nuke node cacheIDs do not include configuration hash

The Nuke OCIO node's cacheIDs do not reflect the cacheID for the current configuration. For example:
*plug a gradient into an OCIOColorSpace

• transform from 'lg10' to 'lnf'
• Quit nuke, point to a new config that also has lg10 / lnf, restart.
• render the gradient followed by the OCIOColorSpace

You will have the cached old answer rather than the new correct image. (This can be alleviated by first choosing 'clear disk cache'). The reason is that the current configuration state is not reflected in the node in any way.

Probably, the simplest solution would be to allow a transform (or config?) to have a cacheID which is reflected on a hidden knob on the nuke node.

Update website

Add sections for "About", "Screenshots", "Documentation", etc. see http://www.virtualbox.org/ for a decent simple example.

Add Config.sanityCheck()

Right now it's possible to create transforms that are malformed at birth. For example, you can add roles that point to ColorSpaces that do not exist. Adding the error checking to each individual call is not ideal, as sometimes in normal workflows you do want to allow transient error states. (Why force someone to add the colorspace before the role? Both order of operations should be allowed).

Instead, a la OpenEXR, add a config.sanityCheck() which would check the whole profile for errors, and throw an exception if any problems were found.

Ideas to check:

• confirm all colorspace roles exist
• confirm there arent duplicate colorspaces
• confirm all colorspace families are specified.
• confirm all files exist with read permissions?
• confirm for all ColorSpaceTransforms the names spaces exist
• confirm no name conflicts between colorspaces and roles

Add Op Collapsing / Optimization

Right now there are many obvious cases of Ops that should, but do not collapse. The simplest example is Matrix + Matrix. This would help performance.

SPI-VFX config XYZ colorspace is not accurate

The SPI configs provide an XYZ colorspace for digital cinema masters, which is implemented as a post-process on the P3 Filmlook'd image. However, it does not account for the 48cd / 52cd luminance scaling in the DCDM. Need to address this.

Port itview

port itview (internal SPI app)

Provide YAML default mechanism to write fewer values

Right now, yaml serialization often spits out all values regardless of whether or not they are 'set'. While this is explicit and easy to understand, it makes for lengthy files. Perhaps in some cases it is more appropriate to omit the value unless a non-default is specified?

Rename UNKNOWN enum to UNSPECIFIED

This is potentially more accurate and descriptive. The enums which use the word 'UNKNOWN' are not unknown, the value is known! It's explicitly unspecified.

Need lattice node

A lattice generation node should be part of the OCIO toolkit. Should generate a 1D lut or 3D lut with allocations corresponding to the std ocio options (uniform, log2, etc).

Remove config->getDisplayColorSpaceName?

The whole use of device + transform name is just another color space alias, where the input key is 2 strings. Would it be possible to get rid of this hard-coded API and make it a convention instead? Is this preferable?

Rename ColorSpace->isTransformSpecified to isTransformExplicit

This is perhaps simpler to understand. The issue isn't whether the transform exists, it always exists. The issue is whether the user has explicitly specified a transform in that direction.

Along the same lines, should an explicit mechanism be added to prevent a colorspace direction from being allowed? Ex: hdbty<->qt?

Add Callback for SetGlobalConfig

If you're writing an app that uses the global config, and its state is reflected in a UI, and the user changes the config out from under you how can your app update? A callback, even a simple global one, will tell the main app that it's config is out of date.

Add SPI Workflow doc

Explain overview of SPI naming, how to use workflows.

per erich ocean...

Do you have any info you can share on how OCIO fits into your OSL/Arnold workflow? I'm currently using OSL with PBRT without any color management, and I'm ready to make the plunge and start using OCIO, but I'm not really seeing how the pieces fit together.

The page you wrote here was really helpful: http://sites.google.com/site/opencolorio/profiles/spi-vfx-profile

I guess I'm looking for more info on how to do the integration with OSL at the level of libraries -- use OIIO to do this, give this kind of data to OSL, get this kind of data out of the PBRT and save it as this.

Windows Support

Add support for compiling on Windows

config.setDefaultLumaCoefs normalize?

should this auto-normalize the input? (to force a sum to 1.0)

Add IFF support

Add an IFF profile

Handle null strings + null rcptrs across API

Most of the exposed API handles null strings and null rcptrs, but not all. This ticket is to validate the API in terms of Null robustness. Additionally, the python API helpers (such as BuildPyColorSpace) should be extended to create a NullRcPtr when the None object is passed. This will let APIs that rely on a null value work from python.

Add equality operator to OCIOTransforms

Add a function to test equality. ".equals(...)" May best be base level. Also expose in python.

OCIO Binary 'bundled' .config format

Need to add a binary 'bundled' file format, which wraps all luts and .ocio config info into a single file (to the extent possible). This would allow for great config portability. Options include .tgz, .zip.

CMake installation does not handle python versions well

Often you need to build with a customized python version, such as python2.5, for plugins in apps that use a hard-coded version. However, this version may be different from your system level installation. (and the python .so gets installed system-level regardless of the default python install). This problem needs to be addressed, perhaps by doing multiple python builds and making sure the installation dirs are version specific.

LUT interpolation upgrade

Current value is unspecified which makes the user always have to consider setting it. It would be more user friendly if a reasonable default was assumed. Perhaps linear?

Also, what about an option called LUT_INTERPOLATION_SMOOTHEST, which uses best available?

Add Allocation Transforms

There are no transforms that correspond to the colorspace allocations. These would be useful to expose.

Clarify intent of DEFAULT_COLOR_ROLE

What is the default role? How and when is it used? How does this relate to parseColorSpaceFromString and strict parsing? Clarify this mechanism.

Nuke LogConvert is applying backwards

What should be log to lin is actually the inverse operation.