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

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 为 <a href="https://link.gitcode.com/i/cadc4b0b6c34e8d34649e4d04077279c" target="_blank">"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）：

Param	Type	Default	Description
name	string		元素名称，结果数据中的标识
toName	string		要标注的图像名称（对应 Image 标签的 name）
[choice]	single | multiple	single	配置每个区域可选择一个还是多个标签
[maxUsages]	number		每个任务中单个标签的最大使用次数
[showInline]	boolean	true	在同一视觉行内显示标签
[opacity]	float	0.6	矩形的填充不透明度
[fillColor]	string		矩形填充色（十六进制）
[strokeColor]	string		描边颜色（十六进制）
[strokeWidth]	number	1	描边宽度
[canRotate]	boolean	true	显示或隐藏旋转控制柄。注意：结果中存储的锚点与旋转工具旋转时使用的锚点不同
[snap]	pixel | none	none	将矩形吸附到图像像素

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）：

Name	Type	Description
original_width	number	原始图像宽度（px）
original_height	number	原始图像高度（px）
image_rotation	number	图像的旋转角度（deg）
value	Object
value.x	number	旋转前左上角 x 坐标（0-100）
value.y	number	旋转前左上角 y 坐标（0-100）
value.width	number	边界框宽度（0-100）
value.height	number	边界框高度（0-100）
value.rotation	number	边界框自身的旋转角度（deg）
value.rectanglelabels	array	该矩形被赋予的标签列表

标准示例 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 归一化到 <a href="https://link.gitcode.com/i/cdf6ac155d7b85855610f6e7fc93ee2d" target="_blank">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 标签。