Label Studio Rectangle 标签完全指南：图像矩形标注框的配置、结果格式与旋转锚点

本篇技术指南围绕 Label Studio 标注配置体系中的核心控制标签 Rectangle（无标签矩形框）及其带标签变体 RectangleLabels 展开，讲解如何在图像目标检测 / 语义分割标注任务中配置矩形边界框、控制绘制工具行为（透明度、描边、旋转、吸附），并深入剖析标注结果（result）中坐标与旋转角度的存储格式。读完本文，你将能够独立编写可运行的矩形标注配置、正确解读输出 JSON 中的 value 坐标语义，并掌握 UI 旋转与结果旋转在锚点上的关键差异。

Rectangle 标签：无需标签的矩形框

Rectangle 是 Label Studio 编辑器中用于在图像上绘制矩形（Bounding Box）的控制标签。与 RectangleLabels 不同，Rectangle 本身不携带标签列表，适用于“图中只有一个目标类别、框即答案”的标注场景。官方示例：

<View>
  <Rectangle name="rect-1" toName="img-1" />
  <Image name="img-1" value="$img" />
</View>

在源码 Rectangle.js 中，该标签被注册为 type: "rectangle"，其工具集为 toolNames: ["Rect", "Rect3Point"]，即支持两种绘制方式：直接拖拽出矩形（Rect），以及通过“三点”方式先定边、再定旋转与宽度（Rect3Point）。Rectangle 适用于 image 类型数据。

标签参数详解

Rectangle 标签的全部参数如下表（见 rectangle.md）：

Param	Type	Default	Description
name	string		元素名称（必须与 toName 配合使用）
toName	string		要标注的图像元素名称
[opacity]	float	0.6	矩形的填充透明度
[fillColor]	string		矩形填充色的十六进制值
[strokeColor]	string	#f48a42	描边颜色的十六进制值
[strokeWidth]	number	1	描边宽度
[canRotate]	boolean	true	是否显示 / 隐藏旋转控制；注意结果中的锚点与旋转工具旋转时的锚点不同
[smart]	boolean		是否显示智能工具，用于交互式预标注
[smartOnly]	boolean		是否仅显示智能工具（交互式预标注专用）
[snap]	pixel | none	none	是否将矩形吸附到图像像素

参数在源码中的实现

对照 Rectangle.js 的模型定义，各参数在运行时被映射为 MST（mobx-state-tree）属性：

• opacity 使用 customTypes.range() 校验，源码中默认值为 "0.2"（文档表给出的默认值为 0.6，两处默认值存在差异，实际以当前仓库源码为准），取值范围为 0～1 的浮点数，控制矩形填充区域的可见程度，便于标注时透视图像内容。
• fillColor 与 strokeColor 使用 customTypes.color 校验，必须是合法的十六进制颜色值；strokeColor 默认 #f48a42（暖橙色），fillColor 未设置时矩形以半透明描边样式呈现。
• strokeWidth 控制边框粗细，默认 1，可适当增大以获得更醒目的边界。
• canRotate 默认 true，决定矩形是否显示旋转控制点；将其设为 false 可简化标注交互（例如仅做轴对齐框标注）。
• snap 支持 pixel 与 none 两种取值，默认 none；设为 pixel 后矩形坐标会对齐到整数像素，适合需要严格像素级标注的任务（如超分辨率、像素级目标检测）。
• 额外的 fillopacity 属性可独立控制填充透明度，与 opacity 配合实现“描边清晰、填充淡色”的效果。

smart 与 smartOnly：交互式预标注

smart / smartOnly 两个布尔参数用于开启交互式预标注（Interactive Pre-annotation）能力。开启后，标注界面会显示智能工具，允许标注者通过点击或框选提示模型生成预标注区域，再以矩形框形式呈现。smart 表示“智能工具与普通矩形工具并存”，smartOnly 表示“界面中仅提供智能工具”。该能力在 RectangleLabels.jsx 中通过 InteractivePromptMixin 混入实现，同时该 mixin 也负责将 LLM 交互提示能力挂载到矩形标签上。

RectangleLabels：带标签的矩形框

当同一张图中存在多个目标类别时，应使用 RectangleLabels 标签。它与 Rectangle 共享全部外观与交互参数，但额外支持标签子节点：

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

完整配置示例见 rectanglelabels.md。从源码看，RectangleLabels.jsx 通过 types.compose 组合了 RectangleModel、LabelsModel、LabelMixin、SelectedModelMixin 与 InteractivePromptMixin，因此它既继承了矩形绘制能力，又具备标签选择能力。标签区域内部还支持 header、view、hypertext 等子元素，便于组织复杂的标签 UI。

RectangleLabels 独有的标签管理参数：

Param	Type	Default	Description
[choice]	single | multiple	single	配置每次标注只能选择一个标签，还是可同时选择多个标签
[maxUsages]	number		单个标签在每项任务中被使用的最大次数
[showInline]	boolean	true	是否将标签显示在同一视觉行内

标注结果（Result）格式与坐标语义

Rectangle / RectangleLabels 产生的标注结果（即任务的 annotations<a href="https://link.gitcode.com/i/6771f0021919d2b529970f94154d1f91" target="_blank">].result[] 数组项）格式如下（见 [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）

完整 JSON 示例：

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

要点解读：

• 坐标是百分比而非像素：value.x、value.y、value.width、value.height 的取值范围均为 0～100，表示相对原始图像宽高的百分比。例如 width: 20 表示框宽为原始图像宽度的 20%。还原为像素需要结合 original_width / original_height 换算。
• x/y 记录的是旋转前的左上角：即存储的是矩形在做旋转之前的锚点坐标，而非旋转后的视觉位置。
• 矩形标签名：使用 RectangleLabels 时，value 中会多出 rectanglelabels 数组字段（如 ["Car"]）；使用 Rectangle 时该字段不存在。
• 回归兼容性：image_rotation 表示整张图像在标注界面中被旋转的角度，旋转后的图像坐标系会自动换算回旋转前的百分比坐标。

上述字段的生成逻辑可在 Image.js 中看到——original_width、original_height 取自图像实体的 naturalWidth / naturalHeight，image_rotation 取自实体旋转状态；对应单元测试见 Image.test.js。

结果中的旋转锚点差异

这是矩形标注中最容易踩坑的一点（详见 image_bbox.md）：

• 在标注界面中用鼠标旋转框：旋转锚点是矩形的中心。拖动旋转手柄时，矩形围绕自身中心点转动。
• 在结果（result）中存储的旋转：无论你如何执行旋转，落盘到 annotation.result[]['value'] 中的 rotation 角度始终是围绕矩形左上角 (x, y) 旋转的角度。也就是说，若你在 Info 面板中直接编辑角度，锚点同样是左上角。

这一差异在 RectRegion.jsx 中有直接体现：矩形区域模型同时维护 rotation（结果中存储的角度，绕左上角）与 rotationAtCreation（创建时的旋转状态）；RectRegion.jsx 中的 bboxCoords 计算在 rotation !== 0 时调用 rotateBboxCoords(bboxCoords, self.rotation, { x: self.x, y: self.y }, ...)，明确以 (x, y) 左上角为旋转中心。因此，当你在后端对结果做几何还原（例如转成 COCO / YOLO 格式）时，必须按“左上角锚点 + rotation 角度”进行变换，否则框的位置会产生偏移。

实战：三种典型标注配置

1. 单类别目标检测（无需标签）

<View>
  <Rectangle name="bbox" toName="img" />
  <Image name="img" value="$image" />
</View>

2. 多类别目标检测（带标签 + 限制使用次数）

<View>
  <RectangleLabels name="labels" toName="img" choice="single" maxUsages="10">
    <Label value="Car" />
    <Label value="Pedestrian" />
    <Label value="Cyclist" />
  </RectangleLabels>
  <Image name="img" value="$image" />
</View>

3. 精细化外观与像素级吸附

<View>
  <RectangleLabels name="labels" toName="img"
                   opacity="0.3" fillColor="#ff0000"
                   strokeColor="#00ff00" strokeWidth="2"
                   canRotate="false" snap="pixel">
    <Label value="Defect" />
  </RectangleLabels>
  <Image name="img" value="$image" />
</View>

该配置将矩形填充透明度降为 0.3 并染红、描边加粗为绿色、禁用旋转并将坐标吸附到像素，适合缺陷检测等需要精确边界与醒目视觉反馈的任务。

总结与进一步阅读

Rectangle 与 RectangleLabels 是 Label Studio 中图像目标检测、语义分割、缺陷定位等任务的基础标注控件：前者面向单类别场景，后者面向多标签场景，二者共享一套外观、旋转与吸附参数，结果统一以“旋转前左上角 + 百分比尺寸 + 旋转角”的格式落盘。使用中需特别留意两点：坐标是 0～100 的百分比，且结果中的旋转永远以左上角为锚点。

• 参数与示例源码：Rectangle.js、RectangleLabels.jsx
• 结果格式参考：rectanglelabels.md
• 旋转锚点详解与三点绘制：image_bbox.md
• 相邻标签：椭圆标注 ellipse.md、多边形标注 polygon.md