imgaug 0.4.0 边界框标签绘制详解:`draw_label_on_image` 与自动标签框功能
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)分为两步:
- 先调用
draw_box_on_image()画出矩形边框; - 若
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),其绘制流程分四步:
- 越界检查:
raise_if_out_of_image=True时调用_do_raise_if_out_of_image,对完全在图像外的边界框抛出异常。 - 颜色预处理(
_preprocess_colors):color_bg缺省时等于color;color_text缺省时按背景色亮度自适应——依据公式gray = 0.299*R + 0.587*G + 0.114*B计算灰度,若gray > 128用黑色文字,否则用白色文字(该策略参考了 SO 上的经典对比度方案,代码中有注释说明)。因此不指定文字颜色也能保证标签可读。 - 计算标签框位置(
_compute_bg_corner_coords):标签框矩形上边位于bb.y1_int - 1 - height(刻意不使用bb.y2,保证标签框位于矩形上方而非下方),水平方向以x1_int - size + 1与x2_int + size为界,最后统一np.clip到图像范围内。若裁剪后x2 <= x1或y2 <= y1(完全越界),直接返回原图。 - 绘制与混合:先生成纯背景色的
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 让边界框标注可视化在数据检查、增强调试与结果展示中变得更加直观和易用,且所有行为均有源码与测试双重背书,可放心集成到自己的视觉流水线中。