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 文件应用到纹理上。

节点参数¶

参数	说明
LUT File	LUT 文件路径，仅支持 `.cube` 和 `.3dl`。
Direction	`Forward` （正向应用）或 `Inverse` （反向应用）。
Input	上游纹理输入。

使用方法¶

在节点编辑器中，把 OCIO LUT 节点接到需要调色的节点之后，例如：
```
素材 → 变换 → OCIO LUT → 序列查看器
```
在 参数编辑器 中点击 LUT File 路径，选择 .cube 或 .3dl 文件。
选择 Direction：
- Forward：把 LUT 的源空间映射到目标空间（常用于 Log→Rec.709、风格 LUT）。
- Inverse：反向应用（用于还原或特殊效果）。
在序列查看器中即可看到效果；导出时会使用原始高质量源并重新计算，LUT 效果会保留。

LUT 库¶

Oak 提供全局 LUT 库（LUT Library）：一组会被扫描 LUT 文件的目录。在 编辑 > 偏好设置 > LUT 中通过 添加... / 移除 进行配置；目录会被递归扫描 .cube 和 .3dl 文件。

在 参数编辑器 中，OCIO LUT 节点的 LUT File 一行带有下拉框，列出库中的所有 LUT（以相对于所属库目录的路径显示），选择其中一项即可填入路径。对于库之外的文件，可选择 其他(自定义文件)... 并使用常规路径输入框和浏览按钮；浏览对话框的侧边栏也会提供 LUT 库目录的快捷方式。

支持的 LUT 格式¶

当前仅支持：

.cube
.3dl

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

错误处理¶

当 LUT 文件缺失、扩展名不受支持或 OCIO 加载失败时，节点会原样透传输入以保证渲染安全；同时节点会记录原因并显示在状态栏中，不再静默失败。

调色节点¶

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

三色轮（Three-Way Color）¶

分别调整 Shadow / Midtone / Highlight 的颜色与强度。
使用 threewaycolor.frag 着色器实时计算。

OCIO 初级调色（Linear）¶

参数包括：Contrast、Offset、Exposure、Saturation、Pivot、Black Clamp、White Clamp。
基于 OCIO::GradingPrimaryTransform 在线性空间处理。
Clamp 的 white > black 不变量会逐帧强制执行，因此即使 Black/White Clamp 打了关键帧或来自连接，也不会产生非法转换；当 Black Clamp 为静态值时，White Clamp 的 UI 最小值会自动跟随它。

显示转换（Display Transform）¶

显式指定 Display、View 与 Direction，用于把参考空间转换到显示空间。
常用于需要精确控制色彩空间转换的场景。

颜色选择对话框¶

点击颜色参数会打开 ColorDialog：

色轮、HSV 明度条、数值输入、色板。
可选择色彩空间，返回值会转换到项目参考空间。
Display 标签页与 display → reference 转换已启用：在显示色彩空间中取色会正确转换回参考空间（并有往返回归测试覆盖）。

限制与已知问题¶

OCIO LUT 节点仅加载 .cube 和 .3dl 文件；其它格式会被原样透传（并在状态栏中提示原因）。
测试覆盖：tests/gtest/color_lut_test.cpp 包含 LUT 扩展名、方向切换、空路径等回归测试；tests/gtest/lut_file_field_test.cpp 覆盖 LUT 库与 LUT 文件字段的 UI 行为。

LUT — Oak Video Editor Manual