LUT¶

Oak 的色彩管理基于 OpenColorIO（OCIO），并通过 OCIO LUT 节点加载外部 LUT 文件进行创意或技术转换。

色彩管理基础¶

每个项目拥有独立的 ColorManager，维护以下设置：

• OCIO 配置文件：项目使用的色彩空间配置文件路径。

• 默认输入色彩空间：新素材默认假设的色彩空间。

• 参考空间（Reference Space）：合成与调色的工作空间，可选 Scene Linear 或 Compositing Log。

• Display / View / Look：用于最终显示与风格 Look。

可在 序列 > 项目属性 > 色彩管理 中修改这些设置。如果没有指定外部 OCIO 配置，Oak 会回退到内置配置 :/ocioconf。

素材的色彩空间¶

• 如果素材元数据中包含色彩空间信息，Oak 会优先使用。

• 否则回退到项目的 默认输入色彩空间。

• 渲染时，素材会先被转换到 参考空间 再进行后续处理。

LUT 节点¶

OCIO LUT 节点用于把 .cube 或 .3dl 文件应用到纹理上。

节点参数¶

使用方法¶

1. 在节点编辑器中，把 OCIO LUT 节点接到需要调色的节点之后，例如：

   素材 → 变换 → OCIO LUT → 序列查看器
   

2. 在 参数编辑器 中点击 LUT File 路径，选择 .cube 或 .3dl 文件。

3. 选择 Direction：

   • Forward：把 LUT 的源空间映射到目标空间（常用于 Log→Rec.709、风格 LUT）。

   • Inverse：反向应用（用于还原或特殊效果）。

4. 在序列查看器中即可看到效果；导出时会使用原始高质量源并重新计算，LUT 效果会保留。

支持的 LUT 格式¶

当前仅支持：

• .cube

• .3dl

其它格式（.csp、.lut、.spi1d / .spi3d 等）暂不被 OCIO LUT 节点加载。

调色节点¶

除 LUT 外，Oak 还提供以下调色节点：

三色轮（Three-Way Color）¶

• 分别调整 Shadow / Midtone / Highlight 的颜色与强度。

• 使用 threewaycolor.frag 着色器实时计算。

OCIO 初级调色（Linear）¶

• 参数包括：Contrast、Offset、Exposure、Saturation、Pivot、Black Clamp、White Clamp。

• 基于 OCIO::GradingPrimaryTransform 在线性空间处理。

显示转换（Display Transform）¶

• 显式指定 Display、View 与 Direction，用于把参考空间转换到显示空间。

• 常用于需要精确控制色彩空间转换的场景。

颜色选择对话框¶

点击颜色参数会打开 ColorDialog：

• 色轮、HSV 明度条、数值输入、色板。

• 可选择色彩空间，返回值会转换到项目参考空间。

限制与已知问题¶

• OCIO LUT 节点没有全局 LUT 库，每个节点独立引用文件路径。

• 文件不存在或扩展名不受支持时，节点会原样透传输入（不报错但无效果）。

• ColorDialog 中 display → reference 的逆向转换被禁用，避免 OCIO 反向崩溃（FIXME）。

• OCIOGradingTransformLinearNode 中 clamp 的最小值动态限制被临时禁用，以免影响关键帧/连接。

• 测试覆盖：tests/gtest/color_lut_test.cpp 包含 LUT 扩展名、方向切换、空路径等回归测试。