# DataForge

**Repository Path**: archerprince/data-forge

## Basic Information

- **Project Name**: DataForge
- **Description**: 数据锻造工坊。包括各种针对数据集的批量化处理。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-17
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DataForge — 数据集批处理工具集

对 VOC / YOLO 格式的目标检测数据集进行批量处理：划分数据集、格式转换、标签修改、数据增强、文件同步等操作。支持可见光、红外等多种数据模态。

## 项目结构

```
DataForge/
├── cli.py                    # 统一命令行入口
├── utils.py                  # 公共工具函数
├── data_ops/                 # 数据集管理
│   ├── split.py              #   划分训练集/验证集/测试集
│   ├── sync.py               #   同步图片与标签
│   └── merge.py              #   合并数据集划分文件
├── dataset/                  # 数据集存放
├── convert/                  # 格式转换
│   ├── voc2yolo.py           #   VOC XML → YOLO TXT
│   └── json2voc.py           #   JSON → VOC XML
├── labels/                   # 标注文件修改
│   ├── xml_tools.py          #   XML 批量操作（改名/改尺寸/清理）
│   └── yolo_labels.py        #   YOLO 标签操作（类别映射/校验）
├── augment/                  # 数据增强
│   ├── color.py              #   颜色/光照增强
│   ├── copy_paste.py         #   复制-粘贴增强
│   └── fp_gen.py             #   生成误检样本
├── image/                    # 图像处理
│   ├── reverse.py            #   灰度反色
│   ├── hsv_augment.py        #   HSV 颜色增强
│   ├── backlit.py            #   背光窗户增强
│   └── video_extract.py      #   视频抽帧
├── file_ops/                 # 文件操作
│   ├── copy_files.py         #   递归查找并复制文件
│   └── count.py              #   统计目录下文件数
└── README.md
```

## 快速开始

所有功能通过 `cli.py` 统一调用：

```bash
python cli.py --help                  # 查看所有命令
python cli.py dataset --help          # 查看子命令
python cli.py dataset split --help    # 查看具体参数
```

## 环境依赖

```bash
pip install opencv-python numpy tqdm
```

> `augment/color.py`（颜色增强）需要额外安装 `albumentations`：
> ```bash
> pip install albumentations
> ```

## 命令参考

### 数据集划分 `dataset`

```bash
# VOC 格式（仅需 images/ 目录）
python cli.py dataset split dataset/vis_dataset/batch0_coco4cls

# YOLO 格式（需 images/ + labels/，只保留有标注的图片）
python cli.py dataset split dataset/vis_dataset/batch0_coco4cls --format yolo

# 自定义比例
python cli.py dataset split dataset/vis_dataset/batch0_coco4cls \
    --train_ratio 0.8 --val_ratio 0.1 --test_ratio 0.1
```

在数据集根目录生成 `train.txt`、`val.txt`、`test.txt`，每行为图片绝对路径。

### 标签同步 `dataset`

```bash
# 删除孤立文件（无对应图片的标签 + 无标签的图片）
python cli.py dataset sync images/ labels/ --mode delete --label-ext .xml

# 移动到 orphan 目录（不丢失数据）
python cli.py dataset sync images/ labels/ --mode move --move-dir orphans/
```

### 合并数据集 `dataset`

```bash
# 将 A 全部合并到 B
python cli.py dataset merge dataset_A/ dataset_B/

# 按比例随机采样 A 后合并
python cli.py dataset merge dataset_A/ dataset_B/ --ratio 0.5
```

### 格式转换 `convert`

```bash
# VOC XML → YOLO TXT
python cli.py convert voc2yolo annotations/ --classes person car truck

# JSON → VOC XML
python cli.py convert json2voc json_dir/ output_xmls/ --width 1920 --height 1080
```

### 标注操作 `labels`

```bash
# XML：重命名类别
python cli.py labels xml rename-tag xmls/ cyclist person

# XML：修改图片尺寸
python cli.py labels xml resize xmls/ 3840 2160

# XML：清理 <path> 标签
python cli.py labels xml clean-path xmls/

# YOLO：类别 ID 映射（3→2, 4→2, 5→2）
python cli.py labels yolo remap --input labels/ --output labels_new/ --mapping "3:2,4:2,5:2"

# YOLO：校验并删除越界坐标行
python cli.py labels yolo validate labels/
```

### 数据增强 `augment`

```bash
# 颜色/光照增强（支持 VOC/YOLO）
python cli.py augment color \
    --input_dir dataset/vis_dataset/batch0_coco4cls \
    --output_dir augmented/ \
    --format voc --augment_per_image 3

# 复制-粘贴增强
python cli.py augment copy-paste backgrounds/ objects/ output_imgs/ output_labels/

# 误检样本生成
python cli.py augment fp-gen backgrounds/ objects/ output_imgs/ output_labels/
```

### 图像处理 `image`

```bash
python cli.py image reverse input/ output/           # 灰度反色
python cli.py image hsv input/ output/ --hue 5       # HSV 色彩增强
python cli.py image backlit input/ output/           # 背光窗户增强
python cli.py image video-extract video.mp4 frames/ 2  # 视频抽帧（每 N 秒）
```

### 文件操作 `file`

```bash
python cli.py file copy-files src/ dst/ .jpg                        # 递归复制
python cli.py file copy-files src/ dst/ .jpg --rename-prefix wjdet # 复制并重命名
python cli.py file count images/                                    # 统计文件数
```

## 数据集目录约定

### VOC 格式
```
dataset/
├── images/        # 图片（.jpg / .png）
└── xmls/          # XML 标注文件（与图片同名）
```

### YOLO 格式
```
dataset/
├── images/        # 图片（.jpg / .png）
└── labels/        # TXT 标注文件（与图片同名）
```