X-AnyLabeling — 项目开发指南

项目概述

X-AnyLabeling 是一个基于 PyQt6 的高级自动标注解决方案，支持图像、视频的多种计算机视觉标注任务。本项目是 CVHub520/X-AnyLabeling 的 Fork 版本，新增了时序事件标注（Temporal Annotation）功能，专门用于手术视频的多层次标注（帧级别三元组、动作/事件、手术阶段）。

• 语言: Python 3.11+
• GUI 框架: PyQt6
• AI 推理: ONNX Runtime（支持 CPU / CUDA 11.x / CUDA 12.x）
• 许可证: GPLv3
• 上游项目: https://github.com/CVHub520/X-AnyLabeling

目录结构

X-AnyLabeling/
├── anylabeling/                  # 主应用包
│   ├── app.py                    # 入口点 (main)
│   ├── app_info.py               # 版本信息、CLI 帮助
│   ├── config.py                 # 配置管理（加载/保存/合并）
│   ├── utils.py                  # 通用工具
│   ├── configs/                  # 默认配置文件
│   │   ├── xanylabeling_config.yaml  # 应用默认配置
│   │   ├── models.yaml           # 模型注册表（360+ 行）
│   │   └── auto_labeling/        # 各模型的 YAML 配置
│   ├── resources/                # 编译后的资源文件 (Qt .qrc)
│   ├── services/                 # 后端服务
│   │   ├── auto_labeling/        # 自动标注引擎（97+ 模型文件）
│   │   │   ├── __base/           # 基类
│   │   │   ├── configs/          # 模型配置
│   │   │   ├── engines/          # 推理引擎
│   │   │   ├── model_manager.py  # 模型下载与管理
│   │   │   └── *.py              # 各模型适配器（yolo, sam, grounding_dino 等）
│   │   └── auto_training/        # 自动训练服务
│   └── views/                    # UI 层
│       ├── mainwindow.py         # 主窗口
│       ├── labeling/             # 标注核心模块
│       │   ├── label_widget.py   # 标注主控件（6514 行，核心）
│       │   ├── label_wrapper.py  # 标注包装器
│       │   ├── label_file.py     # 标签文件 I/O
│       │   ├── label_converter.py# 标签格式转换
│       │   ├── shape.py          # 形状数据结构
│       │   ├── schema.py         # XLABEL JSON 模板
│       │   ├── temporal_annotation.py  # 🆕 时序标注数据模型
│       │   ├── widgets/          # UI 组件
│       │   │   ├── canvas.py     # 画布
│       │   │   ├── toolbar.py    # 工具栏
│       │   │   ├── temporal_annotation_widget.py  # 🆕 时序标注面板
│       │   │   └── ...           # 其他对话框/控件
│       │   ├── settings/         # 设置面板
│       │   ├── utils/            # 工具函数（主题、样式、更新检查等）
│       │   ├── chatbot/          # 聊天机器人
│       │   ├── classifier/       # 分类器
│       │   └── vqa/              # 视觉问答
│       ├── common/               # 通用功能（检查、转换、设备管理）
│       └── training/             # 训练对话框
├── tests/                        # 测试
├── docs/                         # 文档（中/英）
├── examples/                     # 示例（分类/检测/分割/跟踪等 13 个类别）
├── scripts/                      # 构建/发布脚本
├── assets/                       # 静态资源
├── pyproject.toml                # 项目元数据与构建配置
├── 手术视频标注指南.md            # 手术视频标注操作指南
└── CHANGELOG.md                  # 版本变更日志

构建与运行

安装（开发模式）

# CPU 版本
git clone <repo-url> && cd X-AnyLabeling
pip install -e .[cpu,dev]

# GPU CUDA 12.x
pip install -e .[gpu,dev]

# GPU CUDA 11.x
pip install -e .[gpu-cu11,dev]

⚠️ onnxruntime 和 onnxruntime-gpu 不能同时安装。

运行

# 启动 GUI
xanylabeling

# 直接打开图片/目录
xanylabeling --filename /path/to/image.jpg

# 系统检查
xanylabeling checks

# 查看版本
xanylabeling version

# 格式转换
xanylabeling convert --task yolo2xlabel --mode detect --images ./images --labels ./labels --output ./output --classes classes.txt

测试

pytest

打包

$env:TORCH_DISTRIBUTED_DISABLE="1"
$env:USE_DISTRIBUTED="0"
pyinstaller "packaging\pyinstaller\specs\x-anylabeling-win-cpu.spec" --clean

代码格式化与检查

# 格式化
black --line-length 79 anylabeling/

# Lint
flake8 anylabeling/

# Pre-commit 全量检查
pre-commit run --all-files

技术架构

应用入口

anylabeling/app.py:main() 是 CLI 入口，解析参数后创建 MainWindow → LabelingWrapper → LabelingWidget 的 UI 层级。

配置系统

三级配置合并（config.py:get_config()）：

1. 默认配置（xanylabeling_config.yaml）
2. 用户配置文件（~/.xanylabelingrc）
3. CLI 参数覆盖

自动标注服务

services/auto_labeling/ 下每个模型是一个独立模块，继承自 __base/ 基类。模型通过 model_manager.py 统一管理下载和加载。支持的模型系列包括：

• YOLO 系列（v5/v6/v7/v8/v9/v10/v11/v12/World/NAS/Pose/SEG/OBB）
• SAM 系列（SAM/SAM2/SAM-HQ/EdgeSAM/EfficientViT-SAM/MedSAM）
• Grounding DINO / Grounding SAM
• RT-DETR / RF-DETR / DEIM / DFINE
• Depth Anything / Florence2 / PP-OCR / RAM 等

🆕 时序事件标注（本 Fork 核心新增）

三层标注模型：

1. 帧级别三元组 (TripleAnnotation): 主体-动作-对象 + 帧范围
2. 动作/事件 (ActionEventAnnotation): 连续帧事件 + 关联三元组
3. 手术阶段 (SurgicalPhaseAnnotation): 长时程阶段划分

UI 入口：temporal_annotation_widget.py（三标签页面板），数据模型在 temporal_annotation.py。

开发约定

代码风格

• 行宽: 79 字符（black 配置）
• 格式化: black
• Lint: flake8（含 bugbear、docstrings、comprehensions 等插件）
• 文档字符串: Google-style docstring + Python type hints（强制）
• 排除: tests/ 和 anylabeling/resources/resources.py 不参与格式化检查

提交规范

• 使用 pre-commit 钩子（black、flake8、codespell、rstcheck 等）
• 提交信息简洁清晰，聚焦于"为什么"而非"是什么"

测试

• 框架: pytest
• 测试目录: tests/（含 test_models/、test_settings/、test_utils/）
• 标记: @pytest.mark.slow 用于慢速测试

依赖管理

• pyproject.toml 中定义核心依赖和可选依赖组
• [tool.uv] 配置了 CPU/GPU/GPU-CU11 三组互斥约束

关键文件速查

用途	文件
应用入口	anylabeling/app.py
版本信息	anylabeling/app_info.py
配置管理	anylabeling/config.py
默认配置	anylabeling/configs/xanylabeling_config.yaml
模型注册	anylabeling/configs/models.yaml
标注主控件	anylabeling/views/labeling/label_widget.py
标签文件 I/O	anylabeling/views/labeling/label_file.py
时序标注模型	anylabeling/views/labeling/temporal_annotation.py
时序标注 UI	anylabeling/views/labeling/widgets/temporal_annotation_widget.py
自动标注基类	anylabeling/services/auto_labeling/__base/
模型管理器	anylabeling/services/auto_labeling/model_manager.py
手术标注指南	手术视频标注指南.md
构建配置	pyproject.toml
变更日志	CHANGELOG.md

当前版本

v4.0.0-beta.3（2026-03-27），基于上游 X-AnyLabeling v4.0.0-beta.3，新增时序事件标注功能。