Label Studio 椭圆标注模板实战：使用 EllipseLabels 完成图像椭圆目标检测与语义分割-开发者社区

Label Studio 椭圆标注模板实战：使用 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 官方图像标注模板之一——椭圆目标检测模板（docs/source/templates/image_ellipse.md），讲解如何利用EllipseLabels与Image标签组合，在图像上绘制带标签的椭圆区域，用于椭圆形态目标的检测与语义分割标注。读完本文，你将掌握完整的标签配置写法、EllipseLabels/Ellipse全部参数语义、标注结果的 JSON 导出结构，以及背后前端编辑器（web/libs/editor）的源码实现原理，可直接落地到细胞、零件、天体等近似椭圆目标的标注项目中。

模板适用场景：为什么用椭圆而非矩形框

标准的矩形框（RectangleLabels）无法贴合圆形细胞、球状天体、零件端面等近似椭圆的目标轮廓；而多边形（PolygonLabels）虽然精确，却需要逐点描边、标注成本高。椭圆标注在这两者之间取得平衡：只需两次拖拽即可确定椭圆的位置与两轴半径，还能旋转贴合倾斜目标，非常适合对精度要求高于矩形框、又不需要逐点精细分割的语义分割场景。

该模板在仓库中的完整定义位于 image_ellipse.md，其元信息将主题归类为 Computer Vision / Object Detection with Ellipses，用于目标检测与语义分割两类任务。

完整的标签配置

模板给出了可直接复制到 Label Studio 项目「Labeling Setup」中的最小可用配置：

<View> <EllipseLabels name="tag" toName="img"> <Label value="Blood Cell" /> <Label value="Stem Cell" /> </EllipseLabels> <Image name="img" value="$image" /> </View>

配置结构非常清晰：View作为所有标签配置的容器，EllipseLabels是控制标签（提供椭圆绘制工具与标签列表），Image是对象标签（绑定图像数据源$image）。name与toName的对应关系（tag↔img）是控制标签与对象标签建立绑定、从而激活绘制工具的关键，二者名称必须严格匹配。

仓库前端编辑器中还提供了一个带样式参数与附加分类的扩展示例，位于 config.xml：

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

可见EllipseLabels支持fillOpacity、strokeWidth等样式参数，且可与Choices等分类标签叠加使用，形成「区域标注 + 全局分类」的组合标注方案。

EllipseLabels 控制标签详解

参数表

EllipseLabels用于创建带标签的椭圆区域（labeled ellipses），官方参数定义见 ellipselabels.md：

参数	类型	默认值	说明
`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`	是否显示/隐藏旋转控制

其中choice="multiple"适用于需要给同一椭圆打多个标签的场景；maxUsages可限制某个标签的重复使用次数，适合训练数据类别平衡控制；canRotate="false"用于不允许旋转的固定朝向目标。

源码实现

从前端编辑器源码 EllipseLabels.jsx 可以看到，EllipseLabelsModel是ControlBase（控件基础）、LabelsModel（标签集合）、EllipseModel（椭圆控制模型）、LabelMixin（标签混入）与SelectedModelMixin（选中标签跟踪）的组合，其type固定为"ellipselabels"，并声明可包含label、header、view、hypertext四类子节点。最终通过Registry.addTag("ellipselabels", ...)注册为可解析的标签。这意味着除了Label，你还可以在EllipseLabels内部使用Header、View等标签对标签列表做分组排版。

Ellipse 标签：不带标签列表的纯椭圆绘制

若不需要预先定义标签列表，只想在图上画纯粹的椭圆区域，可使用Ellipse标签（对应文档 ellipse.md）：

<View> <Ellipse name="ellipse1-1" toName="img-1" /> <Image name="img-1" value="$img" /> </View>

Ellipse的参数见 includes/tags/ellipse.md：

参数	类型	默认值	说明
`name`	string	—	元素名称（必填）
`toName`	string	—	要标注的图像名称（必填）
`opacity`	float	`0.6`	椭圆透明度
`fillColor`	string	—	椭圆填充色（十六进制）
`strokeColor`	string	`"#f48a42"`	描边颜色（十六进制）
`strokeWidth`	number	`1`	描边宽度
`canRotate`	boolean	`true`	是否显示旋转控制
`smart`	boolean	—	显示智能工具以支持交互式预标注
`smartOnly`	boolean	—	仅显示智能工具用于交互式预标注

smart/smartOnly参数与 Label Studio 的交互式预标注（如 SAM）集成相关，启用后可在椭圆工具旁提供智能分割入口。

从源码 Ellipse.js 可以看出其模型的实际默认值：opacity运行时默认"0.2"、fillcolor与strokecolor默认#f48a42、strokewidth默认"1"、canrotate默认true，并且内部通过ToolManagerMixin挂载了toolNames: ["Ellipse"]绘制工具。注意文档表格中的默认值与源码实际取值存在细微差异（如opacity），以源码为最终实现依据。

Image 对象标签：绑定图像数据

Image标签负责把配置中的$image占位符与任务数据中的图片字段绑定，是椭圆区域绘制的载体：

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

只有当EllipseLabels/Ellipse的toName指向Image的name时，编辑器中才会激活对应的椭圆工具。Image标签的完整参数（如zoom、negativeZoomLimit、rotateControl等）可参考官方文档 image.md。

标注结果的 JSON 结构

椭圆标注导出/保存后的结果由 EllipseRegion.jsx 的serialize()方法生成，官方格式如下：

{ "original_width": 1920, "original_height": 1280, "image_rotation": 0, "value": { "x": 3.1, "y": 8.2, "radiusX": 20, "radiusY": 16, "ellipselabels": ["Car"] } }

各字段含义（见 ellipselabels.md 的 Result parameters 表）：

字段	类型	说明
`original_width`	number	原始图像宽度（px）
`original_height`	number	原始图像高度（px）
`image_rotation`	number	图像整体旋转角度（deg）
`value.x`	number	椭圆中心点 x 坐标（旋转前，0-100 归一化）
`value.y`	number	椭圆中心点 y 坐标（旋转前，0-100 归一化）
`value.radiusX`	number	X 轴半径（0-100 归一化）
`value.radiusY`	number	Y 轴半径（0-100 归一化）
`value.rotation`	number	椭圆自身旋转角度（deg）
`value.ellipselabels`	array	该椭圆关联的标签列表

坐标采用 0-100 归一化比例而非绝对像素，这使得标注在不同分辨率、不同缩放级别下保持一致，训练前按original_width/original_height乘以 0.01 即可还原为像素坐标。image_rotation记录标注时图像被旋转的角度，便于后续数据恢复。

源码层面的坐标与序列化

在 EllipseRegion.jsx 中，EllipseRegionModel的核心字段为x、y、radiusX、radiusY、rotation，并组合了RegionsMixin、AreaMixin、NormalizationMixin、KonvaRegionMixin等，负责坐标归一化与画布渲染。其serialize()直接输出上述value对象，再经由父级createSerializedResult包装original_width等图像元信息。rotation在setPositionInternal中统一规范到(rotation + 360) % 360，保证角度值落在[0, 360)区间。

渲染层基于 Konva：HtxEllipseView使用react-konva的Ellipse图元，将内部归一化坐标通过internalToCanvasX/Y转换为画布坐标，并支持拖拽（onDragEnd）、缩放与旋转（onTransformEnd）等交互，变换结束后写回归一化内部坐标并触发notifyDrawingFinished()记录到标注历史。可编辑字段x / y / Rx / Ry / rotation同时开放了属性面板手动精调入口。

绘制工具的校验逻辑

椭圆绘制工具定义于 tools/Ellipse.js，属于TwoPointsDrawingTool（两点拖拽式绘制：按下起点、拖出半径、释放成型）。它归属segmentation工具组，快捷键注册为tool:ellipse，并声明支持ellipselabels与ellipse两类控制标签。提交绘制前会执行beforeCommitDrawing()校验：仅当radiusX与radiusY均大于MIN_SIZE时才接受该区域，避免误点产生不可用的微小椭圆。

完整实战配置示例

将模板配置扩展为可直接用于细胞影像标注项目的完整示例：

<View> <Header value="Draw ellipses around cells" /> <EllipseLabels name="label" toName="image" choice="multiple" strokeWidth="2" fillOpacity="0.3" canRotate="false"> <Label value="Blood Cell" background="#ff0000" /> <Label value="Stem Cell" background="#00ff00" /> </EllipseLabels> <Image name="image" value="$image" zoom="true" zoomControl="true" /> </View>

该配置在模板基础上补充了：标题说明（Header）、多标签选择（choice="multiple"）、更粗的描边与半透明填充便于观察目标轮廓、禁用旋转以适配固定朝向的细胞切片，以及图像缩放控制，适合在标签类型固定、目标形态近似椭圆的数据集上直接复用。

【免费下载链接】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），仅供参考