OCIOGen Documentation

Table of Contents

• OCIOGen Documentation
  • Table of Contents
  • Project Overview
  • Installation
  • Local Installation
    • Faster Alternative Using uv
  • Running the Software
  • Graphical User Interface Usage (ociogen)
    • General Settings Tab
    • Colorspaces & Roles Tab
    • View Transforms Tab
    • Bottom Controls
  • Configuration Files (YAML)
    • config.yaml (formerly config_settings.yaml)
      • settings
      • roles
      • active_colorspaces
      • colorspaces
    • colorspaces.yaml
  • Command-Line Usage
    • Generating Configs (ociogen run)
    • Localizing Configuration Files (ociogen localize)

---

Project Overview

OCIOGen simplifies OpenColorIO config creation with a user-friendly GUI, flexible YAML definitions, automatic LUT discovery, and command-line generation capabilities. It provides both a graphical user interface (ociogen) and command-line operations (ociogen run, ociogen localize) to generate OCIO configs based on user-defined colorspace definitions and LUTs. All colorimetry math is built in, so all you need to provide for each colorspace is a set of CIE xy chromaticities, a transfer function and your desired reference space. The gamut conversion matrices to or from your reference space are calculated automatically.

Key Features:

• GUI for Interactive Configuration: Run ociogen to launch an intuitive graphical user interface to manage settings, select active colorspaces, configure roles, discover/edit/mutate view transforms, and generate the final OCIO config.
• Flexible Colorspace Definitions: Easily define custom colorspaces from CIE xy chromaticities, custom transfer functions based on a python function or OCIO v2 Built-in transform, with additional attributes like category, encodings, and aliases.
• OCIO v1/v2 Compatibility: Generate configs targeting either major OCIO version.
• YAML-based Configuration: Define core settings, roles, active colorspaces, and colorspace definitions in human-readable YAML files.
• Automatic LUT Discovery: Find user-provided LUTs and parse view name, shaper space and display space based on configurable filename patterns.
• View Transform Generation: Automatically create the necessary OCIO colorspaces and transforms for discovered LUTs.
• View Mutation: Automatically generate additional view transforms for different displays based on existing LUTs and mutation rules. For example, to automatically create "sRGB Display" views from a Rec.1886 LUT.
• Built-in Transform Support (OCIOv2): Optionally use OCIOv2 built-in mathematical transforms instead of generating 1D LUTs for transfer functions (use with caution due to precision issues).
• Command-Line Generation: Use ociogen run to generate configs directly from the terminal using a config.yaml file.
• Configuration Localization: Use ociogen localize to easily copy the default configuration files to your current directory for customization.

---

Installation

This project requires Python 3.7+. It is provided as a standard Python Package on PyPy.org.

To install ociogen, simply run

pip install ociogen

Local Installation

If you don't have network access or want to install locally in a virtual environment, here is how to accomplish that.

1. Create and Activate a Virtual Environment (Recommended)

It's highly recommended to install ociogen within a virtual environment to avoid conflicts with other Python projects or system packages.

• Create the environment:

  python -m venv .venv

  (You can replace .venv with your preferred directory name)

• Activate the environment:

  • Linux/macOS (bash/zsh):

    source venv/bin/activate

  • Windows (Command Prompt):

    venv\Scripts\activate.bat

  • Windows (PowerShell):

    venv\Scripts\Activate.ps1

  Your terminal prompt should change to indicate the active environment (e.g., (venv) your-user@host:...$).

2. Install OCIOGen

Once the virtual environment is active, you can install ociogen and its dependencies using pip.

• Standard Installation: Navigate to the root directory of the ociogen project (where pyproject.toml is located) and run:

  pip install .

  This installs the package into your virtual environment. If you skipped using a virtual environment in step 1 above, this same command will install the package on your system.

3. Deactivate the Virtual Environment (When Finished)

When you're done working with ociogen, you can deactivate the environment:

deactivate

Faster Alternative Using uv

If you grow weary of waiting for pip install . to complete, check out Astral's UV, a blazing fast Rust-based python package manager. Here is how to accomplish the same steps using uv instead:

# Create and activate the environment (uv automatically activates)
uv venv
source .venv/bin/activate # For linux and macos

# Install ociogen
uv pip install .

One caveate is that you must use a system installation of python3.7+ with uv, as it seems the custom compiled python versions do not support tkinter, python module we use for the gui.

---

Running the Software

After installing ociogen (and ensuring your virtual environment is active if you used one):

• Run the GUI:

  ociogen

  (Note: Running ociogen with no arguments launches the GUI)

• Run Command-Line Operations:

  ociogen run [options]
  ociogen localize [scope]

  (See Command-Line Usage for details)

The necessary dependencies (PyOpenColorIO, PyYAML) are automatically installed when you install the ociogen package using pip.

---

Graphical User Interface Usage (ociogen)

The GUI provides an interactive way to configure and generate the OCIO config. It is built with tkinter, so it should work out of the box with python on your system.

Run the GUI by executing ociogen with no arguments in your terminal (ensure your virtual environment is active if used).

The GUI loads the default config_settings.yaml and colorspaces.yaml on startup to populate the initial values. You can then modify these settings before generating the config.

General Settings Tab

This tab mirrors most options found in the settings section of config_settings.yaml.

• Config Name: Sets the config_name.
• Config Description: Sets the config_description (multi-line text input).
• OCIO Version: Selects the target ocio_version_major (1 or 2). Affects availability of subsequent options.
• Use Shortnames: Toggles the use_shortnames setting. Changes how colorspace names are displayed in other parts of the GUI and in the final config.
• Enable Descriptions: Toggles the enable_descriptions setting.
• Verbose Descriptions: Toggles the verbose_descriptions setting (only enabled if "Enable Descriptions" is checked).
• Enable Built-in Transforms (OCIOv2): Toggles the enable_builtins setting (only enabled if OCIO Version is 2).
• Enable Colorspace Encoding (OCIOv2): Toggles the enable_colorspace_encoding setting (only enabled if OCIO Version is 2).
• Enable Colorspace Aliases (OCIOv2): Toggles the enable_colorspace_aliases setting (only enabled if OCIO Version is 2).
• SPI1D LUT Precision (2^n): Sets the spi1d_lut_precision using a spinbox (8-16).
• Category Folder Names: Allows editing the mapping between colorspace categories (work, camera, display, image) and the desired folder/family names for applications.

Colorspaces & Roles Tab

This tab manages the selection of active colorspaces and the assignment of colorspaces to OCIO roles.

• Reference Colorspace (Scene-Linear): A dropdown list to select the reference_colorspace. The list is filtered to only show colorspaces defined with encoding: scene-linear in colorspaces.yaml.
• Active Colorspaces:
  • Listbox: Displays all available colorspaces (based on colorspaces.yaml). Use Ctrl+Click or Shift+Click to select multiple colorspaces to include in the final config. The names displayed respect the "Use Shortnames" setting.
  • Select All / Deselect All Buttons: Select or deselect all colorspaces in the list.
  • Ctrl+A / Cmd+A: Toggles the selection of all items in the listbox.
• Roles Configuration (Treeview):
  • Displays the OCIO roles loaded initially from config_settings.yaml.
  • Columns:
    • Role Name: The name of the OCIO role (e.g., scene_linear, color_timing).
    • Assigned Colorspace: The colorspace currently assigned to this role.
  • Editing:
    • Double-click a Role Name cell to edit the role name (must be unique, no spaces).
    • Double-click an Assigned Colorspace cell to select a colorspace from a dropdown list of all active colorspaces.
  • Reordering: Click and drag rows to change the order in which roles are defined in the final config.
  • Adding: Click "Add Role" to create a new role row (you will be prompted for a name).
  • Deleting: Select one or more rows and click "Delete Selected Role(s)" or press the Delete key.

View Transforms Tab

This tab handles the discovery, configuration, and mutation of view transforms based on LUT files.

• LUT Search Path: Specify the directory containing the view transform LUT files (.cube, .spi3d, .3dl, etc.). Use the "Browse..." button to select a directory.
• LUT Filename Pattern: Define the pattern (excluding extension) used to parse viewName, displaySpace, and optionally shaperSpace from LUT filenames (e.g., {viewName}__{shaperSpace}_to_{displaySpace}).
• Refresh Discovered LUTs: Click this button to scan the "LUT Search Path" using the "LUT Filename Pattern". The treeview below will be populated with discovered LUTs and any default mutations based on the rules in the initially loaded config_settings.yaml.
• View Transforms Treeview:
  • Displays discovered LUTs and user-added mutations.
  • Columns:
    • Type: Indicates if the row represents a LUT or a Mutated view.
    • Source: For LUT type, shows the original LUT filename. For Mutated type, shows which view/display it was mutated from.
    • View Name: The parsed or manually entered view name (e.g., "OpenDRT v1.0.0 Default").
    • Shaper Space: The parsed or manually selected shaper space (must be a log-encoded colorspace or a role resolving to one). Can be empty if the pattern doesn't include {shaperSpace}.
    • Display Space: The parsed or manually selected display colorspace (must have category: display).
    • Status: Shows the validation status (OK, OK (Mutated Default), OK (Mutated User), Manual Entry Required, or specific error messages).
  • Editing: Double-click cells in the View Name, Shaper Space, or Display Space columns to edit their values. Shaper Space and Display Space provide dropdowns filtered to valid options (log spaces/roles for shaper, display spaces for display). View Name is a text entry. Editing is restricted for Mutated rows (View/Shaper cannot be changed).
  • Validation: Edits trigger automatic validation. Rows with errors (e.g., invalid shaper, inactive display) are highlighted in red. Tooltips on status cells may provide more error details.
  • Reordering: Click and drag rows to change the order of views within their respective displays in the final config.
  • Context Menu (Right-Click):
    • Mutate Selected View(s)...: Available if one or more valid LUT rows are selected. Prompts for a target display and adds new Mutated rows to the list for that display, based on the selected LUT(s).
    • Delete Selected View(s): Available if any rows are selected. Deletes the selected rows (LUTs or Mutations) from the list.
  • Delete Key: Deletes the selected row(s).

Bottom Controls

Located at the bottom of the main window.

• Output Directory: Specify the parent directory where the final config folder (containing the .ocio file and LUTs) will be created. Use "Browse..." to select.
• Generate Config: Click this button to start the OCIO config generation process using all the settings configured in the GUI. It performs validation checks before proceeding.
• Status Bar: Displays messages about the current state or the outcome of operations (e.g., "Ready.", "Discovering LUTs...", "Config generated successfully...", "Error...").
• Dark Mode: Toggles the GUI theme between dark and light modes.

---

Configuration Files (YAML)

OCIOGen relies on two primary YAML files for its configuration: config_settings.yaml and colorspaces.yaml.

config.yaml (formerly config_settings.yaml)

This file (typically named config.yaml, though ociogen run --config allows specifying a different path) contains the main settings for the config generation process, including global options, role definitions, active colorspace lists, and view transform discovery rules. The ociogen localize command copies the default version of this file.

settings:
  # ... global settings ...
  view_transform_settings:
    # ... view transform specific settings ...
  view_mutate:
    # ... view mutation rules ...

roles:
  # ... role definitions ...

active_colorspaces:
  # ... list of active colorspace shortnames ...

# colorspaces: !include colorspaces.yaml # Include tag might be used if colorspaces are separate

settings

This section defines global parameters for the generated OCIO config.

• config_name (String): The base name for the generated OCIO config file and the directory containing it and its associated LUTs.
  • Example: OpenDRT_v1.0.0_full-config
• config_description (String): A description embedded within the generated OCIO config file.
  • Example: "An OCIO config generated with ociogen."
• config_location (String): The parent directory where the config folder (named using config_name) will be created. Supports ~ for the user's home directory.
  • Example: /path/to/your/ocio/configs/ or ~/ocio_configs
• ocio_version_major (Integer): Specifies the target major OCIO version (either 1 or 2). This affects available features and syntax.
  • Example: 1
• use_shortnames (Boolean): If true, use the shortname attribute from colorspaces.yaml as the colorspace name in the OCIO config where available. If false or shortname is missing, use the full name.
  • Example: false
• enable_descriptions (Boolean): If true, include the description field for each colorspace in the generated config.
  • Example: false
• verbose_descriptions (Boolean): If true (and enable_descriptions is true), use the full description from colorspaces.yaml. If false, use the colorspace's full name as the description.
  • Example: false
• enable_builtins (Boolean): (OCIOv2 only) If true, use OCIOv2 built-in mathematical transforms (like LogCameraTransform, ExponentWithLinearTransform) defined in tf_builtin in colorspaces.yaml instead of generating .spi1d LUTs from Python tf functions. Use with caution, as built-ins can be significantly less precise than high-resolution LUTs.
  • Example: false
• enable_colorspace_encoding (Boolean): (OCIOv2 only) If true, include the encoding attribute (e.g., scene-linear, log, sdr-video) for colorspaces in the generated config.
  • Example: false
• enable_colorspace_aliases (Boolean): (OCIOv2 only) If true, include the aliases attribute for colorspaces, using the alias field from colorspaces.yaml.
  • Example: false
• spi1d_lut_precision (Integer): Defines the precision for generated 1D LUTs (.spi1d) used for transfer functions. The LUT size will be 2ⁿ. A value of 13 results in 8192 entries.
  • Example: 13
• reference_colorspace (String): The name or shortname of the colorspace to be used as the central reference space (typically a scene-linear space). This gamut is what all other colorspaces calculate their matrices in reference to. Uses a YAML anchor (&ref_lin) for re-use in roles.
  • Example: &ref_lin filmlight-egamut2-lin
• reference_log_colorspace (String): The name or shortname of the primary log colorspace, often used for roles like color_timing. Uses a YAML anchor (&ref_log).
  • Example: &ref_log filmlight-egamut2-tlog
• category_folder_names (List of Dictionaries): Maps colorspace category values (from colorspaces.yaml) to folder names (Families) used in applications like Nuke.
  • Example:

    category_folder_names:
      - work: Working Spaces
      - camera: Camera Spaces
      - display: Display Spaces
      - image: Image Formation # Category for generated view transforms

• view_transform_settings (Dictionary): Contains settings related to view transform LUT discovery.
  • lut_search_path (String): The directory path (absolute or relative to the config.yaml file's location or the current working directory if not specified) where view transform LUTs are located. Supports ~ for home directory.
    • Example: /path/to/luts/ or ../shared_luts
  • lut_filename_pattern (String): A pattern used to parse information from LUT filenames (excluding the extension). Use placeholders {viewName}, {displaySpace}, and optionally {shaperSpace}. Underscores in the matched {viewName} part will be replaced with spaces.
    • Example: "{viewName}__{shaperSpace}_to_{displaySpace}"
• view_mutate (Dictionary): Defines rules for automatically generating additional view transforms for target displays based on LUTs found for a source display. The keys are source display shortnames, and the values are lists of target display shortnames. If a value is null or missing (like display-p3:), it means no targets are defined for that source. Use an empty list [] to explicitly define no targets.
  • Example:

    view_mutate:
      rec1886:
        - srgb-display
      display-p3: [] # Explicitly no targets for Display P3

roles

This section defines the standard OCIO roles and assigns a default colorspace (name or shortname) to each. The reference role is set automatically based on the reference_colorspace setting and should not be defined here. YAML anchors (*ref_lin, *ref_log) can be used to reference the colorspaces defined in the settings section.

• Example:

  roles:
    scene_linear: *ref_lin
    color_timing: *ref_log
    compositing_log: *ref_log
    # ... other roles

active_colorspaces

This is a list of colorspace shortnames (must match the shortname field in the colorspaces definitions, typically loaded from colorspaces.yaml). Only colorspaces whose shortname appears in this list will be included in the generated OCIO config. If this list is missing or empty in the YAML, all defined colorspaces will be considered active.

• Example:

  active_colorspaces:
    - bypass
    - xyz-d65
    - aces
    - acescg
    # ... other shortnames

colorspaces

This key typically uses the special !include tag (if using a custom YAML loader that supports it, like in the GUI's internal loading) to load the colorspace definitions from a separate file, usually colorspaces.yaml. When running ociogen run, it expects the colorspace definitions to be either directly embedded under a colorspaces: key in the main config.yaml or loaded via such an include mechanism if the YAML parser supports it. The ociogen localize all command copies the default colorspaces.yaml.

• Example (using include):

  # In config.yaml
  colorspaces: !include colorspaces.yaml

• Example (embedded):

  # In config.yaml
  colorspaces:
    - name: "sRGB Display"
      shortname: "srgb-display"
      # ... other properties ...
    - name: "ACEScg"
      shortname: "acescg"
      # ... other properties ...

colorspaces.yaml

This file contains a list of colorspace definitions. Each item in the list is a dictionary defining the properties of a single colorspace.

• name (String, Required): The full, descriptive name of the colorspace.
  • Example: "Filmlight E-Gamut / T-Log"
• shortname (String, Required): A concise, often filesystem-friendly name used for identification in active_colorspaces and potentially in the final OCIO config if use_shortnames is true. Must be unique.
  • Example: "filmlight-egamut-tlog"
• category (String, Optional): A category for organizing colorspaces (e.g., work, camera, display, image). Used by category_folder_names in config_settings.yaml.
  • Example: "camera"
• alias (String, Optional): (OCIOv2 only) An alternative, often very short, name for the colorspace. Used if enable_colorspace_aliases is true.
  • Example: "tlog"
• description (String, Optional): A textual description of the colorspace. Used if enable_descriptions is true. Can be multi-line.
  • Example: "Log encoding curve for Filmlight E-Gamut."
• encoding (String, Optional): (OCIOv2 only) Specifies the encoding type. Used if enable_colorspace_encoding is true. Valid values: scene-linear, log, sdr-video, hdr-video, data.
  • Example: "log"
• chr (List or String, Optional): Defines the chromaticity coordinates (gamut).
  • List: A list of 8 float values representing the xy coordinates of Red, Green, Blue, and White points [Rx, Ry, Gx, Gy, Bx, By, Wx, Wy]. A matrix transform to the reference space will be calculated.
    • Example: [0.7347, 0.2653, 0.0000, 1.0986, 0.0001, -0.0987, 0.32168, 0.33767]
  • String: The name or shortname of another colorspace defined in this file. This indicates that the current colorspace shares the same primaries as the referenced one. A ColorSpaceTransform will be generated between the referenced space and the reference role.
    • Example: "aces-ap0" (meaning this space uses ACES AP0 primaries)
• tf (String, Optional): The name of a Python transfer function defined in utilities/transfer_functions.py. An .spi1d LUT will be generated based on this function. The function name should ideally contain oetf (Optical to Electrical Transfer Function: usually for inverse/to_linear LUTs) or eotf/eocf (Electrical to Optical Transfer Function: usually for forward/from_linear LUTs) to guide the LUT generation direction.
  • Example: "oetf_arri_logc3"
• tf_builtin (Dictionary, Optional): (OCIOv2 only) Defines an OCIOv2 built-in mathematical transform to use instead of a Python function LUT (if enable_builtins is true).
  • type (String): The type of OCIO transform (e.g., LogCameraTransform, ExponentWithLinearTransform, LogAffineTransform, ExponentTransform, BuiltinTransform).
  • params (Dictionary): Parameters for the specified transform type, using snake_case keys (they will be converted to camelCase for OCIO). Refer to OCIO documentation for available parameters for each type.
    • Example:

      tf_builtin:
        type: LogCameraTransform
        params:
          lin_side_break: 0.010591
          log_side_slope: 0.247190
          # ... other params ...
          direction: inverse # 'forward' or 'inverse'

• forward (Boolean, Optional): Defines the primary direction of the transform group relative to the reference space. true means TO_REFERENCE, false means FROM_REFERENCE. Defaults to true if omitted. This affects the order of operations when multiple transforms (gamut + transfer function) are present.
  • Example: true

---

Command-Line Usage

The ociogen command provides subcommands for generating configurations and managing files directly from the terminal.

Generating Configs (ociogen run)

This command generates the OCIO configuration based on a YAML configuration file.

ociogen run [--config PATH] [--output DIR]

• Operation:

  1. Find Config: Looks for config.yaml in the current working directory by default.
  2. Override Config Path (Optional): If --config PATH is provided, it uses the YAML file at the specified PATH instead.
  3. Load Settings: Reads settings, roles, active colorspaces, and colorspace definitions from the chosen YAML file. It expects colorspace definitions either embedded under a colorspaces: key or included via !include colorspaces.yaml (if the parser supports it).
  4. Discover LUTs: Performs LUT discovery based on view_transform_settings within the config file.
  5. Apply Mutations: Applies view mutations based on view_mutate rules.
  6. Generate Output: Creates the OCIO config file (config.ocio) and associated LUTs inside a folder.
     • The output folder's name is determined by config_name in the YAML file.
     • The output folder's location is determined by config_location in the YAML file (relative to the YAML file's directory or CWD, supports ~).
  7. Override Output Directory (Optional): If --output DIR is provided, it places the generated config folder inside the specified DIR, overriding the config_location setting from the YAML file.

• Example:

  # Generate using config.yaml in the current directory
  ociogen run
  
  # Generate using a specific config file and output to a specific directory
  ociogen run --config ../configs/my_project_config.yaml --output /mnt/ocio_configs/

Localizing Configuration Files (ociogen localize)

This command copies the default configuration files included with the ociogen package to your current working directory, allowing you to easily customize them.

ociogen localize [scope]

• scope (Optional):

  • config (Default): Copies only config.yaml.
  • all: Copies both config.yaml and colorspaces.yaml.

• Operation: Checks if the target files already exist in the current directory. If they don't, it copies the default version(s) from the package data. It will print warnings if files already exist and skip copying them.

• Example:

  # Copy just the default config.yaml
  ociogen localize
  
  # Copy both config.yaml and colorspaces.yaml
  ociogen localize all

---