Supervision 关键点标注器全解析：Vertex、Edge 与 Ellipse 系列 Annotators 使用指南

Supervision 关键点标注器全解析Vertex、Edge 与 Ellipse 系列 Annotators 使用指南【免费下载链接】supervisionWe write your reusable computer vision tools. 项目地址: https://gitcode.com/GitHub_Trending/su/supervision导读本篇文章基于 Supervision 官方文档 keypoint/annotators.md 编写围绕人体姿态、手部骨骼与面部关键点可视化这一主题系统讲解六个骨骼关键点标注器VertexAnnotator、EdgeAnnotator、VertexLabelAnnotator、VertexEllipseAreaAnnotator、VertexEllipseOutlineAnnotator与VertexEllipseHaloAnnotator。读完本篇你将掌握如何用统一的sv.KeyPoints数据结构驱动不同风格的关键点渲染学会用源码级参数颜色、半径、线宽、sigma 椭圆层级、透明度、防重叠标签等快速产出可直接用于质检与展示的标注画面。前置准备一个可以被标注的KeyPoints在 Supervision 中关键点标注器的输入统一是sv.KeyPoints对象。它把来自不同框架的姿态/关键点结果标准化为一致的字段xy形状(n, m, 2)的坐标数组n为检测到的目标数m为每个目标的特征点数class_id形状(n,)的目标类别 ID可为Nonekeypoint_confidence形状(n, m)的逐点置信度visible形状(n, m)的可选布尔矩阵标记哪些关键点是可见的None时全部视为可见core.py 的字段定义见该文件 docstringdata附加数据的字典与关键点对齐。你可以通过不同模型的适配器生成KeyPoints如KeyPoints.from_ultralytics()接收 YOLO pose 结果、KeyPoints.from_mediapipe()、KeyPoints.from_inference()、KeyPoints.from_transformers()、KeyPoints.from_detectron2()与KeyPoints.from_yolo_nas()详见 keypoint/core.md 与 core.py。生成之后即可像官方文档示例那样把坐标交给任意标注器import supervision as sv image ... # 读取一帧画面numpy.ndarray 或 PIL.Image 均可 key_points sv.KeyPoints(...) # 来自任意模型适配器接下来按能力分三组介绍六个标注器。六个标注器速览标注器作用核心参数构造函数默认值见源码 annotators.pyVertexAnnotator在每个关键点画实心圆colorColor.ROBOFLOW、radius4EdgeAnnotator在关键点之间连线形成骨架colorColor.ROBOFLOW、thickness2、edgesNoneVertexLabelAnnotator为每个关键点绘制带背景的文字标签colorColor.ROBOFLOW、text_colorColor.WHITE、text_scale0.5、text_thickness1、text_padding10、border_radius0、smart_positionFalseVertexEllipseAreaAnnotator基于协方差绘制多层级半透明填充椭圆sigma(1.0, 2.0, 3.0)、color(GREEN, YELLOW, RED)、opacity0.4、max_axisNoneVertexEllipseOutlineAnnotator基于协方差绘制多层级空心椭圆环同上另有thickness2VertexEllipseHaloAnnotator基于协方差绘制径向渐变发光椭圆同 Areaopacity0.6内部_DECAY2.0需要留意的是官方文档示例中的数值如radius10、thickness5属于演示取值构造函数在源码中的默认值如上表所示实际使用时两套值都合法。VertexAnnotator标注关键点顶点VertexAnnotator负责把每个关键点画成实心圆即骨骼的“顶点/关节点”。import supervision as sv image ... key_points sv.KeyPoints(...) vertex_annotator sv.VertexAnnotator( colorsv.Color.GREEN, radius10, ) annotated_frame vertex_annotator.annotate( sceneimage.copy(), key_pointskey_points, )源码层面的执行规则annotators.py 中VertexAnnotator.annotate遍历key_points.xy对每个目标内的每个点调用cv2.circle画实心圆thickness-1表示填充坐标为(0, 0)的占位点会被跳过当key_points.visible存在且对应位置为False时该点被跳过visible is None时不做过滤全部绘制key_points为空时直接返回原始scene不会报错。因此visible与“坐标零值”共同决定了哪些顶点会被画出这对存在遮挡、模型输出置信度低的关键点尤为重要。EdgeAnnotator连接关键点绘制骨架边EdgeAnnotator把关键点两两连线得到完整的骨架结构import supervision as sv image ... key_points sv.KeyPoints(...) edge_annotator sv.EdgeAnnotator( colorsv.Color.GREEN, thickness5, ) annotated_frame edge_annotator.annotate( sceneimage.copy(), key_pointskey_points, )edges参数有三种传法源码中EdgeAnnotator.__init__与annotate的处理逻辑edgesNone默认自动检测骨架根据每个目标的关键点数量在skeletons.py定义的SKELETONS_BY_VERTEX_COUNT字典中查找预设骨架。该字典由内建Skeleton枚举COCO、HAND、GHUM、FACEMESH_TESSELATION_NO_IRIS等多个标准骨架按去重后的顶点数自动索引构建skeletons.py。若按顶点数查不到匹配会打印警告并跳过该目标。传Sequence[tuple[int, int]]单骨架对所有目标实例应用同一组边例如edges[(1, 2), (1, 3)]表示把 1 号点分别连向 2、3 号点。传dict[int, Sequence[tuple[int, int]]]按类别多骨架以class_id为键、各自映射一组边适合“同一批检测里混有多种骨架类型”的数据集例如edges{0: [(1, 2), (1, 3)], 1: [(1, 2)]}。关于边索引的 1-based 约定公共 API 中的边索引采用1-based编号从 1 到m内部会通过_validate_edge_indices校验范围并转换为 0-based 下标后再访问xy数组见源码annotators.py。若索引越界超出[1, m]会抛出ValueError。绘制时若边两端任一坐标为零值或任一端点被visible标记为不可见则该边被跳过源码annotate逻辑。完整的多骨架用例可见源码 docstring 中的示例代码。VertexLabelAnnotator给关键点挂上文字标签当需要直接读出“哪个点是什么关节”时使用VertexLabelAnnotator在每个关键点旁绘制带圆角背景的文字框import supervision as sv image ... key_points sv.KeyPoints(...) vertex_label_annotator sv.VertexLabelAnnotator( colorsv.Color.GREEN, text_colorsv.Color.BLACK, border_radius5, ) annotated_frame vertex_label_annotator.annotate( sceneimage.copy(), key_pointskey_points, )annotate()的labels参数同样支持三种形态源码annotate/_resolve_labelsNone默认以关键点的下标0、1、...作为标签list[str]长度必须等于关键点数量作用于每个实例如labels[head, L-foot, R-foot]dict[int, list[str]]按class_id给不同骨架类型配置各自的标签列表。颜色参数color与text_color既可以是单个Color也可以是按关键点逐个配置的Color列表长度需与点数一致否则抛ValueError。细节特性源码层面border_radius背景圆角半径设成较大值可把背景渲染成圆形smart_positionTrue利用pad_boxes先扩张每个标签框再交给spread_out_boxes把重叠标签“摊开”最后再内缩回原尺寸从而避免标签互相遮挡相关工具函数来自 detection/utils/boxes.py标签框居中于关键点先用cv2.getTextSize测量文字尺寸得到文本包围盒再以其中心对齐关键点坐标背景矩形通过draw_rounded_rectangle绘制与顶点标注一致visible为False的点、或visible为None时坐标为(0,0)的点会被跳过。椭圆家族把不确定度可视化出来VertexEllipseAreaAnnotator、VertexEllipseOutlineAnnotator与VertexEllipseHaloAnnotator三个标注器用于不确定性/概率分布的可视化它们不依赖模型输出的固定坐标而是依据每个关键点的 2×2 协方差矩阵画出与置信区间对应的椭圆。数据要求key_points.data[covariance]三个椭圆标注器共用一个私有基类_BaseVertexEllipseAnnotator并依赖key_points.data中键为covariance的数据其形状必须为(N, K, 2, 2)N目标数、K每目标关键点数矩阵以像素坐标表示。缺少该字段或形状不匹配时_get_covariances会抛出ValueError。官方文档与本源码 docstring 均给出构造示例key_points sv.KeyPoints( xy..., class_id..., data{ covariance: np.array( [[[[800, 0], [0, 400]], # 第 1 个关键点的 2x2 协方差 [[400, 0], [0, 800]], # 第 2 个关键点 [[600, 0], [0, 600]]]], # 第 3 个关键点 dtypenp.float32, ) }, )sigma、color 与 max_axis 的语义三个椭圆标注器共享sigma、color、max_axis三个参数_BaseVertexEllipseAnnotator.__init__sigma每个椭圆环的倍率可传单个浮点数或浮点序列默认(1.0, 2.0, 3.0)。内部会把 sigma 按降序排列因此绘制顺序是“最外圈先画、最内圈最后画”。color每个 sigma 层级对应的颜色可传单个Color或颜色序列默认(Color.GREEN, Color.YELLOW, Color.RED)颜色数量必须与 sigma 数量一致否则抛ValueError。max_axis椭圆半轴长度的像素上限可选。约束在max_axis非空时必须为正。绘制几何的底层逻辑源码_iter_ellipse_params对每个可见、非零坐标的关键点取出其 2×2 协方差矩阵用np.linalg.eigh做特征分解得到特征值与特征向量按特征值降序排列第一主轴方向对应最大方差方向椭圆倾角即由该特征向量经arctan2换算为角度每个 sigma 层级的椭圆半轴长度为sigma * sqrt(特征值)中心落在关键点坐标上协方差含非有限值或特征值非正的矩阵会被安全跳过不做绘制。Area / Outline / Halo 三者的差异VertexEllipseAreaAnnotator —— 半透明实心填充area_annotator sv.VertexEllipseAreaAnnotator( colorsv.Color.GREEN, sigma2.0, )将所有椭圆先在 overlay 副本上用cv2.ellipsethickness-1、抗锯齿LINE_AA填充再通过cv2.addWeighted(overlay, opacity, scene, 1 - opacity, 0)融合回原图opacity默认 0.4。多层同心圆叠加后呈现“靶心”效果内圈颜色代表更高的概率密度。VertexEllipseOutlineAnnotator —— 空心描边环outline_annotator sv.VertexEllipseOutlineAnnotator( colorsv.Color.GREEN, sigma2.0, thickness2, )只画椭圆轮廓cv2.ellipse使用给定的thickness不做任何透明融合适合需要清晰边界、不遮挡底层图像内容的场景。VertexEllipseHaloAnnotator —— 径向渐变的辉光halo_annotator sv.VertexEllipseHaloAnnotator( colorsv.Color.GREEN, sigma2.0, )不依赖 cv2.ellipse而是对每个椭圆外接矩形 ROI 内的像素逐点计算归一化距离dist_sq内部像素的透明度按(1 - dist_sq) ** decay衰减_DECAY 2.0的幂曲线峰值透明度取opacity默认 0.6从而得到“中心最亮、边界渐隐”的柔光效果。兼容别名VertexEllipseAnnotator官方文档特别注明sv.VertexEllipseAnnotator是sv.VertexEllipseAreaAnnotator的兼容别名。这一点在源码中由模块级赋值VertexEllipseAnnotator VertexEllipseAreaAnnotator直接落实annotators.py并且顶层包supervision同时导出了这两个名字见init.py。迁移/升级时代码若使用旧名仍能正常工作。源码级共通细节与注意事项场景类型自适应所有标注器的annotate(scene, key_points)都通过ensure_cv2_image_for_class_method装饰器包装来自 utils/conversion.py因此scene同时接受numpy.ndarray与PIL.Image.Image返回值与输入类型一致若传入其他类型则抛出TypeError。文档示例统一用image.copy()传入避免在原始帧上原地修改。统一基类与返回约定六个标注器除VertexLabelAnnotator单独定义外都继承自抽象基类BaseKeyPointAnnotator接口完全一致便于在视频处理管线里互相替换空KeyPoints一律原样返回scene不会中断逐帧处理流程。可见性过滤语义顶点、边、标签三类标注都尊重visible掩码椭圆族还会额外跳过协方差矩阵异常的点。若想把低置信度关键点“不删除、只不画”可参考KeyPoints.visible的文档建议key_points.visible key_points.keypoint_confidence 0.3core.py。模块路径与兼容性核心实现位于supervision.key_points.annotators与supervision.key_points.core单复数形式为key_points。仓库中旧命名空间的 keypoint/init.py 会在导入时发出弃用警告提示从0.27.0起改用supervision.key_points请在新代码中统一使用后者。对应测试覆盖见 tests/key_points。结语从画点VertexAnnotator、连线EdgeAnnotator、打标签VertexLabelAnnotator到把预测不确定度可视化为多层椭圆VertexEllipseArea/Outline/HaloAnnotatorSupervision 的关键点标注器家族覆盖了姿态、手部与面部等主流应用的全部基础渲染需求。实际使用时只需遵循三条规则先用统一适配器得到sv.KeyPoints再按需在data中提供协方差数据椭圆族最后选择标注器并合理设置visible掩码即可获得干净、专业且利于排查的可视化结果。【免费下载链接】supervisionWe write your reusable computer vision tools. 项目地址: https://gitcode.com/GitHub_Trending/su/supervision创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考