CVAT 形状分组（Shape Grouping）：快捷键操作、group

CVAT 形状分组（Shape Grouping）：快捷键操作、group_id 导出与源码实现解析

【免费下载链接】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 官方文档 Shape grouping 展开，讲清在 CVAT 标注编辑器中如何把多个形状绑定到同一逻辑组（例如一辆车的前后两个轮子框），包括Group Shapes按钮与G/Esc/Shift+G快捷键的完整用法、导出标注中group_id字段的含义，以及Color By Group配色模式。读完后你不仅能上手分组操作，还能结合 cvat-canvas 与 cvat-core 的源码理解分组选择器、组索引分配和撤销/重做（undo/redo）的底层机制。

什么是形状分组

形状分组（Shape grouping）是 CVAT 中用于表达"多个独立形状同属一个对象"的标注能力。典型场景如 DETRAC 等车辆数据集中，一辆车在画面中的前轮、后轮各自是独立的矩形，但逻辑上它们属于同一辆车；通过分组，你可以用标注数据显式表达这种从属关系，而不是仅靠颜色或命名约定。

分组后的形状在数据层面共享同一个组标识。官方文档明确指出：分组后的形状在导出（dumped）标注中会带有group_id字段。没有分组形状（即不属于任何组的形状）没有该字段。这一字段是 CVAT 各导出格式（如 COCO 风格的类别+组结构、PASCAL VOC 扩展等）区分"同一对象多个部件"的关键依据。

操作入口与快捷键

CVAT 文档给出的操作方式有按钮和快捷键两类，完整清单如下：

操作	触发方式	说明
进入/退出分组选择模式	`G`	开始选择（start selection）/ 结束选择（end selection in group mode）
关闭分组模式	`Esc`	取消当前分组选择
重置所选形状分组	`Shift+G`	将已选中形状的分组清除（reset group）
图形化入口	`Group Shapes`按钮	位于右侧标注控制面板（Controls Sidebar）中，效果等价于进入分组模式

选择形状的方式有两种：逐个点击形状，或框选一块区域批量选中。确认选择后即完成分组。Group Shapes按钮的具体位置可见 Controls Sidebar 文档。

group_id 在导出标注中的体现

分组信息会随标注一起落到导出数据里。官方文档原文：

Grouped shapes will havegroup_idfield in dumped annotation.

也就是说：

已分组的形状：导出文件中携带group_id，同组形状取相同的值；
未分组的形状：不带group_id（或取表示"无组"的默认值，具体取决于所选导出格式）。

这一点对下游训练和评估代码很重要：例如按实例聚合部件、做实例级损失或按对象做数据增强时，都可以直接依赖group_id而不是解析标签文本。

Color By Group 配色模式

CVAT 默认按"实例（instance）"维度分配颜色，即每个 track/对象一种颜色。为了直观看到分组结果，编辑器支持把颜色分配切换到组维度：

勾选Color By Group复选框，即可将颜色分配从按实例切换为按组分配；
没有group_id的形状会以白色高亮显示，方便快速识别哪些形状尚未分组。

从源码结构看，组颜色并非固定不变：前端存在changeGroupColorAsyncaction，可对指定组内的所有形状批量设置颜色并触发标注更新（见 annotation-actions.ts）。另外，3D 画布视图同样暴露了按组着色的相关选项（见 canvas3dView.ts 中 color by group 相关代码），可以推断 2D/3D 两种视图在分组可视化上保持了一致的能力。

官方文档附带的两张示例截图分别展示了：一个含分组形状的标注画面，以及一个同时存在"已分组 + 未分组（白色）"形状的画面，可作为操作结果的视觉参照。

源码实现：分组选择器与组索引分配

GroupHandler：分组模式的"开—选—关"生命周期

分组交互的画布侧实现在 GroupHandlerImpl（cvat-canvas 模块）。其核心流程：

进入分组模式：group()收到enabled: true的groupData时调用initGrouping(selectionFilter)，激活ObjectSelector选择器并记录起始时间戳，用户此后点击的形状会累积进statesToBeGrouped；
结束分组模式：enabled: false时调用closeGrouping()——释放选择器后，若statesToBeGrouped非空，则连同选择耗时一起回调onSelectDone(statesToBeGrouped, duration)；
取消：cancel()直接释放选择器并以空结果回调，对应快捷键Esc的"关闭分组模式"语义。

SelectionFilter参数保证了分组模式只接受特定过滤条件下的对象，与编辑器当前的可见/可标注状态保持一致。

组索引分配与 undo/redo 一致性

真正修改数据模型的操作在 AnnotationsCollection.group：

group(objectStates, reset)先校验入参必须是形状数组（checkObjectType）；
组索引取自集合内的groupsInfo计数器：reset为真时组号为0（即清组，对应Shift+G），否则为++this.groupsInfo.max，也就是分配下一个全局递增组号；
给每个形状写入object.group = groupIdx后，把变更前的旧组值与变更后的新组值分别存入undoGroups/redoGroups，注册到撤销栈——这保证了撤销/重做分组操作时，每个形状能精确恢复到原来的组归属。

前端 thunk groupAnnotationsAsync 将选中形状传给jobInstance.annotations.group(statesToGroup, reset)完成持久化更新，把画布交互与数据模型变更串联成完整调用链。

与 Track 切分的关系

从源码结构还可以看到一处容易踩坑的细节：track 在帧上被切分时（annotations-collection.ts 中 split 相关逻辑），会把原 track 的形状"分成两组（before/after 切分帧之前/之后）"，切分出的新对象会继承slicedObject.group。可以推断：分组信息在 track 编辑（插值、切分、合并）中是被显式维护的，而不是在编辑后丢失，这解释了为什么分组能在长视频标注中跨帧保持一致。

验证与延伸阅读

操作入口文档：Controls Sidebar（Group Shapes按钮所在位置）；
形状标注基础：Types of shapes、Track mode basics（分组常与 track 标注配合使用）；
交互实现：groupHandler.ts、objectSelector.ts；
数据模型与持久化：annotations-collection.ts、annotation-actions.ts。

小结：CVAT 的形状分组通过G键进入选择模式、点击或框选形状、再次G确认（或Esc取消）三步完成，Shift+G可清除已选中形状的分组；结果以group_id字段落入导出数据，配合Color By Group模式（未分组形状显示为白色）可直观校验分组结果。实现上由 cvat-canvas 的GroupHandlerImpl负责交互生命周期，cvat-core 的AnnotationsCollection.group负责组号分配与 undo/redo 一致性，二者通过 Redux thunk 串联，形成从按键到数据持久化的完整链路。