Label Studio 图像目标检测标注模板：Bounding Box 矩形框标注配置与旋转锚点详解

2026-09-12 10:28:44作者：齐冠琰

本篇指南聚焦 Label Studio 官方“Object Detection with Bounding Boxes（目标检测矩形框标注）”模板，介绍如何通过 RectangleLabels、Image、Label 标签组合，在图像上绘制矩形包围框并标注框内物体类别。文章除完整给出可直接运行的标注配置外，还会深入讲解旋转矩形框的锚点差异、三种点选绘制流程，以及结果数据（annotation.result[]['value']）中 x/y/width/height/rotation 各字段的含义，帮助你正确采集、解析并导出可直接用于 YOLO、Faster R-CNN 等目标检测模型训练的数据集。

模板核心思路：一次点击完成画框 + 打标签

目标检测任务的数据标注目标非常明确：为图像中的每个目标物体画一个矩形包围框（bounding box），并标注框内物体的类别。本模板在 Label Studio 中把“画框”与“打标签”两个动作合并为一套交互：标注员先在标签面板中选择一个类别（如 Airplane、Car），然后在画布上点击拖拽即可同时完成矩形绘制与类别标注。

模板对应的完整标注配置如下：

<View>
  <Image name="image" value="$image"/>
  <RectangleLabels name="label" toName="image">
    <Label value="Airplane" background="green"/>
    <Label value="Car" background="blue"/>
  </RectangleLabels>
</View>

该配置与仓库内预置模板 object-detection-with-bounding-boxes/config.yml 中 config 字段的内容完全一致，属于官方维护的社区模板，归属于 “Computer Vision” 分组，可直接在新建项目时选择使用。

三个标签的分工

所有标注配置必须用 <View> 标签包裹，它是界面布局的根容器。模板内部由三个标签协作完成标注任务：

1. <Image> 对象标签：指定要标注的图像

<Image name="image" value="$image"/>

name：元素名称，作为后续控制标签 toName 的关联目标；
value：取值绑定到任务数据的 $image 字段，即 JSON 数据中的 image 键或 CSV 中的 image 列，内容为图片 URL；
坐标语义：使用 <Image> 标注图像区域时，所有标注结果都以**原图像尺寸的百分比（0–100）**保存，这正是下文结果字段全部落在 0–100 区间的原因。

2. <RectangleLabels> 控制标签：同时完成画框与打标签

<RectangleLabels name="label" toName="image">
  <Label value="Airplane" background="green"/>
  <Label value="Car" background="blue"/>
</RectangleLabels>

toName="image"：指明矩形框绘制在名为 image 的对象上；
该标签会在画布上提供矩形框绘制工具，并让标注员在绘制前先选定一个类别；
它适用于“框内物体类别多样”的目标检测场景。若你的场景中所有框都对应同一个类别（例如质检中只标“缺陷”一种），可以改用 <Rectangle> 标签——该标签只画框不选标签，配置更简洁（参见 rectangle.md）。

3. <Label> 标签：定义类别与框体颜色

<Label value="Airplane" background="green"/>
<Label value="Car" background="blue"/>

value 定义类别名称，background 定义该类框体的填充颜色，便于标注员在画布上快速区分不同类别（参见 label.md）。

RectangleLabels 与 Rectangle 的常用参数

下表汇总了两个标签的核心参数（来源于 rectanglelabels.md 与 rectangle.md 中的参数表）：

Param	Type	Default	Description
`name`	string	—	元素名称
`toName`	string	—	要标注的图像名称
`choice`	single \| multiple	`single`	是否允许一次选择多个标签（仅 RectangleLabels）
`maxUsages`	number	—	每个标签在单个任务中的最大使用次数（仅 RectangleLabels）
`showInline`	boolean	`true`	标签是否在同一视觉行内展示（仅 RectangleLabels）
`opacity`	float	`0.6`	矩形框的填充不透明度
`fillColor`	string	—	矩形填充色（十六进制）
`strokeColor`	string	`#f48a42`（Rectangle）/ —（RectangleLabels）	描边颜色（十六进制）
`strokeWidth`	number	`1`	描边宽度
`canRotate`	boolean	`true`	是否显示旋转控制手柄；注意结果中的锚点与旋转工具使用的锚点不同
`smart` / `smartOnly`	boolean	—	是否显示/仅显示智能工具用于交互式预标注（仅 Rectangle）
`snap`	pixel \| none	`none`	是否将矩形吸附到图像像素

RectangleLabels 的结果结构

标注完成后，每个矩形框会生成一条 region 结果，其字段定义（来源于 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 中还包含 rectanglelabels 数组，用于存放标注员为这个框选择的类别标签，类别名与配置中 <Label value="..."> 的定义一一对应。

旋转与锚点：UI 旋转和结果数据中的旋转有何不同

旋转矩形框是目标检测中处理倾斜目标（如旋转车辆、斜放物体）的常用手段。模板文档特别强调：旋转的锚点（anchor point）取决于你执行旋转的方式。

在标注界面中用鼠标旋转：锚点是矩形中心

在标注界面中，用鼠标拖拽旋转控制手柄旋转矩形框时，旋转围绕矩形的中心点进行。这是最直观的交互方式——框绕着自己的中心转动。

在结果数据中直接编辑旋转角度：锚点是左上角

在标注界面的 Info（信息）面板中直接修改 rotation 角度值时，旋转围绕矩形的左上角进行。而且无论你当初用哪种方式旋转，最终保存到标注结果 annotation.result[]['value'] 中的数据，其坐标语义都以左上角为锚点：

{
  "x": 50,      # 包围框左上角 x 坐标，占图像宽度的 0-100%
  "y": 60,      # 包围框左上角 y 坐标，占图像高度的 0-100%
  "width": 10,  # 包围框宽度，占图像宽度的 0-100%
  "height": 20, # 包围框高度，占图像高度的 0-100%
  "rotation": 45 # 以包围框左上角为轴心的旋转角度（度）
}

也就是说：交互层（鼠标旋转）以中心为锚点，数据层（结果 JSON）以左上角为锚点。当你在自己的后处理代码中还原或渲染标注时，必须使用左上角锚点语义对 x/y/width/height/rotation 做几何换算，才能得到与界面显示一致的结果。这一点同样被 rectanglelabels.md 与 rectangle.md 文档引用，是解析目标检测标注结果的通用规则。

创建旋转包围框：三点点击与两点点击绘制流程

除了常规的拖拽画框，标注员还可以使用“三点点击（three point click）”或“两点点击（two point click）”方式创建带旋转角度的包围框，适合标注倾斜物体。

三个锚点的含义

第一点点击：确定包围框绘制的起始位置（锚点 0,0）；
第二点点击：确定包围框的旋转角度与宽度（定义 0,1 边及其角度）；
第三点点击：确定包围框的高度（最终锚点 1,1）。

原点锚点 0,0 由第一次点击放置（与普通矩形框相同）；第二个锚点指示 0,1 边的角度以及框的宽度；第三个锚点 1,1 决定框的高度即最终尺寸。创建旋转框至少需要三次点击。

分步操作

放置起点：选中标签后，将鼠标移到画布上任意位置，单击放置第一个锚点 0,0。
- 画布上的参考线（Canvas guides）会指示十字光标的 x 轴与 y 轴方向与位置；
- 包围框的标签指示的是框在画布中的顶部与中心位置，不代表框的朝向。
定义旋转与宽度：移动鼠标到第二个锚点位置。
- 画布参考线会同时显示光标位置并指示朝向；
- click 并 release（按下并释放）放置第二个锚点，完成框的顶边。
绘制高度：继续移动光标放置最后一个锚点，完成创建流程。此时框的底边会跟随光标移动，实时展示高度。
选中并旋转矩形：框创建完成后，无需移动光标即可直接选中并旋转该矩形。

框绘制完成后默认保持选中状态（除非另行设置），随后你可以：

拖动锚点或边缘，将框调整到画布上的目标位置；
判断框的朝向是否受到影响；
在创建过程中实时观察框的朝向与方向。

三点点击的适用限制

三点点击绘制仅在使用 <Rectangle> 标签时可用，不适用于 <RectangleLabels>。

原因在于 <Rectangle> 不需要先选类别，可以在绘制过程中一次性确定位置、角度与尺寸；而 <RectangleLabels> 需要与类别选择联动，交互路径不同。若你的目标检测标注需要旋转框，请评估是选择“多类别 + 普通框”（RectangleLabels）还是“单类别 + 旋转框”（Rectangle）的配置方案。

增强模板：为每个检测框添加描述与反馈

基础模板只采集框的几何信息与类别。若需要为下游任务补充更多语义信息，可以借助按区域（per-region）条件化标注能力，为每个矩形框追加文本描述与选项反馈。

为检测对象添加描述

在标注配置中加入以下片段：

<View visibleWhen="region-selected">
  <Header value="Describe object" />
  <TextArea name="answer" toName="image" editable="true"
            perRegion="true" required="true" />
  <Choices name="choices" toName="image"
           perRegion="true">
    <Choice value="Correct"/>
    <Choice value="Broken"/>
  </Choices>
</View>

各部分的协作机制：

visibleWhen="region-selected"（View 标签参数）：在标注员选中某个包围框之前，隐藏这段描述提示区域，界面保持整洁；
<Header value="Describe object" />（Header 标签）：当标注员选中包围框后显示，作为标注指令；
<TextArea ... perRegion="true" required="true" />（TextArea 标签）：perRegion="true" 使文本框作用于当前选中的包围框，required="true" 强制填写；还可添加 placeholder 参数给标注员提供建议文本；
<Choices ... perRegion="true">（Choices 标签）：同样以 perRegion 参数按区域记录选项反馈，例如判断框内物品状态为 Correct 或 Broken。

由此，每个包围框的标注结果将同时携带几何坐标、类别、文本描述与状态选项四类信息，可直接用于构建带属性/质量标签的目标检测数据集。

从模板到数据集：产出与落地

数据导出格式

完成标注后，Label Studio 会以标准化的 annotation JSON 结构导出结果。每个矩形框对应 result 数组中的一条记录，value 中包含 x、y、width、height、rotation 以及 rectanglelabels（类别数组）。解析时请注意：

坐标均为 0–100 的百分比值，还原为像素需乘以 original_width / original_height；
旋转锚点为左上角，与鼠标旋转时的中心锚点不同；
image_rotation 记录整张图像的旋转，与单框 rotation 相互独立。

模板适用场景

从仓库内模板元信息（object-detection-with-bounding-boxes/config.yml 的 details 字段）可以确认，该模板面向以下典型行业应用：自动驾驶与自驾驶汽车、交通监控、航空与航班追踪、机场安检、监控安防、零售分析与库存管理、仓储自动化、物流与车队管理、行人检测、障碍物检测、车牌检测、行李安检、质量控制、缺陷检测、医学影像等；并常与 YOLO、R-CNN、SSD、Faster R-CNN、RetinaNet、FCOS 等目标检测模型配套使用。