# mahjong-yolo

**Repository Path**: fa0/mahjong-yolo

## Basic Information

- **Project Name**: mahjong-yolo
- **Description**: mahjong-yolo
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-25
- **Last Updated**: 2026-02-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🀄 麻将牌 YOLO 检测训练

基于 **Ultralytics YOLO** 的麻将牌目标检测训练项目。

数据集来源: [Roboflow - jon-chan-gnsoa/mahjong-baq4s](https://universe.roboflow.com/jon-chan-gnsoa/mahjong-baq4s)

## 快速开始

### 1. 安装依赖

```bash
conda create -n mahjong python=3.12
conda activate mahjong
pip install -r requirements.txt
```

### 2. 下载数据集

从 [Roboflow Settings](https://app.roboflow.com/settings/api) 获取 API Key，然后运行：

```bash
python scripts/download_dataset.py --api-key YOUR_ROBOFLOW_API_KEY
```

### 3. (可选) 可视化数据集

查看标注效果：

```bash
python scripts/visualize.py
python scripts/visualize.py --split valid --num 16
```

### 4. 开始训练

```bash
# 默认配置 (yolov8n, 50 epochs)
python scripts/train.py

# 自定义训练
python scripts/train.py --device 0 --model yolo11m.pt --epochs 50 --batch 16 --imgsz 640

# 恢复训练
python scripts/train.py --resume

# 指定设备
python scripts/train.py --device mps     # Apple Silicon
python scripts/train.py --device 0       # NVIDIA GPU
python scripts/train.py --device cpu     # CPU

python scripts/train.py --epochs 2 --batch 8 --model yolo11m.pt --device mps
```

### 5. 推理预测

```bash
# 单张图片
python scripts/predict.py --source path/to/image.jpg

# 目录批量
python scripts/predict.py --source path/to/images/

# 视频
python scripts/predict.py --source path/to/video.mp4

# 摄像头实时
python scripts/predict.py --source 0

# 调整置信度
python scripts/predict.py --source image.jpg --conf 0.5
```

## 项目结构

```
mahjong/
├── requirements.txt              # 依赖
├── config/
│   └── mahjong.yaml              # 备用数据集配置
├── scripts/
│   ├── download_dataset.py       # 数据集下载 (Roboflow)
│   ├── train.py                  # 训练入口
│   ├── predict.py                # 推理预测
│   └── visualize.py              # 标注可视化
├── datasets/mahjong/             # 下载后的数据集
│   ├── data.yaml                 # 自动生成的配置
│   ├── train/
│   │   ├── images/
│   │   └── labels/
│   └── valid/
│       ├── images/
│       └── labels/
└── runs/                         # 训练结果
    ├── detect/mahjong/           # 训练输出
    │   └── weights/
    │       ├── best.pt           # 最佳模型
    │       └── last.pt           # 最新模型
    └── predict/mahjong/          # 推理结果
```

## 训练参数说明

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--model` | `yolov8n.pt` | 预训练模型 (n/s/m/l/x) |
| `--epochs` | `50` | 训练轮数 |
| `--batch` | `16` | 批次大小 |
| `--imgsz` | `640` | 输入图片尺寸 |
| `--device` | 自动 | 训练设备 (cpu/0/mps) |
| `--patience` | `20` | 早停耐心值 |
| `--resume` | - | 恢复上次训练 |

## 导出模型

训练完成后可导出为其他格式：

```bash
# ONNX
yolo export model=runs/detect/mahjong/weights/best.pt format=onnx

# TensorRT
yolo export model=runs/detect/mahjong/weights/best.pt format=engine

# CoreML (Apple)
yolo export model=runs/detect/mahjong/weights/best.pt format=coreml
```