CVAT 矩形标注完全指南：旋转矩形、Shift 角度吸附与 By 4 Points 四极值点绘制原理-平芜编程栈

CVAT 矩形标注完全指南：旋转矩形、Shift 角度吸附与 By 4 Points 四极值点绘制原理

【免费下载链接】cvatComputer Vision Annotation Tool (CVAT) is a leading platform for building high-quality visual datasets for vision AI. It offers open-source, cloud, and enterprise products, as well as labeling services, for image, video, and 3D annotation with AI-assisted labeling, quality assurance, team collaboration, analytics, and developer APIs.项目地址: https://gitcode.com/GitHub_Trending/cvat/cvat

本文围绕 CVAT 文档《Annotation with rectangles》展开，系统讲解 CVAT 中标注矩形（Rectangle）的两种核心技巧：通过旋转点（rotation point）绘制带角度的旋转矩形（按住 Shift 可按 15° 固定步进旋转），以及源自学术界"四极值点"（By 4 points）高效包围框绘制方法。读完后，你不仅能熟练完成矩形标注的实操，还能从前端源码层面理解矩形的数据表示、绘制事件流与命中测试算法的实现细节。

前置知识：Shape 模式与 Track 模式

矩形标注发生在 CVAT 标注编辑器的绘制流程中。开始之前，建议先了解两个基础概念：

Shape 模式（单帧形状）：矩形只存在于当前帧；
Track 模式（跨帧跟踪对象）：矩形框随对象在视频帧间延续，支持自动插值（Interpolate）、自动边界（Autoborder）等能力。

这两者在 CVAT 文档中分别对应 Shape mode (basics) 与 Track mode (basics)，本文的所有操作（包括键盘快捷键Shape、Track、Esc）都建立在这两种模式之上。

矩形的数据表示：4 个点 + 旋转角

在深入操作之前，先明确 CVAT 中矩形是如何被表示的。从源码 cvat-core/src/annotations-objects/rectangle-shape.ts 可以确认，一个矩形实例的坐标点（points）固定为 4 个值：

points = [xtl, ytl, xbr, ybr]

即左上角（top-left）与右下角（bottom-right）两个对角点的坐标，旋转角（rotation/angle）作为形状属性单独存储。构造时还会通过checkNumberOfPoints校验点数合法性（rectangle-shape.ts）。这一表示意味着：无论用"两点拖拽"还是"四极值点"方式绘制，最终落盘的矩形数据结构完全一致——差异只在前端绘制交互阶段。

旋转矩形：rotation point、中心旋转与 15° 吸附

基本操作

拖动矩形上的rotation point（旋转控制点）即可旋转矩形；
旋转是围绕矩形中心进行的；
按住Shift再拖动，旋转角度会被限制为15° 的整数倍（固定角度吸附）；
旋转过程中会实时显示当前的旋转角度数值。

源码视角：旋转矩形的命中测试

"围绕中心旋转"这一点在命中测试（判断光标是否在矩形内、用于点击选中）中有直接体现。RectangleShape提供静态方法distance，其算法（rectangle-shape.ts）：

由[xtl, ytl, xbr, ybr]求出矩形中心(cx, cy)；
将光标坐标(x, y)以-angle绕中心做反向旋转（rotatePoint），把"旋转的矩形"问题转换回"正放矩形"坐标系；
若旋转后的点不落在[xtl, xbr] × [ytl, ybr]区间内，返回null（光标在框外）；
否则返回该点到四条边的最短距离min(rotX - xtl, rotY - ytl, xbr - rotX, ybr - rotY)，这个距离可用于判断光标是否靠近框边（决定显示移动/缩放手柄等行为）。

也就是说，旋转并不改变矩形的存储结构，选中与编辑逻辑始终通过"绕中心旋转坐标系"来处理，这也解释了为什么 UI 上的旋转是围绕中心点而非某个角点。

By 4 Points：四极值点快速绘制矩形

这是文档介绍的第二种矩形绘制方法，也是本篇的实操重点。该方法是一种高效的包围框（bounding box）标注方式，最早由一篇学术论文（arXiv:1708.02750）提出：与其拖出一个近似框再手动修正，不如直接点击目标物体的四个"极值点"，让算法自动推导出正交包围盒。

第一步：在绘制选项中切换到 By 4 Points

按下S（Shape）或T（Track）进入绘制模式前，先打开 "Draw new rectangle" 弹窗，在Drawing method中选择By 4 points：

该选项在 UI 源码中对应 draw-shape-popover.tsx：仅当 2D 场景下形状类型为矩形时渲染Radio.Group，提供By 2 Points（经典拖拽）与By 4 Points（四极值点）两个互斥选项。选项值来自前端画布包的枚举（canvasModel.ts）：

export enum RectDrawingMethod { CLASSIC = 'By 2 points', EXTREME_POINTS = 'By 4 points', }

第二步：依次点击物体的四个极值点

按Shape或Track进入绘制模式后，依次点击物体轮廓上的四个物理极值点：

最上（top-most）点；
最下（bottom-most）点；
最左（left-most）点；
最右（right-most）点。

点击第四个点后绘制自动完成，无需再次确认；按Esc可随时取消编辑。四极值点绘制过程如下动图所示：

源码视角：drawBoxBy4Points 的完整事件流

四极值点的绘制实现在画布绘制处理器中。入口在 drawHandler.ts：当形状类型为rectangle且rectDrawingMethod === RectDrawingMethod.EXTREME_POINTS时调用drawBoxBy4Points()，否则走经典的两点拖拽drawBox()。

drawBoxBy4Points的具体逻辑（drawHandler.ts）：

以隐藏折线收集点击点：在 SVG 画布上创建一个opacity: 0、stroke-width: 0的临时polygon，通过其 SVG 绘制插件的drawstart/drawpoint/undopoint事件统计已点击的点数（支持撤销一个点）；
第四点触发完成：当numberOfPoints === 4时，调用getBBox()取得四个极值点的最小外接正交矩形（axis-aligned bounding box），即points = [bbox.x, bbox.y, bbox.x + bbox.width, bbox.y + bbox.height]；
归一化为标准矩形坐标：经getFinalRectCoordinates(points, true)换算为画布坐标系下的[xtl, ytl, xbr, ybr]；
约束校验后提交：调用checkConstraint('rectangle', [xtl, ytl, xbr, ybr])校验（例如非空尺寸），通过后以points: [xtl, ytl, xbr, ybr]和绘制耗时（Date.now() - this.startTimestamp）调用onDrawDone，交由上层创建 Shape/Track 对象。

可以看到，"四极值点 → 自动完成"的本质就是：以四个极值点构造的最小外接正交矩形，恰好等价于目标的正交包围盒，因此该方法在保证框选精度的同时避免了拖拽式绘制的反复修正。这也与上文的数据表示一致——最终提交的坐标正是[xtl, ytl, xbr, ybr]四点结构。

质量与回归验证

CVAT 的 Cypress 端到端测试中，矩形 Shape 与 Track 标签的创建流程有专门用例覆盖，可参考 tests/cypress/e2e/actions_objects2/case_8_rectangle_shape_track_label.js；该文件中的四极值点绘制场景也验证了"第四点自动完成"的交互契约。若你在自建标注流程或二次开发中修改了绘制交互，可直接运行相关端到端用例回归。

小结

能力	操作要点	对应源码位置
旋转矩形	拖动 rotation point，绕中心旋转；Shift 吸附 15° 步进并实时显示角度	rectangle-shape.ts（绕中心旋转的命中测试）
绘制方式选择	Draw new rectangle 弹窗中选择 By 2 Points / By 4 Points	canvasModel.ts、draw-shape-popover.tsx
四极值点绘制	依次点击上、下、左、右四个极值点，第四点自动完成；Esc 取消	drawHandler.ts
统一数据表示	无论哪种方式，矩形均为`[xtl, ytl, xbr, ybr]`+ 旋转角	rectangle-shape.ts