imgaug 0.4.0 边界框标签绘制详解:`draw_label_on_image` 与自动标签框功能

原创2026-10-13 13:47:091,868 阅读
文章标签:计算机视觉数据增强深度学习机器学习图像处理

imgaug 0.4.0 边界框标签绘制详解:draw_label_on_image 与自动标签框功能

imgaug 自 0.4.0 起(对应 PR #545)为边界框可视化引入了标签框(label box)绘制能力:调用 BoundingBox.draw_on_image() 或 BoundingBoxesOnImage.draw_on_image() 时,系统会在每个边界框矩形上方自动叠加一个显示其 label 文本的小标签框;同时新增了 draw_label_on_image() 与 draw_box_on_image() 两个方法,用于对标签框和矩形框进行更精细的控制。本文结合仓库源码与测试用例,完整梳理该功能的调用方式、全部参数含义与底层绘制原理,帮助你快速在数据可视化、调试增强管线等场景中落地使用。

一、功能背景:一次绘制调用,矩形与标签同时落地

在 0.4.0 之前,BoundingBox.draw_on_image() 只负责画出边界框的矩形边框,标签文本需要开发者自行叠加,流程繁琐且样式难以统一。0.4.0 版本通过 PR #545 将"标签绘制"内建到边界框绘制管线中,具体变更记录见 20200101_bb_label_drawing.md,核心包括三点:

  • 新增方法 imgaug.augmentables.BoundingBox.draw_label_on_image();
  • 新增方法 imgaug.augmentables.BoundingBox.draw_box_on_image();
  • 修改 imgaug.augmentables.BoundingBox.draw_on_image(),使其自动绘制边界框的标签。

从源码结构看,这一系列方法均定义在 bbs.py 的 BoundingBox 类中(draw_label_on_image 位于第 729 行,draw_box_on_image 位于第 801 行,draw_on_image 位于第 902 行)。由于 BoundingBoxesOnImage.draw_on_image() 是逐个调用 BoundingBox.draw_on_image() 的(见第 1741-1750 行),因此单框与多框两条绘制路径都自动获得了标签框能力。

二、draw_on_image():默认自动绘制标签

BoundingBox.draw_on_image() 的签名如下:

def draw_on_image(self, image, color=(0, 255, 0), alpha=1.0, size=1,
                  copy=True, raise_if_out_of_image=False, thickness=None):

其实现逻辑(bbs.py)分为两步:

  1. 先调用 draw_box_on_image() 画出矩形边框;
  2. 若 self.label 不为 None,再调用 draw_label_on_image() 绘制标签框。
image_drawn = self.draw_box_on_image(
    image, color=color, alpha=alpha, size=size,
    copy=copy, raise_if_out_of_image=raise_if_out_of_image,
    thickness=thickness
)
if self.label is not None:
    image_drawn = self.draw_label_on_image(
        image_drawn, color=color, alpha=alpha,
        size=size if thickness is None else thickness,
        copy=False, raise_if_out_of_image=raise_if_out_of_image
    )
return image_drawn

关键行为规则

  • label 为 None 时不绘制标签框:此时结果与只调用 draw_box_on_image() 完全一致。测试用例 test_draw_on_image_label_is_none(test_bbs.py)用 np.array_equal 验证了二者逐像素相等。
  • label 为字符串时自动追加标签框:测试 test_draw_on_image_label_is_str(test_bbs.py)验证了 draw_on_image() 的结果等于"先画矩形、再画标签"两步操作的结果。
  • BoundingBoxesOnImage.draw_on_image() 继承该行为:它在遍历内部 bounding_boxes 时以 copy=False 调用每个框的 draw_on_image()(bbs.py),因此整组框可视化同样会自动带上标签。

参数速览

参数 默认值 说明
color (0, 255, 0)(绿色) 矩形与标签框颜色,按图像通道布局(通常为 RGB);同时作为标签文字/背景色的推导来源
alpha 1.0 透明度,1.0 不透明,0.0 完全不可见
size 1 矩形边框粗细(像素);大于 1 时向框外侧扩展
copy True 是否复制输入图像;False 时原地修改
raise_if_out_of_image False 边界框完全在图像外时是否抛异常
thickness None 已废弃参数,等价于 size,传入时触发弃用警告并重命名

三、draw_box_on_image():只画矩形,不画标签

若你只想绘制矩形边框而不希望出现标签框(例如标签为空时保持干净画面),使用 draw_box_on_image():

def draw_box_on_image(self, image, color=(0, 255, 0), alpha=1.0,
                      size=1, copy=True, raise_if_out_of_image=False,
                      thickness=None):

该方法(bbs.py)的实现要点:

  • 若 raise_if_out_of_image=True 且边界框完全在图像外,抛出 Exception(信息包含框坐标与图像 shape);
  • 支持 color 为单个整数(等价于三通道同值,如 color=128 → (128,128,128)),测试 test_draw_box_on_image_single_int_as_color 对此有验证;
  • 通过 skimage.draw.polygon_perimeter 按 size 逐层向外绘制多边形周长;
  • alpha 处理区分三种情况:alpha >= 0.99 直接写入;浮点图像就地按 (1-alpha)*img + alpha*color 混合;整数图像则先转 float32 混合再 np.clip(0, 255) 转回原 dtype;
  • 当边界框完全在图像内时,坐标会被 np.clip 约束到 [0, H-1] / [0, W-1],避免边框因取整刚好落在图像外而消失。

四、draw_label_on_image():精细控制标签框样式

BoundingBox.draw_label_on_image() 提供比默认绘制更完整的控制粒度,标签框默认放置在边界框矩形的正上方:

def draw_label_on_image(self, image, color=(0, 255, 0),
                        color_text=None, color_bg=None, alpha=1.0, size=1,
                        size_text=20, height=30,
                        copy=True, raise_if_out_of_image=False):

参数详解

参数 默认值 作用
image — 目标图像,(H,W,C) ndarray,当前仅支持 uint8
color (0, 255, 0) 颜色基准;文字与背景色在未显式指定时都由它推导
color_text None 文字颜色;为 None 时由 color_bg 的亮度自动推导
color_bg None 标签框背景色;为 None 时直接采用 color
alpha 1.0 透明度(同样支持半透明混合)
size 1 矩形边框粗细,决定标签框与矩形之间的偏移量
size_text 20 文字字号(像素)
height 30 标签框高度(像素)
copy True 是否复制图像;False 原地绘制
raise_if_out_of_image False 边界框完全在图像外时是否抛异常

使用示例:

import numpy as np
from imgaug.augmentables.bbs import BoundingBox

image = np.zeros((100, 120, 3), dtype=np.uint8)
bb = BoundingBox(x1=10, y1=40, x2=60, y2=70, label="cat")

# 自定义标签框:灰底白字
img_labeled = bb.draw_label_on_image(
    image,
    color_bg=(123, 123, 123),
    color_text=(222, 222, 222),
    size_text=15,
    height=25,
)

五、底层实现原理:_LabelOnImageDrawer 绘制管线

标签框的绘制逻辑封装在 BoundingBox 模块内部的 _LabelOnImageDrawer 类中(bbs.py),其绘制流程分四步:

  1. 越界检查:raise_if_out_of_image=True 时调用 _do_raise_if_out_of_image,对完全在图像外的边界框抛出异常。
  2. 颜色预处理(_preprocess_colors):color_bg 缺省时等于 color;color_text 缺省时按背景色亮度自适应——依据公式 gray = 0.299*R + 0.587*G + 0.114*B 计算灰度,若 gray > 128 用黑色文字,否则用白色文字(该策略参考了 SO 上的经典对比度方案,代码中有注释说明)。因此不指定文字颜色也能保证标签可读。
  3. 计算标签框位置(_compute_bg_corner_coords):标签框矩形上边位于 bb.y1_int - 1 - height(刻意不使用 bb.y2,保证标签框位于矩形上方而非下方),水平方向以 x1_int - size + 1 与 x2_int + size 为界,最后统一 np.clip 到图像范围内。若裁剪后 x2 <= x1 或 y2 <= y1(完全越界),直接返回原图。
  4. 绘制与混合:先生成纯背景色的 label_arr,再调用模块级函数 ia.draw_text()(imgaug.py)以 size_text 字号、从 (2, 2) 偏移处写入 str(label);最后按 alpha 将标签块与图像区域混合(alpha >= 0.99 直接覆盖,否则按 (1-alpha)*bg + alpha*fg 混合并裁剪到 [0, 255])。

文字绘制的字体与 dtype 限制

标签文字最终由 draw_text 借助 Pillow 渲染,使用仓库自带的 DejaVuSans.ttf 字体(PIL_ImageFont.truetype(DEFAULT_FONT_FP, size)),无需额外安装字体文件。注意 draw_text 目前只接受 uint8 与 float32 两种 dtype(float32 会先转 uint8 渲染再转回),其他 dtype 会触发断言错误;文档声明 uint8 为 fully tested,float32 尚未测试。

六、测试验证:行为有据可查

与标签绘制相关的测试集中在 test/augmentables/test_bbs.py,可作为行为契约参考:

  • test_draw_label_on_image_mocked / test_draw_label_on_image_mocked_inplace(第 694-731 行):通过 mock _LabelOnImageDrawer 验证默认参数传递(color=(0,255,0)、alpha=1.0、size=1、size_text=20、height=30、raise_if_out_of_image=False),以及 copy=True/False 分别走 draw_on_image / draw_on_image_ 路径;
  • test_draw_label_on_image(第 733-746 行):端到端验证自定义 color_bg、color_text 后标签背景色与文字色确实出现在结果图像中;
  • test_draw_box_on_image 系列(第 759-881 行):覆盖矩形绘制的颜色(RGB 白/红/单整数)、半透明混合(alpha=0.5,含 float32 图像)、copy=False 原地修改、边界框部分/完全越界及 raise_if_out_of_image=True 抛异常、size=2 粗边框等场景;
  • test_draw_on_image_label_is_none / test_draw_on_image_label_is_str(第 883-904 行):验证 label=None 不画标签框、label="Foo" 自动追加标签框的核心行为。

七、完整实战示例:标注一张图像并输出结果

综合以上 API,一个典型的多框标注流程如下:

import numpy as np
import imgaug as ia
from imgaug.augmentables.bbs import BoundingBox, BoundingBoxesOnImage

image = ia.quokka(size=(256, 256))
bbs = BoundingBoxesOnImage([
    BoundingBox(x1=50, y1=40, x2=180, y2=210, label="cat"),
    BoundingBox(x1=20, y1=220, x2=100, y2=250, label="dog"),
], shape=image.shape)

# 1) 自动绘制:矩形 + 标签框
img_drawn = bbs.draw_on_image(image, color=(0, 255, 0), size=2)

# 2) 只画矩形,不要标签
img_box_only = bbs.draw_on_image(image, color=(255, 0, 0))
# 或者显式只画矩形:
for bb in bbs.bounding_boxes:
    img_box_only = bb.draw_box_on_image(img_box_only, color=(255, 0, 0))

# 3) 精细控制单个标签框(自定义背景与文字颜色、字号、高度)
img_custom = image.copy()
for bb in bbs.bounding_boxes:
    img_custom = bb.draw_label_on_image(
        img_custom,
        color_bg=(0, 0, 200),
        color_text=(255, 255, 255),
        size_text=16,
        height=24,
    )

注意事项

  • draw_* 系列方法当前期望输入为 uint8 图像,绘制前请确认 dtype;
  • BoundingBoxesOnImage.draw_on_image() 内部的 copy 参数只控制最外层是否复制,其内部循环使用 copy=False 逐框累积绘制,因此传入该容器方法时不必担心重复复制开销;
  • 若边界框部分在图像外,raise_if_out_of_image=False 时仅绘制落在图像内的部分(标签框也会被裁剪);若需要过滤越界框,可先用 remove_out_of_image() 等方法预处理。

通过 draw_on_image() 的自动标签能力与 draw_label_on_image() / draw_box_on_image() 的精细控制,imgaug 0.4.0 让边界框标注可视化在数据检查、增强调试与结果展示中变得更加直观和易用,且所有行为均有源码与测试双重背书,可放心集成到自己的视觉流水线中。

登录后查看全文
imgaug