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-studioRectangleLabels是 Label Studio 中用于在图像上绘制**带标签矩形边界框bounding box**的核心控制标签广泛应用于目标检测、语义分割等机器学习数据标注场景。本文以docs/source/tags/rectanglelabels.md及其包含文件docs/source/includes/tags/rectanglelabels.md为骨架结合前端编辑器源码 RectangleLabels.jsx 与区域实现 RectRegion.jsx完整讲解标签参数、结果数据结构、旋转与像素吸附等底层行为帮助你写出可直接运行的标注配置并准确解析标注结果。一、标签概览RectangleLabels是什么RectangleLabels是一个带标签的矩形绘制控件。标注员在图像上拖拽出一个矩形区域后必须为其选择一个预先定义的标签Label标注结果即成为一个类别 边界框的组合这正是目标检测任务的标准标注形态。View RectangleLabels namelabels toNameimage Label valuePerson / Label valueAnimal / /RectangleLabels Image nameimage 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.mdParamTypeDefaultDescriptionnamestring元素名称结果数据中的标识toNamestring要标注的图像名称对应Image标签的 name[choice]single|multiplesingle配置每个区域可选择一个还是多个标签[maxUsages]number每个任务中单个标签的最大使用次数[showInline]booleantrue在同一视觉行内显示标签[opacity]float0.6矩形的填充不透明度[fillColor]string矩形填充色十六进制[strokeColor]string描边颜色十六进制[strokeWidth]number1描边宽度[canRotate]booleantrue显示或隐藏旋转控制柄。注意结果中存储的锚点与旋转工具旋转时使用的锚点不同[snap]pixel|nonenone将矩形吸附到图像像素2.1 必选参数name 与 toNamename该标签组在配置中的唯一标识标注结果中用它来关联对应区域toName必须与某个Image name...的 name 保持一致声明矩形绘制在哪个图像对象上。2.2 标签选择行为choice 与 maxUsageschoicemultiple允许一个矩形同时被赋予多个标签适合多标签分类的目标检测默认single只允许选择一个。maxUsages限制每个标签在单个任务中被使用的次数达到上限后该标签将被禁用用于控制类别分布。2.3 视觉表现参数showInline / opacity / fillColor / strokeColor / strokeWidthshowInline控制标签按钮是否与图像处于同一视觉行。opacity默认0.6控制矩形填充的透明度方便标注时透看底层图像细节。在无标签的Rectangle标签中默认值为0.2见 Rectangle.js而RectangleLabels默认0.6两者可分别按需覆盖。fillColor/strokeColor接受十六进制颜色如#f48a42可覆盖填充与描边配色若不指定则默认依据所选 Label 的背景色渲染。strokeWidth默认1单位为像素。仓库内置示例 image_bbox/config.xml 中即演示了strokeWidth5加粗描边与fillOpacity0.5半透明填充的组合用法。2.4 交互与几何参数canRotate 与 snapcanRotate默认true显示旋转控制柄。关键细节结果 JSON 中value内存储的锚点左上角坐标与使用旋转工具旋转时的锚点并不相同解析旋转结果时必须注意这一差异详见下文第四节。snap取值为pixel或none默认。当设为pixel时矩形边界会吸附到整数像素坐标避免产生亚像素级别的坐标值。从源码 RectRegion.jsx 可以看到吸附逻辑在setPosition中触发将左上角与右下角坐标取整后重新计算宽高并通过minPixelWidth保证吸附后矩形至少保留 1 像素的尺寸。三、标注结果Result 参数与 JSON 格式每个矩形区域产生的标注结果包含以下字段完整继承自docs/source/includes/tags/rectanglelabels.mdNameTypeDescriptionoriginal_widthnumber原始图像宽度pxoriginal_heightnumber原始图像高度pximage_rotationnumber图像的旋转角度degvalueObjectvalue.xnumber旋转前左上角 x 坐标0-100value.ynumber旋转前左上角 y 坐标0-100value.widthnumber边界框宽度0-100value.heightnumber边界框高度0-100value.rotationnumber边界框自身的旋转角度degvalue.rectanglelabelsarray该矩形被赋予的标签列表标准示例 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-100value.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例如上例中x3.1, width20, original_width1920则实际像素 x 约为 59.5px框宽 384px。归一化设计使标注结果与图像原始分辨率解耦——即使图像被浏览器缩放显示结果坐标依然稳定。3.2 结果中的标签数组value.rectanglelabels是字符串数组当choicesingle时数组只有一个元素当choicemultiple时包含多个标签。这一结构与 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宽高比参与运算说明旋转后的包围盒是针对旋转后坐标重新计算的外接框而非简单地对原始框做几何旋转。在实际应用中有两点需要注意图像旋转image_rotation当整张图像本身旋转时如 EXIF 方向修正结果中的image_rotation字段记录该角度解析时需与区域旋转分别处理区域旋转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 namebbox toNameimg choicesingle opacity0.4 strokeWidth3 canRotatetrue snappixel Label valueCar background#ff0000 / Label valuePedestrian background#00ff00 / Label valueCyclist background#0000ff / /RectangleLabels Image nameimg value$image / /View若你的任务只需画框、不需要选标签可改用无标签的Rectangle namerect toNameimg /参见 Rectangle.js。仓库中完整的可运行示例还可在 image_bbox 示例目录 中找到包含 config.xml、任务数据tasks.json与对应标注结果annotations/1.json适合作为格式验证与二次开发的参考。七、要点回顾RectangleLabels面向图像目标检测/语义分割任务绘制标签 边界框必须配合Image标签使用关键参数name/toName必填choice控制单/多标签maxUsages限制标签使用次数snappixel吸附像素坐标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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考