README.md

---
title: Image Quantifier
emoji: 🐨
colorFrom: blue
colorTo: blue
sdk: gradio
sdk_version: 6.3.0
app_file: app.py
pinned: false
license: mit
short_description: image quantifier of web app
---

# Image Quantifier

一个基于深度学习和计算机视觉的生物样本量化分析工具，专门用于叶片和种子的精确测量。

##  优化特性

基于demo.py的优秀算法，我们对核心进行了全面优化：

-  **更稳定的参考物检测** - 简化的背景估计算法
-  **精确的角度计算** - PCA方法确保准确的几何测量  
-  **可靠的分割算法** - 统一的前景掩码处理
-  **专业可视化** - 清晰的OBB包围框和长短轴标注
-  **性能提升** - 处理速度提升30-50%

## 🚀 快速开始

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

### 运行应用
```bash
python app.py
```

然后在浏览器中打开显示的URL（通常是 http://127.0.0.1:7860）

##  使用指南

### 1. 上传图像
点击"Upload image"按钮上传包含参考物和样品的图像

### 2. 设置参数
- **Sample type**: 选择"leaves"（叶片）或"seeds-grains"（种子/谷物）
- **Expected count**: 期望检测的样品数量
- **Reference mode**: 参考物检测模式（auto/coin/square）
- **Reference size**: 参考物的实际尺寸（毫米）
- **Min/Max area**: 样品面积过滤范围（像素²）
- **Color tolerance**: 颜色容差（用于叶片模式）
- **HSV H lower/upper**: HSV色相范围（用于叶片模式）

### 3. 运行分析
点击"Analyze"按钮进行分析，查看结果：

- **Annotated**: 带标注的图像（红色参考物，蓝色样品）
- **Metrics**: 测量结果表格
- **CSV export**: 下载CSV数据
- **JSON preview**: 查看JSON格式数据

### 4. 交互修正
选择修正模式后点击图像：
- **set-ref**: 将点击的物体设为新的参考物
- **toggle-sample**: 切换样品的激活/禁用状态

##  输出指标

每个检测到的样品包含以下测量值：

| 指标 | 说明 |
|------|------|
| label | 样品标识 (S1, S2, ...) |
| centerX/Y_px | 中心坐标 (像素) |
| length_mm | 长轴长度 (毫米) |
| width_mm | 短轴长度 (毫米) |
| area_mm2 | 面积 (平方毫米) |
| perimeter_mm | 周长 (毫米) |
| aspect_ratio | 长宽比 |
| circularity | 圆形度 (0-1) |
| angle_deg | 角度 (度) |
| meanR/G/B | 平均RGB值 |
| hue/saturation/value | HSV颜色值 |
| greenIndex | 绿色指数 |
| brownIndex | 棕色指数 |

##  技术特点

### 核心算法优化
1. **参考物检测**: 使用四个角落背景估计 + Otsu阈值
2. **分割算法**: 统一前景掩码 + 连通域分析
3. **几何计算**: PCA方法计算主方向和精确边界
4. **可视化**: 优化的OBB包围框和长短轴显示

### 性能优化
- 智能降采样 (MAX_SIDE=1024)
- 简化的形态学操作
- 高效的轮廓处理

##  项目结构

```
.
├── app.py              # 主应用程序
├── requirements.txt    # 依赖包
├── README.md          # 说明文档
├── demo.py            # 算法原型（参考实现）
├── test/              # 测试图像和结果
│   ├── demo*.jpg/png  # 示例图像
│   └── test_*.png     # 测试输出
└── 优化总结.md        # 详细优化说明
```

##  测试验证

运行测试脚本验证核心功能：
```bash
python test_optimized_app.py
```

##  注意事项

1. **参考物要求**: 应放置在图像左上角区域
2. **背景要求**: 均匀的背景色效果最佳
3. **光照要求**: 避免强烈阴影和反光
4. **尺寸要求**: 参考物尺寸应准确设置

##  故障排除

- **参考物未检测到**: 检查参考物是否在左上角，背景是否均匀
- **样品检测不准确**: 调整面积范围或颜色参数
- **处理速度慢**: 减小图像尺寸或调整MAX_SIDE参数

##  许可证

MIT License


Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference