# 📋 图片标注检查工具使用教程

## 工具简介

`check_and_clean_images.py` 是一个用于检查和清理数据集的工具，可以：
- ✅ 检查图片文件是否有对应的标注文件
- ✅ 找出没有标注的图片
- ✅ 删除没有标注的图片文件
- ✅ 确保数据集完整性

---

## 🚀 快速开始

### 基本用法

#### 1. 预览模式（推荐先运行）

检查哪些图片没有标注，但**不删除**文件：

```bash
python check_and_clean_images.py
```

**输出示例：**
```
============================================================
检查没有标注的图片
============================================================
图片目录: datasets/handleImage/train
标注目录: datasets/handleImage/label

找到 1330 个图片文件
找到 1223 个标注文件
------------------------------------------------------------
发现 107 个没有标注的图片:
------------------------------------------------------------
  订单1806953_51_7111322.jpg
  订单1805323_51_7096066.jpg
  ...
------------------------------------------------------------

[预览模式] 未实际删除文件
要删除这些文件，请运行: python check_and_clean_images.py --delete
```

#### 2. 删除模式（需要确认）

删除没有标注的图片，但会要求确认：

```bash
python check_and_clean_images.py --delete
```

**交互提示：**
```
⚠ 警告: 将删除没有标注的图片文件！确认继续？(yes/no): 
```

输入 `yes` 确认删除，输入 `no` 取消操作。

#### 3. 直接删除模式（不确认）

直接删除，不需要确认（适合脚本自动化）：

```bash
python check_and_clean_images.py --delete --force
```

---

## 📖 详细说明

### 命令参数

| 参数 | 简写 | 说明 | 示例 |
|------|------|------|------|
| `--delete` | `-d` | 启用删除模式 | `--delete` |
| `--force` | `-f` | 跳过确认，直接删除 | `--force` |
| `--help` | `-h` | 显示帮助信息 | `--help` |

### 默认路径

工具默认检查以下路径：
- **图片目录**: `datasets/handleImage/train`
- **标注目录**: `datasets/handleImage/label`

### 支持的图片格式

工具会自动识别以下图片格式：
- `.jpg` / `.JPG`
- `.jpeg` / `.JPEG`
- `.png` / `.PNG`
- `.bmp`
- `.tiff` / `.tif`

### 标注文件格式

工具查找 `.txt` 格式的标注文件。

---

## 📝 使用场景

### 场景 1: 检查数据集完整性

在训练前检查数据集是否完整：

```bash
# 1. 先预览检查
python check_and_clean_images.py

# 2. 如果有问题，查看具体文件
# 3. 确认后删除
python check_and_clean_images.py --delete
```

### 场景 2: 清理导入的数据

从CVAT或其他工具导入数据后，清理不完整的文件：

```bash
# 直接删除没有标注的图片
python check_and_clean_images.py --delete --force
```

### 场景 3: 批量处理多个数据集

修改脚本中的路径，处理不同数据集：

```python
# 修改 check_and_clean_images.py 中的路径
train_dir = "datasets/你的数据集/train"
label_dir = "datasets/你的数据集/labels"
```

---

## ⚠️ 注意事项

### 1. 备份数据

**重要：** 删除操作不可恢复！建议在删除前备份数据：

```bash
# 备份整个数据集
cp -r datasets/handleImage datasets/handleImage_backup
```

### 2. 文件名匹配规则

工具通过**文件名（不含扩展名）**匹配图片和标注：

- ✅ 匹配：`image001.jpg` ↔ `image001.txt`
- ✅ 匹配：`订单1804264_51_7086683.jpg` ↔ `订单1804264_51_7086683.txt`
- ❌ 不匹配：`image001.jpg` ↔ `image_001.txt`（下划线不同）
- ❌ 不匹配：`image001.jpg` ↔ `image002.txt`（数字不同）

### 3. 空标注文件

如果标注文件存在但为空，工具**不会删除**对应的图片。如果需要处理空标注文件，需要额外检查。

### 4. 目录结构要求

确保目录结构正确：
```
datasets/handleImage/
├── train/          # 图片目录
│   ├── image1.jpg
│   ├── image2.jpg
│   └── ...
└── label/          # 标注目录
    ├── image1.txt
    ├── image2.txt
    └── ...
```

---

## 🔍 输出说明

### 预览模式输出

```
找到 1330 个图片文件          # 图片总数
找到 1223 个标注文件          # 标注总数
发现 107 个没有标注的图片    # 需要删除的数量
```

### 删除模式输出

```
删除完成:
  成功删除: 107 个文件        # 成功删除的数量
  删除失败: 0 个文件          # 删除失败的数量（如果有）
```

### 完成状态输出

```
✓ 所有图片都有对应的标注文件！
```

---

## 💡 使用技巧

### 技巧 1: 先预览再删除

**推荐流程：**
```bash
# 步骤1: 预览检查
python check_and_clean_images.py

# 步骤2: 查看结果，确认要删除的文件
# 步骤3: 确认后删除
python check_and_clean_images.py --delete
```

### 技巧 2: 批量处理多个数据集

创建一个批处理脚本：

```bash
#!/bin/bash
# process_datasets.sh

datasets=("handleImage" "仪表盘" "检测仪")

for dataset in "${datasets[@]}"; do
    echo "处理数据集: $dataset"
    # 修改脚本中的路径或使用参数
    python check_and_clean_images.py
done
```

### 技巧 3: 检查反向问题

如果需要检查**有标注但没有图片**的情况，可以修改脚本或创建新工具。

---

## 🐛 常见问题

### Q1: 提示"目录不存在"

**错误信息：**
```
错误: 图片目录不存在: datasets/handleImage/train
```

**解决方法：**
1. 检查路径是否正确
2. 确认目录是否存在
3. 修改脚本中的默认路径

### Q2: 删除后想恢复文件

**解决方法：**
- 如果之前有备份，从备份恢复
- 如果没有备份，文件无法恢复（删除操作不可逆）

### Q3: 文件名不匹配

**问题：** 图片和标注文件名不完全一致

**解决方法：**
- 检查文件名格式
- 确保文件名（不含扩展名）完全一致
- 可以使用重命名工具统一文件名格式

### Q4: 在非交互式环境运行

**问题：** 使用 `--delete` 时提示需要输入

**解决方法：**
使用 `--force` 参数跳过确认：
```bash
python check_and_clean_images.py --delete --force
```

---

## 📊 实际案例

### 案例 1: 清理 handleImage 数据集

```bash
# 1. 检查数据集
$ python check_and_clean_images.py

找到 1330 个图片文件
找到 1223 个标注文件
发现 107 个没有标注的图片

# 2. 确认后删除
$ python check_and_clean_images.py --delete
⚠ 警告: 将删除没有标注的图片文件！确认继续？(yes/no): yes

删除完成:
  成功删除: 107 个文件

# 3. 再次验证
$ python check_and_clean_images.py

找到 1223 个图片文件
找到 1223 个标注文件
✓ 所有图片都有对应的标注文件！
```

### 案例 2: 处理其他数据集

修改脚本中的路径：

```python
# 在 check_and_clean_images.py 的 main() 函数中修改
train_dir = "datasets/仪表盘/train/images"
label_dir = "datasets/仪表盘/train/labels"
```

然后运行：
```bash
python check_and_clean_images.py
```

---

## 🔗 相关工具

- `verify_seg_labels.py` - 验证分割标注格式
- `check_label_format.py` - 检查标注格式类型
- `convert_bbox_to_seg.py` - 转换标注格式

---

## 📞 需要帮助？

如果遇到问题：
1. 查看本文档的"常见问题"部分
2. 运行 `python check_and_clean_images.py --help` 查看帮助
3. 检查数据集目录结构是否正确

---

## 📝 更新日志

- **v1.0** (2024): 初始版本
  - 支持检查图片和标注文件
  - 支持预览和删除模式
  - 支持强制删除模式

---

**提示：** 使用前建议先备份数据，删除操作不可恢复！