计算机视觉 / 系统课时
添加文字标注
添加文字标注
文字标注常用于检测结果、调试坐标和导出报告。本课直接用 cv2.putText 完成可复用的标注,并把基线坐标、字体缩放、线宽、颜色和抗锯齿这些最容易出错的参数一次讲清。
学习目标
- 能用
cv2.putText设置文字内容、位置、字体、大小、颜色与线宽。 - 能用
cv2.getTextSize计算文字边界,避免文字贴边或超出图像。 - 能根据图像尺寸调整标注位置,并检查保存结果是否正确。
理解文字原点与关键参数
cv2.putText 的 org=(x, y) 不是文字左上角,而是首字符左下方的基线起点。因此把 org 设成 (20, 20) 时,文字上半部分很可能越出图像;更稳妥的做法是先算文字高度,再决定基线位置。

常用参数可直接按下面取值起步:fontFace=cv2.FONT_HERSHEY_SIMPLEX、fontScale=0.6~1.0、thickness=1~2、lineType=cv2.LINE_AA。OpenCV 颜色按 BGR 顺序,例如绿色是 (0, 255, 0),白色是 (255, 255, 255)。
写出可运行的标注示例
下面示例适用于 OpenCV-Python 4.x。它先用 cv2.getTextSize 计算文字尺寸,再绘制深色背景框与白色文字,最后保存到 annotated.png,因此即使原图较亮,文字也能保持可读。
import cv2
import numpy as np
image = np.full((360, 640, 3), 210, dtype=np.uint8)
text = "Status: OK"
font = cv2.FONT_HERSHEY_SIMPLEX
font_scale = 0.8
thickness = 2
padding = 8
# 先计算文字边界,避免把基线坐标误当成左上角。
(text_width, text_height), baseline = cv2.getTextSize(
text, font, font_scale, thickness
)
x = 24
y = 24 + text_height
top_left = (x - padding, y - text_height - padding)
bottom_right = (x + text_width + padding, y + baseline + padding)
# 背景框覆盖文字主体与 baseline,下层图像再亮也保持可读。
cv2.rectangle(image, top_left, bottom_right, (40, 40, 40), -1)
cv2.putText(
image,
text,
(x, y),
font,
font_scale,
(255, 255, 255),
thickness,
cv2.LINE_AA,
)
saved = cv2.imwrite("annotated.png", image)
print("saved:", saved)
print("image_shape:", image.shape)预期输出
saved: True
image_shape: (360, 640, 3)打开 annotated.png 后,应看到左上区域有深色矩形底板,文字完整落在底板内,没有越出画布。若底板能显示但文字被截断,优先检查 y 是否按“基线坐标”计算,而不是把它当作文字顶部坐标。
让标注适配不同图像尺寸
固定写死 (20, 30) 适合调试,但批量处理不同分辨率时更推荐按边距定位。要把文字放在右上角,可用 x = image_width - text_width - margin,并让 y = margin + text_height;margin 可先取短边的 2%~3%。
例如 1920×1080 图像取 margin=24、fontScale=0.8 通常可读;640×360 图像可把 fontScale 降到 0.55~0.7。不要只按图像宽度缩放字体,否则超宽或竖图会得到异常大的文字。
检查颜色、字体与边界问题
最常见错误是把颜色按 RGB 写入。例如想画红字却传 (255, 0, 0),在 OpenCV BGR 规则下实际会得到蓝色;红色应写 (0, 0, 255)。字体也只能使用 OpenCV 内置 Hershey 字体常量,不能直接把系统字体文件路径传给 cv2.putText。
如果必须显示中文或自定义 TTF/OTF 字体,cv2.putText 不是合适工具,应改用 Pillow 的 ImageFont.truetype 后再转换回 NumPy/OpenCV 图像。对英文、数字、坐标和检测标签,优先保留 cv2.putText,依赖更少且绘制速度稳定。