企业官网建设流程全解析

Label Studio 图像椭圆标注实战:image_ellipses 示例的 EllipseLabels 配置、预标注与结果格式解析

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

Label Studio 的EllipseLabels标签用于在图像上绘制带类别标签的椭圆边界框,常用于行星、细胞、圆形 UI 元素等非矩形目标的分段标注。本文基于仓库内官方示例 image_ellipses 及其说明文档 START.md,完整讲解椭圆标注环境的安装、服务启动命令、Label 配置 XML、任务数据与预标注结构,并结合编辑器源码剖析椭圆区域(EllipseRegion)的几何字段与最小尺寸校验逻辑,帮助你在项目中直接复用这套椭圆标注方案。

示例文件结构与角色

image_ellipses示例位于编辑器源码的 examples 目录下,目录结构如下:

index.js 的导出方式说明该示例可直接被 Playground 或 Storybook 类宿主引用:

import config from "./config.xml"; import tasks from "./tasks.json"; import annotation from "./annotations/1.json"; export const ImageEllipselabels = { config, tasks, annotation };

这种「一个目录 = 一个可运行标注场景」的组织方式在 examples 目录下贯穿image_bbox、image_polygons、image_keypoints等所有图像示例,是快速上手各类标注任务的官方模板。

环境安装(Linux / Ubuntu)

START.md 给出的安装步骤基于 Python 3.6 + virtualenv 的独立环境:

# install python and virtualenv apt install python3.6 pip3 install virtualenv # setup python virtual environment virtualenv -p python3 env3 source env3/bin/activate # install requirements cd backend pip install -r requirements.txt

需要注意版本演进带来的路径差异:文档中cd backend对应的是早期仓库布局。在当前仓库中,Label Studio 服务端代码已收敛到 label_studio/ 包,依赖管理改用 pyproject.toml 与uv.lock,因此在新克隆的仓库中按 安装文档 的流程配置环境即可;上述 START.md 步骤仍可作为「用 virtualenv 隔离环境、按 requirements 安装依赖」这一方法论的参考。

启动标注服务:server.py 参数解析

文档给出的启动命令:

python server.py -c config.json -l ../examples/image_ellipses/config.xml -i ../examples/image_ellipses/tasks.json -o output

参数含义:

• -c config.json:服务端本地配置(数据库、认证等);
• -l:指定 Label 配置文件路径;
• -i:导入任务文件(JSON);
• -o:标注输出目录。

两点实操提示:

1. 路径需按当前仓库结构调整。示例中的../examples/image_ellipses/...是旧布局下的相对路径;当前仓库中该示例实际位于 web/libs/editor/src/examples/image_ellipses/,启动时应把-l与-i指向这两个文件的真实位置,例如config.xml与tasks.json的当前完整路径分别为web/libs/editor/src/examples/image_ellipses/config.xml和web/libs/editor/src/examples/image_ellipses/tasks.json。
2. 命令行参数由 label_studio/core/argparser.py 中的parse_input_args解析,服务端入口为 label_studio/server.py,可用于核对参数的完整取值。

标注配置:config.xml 逐项解读

示例的完整 Label 配置:

<View> <Image name="img" value="$image"></Image> <EllipseLabels name="tag" toName="img" fillOpacity="0.5" strokeWidth="3"> <Label value="Planet" background="yellow"></Label> <Label value="Moonwalker" background="red"></Label> </EllipseLabels> <Choices name="choice" toName="img"> <Choice value="Space" /> <Choice value="Underground" /> </Choices> </View>

• <Image name="img" value="$image">:图像对象标签,value绑定任务data字段中的$image;它是所有区域控件的标注目标(toName="img")。
• <EllipseLabels>:带类别的椭圆控件。fillOpacity="0.5"控制椭圆填充透明度,strokeWidth="3"控制描边宽度;两个子<Label>定义类别Planet(黄色背景)与Moonwalker(红色背景),background仅影响编辑器 UI 中类别的视觉颜色。
• <Choices>:与椭圆并行的图像级单选(如场景为Space/Underground),演示了「区域标注 + 全局属性标注」组合的场景。

从源码结构看,椭圆控件的完整属性定义在 web/libs/editor/src/tags/control/Ellipse.js 的TagAttrs中,包含opacity(默认0.2)、fillColor/strokeColor(默认#f48a42)、strokeWidth(默认1)、canRotate(默认true,控制是否显示旋转手柄)以及smart/smartOnly(智能预标注工具开关)。官方属性参考还可对照 ellipse 标签文档 与 ellipselabels 标签文档。

任务数据与模型预标注

tasks.json 包含 3 个任务,每个任务的data.image指向一张示例图片。第一个任务额外携带predictions数组,展示模型预标注(Active Learning)的标准结构:

{ "model_version": "model 1", "created_ago": "3 hours", "result": [ { "from_name": "tag", "to_name": "img", "type": "ellipselabels", "value": { "x": 50.4, "y": 50.763073639274279, "ellipselabels": ["Planet"], "rotation": 0, "radiusY": 10.672358591248665, "radiusX": 13.333333333333334 } } ] }

关键约定:

• type固定为"ellipselabels",与 tools/Ellipse.js 中声明的stateTypes一致;
• from_name/to_name必须与 config.xml 中<EllipseLabels name="tag">和<Image name="img">对应,编辑器据此把预标注挂载到正确的控件上;
• value使用相对坐标(0~100 的百分比体系),而非像素值,因此该预标注在不同分辨率的图片上均可复用。

标注结果格式:annotations/1.json

annotations/1.json 展示了一条完整的人工标注,result数组中有两条记录:

{ "result": [ { "from_name": "tag", "to_name": "img", "type": "ellipselabels", "value": { "x": 50.4, "y": 50.763073639274279, "ellipselabels": ["Planet"], "rotation": 0, "radiusY": 10.672358591248665, "radiusX": 13.333333333333334 } }, { "from_name": "choice", "type": "choices", "value": { "choices": ["Space"] } } ] }

各几何字段的含义:

注意椭圆区域以「中心 + 双半径 + 旋转」表达,与image_bbox示例中「左上角 + 宽/高」的矩形表达不同——这也是椭圆更适合描述行星、瞳孔、圆形徽标等目标的几何原因。

源码实现:Ellipse 工具的绘制与校验逻辑

椭圆标注的交互行为由 web/libs/editor/src/tools/Ellipse.js 定义,几个可验证的实现细节:

1. 工具注册与快捷键:模型名为EllipseTool,group: "segmentation",shortcut: "tool:ellipse",即编辑器工具栏中可切换为椭圆工具,快捷键组为tool:ellipse。
2. 两点式绘制:工具由types.compose组合了BaseTool、ToolMixin与TwoPointsDrawingTool(见 Ellipse.js 组合),说明用户通过拖拽两个对角点定义椭圆的外接矩形,编辑器再换算出中心与双半径。
3. 最小尺寸校验:beforeCommitDrawing 要求radiusX > MIN_SIZE.X && radiusY > MIN_SIZE.Y才允许提交区域,即过小的拖拽不会生成无效标注。
4. 区域字段一致性:createRegionOptions 新建区域时初始化为x, y, radiusX: 1, radiusY: 1,与annotations/1.json中的结果字段完全对应。

椭圆区域的渲染与交互层在 web/libs/editor/src/regions/EllipseRegion.jsx,并有配套单元测试 EllipseRegion.test.jsx 可查证行为边界;<Ellipse>与<EllipseLabels>两个标签均在 tags/control 目录中通过Registry.addTag注册进编辑器。

小结与复用要点

• 复现本示例的最小闭环:准备一张图片 URL → 按 config.xml 编写Image + EllipseLabels配置 → 按 tasks.json 组装任务 → 用server.py -l <config> -i <tasks>启动服务;
• 椭圆结果的标准化输出字段为x / y / radiusX / radiusY / rotation / ellipselabels,下游训练数据管道应按该契约解析;
• 预标注通过predictions[].result注入,字段名必须与控件name一一对应;
• 文档中的安装与启动路径属于早期仓库布局,落地到当前仓库时请按上文「启动标注服务」一节把路径映射到 web/libs/editor/src/examples/image_ellipses/ 的真实位置。

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