# annotation-manager

**Repository Path**: ShiruiTian/annotation-manager

## Basic Information

- **Project Name**: annotation-manager
- **Description**: 标注系统开源代码仓库
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 44
- **Created**: 2026-05-28
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AnnotationManager

医学超声标注数据集的桌面管理工具。基于 **PySide6** 与 **SQLite**，用于在本地集中管理图像、筛选浏览标注、查看统计，并导出 JSON/CSV 及 COCO/VOC/YOLO 等训练格式。

![Python](https://img.shields.io/badge/Python-3.8%2B-3776AB?logo=python&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-green)
![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-555)

[English](README.en.md)

## 界面预览

![AnnotationManager 主界面](docs/images/main-ui.png)

## 文档资源规划

- `docs/images/`：统一存放 README 与文档使用的截图/插图。
- `docs/images/main-ui.png`：主界面预览图（原 `主界面图片.png` 已迁移并改为英文文件名）。
- 后续新增图片建议使用语义化英文命名（如 `filter-panel.png`、`export-dialog.png`）。

## 软件功能

| 功能 | 说明 |
|------|------|
| 数据集目录 | 指定本地根目录，自动维护 `annotations.db` |
| 批量导入 | 从文件夹导入图像及标注（`annotations.json` / `annotations.csv`） |
| 更新 / 合并 | 从标注文件更新或合并已有记录（支持 `.json` / `.cjson` / `.csv`） |
| 筛选查询 | 左侧面板按图像 ID、文件名、创建/更新时间等条件筛选 |
| 列表浏览 | 分页表格查看当前筛选结果 |
| 图像预览 | 叠加显示框/多边形标注，支持上一张/下一张 |
| 属性编辑 | 右侧面板查看并修改切面类型、标准程度等字段 |
| 数据统计 | 右侧统计页展示「切面类型 × 标准等级」交叉统计表 |
| 导出标注 | 导出当前筛选结果为 JSON/CSV，或导出至 COCO/VOC/YOLO |
| 目录整理 | 按切面类型重新组织图像文件目录 |
| 加密标注 | 支持读取 `.cjson` 加密标注（需本地 AES 解密库） |

## 界面布局

| 区域 | 内容 |
|------|------|
| 左侧 Dock | 筛选面板（图像 ID、文件名、创建/更新时间范围） |
| 中央 | **Image list** 分页列表 / **Image view** 图像预览 |
| 右侧 Dock | **属性** 面板 / **统计** 页 |

通过 **View → Left dock / Right dock** 可显示或隐藏左右侧栏。

## 目录结构

```
AnnotationManager/
├── ImageManager.py              # 程序入口
├── requirements.txt             # Python 依赖
├── README.md / README.en.md     # 中英文说明文档
├── LICENSE                      # MIT 许可证
├── docs/
│   └── images/
│       └── main-ui.png          # README 主界面截图
├── help/                        # 使用文档（PDF / DOCX）
├── AnnotationIO/                # 标注 I/O、加解密与格式转换
│   ├── annotation_io.py         # 标注解析（JSON / CSV / CJSON）
│   ├── aes_cipher.py            # AES 加解密（依赖本地动态库）
│   ├── AesCipherUI.py           # 独立加解密小工具（PyQt5）
│   └── converter/               # COCO / VOC / YOLO 等转换器
├── db/
│   ├── db.py                    # SQLite 访问与查询
│   └── config.py                # 切面类型、标准程度枚举
├── iomodule/
│   ├── annotation_io.py         # 导入用的轻量标注解析
│   ├── dataset_importer.py      # 导入 / 更新 / 合并
│   ├── dataset_exporter.py      # 导出
│   ├── dataset_sync.py          # 数据集目录同步
│   └── imageio.py               # 图像文件读取
├── ui/                          # Qt 界面
│   ├── ImageFilterPage.*        # 左侧筛选面板
│   ├── ImagePropertyPage.*      # 右侧属性面板
│   ├── StatisticPage.*          # 右侧统计页
│   ├── PagedTableWidget.*       # 分页列表
│   └── ExportDialog.*           # 高级导出对话框
├── render/
│   └── baserenderwidget.py      # 标注叠加绘制
└── resources/
    ├── resource.qrc
    ├── resource_rc.py
    └── icon/                    # 菜单与工具栏图标
```

## 环境要求

- Python 3.8 及以上
- Windows / macOS / Linux（图形界面需支持 Qt）
- 读取 `.cjson` 时需本地 AES 动态库（`AesCipher.dll` / `AesCipher.so`，通常放在 `AnnotationIO/` 目录）

## 安装与运行

在项目根目录执行：

```bash
pip install -r requirements.txt
python ImageManager.py
```

首次启动：**Settings → Dataset directory**，选择数据集根目录。路径会写入根目录下的 `config.json`。

## 使用流程

1. **设置目录**：Settings → Dataset directory  
2. **导入数据**：File → Import，选择含图像和标注文件的文件夹  
3. **筛选浏览**：左侧面板设置条件，中央 Image list 分页查看结果  
4. **查看图像**：双击列表行，切换到 Image view 预览  
5. **查看统计**：右侧面板切换到统计页，查看当前筛选结果的分布  
6. **导出**：Tools 菜单选择相应导出项（见下表）

> 多数导出操作仅包含**当前筛选结果**，而非数据库中的全部记录。清空筛选条件即可导出全部数据。

### 菜单说明

| 菜单 | 项 | 作用 |
|------|-----|------|
| File | Import | 从文件夹批量导入 |
| File | Update | 从标注文件更新已有记录 |
| File | Merge | 与已有记录合并标注 |
| Tools | Generate json | 在数据集目录生成 `annotations.json` |
| Tools | Generate csv | 在数据集目录生成 `annotations.csv` |
| Tools | Generate json for each type | 按切面类型子目录分别生成 JSON |
| Tools | Generate csv for each type | 按切面类型子目录分别生成 CSV |
| Tools | Export to json | 导出至指定目录（高级导出对话框） |
| Tools | Export to coco | 导出 COCO 格式 |
| Tools | Export to voc | 导出 VOC 格式（含 train/val/test 划分） |
| Tools | Export to yolo | 导出 YOLO 格式（含 class mapping 等选项） |
| Tools | Generate json for videos | 将视频配套的 `.cjson` 解密为 `.json` |
| Tools | Reorganize | 按切面类型重新整理图像文件目录 |
| Settings | Dataset directory | 设置/更改数据集根目录 |
| View | Left dock | 显示或隐藏左侧筛选面板 |
| View | Right dock | 显示或隐藏右侧属性/统计面板 |

### 高级导出对话框

**Export to json / coco / voc / yolo** 会打开导出对话框，可配置：

- 导出路径
- 标注类型：框 / 多边形 / 两者
- train / val / test 划分比例（VOC、YOLO）
- class mapping 文件、每类采样数量、忽略结构等（YOLO）

## 数据说明

### 数据集目录

选定目录后会出现：

- `annotations.db` — 图像元数据与标注的 SQLite 数据库  
- 按切面类型分子目录存放的图像文件（导入时自动归类）

### 支持的标注文件

| 格式 | 说明 |
|------|------|
| `annotations.json` | 标准 JSON 标注 |
| `annotations.csv` | CSV 标注（以框为主） |
| `annotations.cjson` | AES 加密 JSON 标注 |
| `gt_annotations.json` | 优先于 `annotations.json` 被读取 |
| `gt_annotations.cjson` | 优先于 `annotations.cjson` 被读取 |

文件夹导入时读取 `annotations.json` / `annotations.csv`（及 `gt_annotations.json`）。**Update / Merge** 另支持直接选择 `.cjson` 文件。

导入失败或类型不合法时，可能在源目录生成 `error_annotations.json`、`inconsistent.csv`。

### 导入模式

| 模式 | 菜单 | 行为 |
|------|------|------|
| 新增 | File → Import | 导入新图像，跳过已存在的重复项 |
| 更新 | File → Update | 按 MD5 匹配，用新标注覆盖已有记录 |
| 合并 | File → Merge | 按 MD5 匹配，合并新旧标注信息 |

### 切面类型配置

`db/config.py` 中定义了产科/妇科/甲状腺等切面类型及别名。**新增类型请在该文件对应分组的末尾追加**，避免已有记录的 `image_type` ID 错位。

## 依赖

```
PySide6
opencv-python
numpy
loguru
orjson
```

详见 [requirements.txt](requirements.txt)。

## 常见问题

**Q：`config.json` 是什么？**  
记录上次使用的数据集路径，仅本机使用，可手动删除后重新在界面中设置目录。

**Q：导出包含哪些图像？**  
默认导出**当前筛选结果**。若需导出全部数据，请清空左侧筛选条件后再执行导出。

**Q：如何读取 `.cjson` 加密标注？**  
需将 `AesCipher.dll`（Windows）或 `AesCipher.so`（Linux/macOS）放在 `AnnotationIO/` 目录。Update / Merge 及视频 JSON 生成均依赖该库。

**Q：Update 和 Merge 有什么区别？**  
Update 用新标注覆盖匹配到的已有记录；Merge 在保留原有信息的基础上合并新旧标注。

## 开源许可

本项目采用 [MIT License](LICENSE) 发布。

你可以自由使用、修改和分发本软件（包括商业用途），但需满足：

- 在副本或衍生作品中保留版权声明与许可全文；
- 软件按「原样」提供，作者不承担任何明示或暗示的担保责任。

## 作者

Hongyang Zhao — [hyzhao@hnu.edu.cn](mailto:hyzhao@hnu.edu.cn)