用户手册

July 16, 2026 · View on GitHub

本指南提供了使用 X-AnyLabeling 的全面指导，涵盖了从基本的文件管理、标注任务到高级功能和自定义的所有内容。

0. 目录

1. 文件

本章节将详细介绍如何在 X-AnyLabeling 上进行数据的导入、删除、切换以及保存，确保标注流程高效且数据安全可控。

1.1 导入数据

在打开 GUI 界面后，用户可在上方菜单栏中的 文件 下拉框中选择对应的任务类型进行导入，也可直接通过快捷键进行操作。

X-AnyLabeling 目前提供三种数据导入方式：

  • 图片文件目录（Ctrl+U）：支持多级目录嵌套的多个文件同时导入。
  • 单个图片文件（Ctrl+I）：支持导入 *.jpg、*.png、*.bmp、*.webp、*.tif 等多种格式。
  • 单个视频文件（Ctrl+O）：支持导入 *.mp4、*.avi、*.mov、*.mkv、*.wmv、*.flv 等视频格式。

1.2 删除数据

X-AnyLabeling 提供数据删除功能，具体操作如下：

  • 删除标签文件（Ctrl+Delete）：删除当前标注文件结果，此操作不可撤回，请谨慎操作。
  • 删除图像文件（Ctrl+Shift+Delete）：删除当前图片文件，删除后的文件会同步移至当前图片目录下的 _delete_ 文件夹中。

1.3 切换图片

在 X-AnyLabeling 中，用户可以通过快捷键 (A) 和 (D) 快速切换到上一张或下一张图片。

除了常规的切换图片操作外，还支持以下几种方式：

快捷键描述
Ctrl+Shift+A跳转到上一张未检查的标注
Ctrl+Shift+D跳转到下一张未检查的标注

检查状态保存在标注 JSON 的顶层 checked 字段中，右下角文件列表会用圆点展示该状态：绿色表示已检查，灰色表示未检查。可以在画布右键菜单中选择 Mark as Checked / Mark as Unchecked，也可以按 Ctrl+Alt+K 切换当前图像的检查状态。

文件列表中的复选框默认不可编辑，如需启用编辑功能，可通过 Settings（Ctrl+0）在 General 中开启 File List Checkbox Editable，或在配置文件中将 file_list_checkbox_editable 设置为 true。 该复选框表示是否存在标注文件，与圆点展示的检查状态相互独立。

1.4 保存标签数据

X-AnyLabeling 默认开启自动保存功能，用户在初次启动界面时，可点击菜单栏中的 文件 下拉框查看 自动保存 选项是否被勾选。

标签文件默认保存在当前图片目录下，文件格式为 *.json，模板如下：

{
  "version": "${version}", // X-AnyLabeling 版本号
  "flags": {},             // 图片级标志 (如果存在)
  "shapes": [              // 标注的对象列表
    {
      "label": "${label}",        // 类别标签
      "score": null,            // 置信度得分 (e.g., from model), 若无此信息则为 `null`
      "points": [...],          // 对象的顶点坐标列表
      "group_id": null,         // 用于关联同一组内的多个对象 (e.g., pose keypoints)
      "description": null,      // 对象的文本描述
      "difficult": false,       // 标识当前对象是否难以识别
      "shape_type": "${shape_type}", // e.g., "rectangle", "polygon"
      "flags": null,            // 对象级标志 (如果存在)
      "attributes": {}          // 自定义属性字典
    }
    // ... 更多对象
  ],
  "description": null,      // 图片的文本描述
  "checked": false,         // 标注检查状态
  "chat_history": [         // 聊天历史 (for chatbot)
    {
      "role": "user",
      "content": "Hi",
      "image": null
    },
    {
      "role": "assistant",
      "content": "Hi there! How can I help you today?",
      "image": null
    }
    // ... 更多对话
  ],
  "vqaData": {
    "question": "What animals are shown in the image?",
    "answer": "zebras",
    "split": "train",
    "task": "QA",
    "tags": [
      "natural"
    ],
    // ... 更多选项
  },
  "imagePath": "${filename}", // 图片的相对路径
  "imageData": null,         // Base64 编码的图片数据 (如果启用, 请参考 1.5)
  "imageHeight": -1,         // 图片高度
  "imageWidth": -1           // 图片宽度
}

提示：如需更改标签保存路径，请在菜单栏中的 文件 下拉框中点击 更改输出目录 选项并设置相应的保存路径。

1.5 保存图像数据

如果您希望在标注过程中保存当前图像数据（默认 base64 编码），可在菜单栏中的 文件 下拉框中勾选 保存图像数据 选项。

2. 编辑

本章节将指导您如何在 X-AnyLabeling 中创建、编辑和管理不同类型的标注对象及其标签信息，涵盖从基本操作到高级功能的全面指南。

2.1 创建对象

在 X-AnyLabeling 中，我们将每个目标框称为一个单独的对象，其通常包含如下基本属性：

字段类型描述
label字符串对象的类别标签。
score浮点数对象的置信度得分，通常在 AI 模型推理服务中使用，若无此信息则为 null。
points数组对象的顶点坐标列表，具体取决于 shape_type。
group_id整数对象所属的组 ID，用于关联同一组内的多个对象，若无此信息则为 null。
description字符串对象的描述信息，若无此信息则为 null。
difficult布尔值标识当前对象是否难以识别，true 表示难以识别。
shape_type字符串对象类型，例如 "rectangle"、"polygon" 等。
flags字典附加的标志信息，用于存储额外的状态或属性，若无此信息则为 null。
attributes字典对象的属性信息，可以包含任意键值对，若无此信息则为空字典 {}。
kie_linking列表对象间的连接信息，可包含多对连接，例如 [[1,2],[3,4]]，若无此信息则为空字典 []。
cuboid3d字典仅 cuboid 使用的 3D 元数据，包含 version、mode、vertices2d_order、depth_vector、source，用于记录前后面映射和深度向量。

此外，对于一些特殊的属性定义，可参考此文件。

当前，X-AnyLabeling 支持创建以下对象：

  • rectangle（R）：通过左键单击开始绘制，移动光标，左键再次单击结束矩形框绘制；
  • rotation（O）：通过左键单击开始绘制，移动光标，左键再次单击先生成一个水平/竖直方向的旋转框；如需调整角度，可在编辑模式下选中该对象后按 Z、X、C、V 旋转；
  • polygon（P）：通过左键单击开始绘制，沿着物体边缘点击添加分割点，光标移动到起始顶点处单击即可结束绘制。当前最少需绘制 3 个顶点。另外支持画笔模式（Ctrl+N），激活后单击放置起始点，移动鼠标即可自动沿轨迹添加多边形顶点，光标移至起始点附近自动闭合。画笔点间距可通过 Settings > Canvas > brush.point_distance 调整。
  • quadrilateral（T）：通过左键单击开始绘制，依次点击四个顶点，最后一次单击即可结束四边形绘制；
  • point：通过左键单击即可直接创建关键点；
  • line：通过左键单击开始绘制，移动光标，左键再次单击即可结束单线段绘制；按住 Shift 键可将线段吸附为水平或竖直方向；
  • linestrip：通过左键单击开始绘制，移动光标再次单击创建线段，左键双击即可结束多线段绘制；绘制每一段时按住 Shift 键可将当前线段吸附为水平或竖直方向；
  • circle：通过左键单击开始绘制，移动光标确定半径，左键再次单击即可结束圆形绘制；
  • cuboid（Ctrl+R）：先按矩形方式确定正面四点（前面），系统再基于 canvas.cuboid.default_depth_vector 自动生成背面四点（可在 Settings > Canvas > Cuboid 中调整）；当深度过小时会按 canvas.cuboid.min_depth 自动约束。

用户可通过左侧菜单栏中的对应功能选项、鼠标右键或快捷键进行操作。

2.2 编辑对象

当前，X-AnyLabeling 中定义了两种对象操作模式，即 绘制模式 和 编辑模式。

  • 绘制模式：在绘制状态下，可进行对象的快速创建；
  • 编辑模式：在编辑状态下，可进行对象的编辑（Ctrl+E）、撤销（Ctrl+Z）、复制（Ctrl+C）、粘贴（Ctrl+V）、删除（Delete）、移动、缩放、旋转等操作。

用户可通过快捷键 Ctrl+J 在绘制模式与编辑模式之间快速切换。此外：

如需保护已完成的标注，可选择一个或多个对象，并在画布右键菜单中勾选 锁定对象。也可在右侧 Shapes 面板中右键单击已选中的条目，逐个反转其锁定状态；锁定条目会显示锁形图标。锁定对象仍可被选中并修改标签、属性等字段，但无法修改几何坐标或删除。

启用 显示群组 后，每个群组会显示可交互的外接框及 G3 · S5 形式的简洁标签（表示群组 3 包含 5 个对象）。单击对象时仍优先选中该对象；单击群组标签、外接框或框内空白区域可选中整个群组，随后可拖拽或使用方向键整体移动，按住 Shift 可加速键盘移动。复制并粘贴选中的群组时，粘贴结果会自动使用当前图片中下一个可用的群组编号，并产生轻微位置偏移。删除整个群组前会要求确认。

  • 对于矩形框对象，可通过四个角点调整大小；支持多选并通过右键菜单中的合并选中对象进行合并。另外也支持鼠标滚轮编辑功能，可在 Settings > Canvas > Wheel Editing > Enable Wheel Rectangle Editing 中启用，或在用户配置文件中设置（wheel_rectangle_editing）：启用后，滚轮在矩形内可缩放，在外部可调整对应边缘位置。注意：当启用 auto_highlight_shape 时，滚轮矩形编辑将自动关闭。
  • 对于多边形框对象，可通过在边上拖拽新增一个新的顶点或按住 Shift 键配合鼠标左键移除选中顶点（编辑模式下）。当仅选中一个多边形或折线对象时，可按住 Alt 键进入橡皮擦模式，再按住鼠标左键拖过顶点以移除这些顶点，并自动拼接剩余点；若多边形少于 3 个点，或折线少于 2 个点，则会删除整个对象，并可通过撤销恢复。同样也支持多对象合并。当且仅当选中一个 polygon 时，还可通过工具栏、右键菜单或快捷键 Shift+B 启用 编辑笔刷：按住鼠标左键绘制可扩展区域，按住 Ctrl 绘制可擦除区域，滚轮可调整笔刷大小，并支持按笔画撤销和重做。编辑期间会锁定当前对象；右键或关闭编辑笔刷可提交修改，按 Esc、切换图片或切换其他工具会放弃修改并恢复原始多边形。笔刷采样间距和轮廓简化精度可在 Settings > Canvas > Interaction > Brush 中调整；简化精度设为 0 时保留提取出的轮廓点。
  • 对于旋转框对象，可先单击选中目标，拖拽对象上方的旋转控制点快速粗调角度，再通过 Z、X、C、V 对旋转角度和方向进行精细调整。此外，也支持显示实时的旋转角度预览。
  • 对于长方体（cuboid）对象，编辑时会显示 11 个控制点：正面 4 个顶点、正面 4 条边中点、可见背面 2 个顶点、可见背面 1 个边中点（深度控制点）。拖拽正面可整体移动对象；拖拽左/右/背面可调整形体；拖拽背面中点可调整深度，且会保持几何约束。背面哪一侧可见由深度向量方向自动决定。

此外，用户可通过右键菜单中的 复制坐标 功能快速复制当前选中对象的坐标信息到剪贴板。对于矩形框，输出格式为 [x1, y1, x2, y2]（左上角和右下角坐标）；对于其它对象类型，输出格式为 [x1, y1, x2, y2, x3, y3, ...]（所有顶点坐标）。在编辑模式下，双击画布上的对象可快速打开标签编辑框；可在 Settings > Canvas > Interaction > Double Click Edit Label 中关闭，也可在配置中通过 double_click_edit_label（默认为 true）关闭该行为。

在放大画布并出现滚动条时，绘制对象过程中可按住 Space 并使用鼠标左键拖拽，临时平移画布，而无需退出绘制模式。

Tip

X-AnyLabeling 提供两个便捷的对象浏览功能：

  • 遍历放大对象（Ctrl+Shift+N）：依次放大显示画布中的每个对象，便于逐一检查标注质量。
  • 遍历选中对象（Ctrl+Shift+C）：依次选中画布中的每个对象，便于快速编辑或管理标注。

2.3 编辑标签

当用户创建（未勾选自动使用上一个标签）或编辑一个对象时，默认弹出一个标签编辑框，用于编辑对象的标签信息。

字段描述
对象标签输入当前对象的类别标签，支持模糊搜索。
群组编号用于关键点检测、多目标跟踪等特定任务。
困难标签标识当前对象是否难以识别。
标签列表展示当前已添加的标签列表，默认按字母序排列。
标签描述附加的标志信息，用于存储额外的状态或属性，若无此信息则为 null。
标签连接用于标识关键信息提取-关系抽取任务中的连接字段。

2.4 编辑图片

当前，X-AnyLabeling 支持对当前图片进行 Caption 描述。具体操作是打开编辑模式，点击图片空白处，在右侧的 Description 区域填充图片描述。

2.5 搜索图片

文件搜索功能支持多种搜索模式，帮助用户快速定位目标图片。在右侧文件列表上方的搜索框中输入搜索条件，按回车键执行搜索。

也可以在文件列表中的图片上点击鼠标右键，打开快捷菜单执行复制操作：

  • 复制文件名：仅复制当前选中图片的文件名，例如 image001.jpg。
  • 复制文件路径：复制当前选中图片的完整路径到剪贴板。

当前支持的搜索模式包括：

文本搜索

直接输入文本内容，系统会在文件名中查找包含该文本的文件。例如输入 test 可以找到所有文件名包含 "test" 的图片。

编号搜索

使用 #N 格式按序号定位图片，其中 N 必须为正整数。例如：

  • #1 定位当前文件列表中的第 1 张图片
  • #10 定位当前文件列表中的第 10 张图片

正则表达式搜索

使用 <pattern> 格式进行正则表达式搜索。例如：

  • <\.png$> 搜索所有 PNG 格式的图片
  • <test.*\.jpg$> 搜索文件名以 "test" 开头、以 ".jpg" 结尾的图片

属性搜索

支持通过对象属性筛选图片，格式为 属性名::值：

  • difficult::1 或 difficult::true：查找包含困难标注对象的图片
  • gid::0：查找包含群组编号为 0 的对象的图片，支持搜索任意整数群组编号
  • shape::1 或 shape::true：查找已标注的图片（包含至少一个标注对象）
  • label::person：查找包含标签为 "person" 的图片
  • type::rectangle：查找包含矩形框对象的图片，支持的类型包括：rectangle（矩形）、polygon（多边形）、rotation（旋转框）、quadrilateral（四边形）、point（点）、line（线段）、circle（圆形）、linestrip（折线）
  • score::[0,0.5]：查找包含分数在 [0, 0.5] 区间内的对象（闭区间）
  • score::(0,0.6]：查找包含分数在 (0, 0.6] 区间内的对象（左开右闭）
  • score::[0,0.6)：查找包含分数在 [0, 0.6) 区间内的对象（左闭右开）
  • score::(0,0.6)：查找包含分数在 (0, 0.6) 区间内的对象（开区间）
  • description::1 或 description::true：查找包含非空描述的图片
  • checked::1 或 checked::true：查找已检查的图片
  • checked::0 或 checked::false：查找未检查的图片；未生成标签文件的图片也会视为未检查

3. 视图

本章节将向您展示如何在 X-AnyLabeling 中优化和自定义图像及标注对象的显示效果，包括画布和图片的可视化调整，以及对象信息的可视化设置，确保您的标注工作既高效又直观。

3.1 画布可视化

当前，X-AnyLabeling 支持以下对画布的操作：

  • 放大（Ctrl++）
  • 缩小（Ctrl+-）
  • 重置（Ctrl+=）

除了可以在左侧窗口设置缩放比例和使用快捷键触发外，还可以通过按住 Ctrl 键并配合鼠标滚轮对感兴趣的区域进行局部缩放操作，用于精细化和小目标对象标注。如果您想将此更改应用到全局，请务必勾选 视图 下拉选项中的 保留先前的缩放比例 选项。

3.2 图片可视化

X-AnyLabeling 支持调整当前图片的显示效果和标注对象的可见性。具体操作如下：

  • 在界面上方菜单栏中的 视图 下拉选项中选择 亮度对比度 选项，调整合适的亮度和对比度，以获得更好的视觉效果。
  • 如果想将此更改应用到全局，请勾选 视图 下拉选项中的 保持当前亮度 和 保持当前对比度 选项。

通过画布左下角可折叠的 Canvas Display 面板，可以快速调整标注透明度以及图片亮度和对比度。其中，Opacity 仅影响标注对象和掩码，标签文字保持清晰可见；Brightness 和 Contrast 用于调整底图。点击箭头按钮可折叠或展开面板。

此外，当光标移动时，GUI 界面底部的信息栏会实时显示当前图片的文件名及标注进度。

3.3 对象可视化

对象可视化功能包括显示当前图片中已标注对象的文本描述（Ctrl+T）、标签名称（Ctrl+L）、分组编号、旋转角度、预测分数等信息。

用户可以通过快捷键或者在界面上方菜单栏中的 视图 下拉选项中勾选相应功能来进行设置。

同时，当用户将光标移至感兴趣的对象时，GUI 界面底部的信息栏会实时显示当前对象的宽度、高度等信息。

Tip

在 GUI 右侧的 Shapes 列表中，可通过右键菜单中的二级选项 Filter by Label 和 Filter by Group ID 快速筛选对象。
左侧工具栏提供了对象全局显隐切换按钮（eye/hidden 图标）：点击一次隐藏全部对象，再次点击恢复显示。

3.4 十字瞄准线

关于十字瞄准线，用户可以通过界面上方菜单栏中的 视图 下拉选项中点击 设置交叉线 选项，调整当前十字瞄准线的宽度、透明度及颜色。

此外，当光标移动时，GUI 界面底部的信息栏会实时显示位置坐标信息。

3.5 导航器

处理高分辨率图像时，可以通过导航器快速定位到图像的任意区域。

要打开导航器，只需在菜单栏点击 视图 -> 导航器 或直接按快捷键 F9 即可。导航器会在独立窗口中显示当前图像的缩略图，并用红色框标出你当前的可视区域。

你可以直接点击缩略图上的任意位置快速跳转，或者拖拽红色框来移动视野。导航器还会实时显示你标注的所有对象，让你对整体进度一目了然。

在导航器底部，你可以通过输入框精确设置缩放比例（支持1%到1000%），也可以拖拽滑动条进行调整。此外，无论是在主画布还是导航器窗口内，都可以直接用鼠标滚轮缩放。

这个功能特别适合处理超大分辨率图像，既能保持局部的精细操作，又不会失去全局视野。

3.6 对比视图

X-AnyLabeling 提供了对比视图功能，允许你通过分屏界面并排比较两张图像。该功能特别适用包括但不仅限于以下场景：

  • 红外与可见光融合：对比热成像和 RGB 图像，识别在不同光谱下更清晰的目标。
  • 掩码预览：实时查看分割结果与原图的叠加效果。
  • 图像超分：对比增强后的图像与原始图像。

使用方法：

  1. 打开图像目录并加载图像。
  2. 点击 文件 > 对比视图（或按 Ctrl+Alt+C）打开对比目录选择器。
  3. 选择包含对比图像的目录，文件名需与主图像匹配（基础文件名相同，扩展名可不同）。
  4. 使用底部滑块调整分割位置，或按住 Shift 键并滚动鼠标滚轮移动分割线。
  5. 点击滑块上的关闭按钮（×）退出对比视图。

注意：对比图像必须与原图尺寸一致，否则将在状态栏显示警告信息。

4. 标签导入导出

现阶段，X-AnyLabeling 提供了多种主流标签文件的导入/导出功能，下面简单介绍使用步骤。

Tip

您也可以使用命令行工具进行批量转换！CLI 工具提供了更高效、更灵活的标签格式转换功能，特别适合大规模数据集的处理。详情请参考命令行界面文档。

4.1 YOLO标签

X-AnyLabeling 支持一键导入/导出 YOLO 目标检测、实例分割、旋转框检测和关键点检测四大主流任务的标签文件（*.txt）。

在导入/导出 YOLO 标注文件之前，需要准备一份标签配置文件，具体如下：

  1. 对于 YOLO 目标检测、实例分割和旋转框检测任务，请参考 classes.txt 准备配置文件，每一行代表一个类别，编号从上至下从 0 开始依次递增。
  2. 对于 YOLO 关键点检测任务，请参考 yolov8_pose.yaml 进行准备，其中 has_visible 参数请参考官方定义。

要以 YOLO-Pose 格式导出，您需要在标注过程中为每个组（检测框及其关键点）指定 group_id，以便 X-AnyLabeling 在导出时能够理解它们之间的从属关系。

Note

请勿将 YOLO 标签文件（*.txt）与图像文件放置到同一目录下。

导入任务：

  1. 点击上方菜单栏的 上传 按钮。
  2. 选择对应的任务。
  3. 上传准备好的配置文件。
  4. 选择标签文件所在目录。
  5. 可选择勾选"保留现有标注"选项，将新标注与现有标注合并。
  6. 点击确定即可。

导出任务：

  1. 点击上方菜单栏的 导出 按钮。
  2. 上传准备好的配置文件。
  3. 根据需求勾选对应选项，点击确定即可。

导出路径默认保存在当前图片目录的同级目录下的 labels 文件夹内。

YOLO 标签文件样式可参考 demo.txt。

4.2 VOC标签

X-AnyLabeling 支持一键导入/导出检测和分割任务相关的 Pascal-VOC 标签文件（*.xml）。

导入任务：

  1. 点击上方菜单栏的 上传 按钮。
  2. 选择对应的任务。
  3. 选择标签文件所在目录，点击确定即可。

导出任务：

  1. 点击上方菜单栏的 导出 按钮。
  2. 根据需求勾选对应选项，点击确定即可。

导出路径默认保存在当前图片目录的同级目录下的 Annotations 文件夹内。

VOC 标签文件样式可参考 demo.xml。

4.3 COCO标签

X-AnyLabeling 支持一键导入/导出目标检测、实例分割、关键点检测任务相关的 COCO 标签文件（*.json）。

在导入/导出 COCO 标注文件之前，需要准备一份标签配置文件，具体如下：

  1. 对于 COCO 目标检测、实例分割任务，请参考 classes.txt 准备配置文件，其中每一行代表一个类别，编号从上至下依次递增。
  2. 对于 COCO 关键点检测任务，请参考 yolov8_pose.yaml 进行准备，其中 has_visible 参数请参考官方定义。
  3. 对于 COCO 实例分割任务，请参考 labels.txt 进行准备。

导入任务：

  1. 点击上方菜单栏的 上传 按钮。
  2. 选择对应的任务。
  3. 上传准备好的配置文件。
  4. 选择标签文件所在目录，点击确定即可.

导出任务：

  1. 点击上方菜单栏的 导出 按钮。
  2. 选择对应的任务。
  3. 上传准备好的配置文件。
  4. 点击确定即可。

导出路径默认保存在当前图片目录的同级目录下的 annotations 文件夹内。

COCO 格式的对应标签文件样式可参考 annotations 目录。

4.4 DOTA标签

X-AnyLabeling 支持一键导入/导出 DOTA 标签文件（*.txt），其标签格式定义为：

x1 y1 x2 y2 x3 y3 x4 y4 class_name difficult

导入任务：

  1. 点击上方菜单栏的 上传 按钮。
  2. 选择对应的任务。
  3. 选择标签文件所在目录，点击确定即可。

导出任务：

  1. 点击上方菜单栏的 导出 按钮。
  2. 点击确定即可。

导出路径默认保存在当前图片目录的同级目录下的 labelTxt 文件夹内。

DOTA 标签文件样式可参考 demo_obb.txt。 instances_default

4.5 MASK标签

X-AnyLabeling 支持一键导入/导出语义分割任务相关的掩码标签文件（*.png）。

在导入/导出掩码标注文件之前，需要准备好配置文件，具体如下：

  1. 对于彩色图颜色映射表文件，可参考 mask_color_map.json。
  2. 对于灰度图颜色映射表文件，可参考 mask_grayscale_map.json。

导入任务：

  1. 点击上方菜单栏的 上传 按钮。
  2. 选择对应的任务。
  3. 上传准备好的配置文件。
  4. 选择标签文件所在目录，点击确定即可。

导出任务：

  1. 点击上方菜单栏的 导出 按钮。
  2. 上传准备好的配置文件。
  3. 点击确定即可。

导出路径默认保存在当前图片目录的同级目录下的 mask 文件夹内。

4.6 MOT标签

X-AnyLabeling 支持一键导入/导出多目标跟踪任务相关的标签文件。

在导入/导出标注文件之前，需要准备好标签配置文件，具体可参考 classes.txt，其中每一行代表一个类别，编号由上往下依次递增。

导出任务：

  1. 点击上方菜单栏的 导出 按钮。
  2. 上传准备好的配置文件。
  3. 选择保存路径，点击确定即可。

导入任务：

  1. 点击上方菜单栏的 上传 按钮。
  2. 选择对应的任务。
  3. 上传准备好的配置文件。
  4. 选择标签文件（gt.txt）所在目录，点击确定即可。

标签文件样式可参考 MOT 目录，其中包含三个子文件：seqinfo.ini、det.txt 和 gt.txt。

seqinfo.ini

seqinfo.ini 文件包含序列信息，用于描述数据集的元数据。以下是文件的具体内容和字段说明：

[Sequence]
name = MOT            # 序列名称
imdir = mot_label     # 图片目录
framerate = 30        # 帧率
seqlength = 249       # 序列长度（帧数）
imwidth = 1280        # 图片宽度
imheight = 720        # 图片高度
imext = .jpg          # 图片文件扩展名

det.txt

det.txt 文件包含检测结果信息，每一行代表一个检测框。以下是文件的具体内容和字段说明：

帧号, 跟踪ID, 左上角x坐标, 左上角y坐标, 目标框宽度, 目标框高度, 置信度, <x>, <y>, <z>

最后三个字段用于 MOT3D 任务，此处默认为 -1。

gt.txt

gt.txt 文件包含跟踪的标注信息，每一行代表一个标注框。以下是文件的具体内容和字段说明：

帧号, 跟踪ID, 左上角x坐标, 左上角y坐标, 目标框宽度, 目标框高度, 有效性标志, 类别ID, 可见率

这里有效性标志表示当前目标轨迹是否有效，0 表示无效数据（ignore），1 表示有效数据（activate）。用户可通过标签管理器中的 useDifficult 标志位来设置，☑️ 代表当前目标轨迹无效。

此外，针对 MOTS 数据集格式，X-AnyLabeling 支持通过 CLI 导出。请提供包含 XLABEL JSON 文件的目录、输出目录以及 classes.txt 文件：

xanylabeling convert --task xlabel2mots --labels /path/to/xlabel/labels --output /path/to/output --classes classes.txt

Note

请执行此脚本之前, 你需要先正确安装对应的 pycocotools 库。

4.7 PPOCR标签

X-AnyLabeling 支持一键导入/导出以下两种 PPOCR 任务的标签：

  • 文本检测与识别：定位出输入图像中的文字区域，并识别出图像中的具体文字内容。
  • 关键信息提取：用于从图像中提取所需要的关键信息，包含语义实体识别和关系抽取两个字任务。

导入任务：

  1. 点击上方菜单栏的 上传 按钮。
  2. 选择对应的任务。
  3. 选择相应的标签文件，点击确定上传即可。

导出任务：

  1. 点击上方菜单栏的 导出 按钮。
  2. 点击确定即可。

对于文本检测与识别任务，其导出路径默认保存在当前图片目录的同级目录下的 ppocr-rec 文件夹内，其包含：

  1. Label.txt: 标注结果
  2. rec_gt.txt: 识别结果
  3. crop_img: 识别结果对应的图片训练数据

具体的标签文件样式可参考 ppocr-rec。

对于关键信息提取任务，其导出路径默认保存在当前图片目录的同级目录下的 ppocr-kie 文件夹内，其包含：

  1. class_list.txt: 标签类别列表
  2. ppocr_kie.json: KIE 标注结果

具体的标签文件样式可参考 ppocr-kie。

4.8 ODVG标签

X-AnyLabeling 支持一键导入/导出 Grounding 任务相关的标签文件。

在导入/导出 ODVG 标注文件之前，需要准备好一份标签配置文件，具体可参考 classes.txt，其中每一行代表一个类别，编号从上至下依次递增。

导入任务：

  1. 点击上方菜单栏的 上传 按钮。
  2. 选择对应的任务。
  3. 选择标签文件所在目录，点击确定即可.

导出任务：

  1. 点击上方菜单栏的 导出 按钮。
  2. 选择对应的任务。
  3. 上传准备好的配置文件。
  4. 选择保存路径点击确定即可。

ODVG 标签文件样式可参考 ODVG。

4.9 VLM-R1-OVD标签

X-AnyLabeling 支持一键导入/导出 VLM-R1-OVD 标签文件。

导入任务：

  1. 点击上方菜单栏的 上传 按钮。
  2. 选择对应的任务。
  3. 选择标签文件所在目录，点击确定即可.

导出任务:

  1. 点击上方菜单栏的 导出 按钮。
  2. 选择对应的任务。
  3. 根据实际需要填写相应的配置项点击确定即可。

其中，classes.txt 文件用于指定需要导出的类别或短语提示。若不指定，则默认以每张图片为单位检测到所有类别或短语提示作为提示类别进行导出，并自动跳过空标签文件。

VLM-R1-OVD 标签文件导出示例可参考 vlm_r1_ovd.jsonl 文件。

4.10 MMGD标签

X-AnyLabeling 支持一键导入基于 MM-Grounding-DINO 预测所获取的标签文件。

导入流程：

  1. 点击上方菜单栏的 上传 按钮。
  2. 选择对应的任务。
  3. 上传类别文件。
  4. 选择标签文件所在目录，并根据自己需求勾选感兴趣的类别并设置过滤阈值，点击确定即可。

其中，classes.txt 文件用于后续标签序号到类别名称的映射，每一行代表一个类别，编号从上至下从 0 开始依次递增。

5. 工具栏

5.1 数据统计

X-AnyLabeling 具备数据统计功能，允许用户轻松获取当前任务的统计概况。只需在顶部菜单栏选择 工具 下拉选项中的 数据总览 按钮，即可查看当前数据状态。其支持以下功能：

  • 数据导出功能
    • 支持导出 CSV 格式的统计报告
    • 自动生成包含标签信息、对象统计和类别列表的压缩包
    • 导出文件包括：
      • label_infos.csv：标签数量统计
      • shape_infos.csv：标注对象统计
      • classes.txt：所有类别列表
  • 灵活的统计范围
    • 支持选择指定范围内的图像进行统计
    • 可查看单张或多张图像的统计信息
    • 实时更新统计结果
  • 多维度数据分析
    • 按标签类别统计：展示每个类别的标注数量
    • 按对象类型统计：包括多边形、矩形、旋转框、点、线条、圆形、长方体等
    • 总体数据概览：显示数据集的整体分布情况

使用说明：

  1. 点击顶部菜单栏的"工具" -> "数据总览"
  2. 在弹出的统计窗口中查看数据分布
  3. 可选择特定范围的图像进行统计
  4. 点击"导出"按钮将统计结果保存为压缩包

5.2 保存子图

子图保存功能可通过以下步骤实施：

  1. 点击上方菜单栏的 工具 -> 保存子图 选项。
  2. 在弹出的对话框中设置：
  • 保存路径：选择子图保存的目标文件夹
  • 最小宽度：设置过滤的最小宽度像素值
  • 最小高度：设置过滤的最小高度像素值
  1. 点击确定后，系统会自动将所有标注对象按照类别名称分类导出到指定路径下。

此外，用户也可以通过 工具 -> 保存可视化图像 或 保存可视化视频，将当前标注可视化结果导出为图片或视频文件。

5.3 标签管理器

当前，X-AnyLabeling 提供对标签对象的全局管理功能。用户可以通过以下操作进行管理：

  • 删除标签：移除不需要的标签。
  • 替换标签名称：更新标签名称以适应新的分类标准。
  • 控制标签可见性：通过 Visible 列的复选框控制特定标签在画布上的显示或隐藏。
  • 更改标签颜色：调整标签的显示颜色以提高辨识度。

用户可通过点击 工具 -> 标签管理器 选项（快捷键：Alt+L），在弹出的标签管理窗口中进行相应操作。

可见性快捷操作：

  • 在 Visible 列上点击鼠标右键，可快速执行以下操作：
    • Select All：一键显示所有标签
    • Deselect All：一键隐藏所有标签
  • 可见性设置会在切换图片时保持，点击 Go 按钮确认后生效。

此外，当需要快速选择画布上的所有标注对象时，请按照以下步骤操作：

  1. 切换编辑模式 在左侧工具栏中点击选择相应图标（或按快捷键 Ctrl+E）进入编辑模式
  2. 激活标签列表 在右侧对象标签栏中，使用鼠标左键单击任意一个目标标签
  3. 执行全选操作 保持按住 Shift 键的同时：
  • 先按 Home 键选中当前标签以上的所有对象
  • 再按 End 键选中当前标签以下的所有对象

5.4 对象类型转换器

X-AnyLabeling 提供了统一的 Shape Converter（对象转换器）。
可在界面上方菜单栏的 工具（Tools）-> Shape Converter 打开转换窗口，在窗口中选择源对象类型与目标对象类型后执行批量转换。

当前支持的转换关系如下：

  • polygon -> rectangle, rotation
  • rectangle -> rotation, polygon, circle, quadrilateral
  • rotation -> rectangle, quadrilateral, polygon, circle
  • line -> linestrip
  • circle -> rectangle, rotation, quadrilateral, polygon
  • quadrilateral -> polygon

规则说明：

  • 转换为 circle 时，采用内切圆策略。
  • polygon/rotation 转 rectangle 时，使用轴对齐外接矩形（AABB）。
  • circle 转 rectangle/rotation/quadrilateral 时，会基于圆心与半径生成对应四点对象。

注意：部分转换会丢失原始几何信息（如旋转角度、精确边界、曲线细节），属于不可逆操作，请在批量处理前先备份标注数据。

5.5 数字快捷键管理器

数字快捷键管理器是 X-AnyLabeling 提供的一项实用功能，它允许用户为数字键（0-9）配置快速绘制对象的功能，大幅提高标注效率。通过预先设置数字键对应的绘制模式和标签名称，用户可以在标注过程中一键快速创建所需的标注对象。

在主界面上方菜单栏选择工具，然后点击数字快捷键管理器选项，或者直接使用快捷键 Alt+D 即可打开配置界面。

在数字快捷键管理器对话框中，用户可以看到一个包含所有数字键（0-9）的表格，每行包含以下信息：

  • 数字：表示键盘上的数字键（0-9）
  • 绘制模式：从下拉菜单中选择绘制对象的类型，包括矩形框、长方体，多边形、旋转框、四边形、圆形、线段、点、折线或空选项
  • 标签：为该对象指定默认标签名称（必填）

配置快捷键：选择数字对应的绘制模式，输入该对象的默认标签名称（启用绘制模式后必须填写），然后点击确定保存设置。

重置快捷键：点击重置按钮可清除所有快捷键设置，系统会弹出确认对话框，确认后将清除所有配置。

使用快捷键：在标注界面中，直接按下已配置的数字键（0-9），系统会自动切换到对应的绘制模式，并预设标签名称。绘制完成后，标注将自动使用预设的标签名称。

离线配置：除了通过GUI界面配置外，用户还可以直接在用户目录下的 .xanylabelingrc 配置文件中进行离线配置。配置格式如下：

digit_shortcuts:
  0: {mode: polygon, label: person}
  1: {mode: rectangle, label: car}
  2: {mode: rotation, label: truck}
  # 更多配置...

通过GUI界面配置的数字快捷键设置会自动同步保存到当前用户目录下的 .xanylabelingrc 配置文件中，下次启动软件时会自动加载。同样，如果直接修改配置文件，软件重启后也会自动识别并应用这些更改。

通过合理配置数字快捷键，您可以显著提高标注效率，减少重复操作，特别适合需要频繁切换不同标注类型的场景。

5.6 群组编号管理器

群组编号管理器是针对群组编号字段提供的批量管理功能，允许用户对指定范围内的群组编号进行统一修改和删除操作。您可以通过以下两种方式打开：

  • 在主界面上方菜单栏选择工具 -> 群组编号管理器
  • 直接使用快捷键 Alt+G

5.7 对象管理器

对象管理器用于视频帧序列的批量标注处理，通过 工具 -> 对象管理器 或快捷键 Alt+S 打开。

对话框提供四种操作模式（单选）：

  • 删除所有标注：移除指定帧范围内的所有 JSON 标注文件，图像文件保留。执行后会自动取消对应帧的勾选状态。
  • 删除所有图像及标注：同时删除图像和标注文件。图像文件会移至 _delete_ 目录作为备份，而非永久删除。完成后文件列表自动刷新。
  • 移除选定对象：从帧范围内查找并移除与当前选中对象。若某帧仅包含匹配对象则删除整个标注文件，否则仅移除匹配部分。使用前需在画布上至少选中一个对象作为匹配模板。
  • 添加选定对象：将当前选中的对象批量复制到指定帧。系统会自动检测边界并跳过超出图像范围的对象，同时避免重复添加已存在的相同对象。若目标帧无标注文件会自动创建，完成后自动勾选对应帧。

使用时需设置起止帧编号：From 默认为当前帧，To 默认为空需手动填写。帧编号对应文件列表序号（从1开始）。点击 Go 后会弹出二次确认，通过后开始执行。移除和添加操作支持进度显示和中途取消。

![NOTE] 注意删除标注操作不可恢复，删除图像可从备份目录手动恢复。

6. 帮助及语言

6.1 获取版本信息

在界面上方菜单栏中，用户可点击 帮助 -> 关于 选项，查看当前版本的详细信息，包括版本号和运行环境等。

6.2 设置软件语言

在界面上方菜单栏中，用户可点击 语言 下拉框，选择所需语言进行设置。目前支持 中文、英文、日文 和 韩文 四种语言。切换语言后，软件将自动重启，请确保在切换前保存好当前数据，以防数据丢失。

7. 用户配置

X-AnyLabeling 的用户配置文件默认存放在当前用户目录下的 .xanylabelingrc 文件中。您可以通过以下路径找到该文件：

  • Linux: ~/.xanylabelingrc
  • Windows: C:\Users\<用户名>\.xanylabelingrc

现在大多数常用选项都可以直接在 Settings（Ctrl+0）中修改，而配置文件仍适用于手动编辑和高级自定义。若手动修改配置文件，建议关闭 X-AnyLabeling 后编辑，并在修改后重新启动软件使其生效。

7.1 快捷键设置

当前 X-AnyLabeling 默认的快捷键配置如下，用户可以根据自身需求进行修改，确保避免快捷键冲突。也支持在 GUI 中直接修改：按 Ctrl+0 打开 Settings 后，在右侧 Shortcuts 面板内编辑：

快捷键功能
d打开下一个文件
a打开上一个文件
Ctrl + Shift + d打开下一个未检查的标注
Ctrl + Shift + a打开上一个未检查的标注
Ctrl + Alt + k切换当前标注的检查状态
p创建多边形
Ctrl + n创建画笔多边形（切换画笔模式）
o创建旋转框
r创建矩形框
Ctrl + r创建长方体
t创建四边形
i运行模型
qSAM 模式 的正样本点
eSAM 模式 的负样本点
bSAM 模式 快速清除提示点
fSAM 模式 确认完成
g组合选定的对象
u取消组合选定的对象
s隐藏选定的对象
w显示选定的对象
Alt + d打开数字快捷键管理器
Alt + g打开群组编号管理器
Alt + l打开标签管理器，支持批量重命名、删除、显示/隐藏、调整标签颜色
Alt + s打开对象管理器，支持批量新增、删除、移除指定对象
Ctrl + 0打开 Settings
Ctrl + Delete删除当前标签文件
Ctrl + Shift + Delete删除当前图像文件
Ctrl + 1打开聊天机器人对话窗口
Ctrl + 2打开视觉问答窗口
Ctrl + 3打开图像分类器窗口
Ctrl + q退出当前应用程序
Ctrl + i打开图像文件
Ctrl + o打开视频文件
Ctrl + u从目录加载所有图像
Ctrl + e编辑标签
Ctrl + j编辑多边形
Ctrl + c复制选定的对象
Ctrl + v粘贴选定的对象
Ctrl + d复制多边形
Ctrl + g显示当前任务的标注统计
Ctrl + h显示当前图片的所有对象
Ctrl + p切换保留上一个模式
Ctrl + y切换自动使用上一个标签
Ctrl + Shift + g切换自动使用上一个群组编号
Ctrl + b唤醒批量标注
Ctrl + a启用自动标注
Ctrl + s保存当前标注
Ctrl + m显示/隐藏掩码
Ctrl + l显示/隐藏标签
Ctrl + t显示/隐藏文本
Ctrl + k显示/隐藏连接线
Ctrl + Shift + l显示/隐藏属性
Ctrl + Shift + s更改输出目录
Ctrl + z撤销上一操作
Ctrl + =缩放至原始大小
Ctrl + +放大
Ctrl + f适应窗口
Ctrl + Shift + f适应宽度
Ctrl + Shift + m合并选定的对象
Ctrl + Shift + n遍历放大对象
Ctrl + Shift + c遍历选中对象
Ctrl + z撤销上一操作
Delete删除选中对象
Esc取消选择的对象
Backspace删除选定的点
↑→↓←使用键盘箭头移动选定的对象
zxcv使用键盘旋转选定的矩形框
F9显示/隐藏导航器
Ctrl + Alt + c切换对比视图

7.2 修改自定义标签颜色

以下是修改自定义标签颜色的步骤：

a. 打开用户目录下的配置文件 .xanylabelingrc，您可以使用文本编辑器或命令行工具进行编辑。

b. 在配置文件中找到字段 shape_color，确保其值设置为 "manual"，这表示您将手动设置标签的颜色。

c. 定位到 label_colors 字段，这是一个包含各个标签及其对应颜色的部分。

d. 在 label_colors 中，找到您希望修改颜色的标签，例如 "person"、"car"、"bicycle" 等。

e. 使用 RGB 值表示颜色，例如 [255, 0, 0] 表示红色，[0, 255, 0] 表示绿色，[0, 0, 255] 表示蓝色。

f. 将您想要设置的颜色值替换到相应标签的值中，保存文件并关闭编辑器。

具体示例如下：

...
default_shape_color: [0, 255, 0]
shape_color: manual  # null, 'auto', 'manual'
shift_auto_shape_color: 0
label_colors:
  person: [255, 0, 0]
  car: [0, 255, 0]
  bicycle: [0, 0, 255]
  ...
...

完成上述步骤后，您已成功修改了自定义标签的颜色。下次在标注过程中使用这些标签时，它们将显示您所设置的颜色。

X-AnyLabeling 支持在 GUI 界面直接设置 label_colors。您可以点击菜单栏的 工具 -> 标签管理 进行设置，此更改仅对当前窗口生效。

7.3 加载预定义标签

为了兼顾标签管理的灵活性与用户在不同场景下的使用需求，X-AnyLabeling 在支持通过软件启动命令加载标签的基础上，还提供了另外两种便捷方式，用于加载预定义标签。

方式一：通过配置文件设置（永久生效）

直接修改配置文件中的 labels 字段来设置标签。需要注意的是，如果标签名称是纯数字，请务必用单引号 '' 括起来。例如：

labels:
- car
- '1'
- '2'
- 苹果
- _phone

方式二：通过界面上传（临时生效）

只需准备一个简单的文本文件（.txt），将标签名称逐行列出：

person
car
bicycle
dog
cat

然后通过菜单栏的 Upload → Upload Label Classes File 上传该文件。

🔔 小贴士：

  • 配置文件方式设置的标签会永久保存，重启软件后依然有效，适合长期使用固定标签集的场景
  • 界面上传方式的标签仅在当前使用期间有效，重启后需要重新上传，适合需要经常切换不同标签集的场景

7.4 自动切换编辑模式

用户可通过 Settings > General > Behavior > Auto Switch To Edit Mode 调整自动切换至编辑模式功能，也可通过配置文件中的 auto_switch_to_edit_mode 字段进行设置：

选项功能
true创建对象后自动切换为编辑模式。
false支持连续创建多个同类型对象，需手动切换为编辑模式。

7.5 悬浮自动高亮模式

用户可通过 Settings > General > Behavior > Auto Highlight Shape 调整悬浮自动高亮模式功能，也可通过配置文件中的 auto_highlight_shape 字段进行设置：

选项功能
true鼠标悬浮在对象上方时自动高亮，用于快速调整当前选中对象。
false鼠标悬浮在对象上方时需用户手动点击对应对象显示高亮。

注：在多标签分类任务的标定中，当用户手动上传属性文件时，auto_highlight_shape字段会被设置为false，以避免因误触而导致的属性窗口状态栏的切换，从而提升用户体验。

7.6 对象属性自定义

a. 也可先通过 Settings > Shape 调整常用外观选项；如需更细粒度控制，再打开用户目录下的配置文件 .xanylabelingrc，您可以使用文本编辑器或命令行工具进行编辑。

b. 在配置文件中找到字段 shape，根据需求修改相应字段值，包括边框颜色、填充颜色、顶点填充颜色、选中状态下的边框颜色、选中状态下的填充颜色等。

...
shape:
  # drawing
  line_color: [0, 255, 0, 128]
  fill_color: [220, 220, 220, 150]
  vertex_fill_color: [0, 255, 0, 255]
  # selecting / hovering
  select_line_color: [255, 255, 255, 255]
  select_fill_color: [0, 255, 0, 155]
  hvertex_fill_color: [255, 255, 255, 255]
  point_size: 10
  line_width: 4
...

7.7 模型下载源配置

X-AnyLabeling 支持从不同的模型中心下载预训练模型。用户可以通过设置环境变量、在 Settings（Ctrl+0）中修改 General > Behavior > Model Hub、修改配置文件 .xanylabelingrc 或根据软件语言来指定模型下载源。下载源的优先级顺序如下：

  1. 环境变量 (最高优先级): 设置环境变量 XANYLABELING_MODEL_HUB。
  • 例如，在 Linux/macOS 使用 export XANYLABELING_MODEL_HUB=modelscope。
  • 在 Windows 使用 set XANYLABELING_MODEL_HUB=modelscope。
  • 如果此环境变量设置为 modelscope，将强制使用 ModelScope，覆盖配置文件的设置。如果设置为其他值或为空，则会考虑配置文件。
  1. 配置文件 (中等优先级): 通过 Settings（Ctrl+0）修改 General > Behavior > Model Hub，或打开用户目录下的配置文件 .xanylabelingrc。
  • 找到 model_hub 字段。
  • 可选值为 github (默认) 或 modelscope。
  • 如果环境变量 XANYLABELING_MODEL_HUB 未设置或为空，则此配置生效。设置为 model_hub: modelscope 将优先从 ModelScope 下载模型。
  1. 语言设置 (最低优先级):
  • 如果环境变量和配置文件中的 model_hub 都没有明确设置为 modelscope（即它们未设置、为空或为 github），则软件语言设置为中文 (language: zh_CN) 时，会默认尝试从 ModelScope 下载模型。
  • 在其他情况下（例如，语言为英文、日文或韩文，且没有其他设置指定 modelscope），将使用默认的 GitHub URL。

7.8 主题设置

X-AnyLabeling 支持三种主题模式，可在菜单栏一级 Theme 菜单中切换：

选项说明
System（跟随系统）自动检测操作系统的深色/浅色偏好并应用对应主题，为默认值
Light（浅色）始终使用浅色主题
Dark（深色）始终使用深色主题

切换后会弹出确认对话框，点击 OK 保存设置。应用不会自动重启，随后会提示重启后生效；点击 Cancel 则放弃本次切换。

也可直接修改用户配置文件 ~/.xanylabelingrc 中的 theme 字段：

theme: auto  # 可选: auto, light, dark

7.9 字体设置

在 Settings > General > Application Font 中，可从下拉列表选择应用字体。列表会通过 Qt 自动扫描当前系统可用的字体，支持 Windows、macOS 和 Linux。选择字体并点击 Save 后会立即全局生效，无需重启；选择 System Default（系统默认） 可恢复操作系统默认字体及字号。

字体设置会保存到用户配置文件的 font_family 字段，也可手动修改：

font_family: null  # null 表示使用系统默认字体，也可填写字体名称，如 "Sarasa UI SC"

手动填写的字体名称必须已安装在当前系统中；若字体不可用，Qt 将自动回退到系统默认字体。

8. 任务

8.1 图像分类

8.2 目标检测

8.3 图像分割

  • 语义分割 & 实例分割：链接

8.4 姿态估计

8.5 人脸估计

  • 人脸检测与关键点：链接

8.6 多目标跟踪

8.7 深度估计

8.8 光学字符识别

  • 文本检测与识别：链接
  • 关键信息提取：链接

8.9 交互式视频目标分割

8.10 抠图

8.11 视觉-语言

8.12 目标计数

8.13 视觉定位

9. 模型

关于如何加载和导出模型可参阅自定义模型文档。

10. 高级功能