企业官网建设流程全解析

CVAT 立方体（Cuboid）标注的编辑操作与透视原理实战指南

【免费下载链接】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 文档中「Editing the cuboid」为核心，系统讲解 3D 立方体标注的编辑交互：如何通过拖拽顶点、边中点与面来调整形状，如何利用前视面（front face）配合Shift键制作单点透视效果，以及如何通过右键菜单重置或切换透视方向。文中同时结合仓库前端源码，解释这些交互背后的几何模型实现，帮助你在标注车载物体、箱体等 3D 目标时做到精准、高效的形状调整。

编辑前的准备：认识立方体的构成

在 CVAT 中，立方体（Cuboid）用于标注汽车、箱子等三维目标物体。在动手编辑之前，先了解它的基本结构，会让后续操作事半功倍。

立方体由 8 个顶点、12 条边和 6 个面组成，但在编辑器里，你真正需要关注的是以下两类可见元素：

• 顶点（vertices）：立方体的 8 个角点，用于拉伸整个形状；
• 面（faces）：立方体暴露在外的表面，其中有一个非常特殊——前视面（front face）。

前视面是立方体上只以灰色线条绘制（没有填充色）的那个面，你可以从下图中轻松辨认。它在整个编辑流程中扮演「基准面」的角色：所有透视计算、面的定向都以它为参照。从源码看，立方体模型正是围绕这个前视面组织几何数据的，见 cuboid.ts 中的CuboidModel类，它分别记录了 front（前）、right（右）、left（左）、dorsal（背）、top（顶）、bot（底）六个面，以及前右、前左、后右、后左等 12 条边，其中前视面由索引[0,1,3,2]四个点构成。

技术约束：当前版本仅支持「单点透视」（one point perspective），且所有垂直边都与画面侧边严格平行（参见 annotation-with-cuboids/_index.md 的说明）。这一点在你编辑和制造透视效果时非常重要。

立方体的三种基础编辑方式

创建好立方体后（创建方式见 creating-the-cuboid.md，支持「from rectangle」和「by 4 points」两种画法），你可以用以下三种方式对形状进行编辑：

方式一：整体移动

直接拖动前视面背后的区域（即前视面所围成的形状内部），即可整体平移立方体。这是最符合直觉的操作——抓住立方体身体，把它放到目标位置。

方式二：沿边延伸

拖动每条边中间的点，可以沿该边的方向延伸立方体。边中点是专门为拉伸设计的控制柄，拖动后整条边及其相邻面会随之伸缩。

方式三：沿垂直方向拉伸

拖动顶点的点，可以让立方体向上或向下扩展。顶点既负责改变高度，也是后续制造透视效果时的操作对象。

这三种方式可以自由组合：先拖顶点定高度，再拖边中点调宽度，最后拖身体调整位置，就能把一个基础立方体快速塑造成贴合目标的形状。

用前视面与 Shift 键制造透视效果

透视效果是立方体标注最有价值也最需要技巧的能力。它的前提假设是：前视面离相机最近。所有透视操作都以此为基础展开。

操作步骤

1. 首先明确哪个面是前视面（灰色线条绘制、无填充色的那个面），把它当作离镜头最近的面；
2. 按住Shift键不放，拖动不在前视面上的那些顶点（即位于左右、上下的其他角点）；
3. 拖动过程中，被拖动的角点会相对前视面产生远近关系，从而在画面上呈现出近大远小的透视效果；
4. 松开Shift后，立方体进入正常的可编辑状态，你仍可像平时一样继续拖拽调整。

为什么是 Shift？

从源码可以找到答案。在 svg.patch.ts 中有明确注释：对立方体而言，Shift键被专门用于改变透视（对矩形则是用于精确旋转）。也就是说，Shift在立方体编辑场景下被复用作透视模式的开关，而不是常规的「约束/多选」语义。

透视计算的底层逻辑同样在 cuboid.ts 的updateVanishingPoints方法中实现：它会分别求出左、右两侧边线与中间边线的交点，得到左消失点vpl与右消失点vpr；随后通过buildBackEdge方法，从这两个消失点出发推算背面边（back edge）的位置。这也是为什么当你拖动某个非前视面顶点时，背面会自动跟着「收拢」，形成近大远小的观感。

右键菜单：重置透视与切换透视方向

透视效果并非不可逆，CVAT 为它提供了两个右键菜单命令。

重置透视（Reset perspective）

如果你对透视效果不满意，希望让立方体恢复为规则的（无透视）形状：

1. 右键点击该立方体；
2. 在弹出的上下文菜单中选择Reset perspective；
3. 立方体立即恢复为规则立方体。

从源码看，svg.patch.ts 中定义了resetPerspective()方法，并在交互事件处理中（见 svg.patch.ts）被调用；对应的菜单项出现在前端对象菜单中（见 object-item-menu.tsx）。

切换透视方向（Switch perspective orientation）

前视面的位置并非固定不变，你可以把它与相邻的可见侧面互换：

1. 右键点击该立方体；
2. 选择Switch perspective orientation；
3. 前视面的位置会在相邻侧面上切换，同时透视效果会被一并重置。

这一点与源码中的朝向（orientation）机制相呼应：cuboid.ts 定义了Orientation枚举（LEFT/RIGHT），而updateOrientation()方法（cuboid.ts）通过比较前左（fl）与前右（fr）边端点的横坐标来自动判断当前朝向，从而决定后续透视几何如何重建。

关于各侧面的可编辑性

透视切换后你会发现，并非所有面都能独立编辑。文档明确说明：相对于前视面而言，左面（left）、右面（right）和背面（dorsal）这三个面可以被单独拖拽，且互不影响、独立于立方体其余部分运动。也就是说，你可以在保持前视面与顶/底面不动的前提下，单独把某一侧面向外推或向内收——这在标注倾斜停放的车辆时尤其有用。

从数据结构上看，cuboid.ts 的initFaces()将 front、right、dorsal、left 四个面放进了facesList，这正是编辑器支持「面级独立编辑」的几何基础：每个面持有自己的一组顶点索引，拖拽某个面时只需更新该面所引用的顶点，而不必重建整个立方体。

在轨迹模式中使用立方体

立方体同样支持轨迹模式（track mode），其使用方式与矩形在轨迹模式下的操作基本一致。轨迹模式的基础操作（关键帧插值、自动补间、播放校验等）可参考 track-mode-basics.md。

在轨迹模式下标注移动的 3D 目标时，建议结合前文技巧：先在关键帧上摆好透视方向与形状，再利用轨迹插值让立方体跟随目标运动，最后回到个别帧微调顶点和侧面，以保证整段轨迹的形状一致性。

操作速查与最佳实践

几点实践建议：

• 先定透视，再调细节：透视效果会连带影响背面位置，因此建议先完成透视方向的设定，再进行边与面的微调；
• 留意垂直边约束：当前实现强制垂直边与画面侧边平行，拖拽时若感觉「高度被限制」，这是设计约束而非 bug；
• 善用背面推算：拖动角点时背面会自动跟随消失点收拢，你可以借助这个特性快速判断透视是否合理，必要时用Reset perspective一键还原再重来。

相关资源

• annotation-with-cuboids/_index.md：立方体标注功能总览，含「单点透视」「垂直边平行」等能力约束说明；
• creating-the-cuboid.md：立方体的创建方式（from rectangle / by 4 points）；
• track-mode-basics.md：轨迹模式基础操作；
• cuboid.ts：立方体几何模型源码，含消失点计算、面/边定义与朝向判定；
• svg.patch.ts：画布交互实现，含Shift键透视切换与resetPerspective()方法；
• object-item-menu.tsx：对象右键菜单中Reset perspective等命令的实现位置。

【免费下载链接】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