1 OpenColorIO Configuration for ACES#

The OpenColorIO Configuration for ACES is an open-source Python package implementing support for the generation of the OCIO configurations for the Academy Color Encoding System (ACES).

It is freely available under the New BSD License terms.

1.1 Features#

The following features are available:

Automatic OCIO Reference configuration generation for aces-dev CTL reference implementation.
- Discovery of aces-dev CTL transforms.
- Generation of the CTL transforms graph.
- Spreadsheet-driven generation.
Generators producing the OCIO CG and Studio configurations. - Spreadsheet-driven generation.
Included CLF transforms along with generator and discovery support.

1.2 User Guide#

User Guide#

The user guide provides an overview of OpenColorIO Configuration for ACES and explains important concepts and features, details can be found in the API Reference.

Installation Guide#

Cloning the Repository#

The OpenColorIO Configuration for ACES repository uses Git submodules thus cloning the repository requires initializing them:

git clone --recursive https://github.com/AcademySoftwareFoundation/OpenColorIO-Config-ACES.git

If you have already cloned the repository and forgot the –recursive argument, it is possible to initialize the submodules as follows:

git submodule update --init --recursive

Poetry#

The OpenColorIO Configuration for ACES repository adopts Poetry to help managing its dependencies, this is the recommended way to get started with development.

Assuming python >= 3.8 is available on your system along with OpenColorIO >= 2, the development dependencies are installed with Poetry as follows:

git clone --recursive https://github.com/AcademySoftwareFoundation/OpenColorIO-Config-ACES.git
cd OpenColorIO-Config-ACES
poetry install --extras "optional"

The aces-dev CTL reference graph can be plotted but it requires Graphviz to be installed on the system and having installed the optional pygraphviz: python package:

poetry install --extras "optional graphviz"

Docker#

Installing the dependencies for the previous config generator was not a trivial task. For ease of use an aswf-docker based container is now available.

Creating the container from the Dockerfile is done as follows:

docker build -t aswf/opencolorio-config-aces:latest .

or alternatively, if the dependencies described in the next section are satisfied:

invoke docker build

Then, to run bash in the container:

docker run -it -v ${PWD}:/home/aswf/OpenColorIO-Config-ACES aswf/opencolorio-config-aces:latest /bin/bash

Pypi#

The OpenColorIO Configuration for ACES package requires various dependencies in order to run and be able to generate the OCIO configurations:

Primary Dependencies#

Optional Dependencies#

Development Dependencies#

Once the dependencies are satisfied, the OpenColorIO Configuration for ACES package can be installed from the Python Package Index by issuing this command in a shell:

pip install --user opencolorio-config-aces

Usage#

Tasks#

Various tasks are currently exposed via invoke.

This is currently the recommended way to build the configuration until a dedicated CLI is provided.

Listing the tasks is done as follows:

invoke --list

Reference Config#

Task	Command
Build	invoke build-config-reference
Build (Docker)	invoke docker-run-build-config-reference
Updating Mapping File	invoke update-mapping-file-reference

CG Config#

Task	Command
Build	invoke build-config-cg
Build (Docker)	invoke docker-run-build-config-cg
Updating Mapping File	invoke update-mapping-file-cg

Studio Config#

Task	Command
Build	invoke build-config-studio
Build (Docker)	invoke docker-run-build-config-studio
Updating Mapping File	invoke update-mapping-file-studio

Process#

aces-dev Discovery & Classification#

The config generation process starts with a set of definitions and classes to discover, parse and classify the CTL transforms from aces-dev:

Note

This approach allowed us to improve the consistency of the CTL transforms ACEStransformID while fixing various filename issues.

Using ACES2065-1 and OCES as connection spaces, it is possible to build a colour conversion graph with all the high-level relevant transforms.

Analytical & Reference Configs Generation#

The colour conversion graph is then used to create the Analytical config that maps 1-to-1 the aces-dev CTL transforms to theoretical OpenColorIO builtin transforms. This config does not work but it is useful to test basic generation capabilities whilst diagnosing issues in the mapping.

The Reference config is driven by a CSV file generated from a spreadsheet mapping the ACEStransformID to OpenColorIO builtin transforms.

opencolorio_config_aces.generate_config_aces()

CLF Transforms Generation, Discovery & Classification#

The working group decided to express additional colour transforms using CLF. Some CLF transforms can be serialised into a config which reduces the need for external files. Each CLF transform has a CLFtransformID specified according to the CLF Formatting for ACES OCIO Config document.

The repository contains code to generate, discover and classify the additional CLF transforms that the CG and Studio configs require.

CG Config Generation#

The CG config generator also uses a CSV file generated from a spreadsheet that expresses which ACEStransformID should be used from the Reference config and which CLFtransformID should be used from the shipped CLF transforms.

opencolorio_config_aces.generate_config_cg()

The conversion process is as follows:

aces-dev Discovery & Classification -> Reference Config Generation -> CLF Transforms Generation, Discovery & Classification -> CG Config Generation

Studio Config Generation#

The Studio config generator follows the same approach but uses a different pivot table of the spreadsheet.

opencolorio_config_aces.generate_config_studio()

The conversion process is as follows:

aces-dev Discovery & Classification -> Reference Config Generation -> CLF Transforms Generation, Discovery & Classification -> Studio Config Generation

1.3 API Reference#

API Reference#

OpenColorIO Configuration for ACES#

Common LUT Format Discovery#

opencolorio_config_aces

`classify_clf_transforms`(...)	Classify given CLF transforms.
`discover_clf_transforms`([root_directory])	Discover the CLF transform paths in given root directory: The given directory is traversed and the *.clf files are collected.
`filter_clf_transforms`(clf_transforms[, ...])	Filter given CLF transforms with given filterers.
`print_clf_taxonomy`()	Print the builtins CLF taxonomy:
`unclassify_clf_transforms`(...)	Unclassifie given CLF transforms.

Common LUT Format Generation#

opencolorio_config_aces

generate_clf_transform(filename, transforms, ...)

Take a list of transforms and some metadata and write a CLF transform file.

Ancillary Objects

opencolorio_config_aces.clf

`generate_clf_transforms_arri`(output_directory)	Generate CLF files for ARRI color encodings and save to disk.
`generate_clf_transforms_bmdfilm`(output_directory)	Make the CLF file for BMDFilm_WideGamut_Gen5 plus matrix/curve CLFs.
`generate_clf_transforms_canon`(output_directory)	Make the CLF file for Canon C-Log3 Cinema Gamut plus matrix/curve CLFs.
`generate_clf_transforms_davinci`(output_directory)	Make the CLF file for DaVinci Intermediate Wide Gamut plus matrix/curve CLFs.
`generate_clf_transforms_itu`(output_directory)	Generate OCIO Utility CLF transforms.
`generate_clf_transforms_ocio`(output_directory)	Generate OCIO Utility CLF transforms.
`generate_clf_transforms_panasonic`(...)	Make the CLF file for V-Log - V-Gamut plus matrix/curve CLFs.
`generate_clf_transforms_red`(output_directory)	Make the CLF file for RED Log3G10 REDWideGamutRGB plus matrix/curve CLFs.
`generate_clf_transforms_sony`(output_directory)	Make all the Sony CLFs.

Generation#

Profile Version#

opencolorio_config_aces

`ProfileVersion`([major, minor])	Define the data container for an OpenColorIO config profile version.
`PROFILE_VERSION_DEFAULT`	Define the data container for an OpenColorIO config profile version.
`SUPPORTED_PROFILE_VERSIONS`	Built-in mutable sequence.

Config Generation Common Objects#

opencolorio_config_aces

`ConfigData`(schema_version, profile_version, ...)	Define the data container for an OpenColorIO config.
`deserialize_config_data`(path)	Deserialize the JSON OpenColorIO config data container at given path.
`generate_config`(data[, config_name, ...])	Generate the OpenColorIO config from given data.
`serialize_config_data`(data, path)	Serialize the OpenColorIO config data container as a JSON file.
`validate_config`(config)	Validate given OpenColorIO config.

Factories#

opencolorio_config_aces

`BUILTIN_TRANSFORMS`	Mapping of OpenColorIO builtintransforms to their profile version.
`TRANSFORM_FACTORIES`	OpenColorIO transform factories.
`colorspace_factory`(name[, family, encoding, ...])	OpenColorIO Colorspace factory.
`group_transform_factory`(transforms)	OpenColorIO GroupTransform factory.
`look_factory`(name[, process_space, ...])	OpenColorIO Look factory.
`named_transform_factory`(name[, family, ...])	OpenColorIO NamedTransform factory.
`produce_transform`(transform)	Produce given transform.
`transform_factory`(**kwargs)	OpenColorIO transform factory.
`view_transform_factory`(name[, family, ...])	OpenColorIO ViewTransform factory.

Reference Configuration#

aces-dev Discovery#

opencolorio_config_aces

`version_aces_dev`()	Return the current aces-dev version, trying first with git, then by parsing the CHANGELOG.md file.
`classify_aces_ctl_transforms`(...)	Classifie given ACES CTL transforms.
`discover_aces_ctl_transforms`([root_directory])	Discover the ACES CTL transform paths in given root directory: The given directory is traversed and the *.ctl files are collected.
`filter_ctl_transforms`(ctl_transforms[, ...])	Filter given ACES CTL transforms with given filterers.
`print_aces_taxonomy`()	Print aces-dev taxonomy:
`unclassify_ctl_transforms`(...)	Unclassifie given ACES CTL transforms.

aces-dev Conversion Graph#

opencolorio_config_aces

`build_aces_conversion_graph`(ctl_transforms)	Build the aces-dev conversion graph from given ACES CTL transforms.
`conversion_path`(graph, source, target)	Return the conversion path from the source node to the target node in the aces-dev conversion graph.
`ctl_transform_to_node`(graph, ctl_transform)	Return the node name from given ACES CTL transform.
`filter_nodes`(graph[, filterers])	Filter given aces-dev conversion graph nodes with given filterers.
`node_to_ctl_transform`(graph, node)	Return the ACES CTL transform from given node name.
`plot_aces_conversion_graph`(graph, filename)	Plot given aces-dev conversion graph using Graphviz and pyraphviz.

aces-dev Reference Config Generator#

opencolorio_config_aces

`ColorspaceDescriptionStyle`(value)	Enum storing the various OpenColorIO Colorspace description styles.
`version_config_mapping_file`([path])	Return the current version of given CSV mapping file.
`generate_config_aces`([config_name, ...])	Generate the aces-dev reference implementation OpenColorIO config using the Mapping method.

ACES Computer Graphics (CG) Config Generator#

opencolorio_config_aces

generate_config_cg([data, config_name, ...])

Generate the ACES Computer Graphics (CG) OpenColorIO config.

ACES Studio Config Generator#

opencolorio_config_aces

generate_config_studio([data, config_name, ...])

Generate the ACES Studio OpenColorIO config.

Utilities#

Common#

opencolorio_config_aces.utilities

`ROOT_BUILD_DEFAULT`	Path subclass for non-Windows systems.
`DocstringDict`	A `dict` sub-class that allows settings a docstring to `dict` instances.
`first_item`(iterable[, default])	Return the first item of given iterable.
`common_ancestor`(*args)	Return the common ancestor of given iterables.
`paths_common_ancestor`(*args)	Return the common ancestor path from given paths.
`vivification`()	Implement supports for vivification of the underlying dict like data-structure, magical!
`vivified_to_dict`(vivified)	Convert given vivified data-structure to dictionary.
`message_box`(message[, width, padding, ...])	Print a message inside a box.
`is_colour_installed`([raise_exception])	Return if Colour is installed and available.
`is_jsonpickle_installed`([raise_exception])	Return if jsonpickle is installed and available.
`is_networkx_installed`([raise_exception])	Return if NetworkX is installed and available.
`REQUIREMENTS_TO_CALLABLE`	Mapping of requirements to their respective callables.
`required`(*requirements)	Decorate a function to check whether various ancillary package requirements are satisfied.
`is_string`(a)	Return if given \(a\) variable is a string like variable.
`is_iterable`(a)	Return if given \(a\) variable is iterable.
`git_describe`()	Describe the current OpenColorIO Configuration for ACES git version.
`matrix_3x3_to_4x4`(M)	Convert given 3x3 matrix \(M\) to a raveled 4x4 matrix.
`multi_replace`(name, patterns)	Update given name by applying in succession the given patterns and substitutions.
`regularise_version`(version[, add_v_prefix])	Regularise given version name by either adding or removing a v affixe.
`validate_method`(method, valid_methods[, message])	Validate whether given method exists in the given valid methods and returns the method lower cased.
`google_sheet_title`(url)	Return the title from given Google Sheet url.
`slugify`(object_[, allow_unicode])	Generate a SEO friendly and human-readable slug from given object.

Indices and tables#

1.4 About#

OpenColorIO Configuration for ACES by OpenColorIO Contributors
Copyright Contributors to the OpenColorIO Project – ocio-dev@lists.aswf.io
This software is released under terms of New BSD License: https://opensource.org/licenses/BSD-3-Clause
AcademySoftwareFoundation/OpenColorIO-Config-ACES