Label Studio RectangleLabels 标签详解：图像目标检测矩形标注框的配置与数据格式

Label Studio RectangleLabels 标签详解：图像目标检测矩形标注框的配置与数据格式

【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio

RectangleLabels是 Label Studio 中用于在图像上绘制**带标签矩形边界框（bounding box）**的核心控制标签，广泛应用于目标检测、语义分割等机器学习数据标注场景。本文以docs/source/tags/rectanglelabels.md及其包含文件docs/source/includes/tags/rectanglelabels.md为骨架，结合前端编辑器源码 RectangleLabels.jsx 与区域实现 RectRegion.jsx，完整讲解标签参数、结果数据结构、旋转与像素吸附等底层行为，帮助你写出可直接运行的标注配置并准确解析标注结果。

一、标签概览：RectangleLabels是什么

RectangleLabels是一个带标签的矩形绘制控件。标注员在图像上拖拽出一个矩形区域后，必须为其选择一个预先定义的标签（Label），标注结果即成为一个"类别 + 边界框"的组合，这正是目标检测任务的标准标注形态。

<View> <RectangleLabels name="labels" toName="image"> <Label value="Person" /> <Label value="Animal" /> </RectangleLabels> <Image name="image" value="$image" /> </View>

与之对应，项目中还存在一个不带标签的Rectangle标签（源码见 Rectangle.js），适用于"整张图只有一个类别、无需选择标签"的简化场景。从源码看，Rectangle模型的toolNames为["Rect", "Rect3Point"]，即支持普通的对角拖拽画矩形，也支持三点法绘制；而RectangleLabels模型在 RectangleLabels.jsx 中声明type: "rectanglelabels"，其子元素允许label、header、view、hypertext四种类型，并将生成的区域模型注册为RectRegion（对应源码 RectRegion.jsx）。

适用数据类型：image。RectangleLabels的Validation模型通过controlledTags: Types.unionTag(["Image"])明确约束：toName只能指向Image标签，若指向其他类型对象会触发配置校验错误。

二、参数详解：从文档表格到源码实现

下表完整列出RectangleLabels支持的全部参数（取自docs/source/includes/tags/rectanglelabels.md）：

2.1 必选参数：name 与 toName

• name：该标签组在配置中的唯一标识，标注结果中用它来关联对应区域；
• toName：必须与某个<Image name="...">的 name 保持一致，声明矩形绘制在哪个图像对象上。

2.2 标签选择行为：choice 与 maxUsages

• choice="multiple"允许一个矩形同时被赋予多个标签，适合多标签分类的目标检测；默认single只允许选择一个。
• maxUsages限制每个标签在单个任务中被使用的次数，达到上限后该标签将被禁用，用于控制类别分布。

2.3 视觉表现参数：showInline / opacity / fillColor / strokeColor / strokeWidth

• showInline控制标签按钮是否与图像处于同一视觉行。
• opacity默认0.6，控制矩形填充的透明度，方便标注时透看底层图像细节。在无标签的Rectangle标签中默认值为0.2（见 Rectangle.js），而RectangleLabels默认0.6，两者可分别按需覆盖。
• fillColor/strokeColor接受十六进制颜色（如#f48a42），可覆盖填充与描边配色；若不指定，则默认依据所选 Label 的背景色渲染。
• strokeWidth默认1，单位为像素。仓库内置示例 image_bbox/config.xml 中即演示了strokeWidth="5"加粗描边与fillOpacity="0.5"半透明填充的组合用法。

2.4 交互与几何参数：canRotate 与 snap

• canRotate默认true，显示旋转控制柄。关键细节：结果 JSON 中value内存储的锚点（左上角坐标）与使用旋转工具旋转时的锚点并不相同，解析旋转结果时必须注意这一差异（详见下文第四节）。
• snap取值为pixel或none（默认）。当设为pixel时，矩形边界会吸附到整数像素坐标，避免产生亚像素级别的坐标值。从源码 RectRegion.jsx 可以看到，吸附逻辑在setPosition中触发：将左上角与右下角坐标取整后重新计算宽高，并通过minPixelWidth保证吸附后矩形至少保留 1 像素的尺寸。

三、标注结果：Result 参数与 JSON 格式

每个矩形区域产生的标注结果包含以下字段（完整继承自docs/source/includes/tags/rectanglelabels.md）：

标准示例 JSON：

{ "original_width": 1920, "original_height": 1280, "image_rotation": 0, "value": { "x": 3.1, "y": 8.2, "width": 20, "height": 16, "rectanglelabels": ["Car"] } }

3.1 坐标归一化：为什么是 0-100

value.x、value.y、value.width、value.height均为百分比归一化坐标，取值范围 0-100，而非像素值。要还原真实像素边界框，需要结合original_width与original_height换算：

像素x = value.x / 100 * original_width 像素y = value.y / 100 * original_height 像素宽 = value.width / 100 * original_width 像素高 = value.height / 100 * original_height

例如上例中：x=3.1, width=20, original_width=1920，则实际像素 x 约为 59.5px，框宽 384px。归一化设计使标注结果与图像原始分辨率解耦——即使图像被浏览器缩放显示，结果坐标依然稳定。

3.2 结果中的标签数组

value.rectanglelabels是字符串数组：当choice="single"时数组只有一个元素；当choice="multiple"时包含多个标签。这一结构与 Label Studio 的标准化输出格式保持一致，可直接对接目标检测训练管线（如 COCO / YOLO 格式转换）。

四、旋转：锚点差异与坐标还原

文档特别强调：结果中存储的锚点与旋转工具旋转时使用的锚点不同。含义如下：

• 结果 JSON 中的x、y记录的是旋转前边界框的左上角（百分比坐标）；
• 旋转工具交互时，旋转是围绕区域中心进行的。

源码 RectRegion.jsx 给出了旋转坐标的换算实现：当rotation !== 0时，通过rotateBboxCoords(bboxCoords, self.rotation, { x: self.x, y: self.y }, self.parent.whRatio)计算旋转后的包围盒——旋转中心是区域的x/y中心点，同时引入whRatio（宽高比）参与运算，说明旋转后的包围盒是针对旋转后坐标重新计算的外接框，而非简单地对原始框做几何旋转。

在实际应用中有两点需要注意：

1. 图像旋转（image_rotation）：当整张图像本身旋转时（如 EXIF 方向修正），结果中的image_rotation字段记录该角度，解析时需与区域旋转分别处理；
2. 区域旋转（value.rotation）：表示边界框自身的旋转角度，角度按(rotation + 360) % 360归一化到[0, 360)（见源码 RectRegion.jsx）。还原实际像素位置时，应先依据x/y/width/height计算未旋转框，再围绕框中心应用value.rotation旋转。

五、源码级延伸：标签注册与校验

从编辑器源码可以进一步确认RectangleLabels在系统中的身份：

• 标签注册：在 RectangleLabels.jsx 中通过Registry.addTag("rectanglelabels", RectangleLabelsModel, HtxRectangleLabels)注册，因此配置中书写<RectangleLabels>即可被编辑器识别；
• 模型组合：RectangleLabelsModel由ControlBase（基础控制行为）、LabelsModel（标签列表管理）、RectangleModel（矩形几何属性）、LabelMixin、SelectedModelMixin（当前选中标签）与InteractivePromptMixin（交互式提示）等 mixin 组合而成（RectangleLabels.jsx），这也解释了为何该标签天然支持标签选择与矩形绘制的一体化交互；
• 配置校验：Validation模型限定controlledTags仅允许Image，配置面板会在toName指向非图像对象时给出校验错误；
• 子元素约束：children仅允许label、header、view、hypertext，其中header可用于在标签区显示分组标题，view可嵌套做更复杂的布局。

六、可运行的完整示例

结合以上参数，一个具备旋转、像素吸附、多标签能力的完整配置示例如下：

<View> <Header>请框出图像中的车辆与行人</Header> <RectangleLabels name="bbox" toName="img" choice="single" opacity="0.4" strokeWidth="3" canRotate="true" snap="pixel"> <Label value="Car" background="#ff0000" /> <Label value="Pedestrian" background="#00ff00" /> <Label value="Cyclist" background="#0000ff" /> </RectangleLabels> <Image name="img" value="$image" /> </View>

若你的任务只需"画框、不需要选标签"，可改用无标签的<Rectangle name="rect" toName="img" />（参见 Rectangle.js）。仓库中完整的可运行示例还可在 image_bbox 示例目录 中找到，包含 config.xml、任务数据tasks.json与对应标注结果annotations/1.json，适合作为格式验证与二次开发的参考。

七、要点回顾

• RectangleLabels面向图像目标检测/语义分割任务，绘制"标签 + 边界框"，必须配合Image标签使用；
• 关键参数：name/toName必填，choice控制单/多标签，maxUsages限制标签使用次数，snap="pixel"吸附像素坐标，canRotate控制旋转能力；
• 结果数据使用 0-100 的归一化坐标，需结合original_width/original_height还原像素框；
• 旋转结果与旋转工具使用不同的锚点：存储的是旋转前左上角，旋转围绕区域中心，解析旋转框时需先还原未旋转框再绕中心旋转；
• 需要无标签纯矩形时，选择Rectangle标签；需要类别语义时，选择RectangleLabels标签。

【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio