1hew-ComfyUI-1hewNodes/web/docs/1hew_ImageCropWithBBoxMask/zh.md

Image Crop With BBox Mask - 图像遮罩智能裁切

节点功能： 根据遮罩（Mask）的边界框（Bounding Box）智能裁切图像，支持多种比例控制、尺寸约束和批量处理。同时输出裁切后的图像、对应的遮罩以及原始位置的边界框遮罩，便于后续还原。

输入

参数名称	入端选择	数据类型	默认值	取值范围	描述
image	必需	IMAGE	-	-	待裁切的原图像
mask	必需	MASK	-	-	定义裁切主体的遮罩
preset_ratio	-	COMBO	mask	mask / image / auto / 9:16 ...	目标纵横比预设。mask跟随遮罩; image跟随原图; auto自动匹配常见比例
get_crop_ratio	可选	IMAGE	-	-	可选参考图像。若连接，将自动匹配该图像的宽高比，覆盖 preset_ratio
scale_strength	-	FLOAT	0.0	0.0-1.0	缩放强度。在满足比例的前提下，向外扩展裁切框的程度
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：自动计算并匹配最接近的标准比例（如 4:3, 16:9 等）。
  • get_crop_ratio：通过输入图像动态设定目标比例，实现“以图定形”。
• 尺寸约束与调整：
  • scale_strength：允许裁切框在保持比例的同时包含更多背景内容。
  • crop_to_side/crop_to_length：直接控制输出图像的物理分辨率（如固定长边为 1024）。
  • divisible_by：确保输出宽高符合特定倍数（如 SDXL 需要 8 倍数）。
• 批量处理：支持 Image 和 Mask 的批次输入，若批次大小不一致会自动广播对齐。

典型用法

• 局部重绘预处理：利用遮罩提取主体并裁切，进行局部放大或重绘，再利用 bbox_mask 贴回原图。
• 数据集制作：将主体从大图中批量裁切出来，并统一缩放到指定尺寸（如 512x512 或 1024x1024）。

注意与建议

• 连接 get_crop_ratio 时，preset_ratio 的设置将被忽略。
• 若遮罩为空或无效，节点将返回全黑或全白的默认图像以避免报错。