LUT¶

Oak’s color management is built on OpenColorIO (OCIO). Use the OCIO LUT node to load external LUT files for creative or technical transforms.

Color Management Basics¶

Each project has its own ColorManager with the following settings:

• OCIO config file: The color-space configuration file used by the project.

• Default input color space: The assumed color space for new footage.

• Reference space: The working space for compositing and grading, either Scene Linear or Compositing Log.

• Display / View / Look: Used for final display and stylistic looks.

You can change these in Sequence > Project Properties > Color Management. If no external OCIO config is specified, Oak falls back to the built-in :/ocioconf configuration.

Footage Color Space¶

• If a footage file’s metadata contains a color space, Oak uses it.

• Otherwise it falls back to the project’s default input color space.

• During rendering, footage is transformed into the reference space before further processing.

The OCIO LUT Node¶

The OCIO LUT node applies a .cube or .3dl file to a texture.

Node Parameters¶

Usage¶

1. In the Node Editor, place an OCIO LUT node after the node you want to grade, for example:

   Footage → Transform → OCIO LUT → Sequence Viewer
   

2. In the Param Editor, click the LUT File path and choose a .cube or .3dl file.

3. Choose Direction:

   • Forward: maps the LUT’s source space to its target space (common for Log→Rec.709 or stylistic LUTs).

   • Inverse: applies the LUT in reverse (for restoration or special effects).

4. The result is visible in the Sequence Viewer. On export, the original high-quality source is re-rendered and the LUT effect is preserved.

LUT Library¶

Oak maintains a global LUT library: a set of directories that are scanned for LUT files. Configure it in Edit > Preferences > LUT with Add... / Remove; directories are scanned recursively for .cube and .3dl files.

In the Param Editor, the LUT File row of an OCIO LUT node has a combo box listing all library LUTs, shown as paths relative to their library directory. Picking one fills in the path. For files outside the library, use the Other (Custom File)... entry together with the regular path field and browse button. The browse dialog also offers the library directories as sidebar shortcuts.

Supported LUT Formats¶

Currently supported:

• .cube

• .3dl

Other formats (.csp, .lut, .spi1d / .spi3d, etc.) are not loaded by the OCIO LUT node.

Error Handling¶

If the LUT file is missing, has an unsupported extension, or fails to load in OCIO, the node passes the input through unchanged so rendering stays safe. The node records the reason and shows it in the status bar instead of failing silently.

Color Grading Nodes¶

Besides LUTs, Oak provides:

Three-Way Color¶

• Adjusts Shadow / Midtone / Highlight color and intensity.

• Rendered in real time using the threewaycolor.frag shader.

OCIO Grading Primary (Linear)¶

• Parameters: Contrast, Offset, Exposure, Saturation, Pivot, Black Clamp, White Clamp.

• Processes in linear space using OCIO::GradingPrimaryTransform.

• The white>black clamp invariant is enforced per frame, so keyframed or connected clamp values cannot produce invalid transforms. When the black clamp is a static value, the white clamp’s UI minimum tracks it automatically.

Display Transform¶

• Explicitly sets Display, View, and Direction for converting reference space to display space.

• Useful when you need precise control over the color-space transform.

Color Picker Dialog¶

Clicking a color parameter opens the ColorDialog:

• Color wheel, HSV value slider, numeric inputs, and swatches.

• A color-space chooser; returned values are converted to the project reference space.

• The Display tab and display→reference conversion are enabled: a color picked in display space is converted back to the reference space correctly (covered by a round-trip regression test).

Limitations and Known Issues¶

• Only .cube and .3dl files are loaded by the OCIO LUT node; other formats are passed through unchanged (with a status-bar message).

• Regression tests for LUT behavior are in tests/gtest/color_lut_test.cpp; LUT library and LUT file-field UI tests are in tests/gtest/lut_file_field_test.cpp.