集成脚本工具（Integrated Script）

面向计算机视觉数据准备与批处理场景的交互式工具。本文档按程序架构模块组织，给出完整功能边界、菜单树、输入输出约定、预期处理结果与示例。

1. 文档目标与约定

目标：先约定清楚“工具能做什么、不能做什么、每一步会产生什么结果”。
组织方式：
- 先讲架构与功能边界；
- 再按主菜单 / 子菜单逐项说明；
- 最后给出典型使用流程、风险操作提示与常见问题。
说明基线：以当前代码实现为准（交互入口 + processors 实现）。

2. 适用范围（Scope）

2.1 适用场景

本工具适合以下场景：

YOLO 数据集治理
- 检测/分割数据集验证；
- 孤立文件清理；
- CTDS ↔ YOLO 转换；
- YOLO ↔ X-label/Labelme JSON 转换；
- 多数据集合并（同类/异类类别体系）。
图像批处理
- 格式转换、尺寸调整、压缩；
- OpenCV 无法读取图像的批量修复；
- 图像元信息与统计分析。
文件与标签批处理
- 批量复制、移动、按数量搬运；
- 单目录或 images/labels 同步重命名；
- 空标签创建、标签翻转、类别过滤、删除策略。
本地环境与配置管理
- 依赖检查/安装、工作目录初始化；
- 配置查看、修改、加载、保存、重置。

2.2 非适用场景（Out of Scope）

本工具不负责以下能力：

模型训练、推理服务部署、在线标注协作平台能力；
数据集可视化标注编辑器（仅做文件级转换与治理）；
数据库/云对象存储的原生管理（主要面向本地文件系统路径）；
强事务回滚（部分功能提供预览/备份，但并非全局事务系统）。

3. 程序架构模块与职责边界

3.1 启动链路

main.py（仓库根）
src/integrated_script/main.py
src/integrated_script/ui/interactive.py
src/integrated_script/ui/menu.py + 各 processors/*

3.2 模块职责

config/：配置加载、保存、重置、轻量校验、异常定义。
core/：基础设施（日志、进度、文件安全工具、平台兼容）。
processors/：所有业务处理能力（YOLO / image / file / label）。
ui/：菜单路由、用户输入、结果展示。
scripts/：打包、发布、版本脚本（非主菜单核心能力）。

3.3 关键边界约定

UI 层不做重计算：负责输入与展示，核心处理在 processors。
结果结构化返回：处理器返回字典，UI 统一渲染。
路径为系统边界：路径输入先校验、规范化，再执行处理。
高风险操作需确认：删除、重命名、覆盖前提供确认或试运行分支。

4. 运行与安装

4.1 环境要求

Python 3.8+（环境检查通过基线）
Windows / Linux / macOS

4.2 安装

pip install -r requirements.txt
# 或开发模式
pip install -e .

4.3 启动

python main.py
# 或安装后
integrated-script

4.4 常用参数

integrated-script --config path/to/config.yaml
integrated-script --log-level DEBUG
integrated-script --build

当前设计中，核心业务操作通过交互式菜单完成，CLI 参数主要用于配置/日志/打包辅助。

5. 主菜单与子菜单总览

主菜单在非 EXE 环境下会显示“环境检查与配置”；EXE 环境默认隐藏该入口并执行静默检查。

5.1 主菜单

YOLO数据集处理
图像处理
文件操作
标签处理
环境检查与配置（仅非 EXE）
配置管理

5.2 子菜单结构

A. YOLO数据集处理

CTDS数据转YOLO格式
YOLO数据转CTDS格式
YOLO数据转X-label
X-label数据转YOLO
目标检测数据集验证
目标分割数据集验证
清理不匹配文件
合并多个数据集(相同类型)
合并多个数据集(不同类型)

B. 图像处理

格式转换
尺寸调整
图像压缩
修复 OpenCV 读取错误的图像
获取图像信息

C. 文件操作

单目录重命名
数据集重命名
数据集重命名（传统模式）
按扩展名组织文件（暂未开放）
递归删除JSON文件
批量复制文件
批量移动文件
按数量移动图片

D. 标签处理

创建空标签文件
翻转标签坐标
过滤标签类别
删除空标签
删除只包含指定类别标签

E. 环境检查与配置（非 EXE）

一键检查并修复所有环境
仅检查Python依赖
仅安装缺失依赖
仅初始化工作目录

F. 配置管理

查看当前配置
修改配置
加载配置文件
保存配置文件
重置为默认配置

“修改配置”子菜单：

日志级别设置
路径配置
处理配置
图像处理配置
YOLO配置
界面配置

6. 模块化使用说明（按主菜单）

6.1 YOLO数据集处理

6.1.1 CTDS数据转YOLO格式

用途

将 CTDS 目录处理为 YOLO 标准结构（images/ + labels/ + classes.txt）。

输入

CTDS 数据集路径（含 obj.names 和 obj_train_data）。
可选项目名；是否保留空标签。

处理行为

预检测数据集类型（检测/分割/混合）并提示确认；
清理非法或空标签（取决于参数）；
文件重命名并落入标准目录。

预期结果

成功时返回输出路径、项目名、统计信息（总处理、有效/无效数量，以及标签越界、标签缺图、图片缺标等细分统计）。

示例输出（节选）

✅ 处理成功!
📁 输出路径: /data/output/project-01234
📝 项目名称: project
📊 处理统计:
  - 总处理文件数: 1260
  - 有效文件数: 1234
  - 无效文件数: 26
  - 标签越界数: 8
  - 标签缺图数: 10
  - 图片缺标数: 8

6.1.2 YOLO数据转CTDS格式

用途

将现有 YOLO 数据集重新封装为 CTDS 结构（含 obj.names、obj_train_data、train.txt、obj.data）。

输入

YOLO 数据集路径（必须有 images/、labels/，且存在 obj.names 或 classes.txt）。

预期结果

输出一个 _ctds 目录（或用户指定目录），包含复制后的标签、图像、类别文件与辅助文件。
若标签缺失对应图像，会记录缺失列表。

示例输出（节选）

✅ 输出路径: /data/my_dataset_ctds
  - 标签数: 1200
  - 复制标签: 1200
  - 复制图像: 1198
  - 缺失图像: 2

6.1.3 YOLO数据转X-label（自动识别）

用途

自动识别检测/分割后，转换到 X-label/Labelme JSON。

输入

处理行为

自动识别类型 + 置信度；
用户确认类型后执行对应转换函数。

预期结果

输出同名 JSON（与图片配套），保留类别语义。

6.1.4 X-label数据转YOLO（自动识别）

用途

从 Labelme/X-label JSON 自动判断检测/分割并转换为 YOLO。

输入

X-label 数据集路径、可选输出目录。

关键交互

自动扫描类别；
支持用户自定义类别顺序（直接决定 class_id 映射）。

预期结果

生成标准 YOLO 标注文本与类别文件。

6.1.5 目标检测/分割数据集验证

用途

检查 images/ 与 labels/ 一一匹配关系。

额外行为

分割验证会检查标签格式（每行至少 7 列）。
可在验证后触发自动清理流程（先试运行，再确认删除）。

预期结果

返回统计字段：
- total_images, total_labels, matched_pairs
- orphaned_images, orphaned_labels
- invalid_labels, empty_labels
- is_valid

6.1.6 清理不匹配文件

用途

删除孤立图片、孤立标签、无效标签、空标签。

推荐流程

先 dry_run（试运行）；
查看待删除文件样例；
再执行正式删除。

预期结果

输出删除统计：总删除、图片删除数、标签删除数。

6.1.7 合并多个数据集（同类 / 异类）

同类合并

要求 classes.txt 一致；
统一命名规则与图片前缀。

异类合并

自动汇总所有类别；
建立统一类别映射（旧 class_id -> 新 class_id）；
支持用户调整输入数据集优先顺序。

预期结果

输出合并目录、总图像数、总标签数、统一类别表、分数据集统计。

6.2 图像处理

6.2.1 格式转换

输入

单文件或目录；目标格式（jpg/png/webp 等）；可选质量；是否递归。

输出

单文件：输出文件路径 + 压缩比。
目录：成功/失败统计 + 文件列表。

6.2.2 尺寸调整

输入

目标尺寸（WxH 或单值）；是否保持宽高比；可递归。

输出

单文件：原尺寸/新尺寸。
目录：总处理数、成功数、失败数。

6.2.3 图像压缩（多进程分批）

特性

可指定质量、目标格式、最大尺寸；
目录模式使用“分批 + 多进程 + 进度显示”。

预期结果

输出压缩统计：
- 总文件、成功/失败；
- 输入总大小、输出总大小；
- 空间节省与压缩比例。

示例输出（节选）

=== 压缩统计 ===
总文件数: 5000
成功压缩: 4972
失败文件: 28
原始总大小: 12.4 GB
压缩后大小: 4.1 GB
空间节省率: 66.9%

6.2.4 修复 OpenCV 读取错误图像

用途

扫描目录，尝试读取图像，读取失败时重写编码。

注意

依赖 OpenCV；
支持递归、扩展名过滤、隐藏文件过滤。

输出

总检查数、成功加载数、重写数、失败数、失败文件列表。

6.2.5 获取图像信息

单文件输出

大小、格式、宽高、宽高比、像素数、颜色模式、透明度等。

目录输出

汇总统计 + 分辨率分布 + 清晰度分布。

6.3 文件操作

6.3.1 单目录重命名

用途

按模式批量重命名（支持位数、前缀、乱序）。

关键机制

两阶段临时命名防冲突（temp_xxx -> 目标名）。

6.3.2 数据集重命名（images/labels 同步）

用途

仅对有配对关系的图片/标签同步重命名。

两种模式

标准模式：可设位数（如 5 位补零）。
传统模式：不补零（1,2,3...）。

风险控制

失败时尝试回滚原名；失败项会出现在 failed_pairs。

6.3.3 按扩展名组织文件（当前版本暂未开放）

当前主菜单存在该入口；
处理器侧尚未提供对应公开方法实现（FileProcessor.organize_by_extension）；
现阶段请不要将其视为可用功能，避免运行时触发方法不存在错误。

6.3.4 递归删除 JSON

先扫描并预览（显示前 10 个）；
二次确认后永久删除。

6.3.5 批量复制 / 批量移动

支持路径校验、递归、覆盖控制、结构保留；
当不覆盖时会尝试唯一命名，避免直接冲突失败。

6.3.6 按数量移动图片

规则

先根目录图片，再按子目录名称顺序处理子目录图片。
输入 9999 表示移动全部。

6.4 标签处理

6.4.1 创建空标签文件

根据图像列表创建同名 .txt；
可覆盖或跳过已存在标签。

6.4.2 翻转标签坐标

支持 horizontal / vertical / both；
可选备份 .bak。

6.4.3 过滤标签类别

keep：仅保留目标类别。
remove：移除目标类别。

6.4.4 删除空标签及对应图像

判断标签内容为空则删除标签，并删除对应图像（按常见扩展名查找）。

6.4.5 删除仅包含指定类别的标签及对应图像

基于每个标签文件中类别集合判断；
仅当该文件有效标注类别集合等于 {target_class} 才删除。

6.5 环境检查与配置（非 EXE）

功能

一键检查并修复所有环境
仅检查 Python 依赖
仅安装缺失依赖
仅初始化工作目录

自动修复覆盖点

依赖完整性（requirements.txt）；
配置文件存在性；
工作目录（如 logs/、temp/、config/）；
核心模块导入可用性。

EXE 模式说明

启动时会执行静默检查；
部分异常会被吞掉以保证主流程可进入菜单。

6.6 配置管理

6.6.1 查看当前配置

可查看分组：

版本/调试/日志级别
路径配置
处理配置
YOLO 配置
图像处理配置
UI 配置

6.6.2 修改配置

支持以下子配置域：

日志级别
路径（输入/输出/临时/日志）
处理参数（批大小、并发、超时、重试）
图像参数（默认格式、质量、并行、分块）
YOLO 参数（标签格式、类别文件、加载验证）
UI 参数（语言、主题、是否显示进度）

6.6.3 加载/保存/重置

可从指定文件加载并合并到当前配置；
可保存当前配置到指定文件；
可重置为默认配置。

7. 通用输入输出约定

7.1 通用结果结构（处理器层）

多数处理结果遵循：

{
  "success": true,
  "statistics": {"...": 0},
  "...": "按功能附加字段"
}

常见 statistics 字段：

total_files, converted_count, resized_count, compressed_count
failed_count, removed_images, removed_labels
total_input_size, total_output_size, space_saved

7.2 用户中断与异常行为

输入阶段 Ctrl+C / EOF 通常会被包装为用户中断，返回上级菜单或取消当前操作；
批处理中单文件失败会记录到失败列表，不一定立即中断整个批次；
严重结构错误（目录缺失、配置不可读等）会抛出对应错误并停止当前功能。

8. 典型使用流程（推荐）

8.1 新数据集入库治理（检测/分割）

进入「YOLO数据集处理 -> 目标检测/分割数据集验证」
看统计与问题项
进入「清理不匹配文件」先试运行
确认后正式删除
再次验证，直至 is_valid=true

8.2 X-label/YOLO 互转流程

先自动识别数据集类型；
人工确认识别结果与置信度；
如有类别映射需求，手工调整 class_id 顺序；
转换后抽样检查输出标注文件。

8.3 大批量图像压缩流程

进入「图像压缩」
设定质量、目标格式、最大尺寸（可选）
配置批次数与进程数
关注最终压缩比、失败清单并回看异常文件

9. 风险操作清单（务必先确认）

下列操作会直接修改或删除文件：

清理不匹配文件（删除）
删除空标签/指定类别标签（删除）
递归删除 JSON（删除）
批量移动（源目录文件会减少）
同步重命名（文件名批量变化）

建议：

先在小样本目录演练；
优先使用试运行/预览模式；
重要数据先备份。

10. 打包与发布（单人开发标准流程）

10.1 打包

pip install pyinstaller
python build_exe.py
# 或
integrated-script --build

10.2 发布（推荐：tag 驱动自动发布）

当前仓库以 GitHub Actions 的 release.yml 作为唯一发布入口：

触发条件：push tag（v*.*.*）
自动执行：多平台构建 + 上传 Release 附件 + 生成发布说明

发布前建议：

更新 pyproject.toml 的版本号；
运行一次 make check-all；
使用 annotated tag 写入发布概况块；
push tag 触发发布。

示例：

git tag -a v2.0.3 -m "$(cat <<'EOF'
release: v2.0.3

<!-- release-overview:start -->
## 发布概况
- 新增 xxx
- 修复 yyy
<!-- release-overview:end -->
EOF
)"

git push origin v2.0.3

10.3 Release 页面内容生成规则（`release.yml`）

Release 页面正文由 workflow 自动生成，逻辑如下：

标题：当前 tag；
对比范围：上一 release tag 到当前 tag；
分类：按提交前缀汇总（新增/修复/文档/CI/构建/重构/测试/其他）；
时间：附加北京时间生成时间。

同时支持“发布概况块”注入：

workflow 会从 tag annotation 中提取以下标记内容：

<!-- release-overview:start -->
...你的概况 markdown...
<!-- release-overview:end -->

若未提供该块，不会阻断发布，仅展示自动生成的分类内容。

11. 常见问题

Q1：为什么主菜单里有时看不到“环境检查与配置”？

A：在 EXE 运行模式下，该入口默认隐藏，改为启动时执行静默检查。

Q2：为什么同一个操作既有“标准重命名”又有“传统模式”？

A：兼容不同命名偏好：标准模式支持补零位数；传统模式保持 1,2,3… 序号。

Q3：为什么会出现“识别类型置信度低”的提示？

A：自动判型是基于样本统计，不是绝对判断；低置信度时需人工确认，以避免错误转换。

Q4：是否支持把处理结果回滚到完全原状态？

A：不提供全局事务回滚。部分功能提供备份或试运行，但应自行做目录级备份。

12. 快速入口

快速上手：QUICK_START.md
架构与模块索引：CLAUDE.md
模块级细节：
- src/integrated_script/CLAUDE.md
- src/integrated_script/config/CLAUDE.md
- src/integrated_script/core/CLAUDE.md
- src/integrated_script/processors/CLAUDE.md
- src/integrated_script/ui/CLAUDE.md

Name		Name	Last commit message	Last commit date
Latest commit History 146 Commits
.githooks		.githooks
.github/workflows		.github/workflows
config		config
src/integrated_script		src/integrated_script
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
QUICK_START.md		QUICK_START.md
README.md		README.md
build_exe.py		build_exe.py
config.json		config.json
main.py		main.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

集成脚本工具（Integrated Script）

1. 文档目标与约定

2. 适用范围（Scope）

2.1 适用场景

2.2 非适用场景（Out of Scope）

3. 程序架构模块与职责边界

3.1 启动链路

3.2 模块职责

3.3 关键边界约定

4. 运行与安装

4.1 环境要求

4.2 安装

4.3 启动

4.4 常用参数

5. 主菜单与子菜单总览

5.1 主菜单

5.2 子菜单结构

A. YOLO数据集处理

B. 图像处理

C. 文件操作

D. 标签处理

E. 环境检查与配置（非 EXE）

F. 配置管理

6. 模块化使用说明（按主菜单）

6.1 YOLO数据集处理

6.1.1 CTDS数据转YOLO格式

6.1.2 YOLO数据转CTDS格式

6.1.3 YOLO数据转X-label（自动识别）

6.1.4 X-label数据转YOLO（自动识别）

6.1.5 目标检测/分割数据集验证

6.1.6 清理不匹配文件

6.1.7 合并多个数据集（同类 / 异类）

6.2 图像处理

6.2.1 格式转换

6.2.2 尺寸调整

6.2.3 图像压缩（多进程分批）

6.2.4 修复 OpenCV 读取错误图像

6.2.5 获取图像信息

6.3 文件操作

6.3.1 单目录重命名

6.3.2 数据集重命名（images/labels 同步）

6.3.3 按扩展名组织文件（当前版本暂未开放）

6.3.4 递归删除 JSON

6.3.5 批量复制 / 批量移动

6.3.6 按数量移动图片

6.4 标签处理

6.4.1 创建空标签文件

6.4.2 翻转标签坐标

6.4.3 过滤标签类别

6.4.4 删除空标签及对应图像

6.4.5 删除仅包含指定类别的标签及对应图像

6.5 环境检查与配置（非 EXE）

功能

自动修复覆盖点

EXE 模式说明

6.6 配置管理

6.6.1 查看当前配置

6.6.2 修改配置

6.6.3 加载/保存/重置

7. 通用输入输出约定

7.1 通用结果结构（处理器层）

7.2 用户中断与异常行为

8. 典型使用流程（推荐）

8.1 新数据集入库治理（检测/分割）

8.2 X-label/YOLO 互转流程

8.3 大批量图像压缩流程

9. 风险操作清单（务必先确认）

10. 打包与发布（单人开发标准流程）

10.1 打包

10.2 发布（推荐：tag 驱动自动发布）

10.3 Release 页面内容生成规则（release.yml）

11. 常见问题

Q1：为什么主菜单里有时看不到“环境检查与配置”？

Q2：为什么同一个操作既有“标准重命名”又有“传统模式”？

Q3：为什么会出现“识别类型置信度低”的提示？

Q4：是否支持把处理结果回滚到完全原状态？

10.3 Release 页面内容生成规则（`release.yml`）

Packages