yoloutils 操作手册

YOLO 标签工具集 - 用于处理 YOLO 目标检测数据集的标签和图片。

作者: Neo netkiller@msn.com
官网: https://www.netkiller.cn

---

目录

1. 安装指南
2. 标签管理 (label)
3. 合并标签 (merge)
4. 复制标签 (copy)
5. 删除标签 (remove)
6. 修改标签 (change)
7. 图片裁剪 (crop)
8. labelimg 转 YOLO (labelimg)
9. 修改图片尺寸 (resize)
10. 图像分类 (classify)

---

安装指南

方式一：使用 pip 安装

# 从 PyPI 安装
pip install netkiller-yoloutils

# 或从源码安装
pip install build
python -m build
pip install dist/netkiller_yoloutils-0.0.1-py3-none-any.whl --force-reinstall

方式二：开发模式安装

git clone https://github.com/netkiller/yoloutils.git
cd yoloutils
pip install -e .

方式三：手动安装

pip install setuptools wheel twine
python3 setup.py sdist
python3 setup.py install

---

标签管理 (label)

查看 classes.txt 文件、统计标签数量、搜索指定标签。

查看 classes.txt

yoloutils label --source /path/to/dataset --classes

统计标签图数量

yoloutils label --source /path/to/dataset --total

统计标签索引数量

yoloutils label --source /path/to/dataset --index

搜索指定标签

# 搜索索引为 1, 2, 3 的标签
yoloutils label --source /path/to/dataset --search 1 2 3

---

合并标签 (merge)

将两个目录中的 YOLO 标签 TXT 文件合并到新目录。

yoloutils merge \
    --left /path/to/dir1 \
    --right /path/to/dir2 \
    --output /path/to/output \
    --clean

参数说明：

参数	说明
--left	左侧目录路径
--right	右侧目录路径
--output	最终输出目录
--clean	清理之前的数据

注意： 目标文件夹不能与原始图片文件夹相同。

---

复制标签 (copy)

根据指定标签从源目录复制图片和标签文件到目标目录。

yoloutils copy \
    --source /path/to/source \
    --target /path/to/target \
    --label person,dog \
    -u \
    -c

参数说明：

参数	说明
--source	图片来源地址
--target	图片目标地址
--label	逗号分割的标签名称（如 person,dog）
-u, --uuid	使用 UUID 作为输出文件名
-c, --clean	清理目标文件夹

示例：

# 复制包含 "cat" 标签的所有图片
yoloutils copy --source ./dataset --target ./output --label cat

# 复制多个标签
yoloutils copy --source ./dataset --target ./output --label person,car,bicycle

# 使用 UUID 重命名并清理目标
yoloutils copy --source ./dataset --target ./output --label dog -u -c

---

删除标签 (remove)

从 YOLO TXT 文件中删除指定标签。

yoloutils remove \
    --source /path/to/source \
    --target /path/to/target \
    --classes 1 2 3 \
    --clean

参数说明：

参数	说明
--source	图片来源地址
--target	图片目标地址
--classes	标签序号（索引），可指定多个
--label	标签名称，可指定多个
--clean	清理之前的数据

示例：

# 按索引删除标签
yoloutils remove --source ./dataset --target ./output --classes 0 1 2

# 按名称删除标签
yoloutils remove --source ./dataset --target ./output --label cat dog

# 删除后清理目标目录
yoloutils remove --source ./dataset --target ./output --classes 0 --clean

---

修改标签 (change)

修改 YOLO TXT 文件中的标签索引。

yoloutils change \
    --source /path/to/dataset \
    --search 0 1 2 \
    --replace 3 4 5

参数说明：

参数	说明
--source	目录路径
--search	要查找的标签序号
--replace	替换后的标签序号

示例：

# 将标签索引 0 替换为 5，1 替换为 6
yoloutils change --source ./dataset --search 0 1 --replace 5 6

---

图片裁剪 (crop)

使用 YOLO 模型检测并裁剪图片。

yoloutils crop \
    --source /path/to/source \
    --target /path/to/target \
    --model best.pt \
    --output /path/to/crops \
    --clean

参数说明：

参数	说明
--source	图片来源地址
--target	图片目标地址
--model	YOLO 模型文件路径
--output	YOLO 输出目录（包含裁剪结果）
--clean	清理之前的数据

示例：

# 使用模型裁剪图片
yoloutils crop --source ./images --target ./cropped --model best.pt

---

labelimg 转 YOLO (labelimg)

将 labelimg 标注格式转换为 YOLO 训练数据集格式。

yoloutils labelimg \
    --source /path/to/labelimg \
    --target /path/to/yolo \
    --classes /path/to/classes.txt \
    --val 10 \
    --uuid \
    --check \
    --clean

参数说明：

参数	说明
--source	labelimg 格式的标注文件目录
--target	YOLO 格式输出目录
--classes	classes.txt 文件路径
--val	验证集数量（默认 10）
--uuid	使用 UUID 作为输出文件名
--check	检查图片完整性（损坏的 JPEG 会修复并保存）
--clean	清理之前的数据

输出目录结构：

target/
├── train/
│   ├── images/
│   └── labels/
├── val/
│   ├── images/
│   └── labels/
├── test/
│   ├── images/
│   └── labels/
├── classes.txt
└── data.yaml

示例：

# 基本转换
yoloutils labelimg --source ./labelimg_data --target ./yolo_data --classes ./classes.txt

# 转换为 YOLO 格式，10% 作为验证集，使用 UUID
yoloutils labelimg --source ./labelimg_data --target ./yolo_data --classes ./classes.txt --val 10 --uuid

# 清理后重新转换
yoloutils labelimg --source ./labelimg_data --target ./yolo_data --classes ./classes.txt --clean

---

修改图片尺寸 (resize)

修改图片尺寸，保持长边为指定大小。

yoloutils resize \
    --source /path/to/source \
    --target /path/to/target \
    --imgsz 640 \
    --clean

参数说明：

参数	说明
--source	图片来源地址
--target	图片目标地址
--imgsz	长边尺寸（默认 640）
--output	输出识别图像目录
--clean	清理之前的数据

示例：

# 将图片长边调整为 640 像素
yoloutils resize --source ./images --target ./resized --imgsz 640

# 调整为 1920 像素
yoloutils resize --source ./images --target ./resized --imgsz 1920

---

图像分类 (classify)

处理分类数据集，自动划分为 train/test/val 目录结构。

yoloutils classify \
    --source /path/to/source \
    --target /path/to/target \
    --test 100 \
    --crop \
    --model best.pt \
    --uuid \
    --verbose \
    --clean

参数说明：

参数	说明
--source	图片来源地址（目录结构：source/classname/image.jpg）
--target	图片目标地址
--test	每个类别测试集数量（默认 10）
--crop	启用裁剪功能
--model	裁剪使用的 YOLO 模型
--uuid	使用 UUID 作为输出文件名
--verbose	输出详细过程信息
--output	输出识别图像目录
--checklist	输出检查列表目录
--clean	清理之前的数据

输入目录结构：

source/
├── cat/
│   ├── image1.jpg
│   └── image2.jpg
├── dog/
│   ├── image3.jpg
│   └── image4.jpg

输出目录结构：

target/
├── train/
│   ├── cat/
│   └── dog/
├── test/
│   ├── cat/
│   └── dog/
└── val/
    ├── cat/
    └── dog/

示例：

# 基本分类处理
yoloutils classify --source ./images --target ./dataset

# 每个类别取 100 张作为测试集
yoloutils classify --source ./images --target ./dataset --test 100

# 使用模型裁剪并生成检查列表
yoloutils classify --source ./images --target ./dataset --crop --model best.pt --checklist ./checklist

# 使用 UUID 重命名
yoloutils classify --source ./images --target ./dataset --uuid

---

通用参数

以下参数适用于多个子命令：

参数	说明
--source	图片来源地址
--target	图片目标地址
--clean	清理之前的数据（先删除目标目录）

---

注意事项

1. YOLO TXT 格式：工具处理的标签文件格式为 index x_center y_center width height，其中 index 从 0 开始。

2. classes.txt：某些操作需要 classes.txt 文件，格式为每行一个类别名称。

3. 路径处理：所有路径建议使用绝对路径，避免相对路径带来的问题。

4. 数据备份：使用 --clean 参数前请确保已备份重要数据，该操作会删除目标目录。

5. 依赖项：确保安装了所有依赖，包括 ultralytics（YOLO 库）、opencv-python、pillow、pyyaml、tqdm、texttable。

---

常见问题

Q: 显示 “classes.txt 文件不存在”
A: 确保源目录包含 classes.txt 文件，且路径正确。

Q: 标签索引超出范围
A: 检查 classes.txt 中的类别数量，确保标签索引在有效范围内（0 到 len(classes)-1）。

Q: 图片找不到
A: 确保 TXT 文件对应的图片文件（JPG/PNG）存在于相同目录。

---

yoloutils

YOLO Utilities

帮助信息

(.venv) neo@Neo-Mac-mini-M4 yoloutils % yoloutils
usage: yoloutils [-h] {label,merge,copy,remove,change,crop,labelimg,resize,classify} ...

Yolo 标签工具

options:
  -h, --help            show this help message and exit

subcommands:
  valid subcommands

  {label,merge,copy,remove,change,crop,labelimg,resize,classify}
                        additional help
    label               标签处理工具
    merge               合并两个TXT文件中的标签到新TXT文件
    copy                从指定标签复制图片文件
    remove              从YOLO TXT文件中删除指定标签
    change              修改标签索引
    crop                图片裁剪
    labelimg            labelimg 格式转换为 yolo 训练数据集
    resize              修改图片尺寸
    classify            图像分类数据处理

Author: netkiller - https://www.netkiller.cn

标签管理

(.venv) neo@Neo-Mac-mini-M4 yoloutils % yoloutils label -h
usage: yoloutils label [-h] [--source /tmp/dir1] [--classes] [--total] [--index] [--search 1 2 3 [1 2 3 ...]]

options:
  -h, --help            show this help message and exit
  --source /tmp/dir1    目录
  --classes             查看 classes.txt 文件
  --total               统计标签图数量
  --index               统计标签索引数量
  --search 1 2 3 [1 2 3 ...]
                        搜索标签

合并标签

(.venv) neo@Neo-Mac-mini-M4 yoloutils % yoloutils merge -h
usage: yoloutils merge [-h] [--left /tmp/dir1] [--right /tmp/dir2] [--output /tmp/output] [--clean]

options:
  -h, --help            show this help message and exit
  --left /tmp/dir1      左侧目录
  --right /tmp/dir2     右侧目录
  --output /tmp/output  最终输出目录
  --clean               清理之前的数据

复制标签

(.venv) neo@Neo-Mac-mini-M4 yoloutils % yoloutils copy -h
usage: yoloutils copy [-h] [--source SOURCE] [--target TARGET] [--label LABEL] [-u] [-c]

options:
  -h, --help       show this help message and exit
  --source SOURCE  图片来源地址
  --target TARGET  图片目标地址
  --label LABEL    逗号分割多个标签
  -u, --uuid       UUID 文件名
  -c, --clean      清理目标文件夹

删除标签

(.venv) neo@Neo-Mac-mini-M4 yoloutils % yoloutils remove -h
usage: yoloutils remove [-h] [--source SOURCE] [--target TARGET] [--clean] [--classes 1 2 3 [1 2 3 ...]]
                        [--label label1 label2 [label1 label2 ...]]

options:
  -h, --help            show this help message and exit
  --classes 1 2 3 [1 2 3 ...]
                        标签序号
  --label label1 label2 [label1 label2 ...]
                        标签名称

通用参数:
  --source SOURCE       图片来源地址
  --target TARGET       图片目标地址
  --clean               清理之前的数据

修改标签

(.venv) neo@Neo-Mac-mini-M4 yoloutils % yoloutils change -h
usage: yoloutils change [-h] [--source /tmp/dir1] [--search 1 2 3 [1 2 3 ...]] [--replace 4 5 6 [4 5 6 ...]]

options:
  -h, --help            show this help message and exit
  --source /tmp/dir1    目录
  --search 1 2 3 [1 2 3 ...]
                        标签序号
  --replace 4 5 6 [4 5 6 ...]
                        标签名称

裁剪图片

(.venv) neo@Neo-Mac-mini-M4 yoloutils % yoloutils crop -h  
usage: yoloutils crop [-h] [--source SOURCE] [--target TARGET] [--clean] [--model best.pt] [--output /tmp/output]

options:
  -h, --help            show this help message and exit
  --model best.pt       模型
  --output /tmp/output  Yolo 输出目录

通用参数:
  --source SOURCE       图片来源地址
  --target TARGET       图片目标地址
  --clean               清理之前的数据

labelimg 转 yolo 训练数据集

(.venv) neo@Neo-Mac-mini-M4 yoloutils % yoloutils labelimg -h
usage: yoloutils labelimg [-h] [--source SOURCE] [--target TARGET] [--clean] [--classes CLASSES] [--val 10] [--uuid] [--check]

options:
  -h, --help         show this help message and exit
  --classes CLASSES  classes.txt 文件
  --val 10           检验数量
  --uuid             输出文件名使用UUID
  --check            图片检查 corrupt JPEG restored and saved

通用参数:
  --source SOURCE    图片来源地址
  --target TARGET    图片目标地址
  --clean            清理之前的数据

修改图片尺寸

(.venv) neo@Neo-Mac-mini-M4 yoloutils % yoloutils resize -h  
usage: yoloutils resize [-h] [--source SOURCE] [--target TARGET] [--clean] [--imgsz 640] [--output ]

options:
  -h, --help       show this help message and exit
  --imgsz 640      长边尺寸
  --output         输出识别图像

通用参数:
  --source SOURCE  图片来源地址
  --target TARGET  图片目标地址
  --clean          清理之前的数据

图像分类数据处理

(.venv) neo@Neo-Mac-mini-M4 yoloutils % yoloutils classify -h
usage: yoloutils classify [-h] [--source SOURCE] [--target TARGET] [--clean] [--output ] [--checklist ] [--test 100] [--crop] [--model ]
                          [--uuid] [--verbose]

options:
  -h, --help       show this help message and exit
  --output         输出识别图像
  --checklist      输出识别图像
  --test 100       测试数量
  --crop           裁剪
  --model          裁剪模型
  --uuid           重命名图片为UUID
  --verbose        过程输出

通用参数:
  --source SOURCE  图片来源地址
  --target TARGET  图片目标地址
  --clean          清理之前的数据