Decode HDR Latents 算子节点

专门解码具备原生高动态范围 (HDR) 的潜空间张量，施加专业电影级色调映射 (Tone Mapping)，并可选地将未压缩的原始场景线性 OpenEXR 帧序列无损落盘导出。

算子所属分类：ModularDiffusion/Encode\Decode

核心速查 (TL;DR)

原生继承并大幅拓展 Decode Media Latent：拥有相同的输入插槽与自适应图像/视频端口，专为影视级 HDR 视频管线（如 LTX 2.3 HDR）量身定制了色调映射与 EXR 序列帧导出支持；
双轨并行输出机制：
画布端口始终输出经过色调映射后的标准动态范围 (SDR) 预览图像或 .mp4 视频；
只要指定了 exr_output_folder 存储路径，系统会在色调映射介入前，将最底层的 16 位 / 32 位原始场景线性 HDR 每一帧无损写入磁盘为 OpenEXR 图像序列；
非 HDR 管线平稳回退兼容：如果输入的是常规标准管线，节点行为与基础 Decode 节点完全一致，不额外施加色调映射；
仅对支持线性帧输出的底层驱动生效：HDR 物理提取逻辑仅作用于明确返回线性浮点 np.ndarray 帧的管线驱动（如 LTX 2.3 HDR）。

Generate Media Latents → [Decode HDR Latents] → Save Image / Save Video
                                     └─────────→ (磁盘直接落盘保存原始线性 .exr 帧序列)

Decode HDR Latents 算子节点外观

端口名称	数据类型	是否必填	详细功能与业务规范说明
`pipeline`	`Pipeline Config`	是	来自上游 Pipeline Builder。必须与当初去噪生成潜变量的管线架构完全匹配。请使用支持 HDR 的专属模型（如 LTX 2.3 HDR）以激活线性帧输出通道。
`latent_tensor`	`LatentArtifact`	是	待反显解码的高动态潜空间特征张量。

端口名称	数据类型	详细功能与业务规范说明
`output_image`	`ImageArtifact`	历经色调映射压缩后的标准动态范围 (SDR) 成品图像。
`output_video`	`VideoUrlArtifact`	历经色调映射后的高质量标准 SDR MP4 视频流（仅在视频管线模式下显现）。
`logs`	`str`	记录每一帧 EXR 物理写入落盘耗时与路径的详细日志；仅在声明了 `exr_output_folder` 时填充。

参数名称	数据类型	默认值	详细业务功能与调优说明
`tone_mapping`	下拉枚举 (`clip \\| reinhard \\| aces_filmic \\| cv2_reinhard \\| cv2_mantiuk`)	`aces_filmic`	将场景线性 HDR 浮点数值压缩映射为 SDR 范围所采用的色调映射算法。`aces_filmic` 符合电影工业标准，高光滚降极为自然；非 HDR 管线忽略此项。
`fps`	`int` (1~120)	`25`	导出的视频播放帧率。仅在视频管线模式下显现。
`exr_output_folder`	文件路径 (path)	留空	存储未压缩的原始场景线性 HDR EXR 帧序列的物理目标目录或模板路径。留空则跳过物理落盘。
`save_exr_as_half_float`	`bool`	`True`	是否将 EXR 帧以 16 位半精度浮点 (`HALF`) 格式写入——文件体积大幅缩减 2.5 倍，且画面动态精度损失微乎其微。

aces_filmic 相对 clip 能保留极其平滑的高光细节：仅在色彩纯度精度要求极高或进行纯数值对比测试时使用强硬硬截断的 clip；在绝大多数影视级创作中，始终推荐首选 aces_filmic 算法。
EXR 文件名落盘三种自动解析规则：
规则 1：output/frames/（带有末尾正斜杠的目录）$\rightarrow$ 序列帧按 output/frames/frame_0000.exr、frame_0001.exr 格式自增命名；
规则 2：output/frames（无末尾斜杠且无后缀）$\rightarrow$ 解析逻辑与规则 1 完全一致，前缀词根默认为 frame；
规则 3：output/frames/shot.exr（显式以 .exr 结尾）$\rightarrow$ 自动以词干作为前缀，生成 output/frames/shot_0000.exr、shot_0001.exr 等标准化序列。
解码大画幅时务必关注物理显存：高分辨率或数十帧视频潜变量在 VAE 全量解码为高精度浮点时极耗显存；如遇 OOM 崩溃，请在最初的 Pipeline Builder 节点中开启 vae_slicing。