1hew
0552ee57f2
feat(float): 新增 Float Mask Area Ratio，输出遮罩覆盖整幅图像的面积比例（0–1 浮点数）：软值按权重计算、批次取平均、越界先钳制，None / 空张量 / 非遮罩输入返回 0.0，round（0–10，默认 2）控制小数位，前端在 float 输出上直接显示数值。 feat(text): 新增 Text System Prompt，把 utils/system_prompt/ 下的每个 .txt 作为 <模型>/[<语言>] <名称> 下拉项并原样输出正文；键表启动时扫描一次、正文按 mtime 热更新、_ / . 前缀跳过，目录为空或键不存在返回 ""。内置 Qwen-Image-2.1 t2i / edit 提示词改编自 benjiyaya/ComfyUI-Qwen-Image-2.1-Prompt-Enhancer（MIT）。 feat(image): Image Crop With BBox Mask 的 auto 预设改为自适应构图：先忽略稀疏噪点，比例与最近标准比例线性偏差 ≤30% 时才吸附，对齐后的框必然放进原图；scale_strength 改为取景权重，0 贴遮罩、1 近似全图，宽高各自按对数过渡。 feat(util): Range Mapping 的小数位输入 rounding 更名为 round（范围 0–10、默认 3 不变），与新浮点节点统一，旧工作流该参数回落到默认值。 refactor(shared): 把成对像素颜色估计迁到 utils/_color_fit.py 并由 Image Align Change Mask 复用，结构采样、增益/偏置上限与留出验证收敛到一处，校正幅度保持原包络。 refactor(pad): 统一 Image Pad By BBox Mask、Image Edge Crop/Pad、Multi Image Batch、Multi Image Stitch、Multi Video Stitch、Image Main Stitch、Image Edit Stitch、Image Resize Universal / Area 与 Image Minimum Area 的 pad_color 空值语义：留空或 transparent 一律输出 RGBA（3 通道扩为 4 通道，原内容不透明、补边 (0,0,0,0)；resize 系列 crop / stretch 不补边仍为 RGB），resize 系列空值底色不再回落黑色。 test: 新增颜色拟合内核、Float Mask Area Ratio、Text System Prompt、auto 取景链路（噪点、长条图、比例吸附、divisible_by、scale_strength 过渡、贴边主体平移、批次）以及空值 / transparent 补边的回归测试。 docs: 新增两个新节点的中英文文档，更新 Image Crop With BBox Mask / Range Mapping 等 21 份文档，README 节点列表新增「浮点节点」分区并在致谢标注内置提示词来源。 chore(release): 版本号升至 4.4.0。
4.9 KiB
4.9 KiB
Image Crop With BBox Mask - 图像遮罩智能裁切
节点功能： 根据遮罩（Mask）的边界框（Bounding Box）智能裁切图像，支持多种比例控制、尺寸约束和批量处理。同时输出裁切后的图像、对应的遮罩以及原始位置的边界框遮罩，便于后续还原。
输入
| 参数名称 | 入端选择 | 数据类型 | 默认值 | 取值范围 | 描述 |
|---|---|---|---|---|---|
image |
必需 | IMAGE | - | - | 待裁切的原图像 |
mask |
必需 | MASK | - | - | 定义裁切主体的遮罩 |
preset_ratio |
- | COMBO | mask |
mask / image / auto / 9:16 / 2:3 / 3:4 / 4:5 / 1:1 / 5:4 / 4:3 / 3:2 / 16:9 / 21:9 |
目标纵横比预设。mask跟随遮罩; image跟随原图; auto按遮罩自适应构图（忽略离群噪点，scale_strength 从贴遮罩过渡到近似全图） |
get_crop_ratio |
可选 | IMAGE | - | - | 可选参考图像。若连接，将自动匹配该图像的宽高比，覆盖 preset_ratio |
scale_strength |
- | FLOAT | 0.0 | 0.0-1.0 | 缩放强度。auto 下 0 = 刚好装下遮罩、1 ≈ 全图，中间按对数等比过渡；其它模式在尺寸档位间取位；crop_to_side 非 None 时不生效 |
crop_to_side |
- | COMBO | None |
None / longest / shortest / width / height |
目标边长控制模式 |
crop_to_length |
- | INT | 1024 | 8-8192 | 目标边长的数值 |
divisible_by |
- | INT | 8 | 1-1024 | 输出尺寸整除约束（通常用于模型输入对齐） |
输出
| 输出名称 | 数据类型 | 描述 |
|---|---|---|
cropped_image |
IMAGE | 裁切并调整大小后的图像 |
bbox_mask |
MASK | 原始图像尺寸的遮罩，白色区域表示裁切发生的具体位置 |
cropped_mask |
MASK | 与裁切图像对应的遮罩 |
功能说明
- 智能比例控制：
mask：尽可能贴合遮罩主体的比例。auto：按遮罩自适应，不怕长条图和脏遮罩 ——- 先忽略稀疏离群噪点：只丢掉比最密行/列轻 10 倍、且累计不超过总量 1% 的边，实心主体的边缘不会被削掉；
- 以去噪后 bbox 的比例为基准，与最近标准比例的线性偏差 ≤30% 时才吸附（得到 4:3 / 16:9 这类整齐比例），否则保留遮罩比例，细长主体不会被 16:9 之类的固定比例压成小窄条；
- 最小裁剪框刚好含住 bbox（对齐
divisible_by）并且必然能放进原图，不会像固定比例那样“装不下就整幅返回”； scale_strength是取景权重：0恰好装下遮罩（遮罩比例、主体占满画面），1是原图能提供的最大对齐框（≈ 全图、原图比例）；中间在对数尺度上等比放大（每 0.1 是固定倍率），宽高各自插值，所以比例从遮罩比例平滑过渡到原图比例。例：1663×521 里一个 431px 的圆 +divisible_by=32，0/0.5/1分别得到 448×448、864×480、1632×512；- 裁剪框以遮罩 bbox 为中心，越界时向图内平移，所以遮罩靠边时会自动把空旷一侧的背景补进来；
crop_to_side/crop_to_length非None时由它们接管尺寸（仍按 auto 比例取档），scale_strength不参与。
get_crop_ratio：通过输入图像动态设定目标比例，实现“以图定形”。
- 尺寸约束与调整：
scale_strength：auto下0→1从“遮罩紧贴”过渡到“近似全图”（比例同时过渡）；其它模式下保持比例、只向外扩展。crop_to_side/crop_to_length：直接控制输出图像的物理分辨率（如固定长边为 1024）。divisible_by：确保输出宽高符合特定倍数（如 SDXL 需要 8 倍数）。
- 批量处理：支持 Image 和 Mask 的批次输入，若批次大小不一致会自动广播对齐。
典型用法
- 局部重绘预处理：利用遮罩提取主体并裁切，进行局部放大或重绘，再利用
bbox_mask贴回原图。 - 数据集制作：将主体从大图中批量裁切出来，并统一缩放到指定尺寸（如 512x512 或 1024x1024）。
注意与建议
- 连接
get_crop_ratio时，preset_ratio（含auto）的设置将被忽略。 auto忽略掉的噪点不会被裁进来，也不会落在bbox_mask内，贴回原图时该区域保持不变；如果这些点本身是有效内容，请改用mask或明确的比例。auto的1.0受divisible_by约束，会略小于原图（1663×521、32 倍数时是 1632×512），这是为了保持模型输入对齐。- 旧版
auto（按原图比例吸附标准比例）已并入本模式：现在的auto以遮罩为主，只有scale_strength=1才过渡到原图比例。使用过旧auto的工作流重新打开后输出会按新语义变化，属预期。 - 若遮罩为空或无效，节点将返回全黑或全白的默认图像以避免报错。