如何用 supervision 的 VertexAnnotator 和 EdgeAnnotator 绘制关键点及连接线

原创2026-09-08 19:30:511,371 阅读
文章标签:计算机视觉图像处理数据标注视频处理模型评测开发工具

如何用 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 有三种形态,文档分别说明了各自的适用条件:

  1. 显式传入 Sequence[tuple[int, int]]:同一套骨架结构应用到每个实例,是最常用的方式;
  2. edges=None(默认):按每个对象的顶点数量自动匹配内置骨架(COCO、HAND、GHUM、FACEMESH 等,定义见 src/supervision/key_points/skeletons.py)。如果顶点数匹配不到任何内置骨架,会发出 No skeleton found with {n} vertices 的警告并跳过该对象;
  3. 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 文档。

登录后查看全文
supervision