# coffee-bean-analyzer

**Repository Path**: Eric1689/coffee-bean-analyzer

## Basic Information

- **Project Name**: coffee-bean-analyzer
- **Description**: 基于深度学习的咖啡豆烘焙程度智能识别系统研究
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-07
- **Last Updated**: 2026-07-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ☕ Coffee Bean Analyzer (YOLO11 Edition)

> 基于深度学习的咖啡豆烘焙程度智能识别系统
>
> **引擎升级**: ResNet18 CNN -> **Ultralytics YOLO11** (最新版)

## ✨ 新版本特性

| 功能 | v1.0 (旧版) | **v2.0 (YOLO11)** |
|------|------------|-------------------|
| 目标定位 | OpenCV 传统图像处理 | **YOLO11 目标检测** |
| 分类模型 | 自定义 ResNet18 | **YOLO11 预训练模型** |
| 批量检测 | 不支持 | **支持多豆同时检测** |
| 推理速度 | ~200ms/张 | **~30ms/张 (GPU)** |
| 准确率 | 依赖训练数据 | **迁移学习 + 预训练权重** |

## 🚀 快速开始

### 方式一：一键启动

**Windows:**
```bash
start.bat
```

**Linux/Mac:**
```bash
chmod +x start.sh
./start.sh
```

### 方式二：手动启动

```bash
# 1. 进入后端目录
cd backend

# 2. 安装依赖
pip install -r requirements.txt

# 3. 启动服务
python app.py
```

服务地址: `http://localhost:5000`

## 📡 API 接口

### 基础信息
- `GET /` - 服务状态和可用接口
- `GET /api/info` - 模型信息、支持的类别和特征

### 核心接口

#### 1. 完整分析 (推荐)
```
POST /api/analyze
Content-Type: application/json

{
    "image": "data:image/jpeg;base64,...",
    "confidence": 0.25,      // 可选，检测置信度阈值
    "iou_threshold": 0.45     // 可选，NMS IoU阈值
}
```
**返回**: 检测到的所有咖啡豆的详细分析（烘焙程度、特征、质量评分）

#### 2. 单豆分析 (快速)
```
POST /api/analyze-single
Content-Type: application/json

{
    "image": "data:image/jpeg;base64,..."
}
```
**用途**: 已裁剪好的单个咖啡豆图像，跳过检测步骤

#### 3. 仅检测位置
```
POST /api/detect
Content-Type: application/json

{
    "image": "data:image/jpeg;base64,..."
}
```
**返回**: 咖啡豆边界框坐标和置信度（不执行分类）

#### 4. 重新训练
```
POST /api/retrain
Content-Type: application/json

{
    "task": "all",           // 'detection' | 'classification' | 'all'
    "epochs": 50
}
```

## 🔧 训练自定义模型

### 准备数据集

将咖啡豆图片按类别放入对应目录：
```
backend/sample_images/
├── light_roast/      # 浅烘咖啡豆图片
├── medium_roast/     # 中烘咖啡豆图片  
├── dark_roast/       # 深烘咖啡豆图片
└── defective/        # 缺陷豆图片
```

### 执行训练

```bash
cd backend

# 仅准备 YOLO 格式数据集
python train_yolo.py --prepare-only --task all

# 训练检测模型
python train_yolo.py --task detection --epochs 100 --det-size n

# 训练分类模型
python train_yolo.py --task classification --epochs 50 --cls-size s

# 同时训练两个模型
python train_yolo.py --task all --epochs 50 --validate
```

### 模型大小选项

| 大小 | 参数量 | 速度 (GPU) | 适用场景 |
|------|--------|------------|----------|
| `n` (nano) | 2.6M | 最快 | 实时应用、边缘设备 |
| `s` (small) | 9.4M | 快 | 平衡性能 |
| `m` (medium) | 20.1M | 中等 | 高精度需求 |
| `l` (large) | 25.3M | 较慢 | 研究用途 |
| `x` (xlarge) | 43.7M | 最慢 | 最高精度 |

## 📊 支持的识别功能

### 烘焙程度分类
| 类别 | 说明 |
|------|------|
| 浅烘 | 颜色较浅，酸度明显，保留原豆风味 |
| 中烘 | 颜色中等，酸苦平衡，最常见 |
| 深烘 | 颜色深黑，苦味明显，表面油亮 |
| 缺陷豆 | 存在裂纹、颜色不均等缺陷 |

### 特征检测 (8项)
- 表面油亮 / 皱褶 / 裂纹 / 颜色不均
- 颜色过浅 / 颜色过深 / 光泽度 / 表面平滑

### 质量评分
- 评分范围: 0-100
- 等级: 特级 / 一级 / 二级 / 三级 / 等外

## 🏗️ 项目结构

```
backend/
├── app.py              # Flask API 主程序 (v2.0 YOLO)
├── yolo_detector.py    # YOLO11 检测器 & 分类器核心
├── train_yolo.py       # 模型训练脚本
├── dataset_utils.py    # 数据集工具 (兼容旧版)
├── model.py            # 旧版模型定义 (已弃用)
├── requirements.txt    # Python 依赖
├── sample_images/      # 样本图像目录
│   ├── light_roast/
│   ├── medium_roast/
│   ├── dark_roast/
│   └── defective/
├── models/             # 训练好的模型文件
├── datasets/           # YOLO 格式数据集 (自动生成)
└── runs/               # 训练日志和输出
```

## ⚙️ 技术栈

- **目标检测**: Ultralytics [YOLO11](https://docs.ultralytics.com/)
- **图像分类**: YOLO11-cls
- **Web框架**: Flask 3.0 + CORS
- **深度学习**: PyTorch 2.x
- **图像处理**: OpenCV + Pillow

## 🔄 从 v1.0 迁移

如果你有旧版的训练数据或模型：

1. **数据集**: 兼容原有的 `sample_images/` 目录结构
2. **API**: 保持相同的 `/api/analyze` 接口格式（增强）
3. **新功能**:
   - 支持多豆批量分析 (`/api/detect`)
   - 单豆快速模式 (`/api/analyze-single`)
   - 自动生成带标注的可视化结果

## 📝 开发计划

- [ ] 添加视频流实时检测支持
- [ ] Web UI 前端界面
- [ ] 移动端适配 API
- [ ] 导出分析报告 (PDF)
- [ ] 多语言支持

## 📄 License

MIT License