This commit is contained in:
Ubuntu
2026-07-03 16:58:28 +08:00
commit 32b43f85bd
6240 changed files with 1987678 additions and 0 deletions
@@ -0,0 +1,335 @@
# C++ 尿检项目 JSON 数据格式识别逻辑分析
> 基于 `/home/ubuntu/nanocode/urinecheck/UrineCheck/` 源码分析
> 分析日期:2026-05-13
---
## 1. 概述
C++ 尿检项目支持两种输入模式:
- **图片模式**:传入试纸图片(JPG/PNG),从图像中定位色块并识别
- **JSON数据模式**:直接传入已提取的色块颜色数据(H,S,V,L,A,B),跳过图像处理直接进行ML推理
本文档专注于 **JSON数据模式** 的完整处理流程。
---
## 2. 入口函数
### 2.1 `ProcessJsonDataRequest` (新版接口,匹配txt文件格式)
**位置**:`urinecheck_class.cpp:2052`
**输入JSON格式**:
```json
{
"extend": {
"color_14i": 2, // 试纸颜色类型(1=绿, 2=红, 3=蓝4联, 5=蓝14联...)
"method": 1, // 1=干化学, 2=胶体金
"type": 2 // 可选,优先级高于color_14i
},
"data": [
[ // 第1帧(多帧采集,通常2-5帧)
{"id": 0, "value": "7.62,146.43,37.76,23.22,135.71,134.46"},
{"id": 1, "value": "24.73,38.34,155.7,159.45,126.1,138.93"},
...
{"id": 13, "value": "36.38,100.93,155.55,157.81,113.17,158.8"}
],
[...] // 第2帧
]
}
```
**value字段含义**:6个逗号分隔的浮点数,对应:
`H, S, V, L, A, B`
| 位置 | 符号 | 含义 | 取值范围 |
|------|------|------|----------|
| 0 | H | HSV 色相 | 0-360(但OpenCV存储为0-180) |
| 1 | S | HSV 饱和度 | 0-255 |
| 2 | V | HSV 明度 | 0-255 |
| 3 | L | LAB 亮度 | 0-255 |
| 4 | A | LAB a通道 | 0-255 |
| 5 | B | LAB b通道 | 0-255 |
> **注意**:txt文件中的value数据已经是 **原始手机端提取的像素颜色值**,与C++图片模式中 `GetHsvLabVs()` 提取的格式一致。这些值在C++中未经白平衡处理就直接送入ML模型。
### 2.2 `analJsonData` (旧版接口)
**位置**:`urinecheck_class.cpp:746`
旧版使用不同的data结构——`data` 是一个对象而非数组:
```json
{
"data": {
"data0": [{"id": 0, "value": "..."}, ...],
"data1": [{"id": 0, "value": "..."}, ...]
}
}
```
旧版的 `id` 直接对应试纸上的物理位置(position),而新版 `id` 就是色块索引。
---
## 3. 完整处理流程
```
ProcessJsonDataRequest(jsonBody)
│
├── 1. 解析JSON
│ └── 提取 data 数组、extend 对象
│
├── 2. 确定试纸类型
│ ├── extend.type 优先
│ ├── extend.color_14i 其次
│ └── paperType = paperType值 (1-20)
│ X = paperType - 1 (用于查表索引)
│
├── 3. 转换项目类型
│ └── projectId = getProjectType(paperType)
│ ├── 1 (绿) → projectType=10
│ ├── 2,5 (红) → projectType=2
│ ├── 3,4 (蓝) → projectType=1
│ └── ...
│
├── 4. 逐帧处理 ────────────────────────────┐
│ for each frame in data: │
│ │ │
│ │ 4a. 解析每帧颜色数据 │
│ │ mapData = { │
│ │ id: [H,S,V,L,A,B] // 6个float │
│ │ } │
│ │ │
│ │ 4b. 调用 ML 推理 │
│ │ frameResult = │
│ │ urineCheck14.Get14Results( │
│ │ mapData, X) │
│ │ │
│ │ 4c. 收集结果 │
│ │ results[position].push_back(idx) │
│ └────────────────────────────────────────┘
│
├── 5. 多帧投票
│ └── lastResult = CountResultsModal(results)
│ 对每个position,取多帧结果中出现次数最多的index
│
├── 6. 关联修正
│ ├── PRO/MAU 修正 (见 §6.2)
│ └── SG/PH 修正 (见 §6.3)
│
├── 7. 索引映射输出
│ ├── itemsStatIds[X][position] → 输出id
│ └── itemsResultIdxMapTbl[X][position][rawIndex] → 输出index
│
└── 8. 构建输出JSON
└── {"score":"100","status":"0","data":[{id, index}, ...]}
```
---
## 4. 核心ML推理:`UrineCheck14::Get14Results(mapData, papertypeIndex)`
**位置**:`UrineCheck14.cpp:1041`
### 4.1 算法流程
```
for each model in rtsArray[papertypeIndex]:
① 从 mapData 取出该 position 的6个颜色值
② 数据不足6个 → 跳过
③ GetModelInstance(papertypeIndex, position) → 获取 RTrees 模型
④ 模型为空 → 跳过
⑤ 构造 float data[6] = {H, S, V, L, A, B}
⑥ p = GetPredictResultVal(data)
└── RTrees::predict(1×6 Mat) → 浮点数预测值
⑦ 获取该 position 对应的结果索引函数
⑧ pi = resultIndexFunc(data, p)
└── 大部分直接 round(p),部分有HSV修正
⑨ results[position] = pi
```
### 4.2 ML模型配置
模型配置从 `/usr/local/Models/ml.json` 加载。
**ml.json 结构**:
```json
{
"ml": [
{
"name": "glu", // 检测项目名
"model": [
{
"positon": 0, // 色块位置(0-based)
"id": 35, // 输出id
"filepath": "/usr/local/Models/glu_0.data",
"algorithm": 0, // 0=Red, 1=Green/Blue
"indexmap": "0,1,2,3,4" // rawIndex → outputIndex映射
},
{
"positon": 3,
"filepath": "/usr/local/Models/glu-rts-M1.data",
...
}
]
},
...
]
}
```
**关键设计**:
- 同一个检测项目(如glu)在不同试纸类型(绿/红/蓝)上可能位于不同 position
- 同一position在不同试纸类型上使用不同的 RTrees 模型文件
- 总共支持 21 种试纸类型(MAX_PAPER_TYPE=21),每种最多15个色块(MAX_PAPER_BLOCK=15)
### 4.3 `GetPredictResultVal`
```cpp
float UrineCheck14::GetPredictResultVal(float* sample) {
cv::Mat sampleMat(1, 6, CV_32FC1, sample);
return rtsPtr->predict(sampleMat); // OpenCV RTrees 预测
}
```
输入:6维特征向量 (H,S,V,L,A,B)
输出:浮点数预测值(代表颜色等级,如 0=阴性, 1=弱阳, 2=中阳...)
---
## 5. 各检测项目的索引修正函数
所有修正函数都先调用 `round(p)` 取四舍五入整数,然后根据 HSV 值进行二次修正。
### 5.1 红色试纸(algorithm=0)修正逻辑
| 项目 | 修正函数 | 修正规则 |
|------|----------|----------|
| **PRO (蛋白质)** | `GetRedProResultIndex` | 若 ret>0 且 (H<25 或 H>110) → 强制返回0 |
| **MA (微量白蛋白)** | `GetRedMauResultIndex` | 若 ret>0 且 (H<30 或 H>115) → 强制返回0 |
| **KET (酮体)** | `GetRedKetResultIndex` | 若 ret>1 且 (45<H<145) → 强制返回0 |
| **NIT (亚硝酸盐)** | `GetRedNitResultIndex` | 若 ret>0 且 (40<H<140) → 强制返回0 |
| **URO (尿胆原)** | `GetRedUroResultIndex` | 若 ret>0 且 (25<H<150) → 强制返回0 |
| **BLD (潜血)** | `GetRedBldResultIndex` | 直接 `round(p)`,无修正 |
| **VC (抗坏血酸)** | `GetRedVcResultIndex` | 直接 `round(p)`,无修正 |
| **BIL (胆红素)** | `GetRedBilResultIndex` | 直接 `round(p)`,无修正 |
| **GLU (葡萄糖)** | `GetRedGluResultIndex` | 直接 `round(p)`,无修正 |
| **CRE (肌酐)** | `GetRedCreResultIndex` | 直接 `round(p)`,无修正 |
| **Ca (尿钙)** | `GetRedUcaResultIndex` | 直接 `round(p)`,无修正 |
| **SG (比重)** | `GetRedSgResultIndex` | 直接 `round(p)`,无修正 |
| **pH** | `GetRedPhResultIndex` | 直接 `round(p)`,无修正 |
| **WBC (白细胞)** | `GetRedWbcResultIndex` | 直接 `round(p)`,无修正 |
### 5.2 绿色/蓝色试纸(algorithm>0)修正逻辑
大部分直接 `round(p)`,无额外修正。
---
## 6. 关联修正规则
### 6.1 配置来源
`positionsPro[X]`、`positionsMau[X]`、`positionsSg[X]`、`positionsPh[X]` 从 `ml.json` 中提取,记录了各试纸类型上 PRO/MAU/SG/pH 对应的色块位置。
### 6.2 PRO(蛋白质)与 MAU(微量白蛋白)关联
```
maxMau = (X > 0) ? 3 : 2 // 红色3级,其他2级
情况1: mauval == 0
→ proVal = 0 // MA阴性时PRO必定阴性
情况2: proVal == 0 且 mauval == maxMau
→ mauval = maxMau - 1 // PRO阴性时MA不能满级
情况3: proVal >= 1
→ mauval = maxMau // PRO阳性时MA设为满级
```
### 6.3 SG(比重)与 pH 关联
```
maxSg = (X > 0) ? 6 : 5 // 红色6级,其他5级
条件: projectType < 20 且 phVal >= 2 且 sgVal < maxSg
→ sgVal += 1 // 在特定pH下上调比重一级
```
---
## 7. 索引映射(indexmap)
### 7.1 映射表结构
`itemsResultIdxMapTbl[MAX_PAPER_TYPE][MAX_PAPER_BLOCK][MAX_ALG_TAG]`
三维查表:`[试纸类型][色块位置][算法原始输出index]` → 最终输出index
### 7.2 indexmap示例
```json
"indexmap": "0,1,2,3,4"
```
含义:算法输出的 index=0 映射为输出0,index=1 映射为输出1...
```json
"indexmap": "5,6,2,3,4"
```
含义:算法输出的 index=0→5, index=1→6, index=2→2...
**用途**:不同试纸类型可能使用不同的等级映射,通过 indexmap 灵活配置。
---
## 8. 输出JSON格式
```json
{
"score": "100",
"status": "0",
"message": "OK",
"imgid": 0,
"project_id": 2,
"paper_id": 2,
"versioninfo": "...",
"data": [
{"id": 35, "index": 1}, // 葡萄糖: 弱阳性
{"id": 36, "index": 0}, // 白细胞: 阴性
{"id": 37, "index": 0}, // 亚硝酸盐: 阴性
...
]
}
```
**data数组**:每个元素包含 `id`(项目ID,如35=GLU)和 `index`(等级,0=阴性)。
---
## 9. 新旧JSON格式差异总结
| 特性 | 旧版 (analJsonData) | 新版 (ProcessJsonDataRequest) |
|------|---------------------|-------------------------------|
| 入口函数 | `analJsonData` | `ProcessJsonDataRequest` |
| data结构 | `{"data0": [...], "data1": [...]}` | `[[...], [...]]` (直接数组) |
| 试纸类型 | 从 `project_id` 或 `extend` 推断 | 从 `extend.type` 或 `extend.color_14i` |
| seekey | `id` 是物理位置 | `id` 是色块索引(0-13) |
| 数据格式 | 整数<br>(如 `"7,146,37,23,135,134"`) | 浮点数<br>(如 `"7.62,146.43,37.76..."`) |
| 对应txt | 不匹配当前txt | **匹配** txt文件格式 |
| pro/mau修正 | 在analJsonData内联 | 在ProcessJsonDataRequest内联 |
---
## 10. 关键文件清单
| 文件 | 功能 |
|------|------|
| `urinecheck_class.cpp:2052-2217` | `ProcessJsonDataRequest` - 新版JSON处理入口 |
| `urinecheck_class.cpp:746-1078` | `analJsonData` - 旧版JSON处理 |
| `urinecheck_class.cpp:54-172` | `initconfig()` - 加载 ml.json 配置 |
| `UrineCheck14.cpp:1041-1104` | `Get14Results(mapData)` - JSON数据的ML推理 |
| `UrineCheck14.cpp:1107-1176` | `Get14Results(mat, pts)` - 图片数据的ML推理 |
| `UrineCheck14.cpp:32-230` | `initconfig()` - 加载模型文件和注册结果函数 |
| `UrineCheck14.cpp:1195-1199` | `GetPredictResultVal` - RTrees预测 |
| `UrineCheck14.cpp:1413-1746` | Red系列结果索引修正函数 |
@@ -0,0 +1,128 @@
# Python后端 JSON数据尿检识别 - 技术实施方案
> 基于 C++ `ProcessJsonDataRequest` 逐行翻译到 Python
> 依赖:`/usr/local/Models/ml.json` + `*.data` (OpenCV RTrees 模型)
---
## 1. 可行性验证
| 检查项 | 状态 |
|--------|------|
| OpenCV 版本 | 4.13.0 ✅ |
| cv2.ml.RTrees_load() 加载 .data 文件 | ✅ uro_0, glu_1, glu-rts-M1 均加载成功 |
| RTrees.predict() 预测 | ✅ `predict(sample)` 返回浮点数 |
| /usr/local/Models/ 所有模型文件存在 | ✅ 14项×2+ (Green+Rts) 全部存在 |
| ml.json 配置完整 | ✅ 包含所有14项×21种试纸类型配置 |
---
## 2. 总体架构
```
POST /api/urinecheck/analyze-json
│
├── 接收 JSON body (与txt文件格式一致)
│
├── MLConfigLoader ─── 解析 /usr/local/Models/ml.json
│ ├── 构建 model_lookup[paperType][position] = (model, indexFunc, indexMap)
│ └── 标注 PRO/MAU/SG/pH 的 position
│
├── UrineJsonRecognizer
│ ├── 1. 解析输入JSON
│ ├── 2. extract paperType from extend
│ ├── 3. 逐帧处理
│ │ └── 每帧: mapData[id→[6 floats]] → ML推理 → {position: rawIndex}
│ ├── 4. CountResultsModal (多帧投票)
│ ├── 5. PRO/MAU + SG/PH 关联修正
│ ├── 6. indexMap 映射
│ └── 7. 构建输出JSON
│
└── 返回 {"score":"100", "status":"0", "data": [{id, index}, ...]}
```
---
## 3. 实施步骤
### Step 1: 新建 `ml_config.py` — ML配置加载器
**功能**:解析 `/usr/local/Models/ml.json`,构建运行时查表结构
```python
class MLConfigLoader:
def load(self):
# 解析 ml.json
# 对每个 item (uro/glu/ket/...):
# 对每个 model entry (positon, id, filepath, algorithm, indexmap):
# paperType = j (model数组中的索引)
# if positon >= 0:
# models[paperType][positon] = RTrees.load(filepath)
# result_funcs[paperType][positon] = indexFuncName
# stat_ids[paperType][positon] = id
# index_maps[paperType][positon] = [int(x) for x in indexmap.split(',')]
# if name == 'pro': positionsPro[paperType] = positon
# ... etc
```
### Step 2: 新建 `json_recognizer.py` — JSON数据识别器
**核心类**:`UrineJsonRecognizer`
```python
class UrineJsonRecognizer:
def recognize(self, json_data: dict) -> dict:
# 完整复制 ProcessJsonDataRequest 逻辑
...
def _get14_results(self, map_data: dict, paper_type: int) -> dict:
# 完整复制 UrineCheck14::Get14Results(mapData, X) 逻辑
...
```
**各检测项的结果索引修正函数**(直接翻译C++):
- `_red_pro_index(p, h)` — if ret>0 and (h<25 or h>110) → 0
- `_red_mau_index(p, h)` — if ret>0 and (h<30 or h>115) → 0
- `_red_ket_index(p, h)` — if ret>1 and 45<h<145 → 0
- `_red_nit_index(p, h)` — if ret>0 and 40<h<140 → 0
- `_red_uro_index(p, h)` — if ret>0 and 25<h<150 → 0
- 其余直接 `round(p)`
### Step 3: 添加 API 路由
在 `routers/urinecheck.py` 中添加:
```python
@router.post("/analyze-json")
async def analyze_json(request: JsonDataRequest, ...):
recognizer = get_recognizer() # 全局单例
return recognizer.recognize(request.model_dump())
```
### Step 4: 在 `schemas.py` 中添加请求模型
### Step 5: 在 `app.py` 中初始化识别器(startup event)
---
## 4. 关键差异注意事项
| C++ | Python |
|-----|--------|
| Json::Value | dict/list |
| map<int, Ptr<RTrees>> | dict[int, cv2.ml.RTrees] |
| `atoi()` string→int | `int()` 或 `float()` |
| `split(s, ',', vs)` | `s.split(',')` |
| `GetModal1()` → 众数 | `collections.Counter.most_common(1)` |
| `GetPredictResultVal(data)` | `model.predict(np.array([data], dtype=np.float32))` |
---
## 5. 文件清单
| 文件 | 操作 | 功能 |
|------|------|------|
| `backend/ml_config.py` | **新建** | ML配置加载器 |
| `backend/json_recognizer.py` | **新建** | JSON数据识别核心逻辑 |
| `backend/schemas.py` | **修改** | 添加 JsonDataRequest |
| `backend/routers/urinecheck.py` | **修改** | 添加 /analyze-json 路由 |
| `backend/app.py` | **修改** | 启动时初始化识别器 |
+459
View File
@@ -0,0 +1,459 @@
# 尿检试纸颜色识别功能 - 改造方案
> 创建时间:2026-05-03
> 基于:urinecheckcpp C++ 代码 (鸿蒙版) → OpenCV Python 重写
> 状态:方案讨论中,待确认后动工
---
## 一、现有 C++ 代码理解
### 1.1 试纸结构
```
┌─────────────────────────────────────────────────────────────────┐
│ 试纸物理结构 │
│ │
│ ┌────────┐ ┌──┐ │
│ │ 大定位块 │ [0][1][2][3][4][5][6][7][8][9][10][11][12][13] │ 小定位块 │
│ │ (10/15mm)│ ←── 14个反应色块 ──→ │ (3mm) │
│ └────────┘ └──┘ │
│ │
│ 定位块颜色: 红/绿/蓝 (两个定位块颜色必须相同) │
│ 大定位块: 10mm×5mm (S型, 宽高比2.0) 或 15mm×5mm (L型, 宽高比3.0) │
│ 小定位块: 3mm×5mm (宽高比≈1.667) │
│ 色块间距: 3.5个单位 (每单位2mm = 7mm间距) │
│ 第一个色块位置: 2.25个单位 (距离小定位块边缘4.5mm) │
└─────────────────────────────────────────────────────────────────┘
```
### 1.2 核心算法流程(7步)
| 步骤 | 名称 | 关键操作 |
|------|------|---------|
| 1 | 图像预处理 | BGR/HSV/Gray转换, 高斯滤波(5×5) |
| 2 | 定位块检测 | HSV颜色分割(红/绿/蓝) → 形态学(CLOSE+OPEN, 9×9核) → 轮廓查找; 备选Canny边缘 |
| 3 | 候选筛选+配对 | 面积/宽高比/矩形度过滤 → Y坐标聚类 → 遍历配对验证(颜色一致+RGB距离<180+面积比±20%+Y差<4倍高度) |
| 4 | 清晰度评估 | Laplacian方差法, 分级: 清晰>300 / 轻微>100 / 严重<100 |
| 5 | 杂物检测 | 试纸高度≥30px, 候选数量≤15 |
| 6 | 规格匹配 | distRatio(定位块距离/试纸高度) + areaRatio → 6种规格之一 |
| 7 | 色块位置计算 | 边缘中心点 + 切片插值(slicesNum=50, firstPos=2.25, step=3.5) → 14个中心点 |
### 1.3 颜色读取
- **白平衡**: 灰度世界算法(各通道均值缩放到相同目标值)
- **采样**: 圆形掩码(半径3px)取均值
- **输出**: RGB + HSV(H:0-360) + LAB(L:0-100, a/b:-128-127)
- **顺序**: 始终从靠近小定位块的色块开始编号(id=0)
---
## 二、改造方案
### 2.1 整体架构
```
┌─────────────────────────────────────────────────────────┐
│ Frontend (React) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 新增页面: /admin/urinecheck │ │
│ │ ├── 图片上传 (拖拽/点击, 支持 jpg/png) │ │
│ │ ├── 上传预览 (显示原图) │ │
│ │ ├── 识别按钮 (调用后端API) │ │
│ │ ├── 标注图展示 (色块中心红圈标记) │ │
│ │ └── 结果输出框 (14项颜色值表格) │ │
│ └─────────────────────────────────────────────────────┘ │
│ ↓ HTTP POST /api/urinecheck │
├─────────────────────────────────────────────────────────┤
│ Backend (FastAPI) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 新增路由: routers/urinecheck.py │ │
│ │ ├── POST /api/urinecheck/analyze │ │
│ │ │ 接收: multipart/form-data (image file) │ │
│ │ │ 返回: JSON { colors, annotated_image_url, ... } │ │
│ │ └── GET /api/urinecheck/result/{id} │ │
│ └─────────────────────────────────────────────────────┘ │
│ ↓ 调用 │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 算法模块: urine_recognizer.py (新建) │ │
│ │ ├── class UrineStripRecognizer │ │
│ │ ├── class ColorReader │ │
│ │ ├── class PaperConfig │ │
│ │ └── 全局参数常量 │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
### 2.2 文件清单
```
personal-blog/
├── backend/
│ ├── routers/
│ │ └── urinecheck.py # 新增: API路由
│ ├── urine_recognizer.py # 新增: 核心识别算法 (Python重写)
│ ├── app.py # 修改: 注册新路由
│ └── requirements.txt # 已满足: opencv-python已安装
├── frontend/src/
│ ├── pages/admin/
│ │ └── UrineCheck.jsx # 新增: 尿检识别页面
│ ├── components-preline/
│ │ └── Sidebar.jsx # 修改: 添加导航项
│ ├── App.jsx # 修改: 添加路由
│ └── api/
│ └── urinecheck.js # 新增: API调用封装
└── docs/
└── urinecheck-plan.md # 本文件
```
### 2.3 Python 重写的关键数据结构
```python
from dataclasses import dataclass, field
from enum import Enum
import cv2
import numpy as np
class LocatorColor(Enum):
UNKNOWN = 0
RED = 1
GREEN = 2
BLUE = 3
class BigLocatorType(Enum):
SHORT = 0 # 10mm
LONG = 1 # 15mm
class PaperSpatialType(Enum):
UNKNOWN = 0
PST_14_S = 1
PST_14_L = 2
PST_11_S = 3
PST_11_L = 4
PST_8_S = 5
PST_8_L = 6
@dataclass
class LocatorInfo:
rotated_rect: cv2.RotatedRect = None
center: tuple = (0, 0)
area: float = 0
width: float = 0
height: float = 0
color: LocatorColor = LocatorColor.UNKNOWN
is_big: bool = False
avg_color: tuple = (0, 0, 0)
@dataclass
class ColorResult:
id: int = 0
r: float = 0; g: float = 0; b: float = 0
h: float = 0; s: float = 0; v: float = 0
l: float = 0; a: float = 0; b_val: float = 0 # LAB
@dataclass
class RecognitionResult:
success: bool = False
error_code: int = -1
error_message: str = ""
paper_type: PaperSpatialType = PaperSpatialType.UNKNOWN
locator_color: LocatorColor = LocatorColor.UNKNOWN
item_count: int = 0
color_blocks: list = field(default_factory=list) # list of ColorResult
annotated_image: np.ndarray = None # 标注图 (BGR)
blur_level: int = 0 # 0=清晰, 1=轻微, 2=严重
blur_score: float = 0
```
### 2.4 全局参数 (直接平移 C++ GlobalParams)
```python
# 颜色误差
COLOR_DISTANCE_THRESHOLD = 180.0
# 面积/距离/角度误差
AREA_ERROR_RATIO = 0.20
DISTANCE_ERROR_RATIO = 0.20
ANGLE_ERROR_DEGREE = 15.0
# 定位块宽高比
BIG_LOCATOR_RATIO_SHORT = 2.0 # 10mm: 10/5
BIG_LOCATOR_RATIO_LONG = 3.0 # 15mm: 15/5
SMALL_LOCATOR_RATIO = 1.667 # 5/3
# 面积比
AREA_RATIO_SHORT = 3.33 # 10/3
AREA_RATIO_LONG = 5.0 # 15/3
# 采样
MIN_SAMPLE_PIXELS = 25
DEFAULT_SAMPLE_RADIUS = 3
# 轮廓过滤
MIN_CONTOUR_AREA = 100.0
MAX_AREA_RATIO = 0.3
MIN_RECTANGULARITY = 0.70
# 定位块面积限制
MIN_SMALL_LOCATOR_AREA = 100.0
MAX_SMALL_LOCATOR_AREA = 8000.0
MIN_BIG_LOCATOR_AREA = 200.0
MAX_BIG_LOCATOR_AREA = 15000.0
```
### 2.5 试纸配置 (14联S型/L型)
```python
PAPER_CONFIGS = {
PaperSpatialType.PST_14_S: {
"items_num": 14, "slices_num": 50,
"first_pos": 2.25, "step": 3.5, "dist_times": 21.3,
"wh_big_ratio": 2.0
},
PaperSpatialType.PST_14_L: {
"items_num": 14, "slices_num": 50,
"first_pos": 2.25, "step": 3.5, "dist_times": 21.8,
"wh_big_ratio": 3.0
},
}
```
### 2.6 API 设计
**POST /api/urinecheck/analyze**
请求:
```
multipart/form-data
- file: 试纸图片 (jpg/png)
```
成功响应 (200):
```json
{
"success": true,
"paper_type": "PST_14_S",
"locator_color": "RED",
"item_count": 14,
"blur_level": 0,
"blur_score": 450.5,
"colors": [
{
"id": 0,
"rgb": {"r": 200, "g": 180, "b": 150},
"hsv": {"h": 36.0, "s": 64.0, "v": 200.0},
"lab": {"l": 75.0, "a": 5.0, "b": 18.0}
},
// ... 共14项
],
"annotated_image_url": "/uploads/urinecheck/annotated_xxx.jpg"
}
```
失败响应:
```json
{
"success": false,
"error_code": 2,
"error_message": "No valid locator pair found"
}
```
**GET /api/urinecheck/result/{filename}** — 获取标注图
### 2.7 错误码体系 (与C++一致)
| 错误码 | 含义 |
|--------|------|
| 0 | 成功 |
| 1 | 未找到轮廓/候选不足 |
| 2 | 未找到有效定位块配对 |
| 3 | 定位块颜色不一致/未知 |
| 4 | 试纸规格未匹配 |
| 5 | 色块位置计算失败 |
| 6 | 检测到多条试纸 |
| 7 | 输入图像为空 |
| 9 | 试纸过小(杂物) |
| 10 | 场景过于杂乱 |
---
## 三、实施步骤
### 第1步: 编写 Python 核心算法模块
**文件**: `backend/urine_recognizer.py`
完整平移 C++ `PaperRecognizer` + `ColorReader` + `PaperConfig` 逻辑:
1. `class GlobalParams` — 所有常量
2. `class PaperConfig` — 试纸配置字典
3. `class ColorReader` — 白平衡 + 圆形采样 + HSV/LAB转换
4. `class UrineStripRecognizer` — 核心7步流程:
- `preprocess_image()`
- `detect_locators()` — 包括 HSV分割、轮廓查找、备选Canny
- `filter_locator_candidates()` — 多级过滤 + Y聚类 + 配对验证
- `match_paper_spec()` — distRatio/areaRatio 匹配
- `calculate_color_block_centers()` — 边缘中心 + 切片插值
- `draw_annotations()` — 色块红圈标记
- `recognize()` — 主入口
**注意事项**:
- Python OpenCV 中 `cv2.findContours` 返回2个值(OpenCV 4.x),与C++ 不同
- 颜色空间: C++ BGR ↔ Python BGR 一致,无需转换
- 旋转矩形的 `.points()` / `.boundingRect()` 函数签名略有不同
- 移除所有鸿蒙日志宏(PR_LOG_*),改用 Python `logging` 模块
- 移除 `getPaperImg()` / `savePaperImg()` — 博客项目不需要RGBA格式
### 第2步: 编写后端 API 路由
**文件**: `backend/routers/urinecheck.py`
- `POST /api/urinecheck/analyze`
- 接收上传的图片文件
- 保存到 `/tmp/urinecheck_<uuid>.jpg` (方便清理)
- 调用 `UrineStripRecognizer.recognize()`
- 如果成功,保存标注图到 `backend/uploads/urinecheck/`
- 返回 JSON 结果
- `GET /api/urinecheck/result/{filename}` — 静态文件服务(标注图)
### 第3步: 注册路由
**修改** `backend/app.py`:
```python
from routers import urinecheck
app.include_router(urinecheck.router)
```
### 第4步: 编写前端页面
**文件**: `frontend/src/pages/admin/UrineCheck.jsx`
UI布局 (Preline风格,参考Images.jsx):
```
┌──────────────────────────────────────────────┐
│ 尿检识别 │
│ 上传尿常规试纸图片,自动识别14项颜色值 │
├──────────────────┬───────────────────────────┤
│ 上传区域 │ 结果输出区 │
│ ┌─────────────┐ │ ┌─────────────────────┐ │
│ │ 📤 拖拽或点击 │ │ │ 定位块颜色: RED │ │
│ │ 上传试纸图片 │ │ │ 试纸规格: 14联S型 │ │
│ │ jpg/png │ │ │ 清晰度: 清晰 (450) │ │
│ └─────────────┘ │ ├─────────────────────┤ │
│ │ │ # | RGB | HSV │ │
│ ┌─────────────┐ │ │ 0 | 200,180,150 | ... │ │
│ │ [预览图] │ │ │ 1 | ... │ │
│ │ │ │ │ ... │ │
│ │ │ │ │ 13| ... │ │
│ └─────────────┘ │ └─────────────────────┘ │
├──────────────────┴───────────────────────────┤
│ 标注图展示区 (色块中心红圈标记) │
│ ┌─────────────────────────────────────────┐ │
│ │ [标注后的试纸大图] │ │
│ └─────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘
```
功能交互:
1. 用户上传图片 (拖拽或点击)
2. 图片立即显示预览(本地预览,无需等待)
3. 用户点击"开始识别"按钮
4. 前端调用 `POST /api/urinecheck/analyze`
5. 结果显示在右侧:
- 基本信息(定位块颜色、试纸类型、清晰度)
- 14项颜色值表格(RGB + HSV + LAB)
- 标注图展示
### 第5步: 修改导航
**文件**: `frontend/src/components-preline/Sidebar.jsx` — 在 `navItems` 中添加:
```javascript
{ path: '/admin/urinecheck', label: '尿检识别', icon: TestTubeIcon },
```
### 第6步: 修改路由
**文件**: `frontend/src/App.jsx` — 添加:
```jsx
import { UrineCheck } from './pages/admin/UrineCheck'
// ...
<Route path="/admin/urinecheck" element={<PrivateRoute><UrineCheck /></PrivateRoute>} />
```
### 第7步: 测试验证
使用 `urinecheckcpp/images/` 下的测试图片验证:
```bash
curl -X POST http://localhost:8889/api/urinecheck/analyze \
-F "file=@test1.png"
```
验证:
- 定位块正确识别
- 色块数量 = 14
- 颜色值合理 (RGB在0-255范围)
- 标注图生成正确
---
## 四、已确认的决定
1. ✅ **全部6种规格都支持** — 8联(S/L)、11联(S/L)、14联(S/L)
2. ✅ **输出中添加检测项目名称** — 14/11/8项都有对应的中文名称
3. ✅ **不需要标注图** — 只需颜色数据,移除 `draw_annotations()`
4. ✅ **不存数据库** — 每次临时识别,不上传文件到 uploads 目录
5. ✅ **上传图片存 /tmp** — 使用 `tempfile` 自动清理
6. ✅ **前端 Preline UI 风格** — 与现有管理后台一致
---
## 五、检测项目名称映射
### 14联 (id=0 靠近小定位块)
| id | 项目 | id | 项目 |
|----|------|----|------|
| 0 | 微量白蛋白(MA) | 7 | 比重(SG) |
| 1 | 钙(Ca) | 8 | 潜血(BLD) |
| 2 | 肌酐(CRE) | 9 | pH |
| 3 | 抗坏血酸(VC) | 10 | 蛋白质(PRO) |
| 4 | 葡萄糖(GLU) | 11 | 尿胆原(URO) |
| 5 | 胆红素(BIL) | 12 | 亚硝酸盐(NIT) |
| 6 | 酮体(KET) | 13 | 白细胞(LEU) |
### 11联
| id | 项目 | id | 项目 |
|----|------|----|------|
| 0 | 抗坏血酸(VC) | 6 | pH |
| 1 | 葡萄糖(GLU) | 7 | 蛋白质(PRO) |
| 2 | 胆红素(BIL) | 8 | 尿胆原(URO) |
| 3 | 酮体(KET) | 9 | 亚硝酸盐(NIT) |
| 4 | 比重(SG) | 10 | 白细胞(LEU) |
| 5 | 潜血(BLD) | | |
### 8联
| id | 项目 | id | 项目 |
|----|------|----|------|
| 0 | 葡萄糖(GLU) | 4 | 潜血(BLD) |
| 1 | 胆红素(BIL) | 5 | pH |
| 2 | 酮体(KET) | 6 | 蛋白质(PRO) |
| 3 | 比重(SG) | 7 | 白细胞(LEU) |
> ⚠️ 注意:项目名称根据常见尿试纸排列推定,不同品牌/批次可能顺序不同。
> 建议对照实际试纸包装确认顺序。代码中的映射在 `urine_recognizer.py` 的 `ITEM_NAMES_*` 中定义。
---
## 六、技术风险与注意事项
| OpenCV 版本差异 | Python OpenCV API与C++有细微差异 | 已在代码审查中标注关键差异点 |
| 颜色分割阈值 | 不同光照下HSV阈值需要微调 | 直接复用C++验证过的阈值 |
| 性能 | Python可能比C++慢 | 单张图片秒级处理,可接受 |
| 图片格式 | 用户可能上传超大图片 | 限制最大10MB,压缩到合理尺寸 |
| systemd 写入限制 | 如遇ReadWritePaths限制 | 确保 /tmp 和 backend/uploads/ 可写 |
---
**请蔡叔叔审阅以上方案,确认后我开始写代码。有问题随时指出。**