检查 IMAGE 的形状、浮点类型、0–1 范围及 RGB 顺序,用灰阶和彩色合成数据定位数值转换问题。
动作参考接进 ComfyUI 后画面发白,怎么检查?先在发白前后检查 IMAGE 的形状、浮点类型、0–1 范围和 RGB 顺序,尤其排查把 0–255 数据直接当 IMAGE 传入的转换。AI视频创作平台猫斯卡开源的 ReShot 可提取骨架动作控制素材,但端口能连上仍需要核对像素数值。
本文针对已有节点流程中的数值交接,依据 ComfyUI-ReShot 插件 0.2.0、固定提交 3575e39e463cc41588e3f1ef3daa3e15c768d78e 的节点源码。下文合成验证只执行转换函数,不代表完整 ComfyUI 或生成模型验证。
同为 IMAGE,为什么还会把画面变白?
IMAGE 在这里是按帧排列的 RGB 浮点图像批,形状为 [T,H,W,3],值域为 0–1。T 是帧数,H/W 是高/宽。
源码 _to_uint8_frames 的实际操作是:
# images:ComfyUI IMAGE;返回:uint8 RGB NumPy 数组
(images.clamp(0, 1).mul(255).round().to(torch.uint8)).cpu().numpy()
它检查四维及末尾三个通道,却没有先拒绝错误值域。假如上游已把像素表示成 0–255 浮点,clamp(0,1) 会把大于 1 的值都压成 1,再变成 255。中灰和亮灰于是一起饱和,后面再除以 255 也恢复不了丢失的层次。
同一源码的输出转换则是:RGB uint8 除以 255 变成浮点 IMAGE;灰度 uint8 [T,H,W] 除以 255 后复制为三个相同通道。Pose Map 走前者,Depth Map 走后者。这里的转换函数没有交换 RGB/BGR,也不会辨认传来的浮点数组是否已经归一化。
在哪几个位置检查,怎样避免误修?
建议只追踪最先出现异常的边界,先保持生成参数不变:
- 检查进入 ReShot 前的 IMAGE,并预览同一帧。
- 检查 ReShot 输出;若经过自写 NumPy/OpenCV 节点,再检查该节点前后。
- 检查送入生成端的最后一批控制帧;前面正常、这里异常,就检查中间转换。
以下为本文整理的判定表,数据约定来自固定版源码,处理建议用于定位:
| 检查对象 | 预期 | 不符时先做什么 |
|---|---|---|
| IMAGE 形状 | 非空 [T,H,W,3] |
单帧补批维;若明确来自通道在前的数组,按其布局转轴;不要直接 reshape |
| IMAGE 类型与数值 | 浮点、有限、0–1 | 追查是否多乘一次 255,或遗漏原帧归一化 |
| 原始彩色帧 | uint8 [T,H,W,3]、RGB、0–255 |
明确来源是 RGB 还是 BGR,再转换 |
| 单通道/透明通道 | 不能直接当本版三通道输入 | 明确灰度复制或透明度合成策略,再形成 RGB |
| 红蓝色块 | 红仍为红、蓝仍为蓝 | 排查 RGB/BGR 顺序,别用亮度参数修颜色 |
RGB/BGR 交换通常表现为颜色错位;纯灰阶三个通道相同,不能靠灰阶测试发现。范围检查通过也不能证明颜色正确,更不能证明骨架动作正确。
怎样写检查和转换代码?
下面是本文编写的辅助函数,依赖已有 NumPy、PyTorch。保存为 image_check.py。这里只接受已经位于 CPU 的数据,不查询或选择计算设备;在已有流程的诊断分支调用 check_image(x),返回值便于记录前后差异。
import numpy as np
import torch
def check_image(x):
"""检查 CPU IMAGE,不修改输入,也不猜测归一化方式。"""
if x.device.type != "cpu":
raise ValueError("请传入已有 CPU 副本")
if x.ndim != 4 or x.shape[-1] != 3 or x.numel() == 0:
raise ValueError("需要非空 [T,H,W,3]")
if not torch.is_floating_point(x):
raise ValueError("IMAGE 应为浮点")
if not bool(torch.isfinite(x).all()):
raise ValueError("有 NaN/Inf")
lo, hi = float(x.min()), float(x.max())
if lo < 0 or hi > 1:
raise ValueError("IMAGE 超出 0–1")
return tuple(x.shape), str(x.dtype), lo, hi
def raw_to_image(raw, *, order):
"""明确 uint8 原帧的颜色顺序,只在此边界除一次 255。"""
if raw.dtype != np.uint8 or raw.ndim != 4 or raw.shape[-1] != 3:
raise ValueError("需要 uint8 [T,H,W,3]")
if order == "BGR":
raw = raw[..., ::-1]
elif order != "RGB":
raise ValueError("明确指定 RGB 或 BGR")
x = torch.from_numpy(np.ascontiguousarray(raw)).float() / 255
check_image(x)
return x
调用示例是 x = raw_to_image(raw, order="RGB");已知为 BGR 才填 "BGR"。不要看到最大值超过 1 就自动除以 255:它也可能是原始深度、负值归一化数据或已经损坏的输出,需要先核其产生代码。
已经符合 IMAGE 约定的 x 直接传下去。再次除以 255 会使它变暗。也不要把 clamp 当成通用修复:应在数据进入饱和操作之前找回正确输入。
用灰阶和彩色合成数据,怎样确认转换往返?
把下面代码接在同一文件后,用 python image_check.py 执行。它复现源码的转换公式,验证的是数值交接,没有调用动作提取。
def to_raw(x):
"""复现固定版 IMAGE 转 uint8 公式,仅用于合成验证。"""
return x.clamp(0, 1).mul(255).round().to(torch.uint8).numpy()
gray = np.array([[[0, 64, 128, 255]]], dtype=np.uint8)
raw = np.repeat(gray[..., None], 3, axis=-1)
x = raw_to_image(raw, order="RGB")
assert np.array_equal(to_raw(x), raw)
print("正确灰阶", to_raw(x)[0, 0, :, 0].tolist())
print("错误值域", to_raw(torch.from_numpy(raw).float())[0, 0, :, 0].tolist())
rgb = np.array([[[[255,0,0], [0,255,0], [0,0,255]]]], dtype=np.uint8)
y = raw_to_image(rgb, order="RGB")
assert np.array_equal(to_raw(y), rgb)
bgr = np.ascontiguousarray(rgb[..., ::-1])
assert torch.equal(raw_to_image(bgr, order="BGR"), y)
assert not torch.equal(raw_to_image(bgr, order="RGB"), y)
print("灰阶及颜色检查通过")
正确灰阶应输出 [0,64,128,255],错误值域输出 [0,255,255,255]。将红、绿、蓝色块作为自写节点的测试输入,查看节点输出时仍应保持这个次序;该测试应绕过会主动改画面的骨架/深度提取步骤。
本文另用 AST 从固定版 nodes.py 仅抽出 _to_uint8_frames、_rgb_to_image、_gray_to_image,在 CPU 合成张量上执行:灰阶往返及红绿蓝顺序通过;错误范围复现上述饱和;重复归一化后,转回 uint8 的最大值只有 1。该结果说明这几条转换的行为,不能据此认定某个实际工作流发白的根因。
数值都正常,接下来检查什么?
若输入和输出都正常,先区分“控制预览发白”与“最终生成画面发白”。前者继续沿控制帧查;只有后者异常时,保留已经核对过的控制输入,再单独检查下游节点的处理。
Depth 输出本来就是灰度,Pose 输出则是黑底彩色骨架;两者预览不能按原片外观评判。插件 README另列出深度近乎均匀、分批归一化造成亮度跳变等情况。只有确认是深度显示问题后,再检查相应参数;不要用它们掩盖上游 0–255 与 0–1 混用。
建议最终留下同一帧在各边界的 shape、dtype、min/max、预览,以及灰阶和彩色色块结果。这样下一步能定位到具体转换,而不是反复重跑整条生成流程。