如何用 supervision 的 VertexAnnotator 和 EdgeAnnotator 绘制关键点及连接线
如何用 supervision 的 VertexAnnotator 和 EdgeAnnotator 绘制关键点及连接线
拿到一张图片以及一组关键点坐标(来自 pose 估计模型,或你自己构造的坐标数组)之后,需要把关键点画成圆点、把骨架关节连成线,输出可直接保存或展示的标注图。supervision 的 sv.VertexAnnotator 负责画关键点(顶点),sv.EdgeAnnotator 负责按骨架结构画连接线,两者都以 sv.KeyPoints 对象作为输入,作用于 numpy.ndarray 或 PIL.Image.Image 类型的图像。本文的完整操作路径:安装 supervision → 准备 sv.KeyPoints → 用两个 annotator 分别绘制顶点与边 → 按文档给出的规则核对渲染行为。
准备:安装 supervision 并准备 KeyPoints
安装 supervision 本体即可使用两个 annotator,文档给出的安装命令为:
pip install supervision
标注的输入是 sv.KeyPoints 对象,其字段结构在 KeyPoints 文档 中有明确定义:
xy:形状(n, m, 2)的数组,n个检测目标,每个目标m个关键点,每个点是[x, y];class_id:形状(n,)的类别 id,可选;visible:形状(n, m)的布尔数组,标记哪些关键点是可见的,可选。
如果手头没有现成模型结果,可以按 annotators 文档 中的示例直接用 NumPy 数组构造 KeyPoints:
import numpy as np
import supervision as sv
image = np.zeros((800, 800, 3), dtype=np.uint8)
key_points = sv.KeyPoints(
xy=np.array(
[[[400, 200], [300, 500], [500, 500]]],
dtype=np.float32,
),
class_id=np.array([0]),
visible=np.array([[True, True, True]]),
)
这是文档(见 src/supervision/key_points/annotators.py 中 annotator 的示例)给出的最小示例:1 个对象、3 个关键点,坐标分别为 (400, 200)、(300, 500)、(500, 500)。实际项目中,key_points 通常来自模型推理,KeyPoints 文档给出了从 Ultralytics YOLO pose、MediaPipe、Inference 等结果转换的方法,例如:
from supervision import _cv2 as cv2
import supervision as sv
from ultralytics import YOLO
# 将 <SOURCE_IMAGE_PATH> 替换为你自己的图片路径
image = cv2.imread("<SOURCE_IMAGE_PATH>")
model = YOLO('yolo11s-pose.pt')
result = model(image)[0]
key_points = sv.KeyPoints.from_ultralytics(result)
sv.VertexAnnotator 和 sv.EdgeAnnotator 都从 sv 顶层导出,无需从子模块导入。
用 VertexAnnotator 绘制关键点
VertexAnnotator 在每个关键点位置画一个实心圆。按 annotators 文档 的用法:
import supervision as sv
vertex_annotator = sv.VertexAnnotator(
color=sv.Color.GREEN,
radius=10,
)
annotated_frame = vertex_annotator.annotate(
scene=image.copy(),
key_points=key_points,
)
color:圆点的颜色,文档示例使用sv.Color.GREEN;radius:圆点半径,文档示例取 10。
annotate 会直接修改传入的 scene 并返回同一张图像,文档示例中因此传入 image.copy() 以保留原图。返回值类型与 scene 一致:numpy.ndarray 进、numpy.ndarray 出,PIL.Image.Image 进、PIL.Image.Image 出;如果 scene 既不是这两者会抛 TypeError。
用 EdgeAnnotator 绘制连接线
EdgeAnnotator 按边列表把关键点连成线。文档中的基本用法:
edge_annotator = sv.EdgeAnnotator(
color=sv.Color.GREEN,
thickness=5,
edges=[(1, 2), (1, 3)],
)
annotated_frame = edge_annotator.annotate(
scene=image.copy(),
key_points=key_points,
)
三个参数在 src/supervision/key_points/annotators.py 的定义中:
color:线的颜色;thickness:线的粗细;edges:要画的边。这里使用1-based(从 1 开始)的顶点编号,[(1, 2), (1, 3)]表示连接第 1 个关键点和第 2 个、第 3 个关键点,与上文 3 个关键点的示例数据正好构成一个三角形。
edges 有三种形态,文档分别说明了各自的适用条件:
- 显式传入
Sequence[tuple[int, int]]:同一套骨架结构应用到每个实例,是最常用的方式; edges=None(默认):按每个对象的顶点数量自动匹配内置骨架(COCO、HAND、GHUM、FACEMESH 等,定义见 src/supervision/key_points/skeletons.py)。如果顶点数匹配不到任何内置骨架,会发出No skeleton found with {n} vertices的警告并跳过该对象;dict[int, Sequence[tuple[int, int]]]:以class_id为 key,为不同类别指定不同骨架,适用于画面中同时存在多种骨架类型的数据集。此时KeyPoints必须带class_id,否则会抛ValueError;某个class_id没有定义边时同样抛ValueError。文档给出的多骨架示例:
edge_annotator = sv.EdgeAnnotator(
color=sv.Color.ROBOFLOW,
thickness=3,
edges={0: [(1, 2), (1, 3)], 1: [(1, 2)]},
)
绘制结果与文档定义的判断规则
标注完成后可直接展示或保存 annotated_frame。supervision 自带 sv.ImageWindow,文档中的常见展示方式是:
sv.ImageWindow("annotated_frame").show(annotated_frame)
判断渲染是否符合预期时,以文档明确给出的行为为准:
- 零坐标点:坐标为
(0, 0)的关键点会被跳过,VertexAnnotator不画它,EdgeAnnotator也会跳过任何一端落在(0, 0)的边; visible过滤:当key_points.visible已设置时,标记为不可见的关键点不画顶点,两端任一端不可见的边也不画;文档还给出了按置信度设置可见性的写法:key_points.visible = key_points.keypoint_confidence > 0.3;- 空结果:
len(key_points) == 0时两个 annotator 直接原样返回scene,不做任何绘制; - 边编号越界:
edges必须遵守 1-based 约定且落在[1, 顶点数]范围内,否则抛出ValueError,错误信息形如Edge indices must use the 1-based convention and be within the available keypoint range [1, {vertex_count}], got {edge}.
以上规则都能在 src/supervision/key_points/annotators.py 的 VertexAnnotator.annotate 与 EdgeAnnotator.annotate 实现及其 docstring 中逐条核对。
边界与下一步
需要注意的限制:
EdgeAnnotator的自动骨架匹配只认内置骨架的顶点数,自定义的稀疏关键点集合(例如上文的 3 点示例若顶点数不匹配内置骨架)在edges=None时不会画线,应显式传入edges;- 多类别场景使用
dict形式的edges时,每个出现的class_id都必须在字典中有定义。
如果还需要在关键点旁显示文字标签,同一文档页给出了 sv.VertexLabelAnnotator,用法与上述两个 annotator 一致,同样接受 scene 和 key_points 两个参数,细节见 annotators 文档。