AdjustImageLevels 专业色阶与动态范围映射节点

节点核心功能 (What is it?)

AdjustImageLevels 节点为创作者提供了媲美 Photoshop 专业“色阶”（Levels）工具的高精度图像影调调控能力。它允许您独立调整输入端黑场暗部（Shadows）、中间调伽马（Midtones Gamma）以及白场高光（Highlights），并重新映射到指定的输出动态范围区间，是校正画面曝光、挽救灰暗暗沉素材以及构建高反差电影感影调的核心利器。

典型适用场景 (When would I use it?)

在以下情况下使用该节点：

精细重塑图像的全局影调区间与灰阶阶调（Tonal Range）；
独立控制和矫正暗部死黑与高光过曝裁切；
利用非线性伽马曲线（Gamma Correction）提亮或压暗画面中间调；
制作通透的高对比度或柔和的低反差胶片质感；
修复因拍摄时光照不足或过度曝光导致的直方图失衡；
在自动化管线中对齐多张输入图像的整体明暗分布标准。

使用指南 (How to use it)

基础配置流程 (Basic Setup)

在工作流画布中添加 AdjustImageLevels 节点。
将图像数据源接入 input_image 输入插槽。
拖动输入色阶与输出色阶的滑块，实时观察色调变化。
在 output 引脚即可提取完成专业色阶校准后的全新图像资产。

参数输入插槽 (Parameters)

输入色阶配置 (Input Levels)

shadows（0–255，默认 0）：输入黑场暗部阈值：
- 图像中原先低于该数值的暗部像素将被强制映射为输出黑电平；
- 调高该值将压暗暗部，裁切更多深灰细节，增强画面沉稳厚重感。
midtones（0.1–10.0，默认 1.0）：中间调伽马（Gamma）校正系数：
- < 1.0：非线性提亮画面中间调（暗部和亮部锚定，主体整体变亮变透）；
- > 1.0：非线性压暗画面中间调；
- 1.0：保持原始线性中间调。
highlights（0–255，默认 255）：输入白场高光阈值：
- 图像中原先高于该数值的亮部像素将被强制映射为输出白电平；
- 调低该值将提亮高光，使灰白区域迅速冲顶至纯白，大幅提高明亮感。

输出色阶配置 (Output Levels)

output_shadows（0–255，默认 0）：输出黑场电平（最低亮度保底值）：
- 调高该值将使整幅图像的纯黑区域转变为深灰，形成类似褪色复古胶片的“黑场泛灰”效果。
output_highlights（0–255，默认 255）：输出白场电平（最高亮度封顶值）：
- 调低该值将压低整幅画面的最亮高光，避免刺眼过曝。

输出引脚 (Outputs)

output：应用了色阶查找表映射后输出的全新高动态范围图像工件（ImageArtifact）。

典型工作流示例 (Example)

拯救欠曝灰暗的人像照片：

使用 LoadImage 导入一张原图直方图偏灰、缺乏明暗层次的照片。
将其接入 AdjustImageLevels 节点的 input_image 参数。
精细设置色阶参数：
- 将 shadows 适度提至 20，夯实画面黑场；
- 将 midtones 降至 0.8，自然提亮人物肤色与主要细节；
- 将 highlights 收紧至 240，让高光更加通透饱满；
- 将 output_shadows 设为 5，保留暗部呼吸感。
连入 DisplayImage 查看瞬间焕然一新、层次分明的通透照片。

关键技术特性 (Important Notes)

预计算查表加速 (256-step LUT)：底层采用 256 阶硬件级查找表（Lookup Table）计算映射关系，毫秒级实时演算，绝无卡顿。
透明通道无损隔离 (RGBA Support)：针对 RGBA 图像，色阶映射严格限定在 RGB 色彩通道，Alpha 蒙版轮廓分毫不差。
输入参数自洽校验：节点自动防御非法输入，确保 shadows < highlights，杜绝色彩反相或数学除零错误。

常见问题与排查 (Common Issues)

画面没有发生变化：确认各滑块是否脱离了初始默认值（0, 1.0, 255）。
画面细节丢失（断层或死黑）：若将 shadows 设得过高或 highlights 设得过低，会导致大面积像素裁切（Clipping），建议结合直方图进行微调。