跳转至

AddBoundingBoxes 目标检测检测框绘制与标签标注节点

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

AddBoundingBoxes 节点负责根据输入的坐标字典数据，在目标图像上精确绘制彩色矩形边界框（Bounding Boxes）并叠加文字标签（Labels）。它专为计算机视觉管线中的目标检测（Object Detection）成果可视化而设计，能够无缝渲染来自 YOLO、SSD、人脸识别或任意基于坐标的检测模型产物。

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

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

  • 可视化 YOLO、SSD 或视觉大模型的目标检测定位结果；
  • 标注人脸检测框并显示置信度得分（Confidence Score）；
  • 在工业巡检中标记缺陷或特定感兴趣区域（ROI）；
  • 为计算机视觉工作流提供即时的视觉反馈与质检视口；
  • 调试并验证视觉检测模型的输出边界精度；
  • 在单张图像上合并呈现多类别混合检测结果。

使用指南 (How to use it)

基础配置流程 (Basic Setup)

  1. 在画布中添加 AddBoundingBoxes 节点。
  2. 将图像数据源接入 input_image 输入插槽。
  3. 将包含检测框坐标的字典（或字典列表）接入 bounding_boxes 输入插槽。
  4. （可选）自定义边框线宽、框体颜色与标签文字模板。
  5. 在 output 引脚即可提取完成图层标注绘制后的全新图像资产。

参数输入插槽 (Parameters)

核心输入 (Required Inputs)

  • input_image：待绘制边界框的底图资产（ImageUrlArtifact 或 ImageArtifact）。
  • bounding_boxes：包含检测框坐标的单一字典或字典列表（dict 或 list[dict]）。
    • 每个字典必须包含：x、y、width、height（整数或可解析的数字字符串）；
    • 支持携带任意自定义扩展字段用于标签模板（例如 class 类别、confidence 置信度等）；
    • 示例：{"x": 100, "y": 50, "width": 200, "height": 150, "class": "person", "confidence": 0.95}。

边框样式 (Styling Parameters)

  • box_color（十六进制颜色代码，默认 "#FF0000" 亮红）：边界框轮廓线条的绘制颜色。
  • line_thickness（1–10 像素，默认 2）：边界框线条物理宽度（数值越大越粗壮醒目）。

标签文本配置 (Label Parameters)

  • show_labels（布尔值，默认 true）：是否在边界框上方渲染文字标签条。
  • label_key（字符串模板）：用于构造标签文字的格式化模板。
    • 默认："{x}, {y}, width: {width}, height: {height}"；
    • 使用 {key} 占位符提取坐标字典中的对应字段；
    • 示例："Class: {class}, Conf: {confidence}" 或 "{class} ({confidence:.2f})"；
    • 字典中不存在的键将原样保留为 {key} 字符串。

输出引脚 (Outputs)

  • output：叠加绘制了矩形边框与半透明文字衬底的全新图像资产（ImageArtifact）。

典型工作流示例 (Example)

目标检测结果可视化流水线：

  1. 通过 LoadImage 导入监控或街景素材。
  2. 运行检测模型产出结构化检测坐标列表： 
    [
  {"x": 100, "y": 50, "width": 200, "height": 150, "class": "person", "confidence": 0.95},
  {"x": 350, "y": 120, "width": 180, "height": 200, "class": "car", "confidence": 0.87}
]
  3. 将底图接入 input_image，将检测坐标接入 bounding_boxes。
  4. 将 label_key 设为 "Class: {class}, Conf: {confidence}"。
  5. 将 box_color 设为 "#00FF00"（醒目荧光绿），line_thickness 设为 3。
  6. 将 output 接入 DisplayImage 进行全分辨率质检查看。

关键技术特性 (Important Notes)

  • 坐标系统一规范：以图像左上角为原点 (0, 0)，x 为横坐标、y 为纵坐标，width 与 height 分别向右和向下延展。
  • 字符串容错转换：节点自动将 "100" 等字符串格式的坐标解析为整型，无需前置转换。
  • 智能避让标签定位 (Smart Positioning)：标签默认绘制在边框正上方；若检测框已贴近图像顶边缘（无向上容纳空间），标签将自动智能沉降绘制在边框内部顶端，杜绝文字被图像边界切断。
  • 自适应动态字体字号：文字字号根据图像物理高度自适应等比缩放为 4%（LABEL_HEIGHT_PERCENT），保证在 720p、4K 等不同分辨率下标签都具备极佳的可读性。
  • 全多态透明度保留：严格保护输入 RGBA 图像的原有透明度。

常见问题与排查 (Common Issues)

  • 缺少必需键名：确保每个字典严格包含 x, y, width, height 四大键名。
  • 坐标出现负数：坐标 x ≥ 0, y ≥ 0，尺寸 width > 0, height > 0。
  • 标签未显示：检查 show_labels 是否被置为 false，并确认模板中的 {key} 与字典字段名拼写严格匹配。