Files
nanocode/web-opencv/cpp/docs/详细设计文档.md
T
Ubuntu 32b43f85bd a
2026-07-03 16:58:28 +08:00

749 lines
26 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 尿检试纸识别系统 - 详细设计文档
> 文档创建时间:2026-03-30
> 最后更新:2026-04-03
> 版本:v1.1
> 适用范围:PaperRecognizer、ColorReader、PaperConfig、NAPI接口
---
## 一、系统概述
### 1.1 功能描述
尿检试纸识别系统用于从拍摄的试纸图片中自动识别:
1. **定位块**:试纸两端的红色/绿色/蓝色定位块
2. **试纸规格**:根据定位块特征判断8/11/14联及S/L型
3. **反应色块位置**:计算每个反应色块的精确中心坐标
4. **颜色数据**:读取每个反应色块的HSV+LAB颜色值
### 1.2 设计原则
- **模块化**:识别器、颜色读取器、配置管理器独立设计
- **鲁棒性**:多级过滤、多重验证、容错处理
- **可维护性**:清晰的代码结构、详细的注释
- **可扩展性**:支持新增试纸规格
### 1.3 支持的试纸规格
| 类型 | 联数 | 大定位块 | 面积比 | 距离比范围 |
|------|------|----------|--------|-----------|
| PST_14_S | 14 | 10mm | ~3.33 | 19.5-23.5 |
| PST_14_L | 14 | 15mm | ~5.0 | 20.0-24.0 |
| PST_11_S | 11 | 10mm | ~3.33 | 15.9-19.2 |
| PST_11_L | 11 | 15mm | ~5.0 | 16.2-19.6 |
| PST_8_S | 8 | 10mm | ~3.33 | 11.6-14.1 |
| PST_8_L | 8 | 15mm | ~5.0 | 12.0-14.6 |
---
## 二、核心模块设计
### 2.1 PaperRecognizer(试纸识别器)
#### 2.1.1 类图
```
┌─────────────────────────────────────────────────────┐
│ PaperRecognizer │
├─────────────────────────────────────────────────────┤
│ - originalImage_: cv::Mat // 原图 │
│ - processImage_: cv::Mat // 处理用图像 │
│ - hsvImage_: cv::Mat // HSV图像 │
│ - grayImage_: cv::Mat // 灰度图像 │
│ - locator1_: LocatorInfo // 定位块1 │
│ - locator2_: LocatorInfo // 定位块2 │
│ - bigLocator_: LocatorInfo* // 大定位块指针 │
│ - smallLocator_: LocatorInfo* // 小定位块指针 │
│ - centers_: vector<Point2f> // 色块中心点 │
│ - config_: PaperConfig* // 匹配的配置 │
│ - result_: RecognitionResult // 识别结果 │
│ - paperImg_: cv::Mat // 裁剪的试纸图 │
│ - candidateCount_: size_t // 候选数量(新增) │
├─────────────────────────────────────────────────────┤
│ + recognize(image): RecognitionResult │
│ + getPaperImg(): cv::Mat │
├─────────────────────────────────────────────────────┤
│ - preprocessImage(image) │
│ - detectLocators(): bool │
│ - filterLocatorCandidates(contours): bool │
│ - validateLocatorPair(): bool │
│ - groupCandidatesByY(candidates): vector<vector<*>> │
│ - findValidLocatorPairInGroup(group): LocatorPair │
│ - determineLocatorColorByCenter(rect): LocatorColor │
│ - matchPaperSpec(): bool │
│ - calculateColorBlockCenters() │
│ - drawAnnotations() │
│ - savePaperImg() │
│ - assessLocatorBlur(gray, locator, score): BlurLevel│ // 清晰度评估(新增)
└─────────────────────────────────────────────────────┘
```
#### 2.1.2 主流程
```cpp
RecognitionResult PaperRecognizer::recognize(const cv::Mat& image) {
// Step 1: 图像预处理
preprocessImage(image);
// Step 2: 定位块检测(包含多试纸处理)
if (!detectLocators()) {
return result_; // 返回错误
}
// Step 3: 颜色判断(在 validateLocatorPair 中完成)
// Step 3.5: 清晰度评估(新增)
double bigScore, smallScore;
BlurLevel bigBlur = assessLocatorBlur(grayImage_, bigLocator_->rotatedRect, bigScore);
BlurLevel smallBlur = assessLocatorBlur(grayImage_, smallLocator_->rotatedRect, smallScore);
result_.blurLevel = max(bigBlur, smallBlur);
result_.blurScore = min(bigScore, smallScore);
// Step 3.6: 杂物检测(新增)
if (bigLocator_->height < 30.0) { // 试纸高度太小
result_.errorCode = 9;
return result_;
}
if (candidateCount_ > 15) { // 候选太多,场景杂乱
result_.errorCode = 10;
return result_;
}
// Step 4: 规格匹配
if (!matchPaperSpec()) {
return result_;
}
// Step 5: 计算色块中心点
calculateColorBlockCenters();
// Step 6: 绘制标注
drawAnnotations();
// Step 7: 保存试纸图片(NAPI用)
savePaperImg();
result_.success = true;
return result_;
}
```
#### 2.1.3 定位块检测流程
```
输入: 原图
输出: 两个定位块信息 (bigLocator_, smallLocator_)
1. 图像预处理
- 颜色空间转换: BGR -> HSV, GRAY
- 高斯滤波: 5x5 核
2. 轮廓检测
- 二值化: THRESH_OTSU
- findContours: RETR_EXTERNAL
3. 候选过滤
for each contour:
- 面积过滤: 100 < area < 10000
- 正方形过滤: aspectRatio 不在 [0.9, 1.1]
- 宽高比过滤:
- 大定位块: 2.0 ± 0.5 或 3.0 ± 0.5
- 小定位块: 1.667 ± 0.5
- 计算颜色(延迟到最后)
4. Y坐标聚类(多试纸处理)
- 按 Y坐标排序候选
- 相邻候选 Y差 < 3*平均高度 -> 同组
- 得到多个组
5. 组内配对验证
for each group:
- 找一大一小配对
- 验证面积比: ~3.33 或 ~5.0
- 验证颜色一致: RGB欧式距离 < 阈值
- 验证 Y坐标相近: 差 < 阈值
6. 结果判定
- validPairs.size() == 1: 成功
- validPairs.size() > 1: errorCode = 6 (多条试纸)
- validPairs.size() == 0: errorCode = 1 (未检测到)
```
#### 2.1.4 定位块颜色判断
```cpp
LocatorColor PaperRecognizer::determineLocatorColorByCenter(
const cv::RotatedRect& rotatedRect) {
// 获取旋转矩形中心30%区域的颜色
cv::Scalar avgColor = getCenterRegionColor(rotatedRect);
double r = avgColor[2];
double g = avgColor[1];
double b = avgColor[0];
// RGB 主判断
double maxChannel = std::max({r, g, b});
// 红色: R最大且优势明显
if (r == maxChannel && r > g + 20 && r > b + 20) {
return LocatorColor::RED;
}
// 绿色: G最大
if (g == maxChannel && g > r + 10 && g > b + 10) {
return LocatorColor::GREEN;
}
// 蓝色: B最大且优势明显(降低阈值处理深蓝)
if (b == maxChannel && b > r + 15 && b > g + 15) {
return LocatorColor::BLUE;
}
// HSV 辅助判断
// ... 省略 HSV 计算细节
return LocatorColor::UNKNOWN;
}
```
#### 2.1.5 色块位置计算
**核心原则:`centers_[0]` 始终靠近小定位块**
```cpp
void PaperRecognizer::calculateColorBlockCenters() {
// 判断小定位块位置
result_.smallLocatorOnLeft = !locator1_.isBig;
// 计算定位块边缘中心点
cv::Point2f bigEdgeCenter, smallEdgeCenter;
// 情况1: 小定位块在左边
if (result_.smallLocatorOnLeft) {
// 方向向量: 从小指向大
double dx = bigLocator_->center.x - smallLocator_->center.x;
double dy = bigLocator_->center.y - smallLocator_->center.y;
// ...
// smallEdgeCenter = 小定位块右边缘中心
// bigEdgeCenter = 大定位块左边缘中心
}
// 情况2: 小定位块在右边
else {
// 方向向量: 仍然从小指向大(反向计算)
double dx = bigLocator_->center.x - smallLocator_->center.x;
double dy = bigLocator_->center.y - smallLocator_->center.y;
// ...
// smallEdgeCenter = 小定位块左边缘中心
// bigEdgeCenter = 大定位块右边缘中心
}
// 计算步长
double effectiveDist = distance(bigEdgeCenter, smallEdgeCenter);
double avgDist = effectiveDist / config_->slicesNum;
double firstOffset = avgDist * config_->firstPos;
double stepOffset = avgDist * config_->step;
// 始终从小定位块边缘开始计算
for (int i = 0; i < config_->itemsNum; ++i) {
double offset = firstOffset + stepOffset * i;
cv::Point2f center = smallEdgeCenter + offset * unitVector;
centers_.push_back(center);
}
// 结果: centers_[0] 靠近小定位块
}
```
### 2.2 ColorReader(颜色读取器)
#### 2.2.1 类设计
```cpp
class ColorReader {
public:
// 读取颜色(可选择是否应用白平衡)
std::vector<ColorResult> readColors(
const cv::Mat& image,
const std::vector<cv::Point2f>& centers,
bool smallLocatorOnLeft,
bool applyWB = true // 白平衡开关
);
private:
// 白平衡处理(灰度世界算法)
void applyWhiteBalance(cv::Mat& image);
// 计算自适应ROI大小
int calculateAdaptiveROI(double locatorHeight);
// 采样颜色
cv::Scalar sampleColor(const cv::Mat& image,
const cv::Point2f& center,
int roiSize);
};
```
#### 2.2.2 白平衡算法
```cpp
void ColorReader::applyWhiteBalance(cv::Mat& image) {
// 灰度世界算法
cv::Scalar avgScalar = cv::mean(image);
double avgGray = (avgScalar[0] + avgScalar[1] + avgScalar[2]) / 3.0;
std::vector<cv::Mat> channels;
cv::split(image, channels);
// 各通道缩放
for (int i = 0; i < 3; ++i) {
double scale = avgGray / avgScalar[i];
channels[i] = channels[i] * scale;
}
cv::merge(channels, image);
image.convertTo(image, CV_8UC3);
}
```
#### 2.2.3 自适应ROI
```cpp
// ROI大小: 定位块高度的0.6倍
// 范围限制: 5x5 到 15x15 像素
int calculateAdaptiveROI(double locatorHeight) {
int halfSize = static_cast<int>(locatorHeight * 0.6);
halfSize = std::max(5, std::min(15, halfSize));
return halfSize * 2 + 1; // 11, 13, ..., 31
}
```
### 2.3 PaperConfig(试纸配置)
#### 2.3.1 配置参数
```cpp
struct PaperConfig {
PaperSpatialType type; // 试纸类型
BlockItems blockItems; // 联数
BigLocatorType locatorType; // 大定位块类型
int itemsNum; // 反应色块数量
int slicesNum; // 最小分割单位数量
double firstPos; // 第一个色块位置倍数
double step; // 步长倍数
};
```
#### 2.3.2 规格匹配
```cpp
PaperSpatialType PaperConfigManager::matchConfig(
double distRatio, double areaRatio) const {
// distRatio = 定位块中心距离 / 试纸高度
// areaRatio = 大定位块面积 / 小定位块面积
// S型 (10mm大定位块, areaRatio < 4.0)
if (areaRatio < 4.0) {
if (distRatio > 19.5 && distRatio < 23.5) return PST_14_S;
if (distRatio > 15.9 && distRatio < 19.2) return PST_11_S;
if (distRatio > 11.6 && distRatio < 14.1) return PST_8_S;
}
// L型 (15mm大定位块, areaRatio >= 4.0)
else {
if (distRatio > 20.0 && distRatio < 24.0) return PST_14_L;
if (distRatio > 16.2 && distRatio < 19.6) return PST_11_L;
if (distRatio > 12.0 && distRatio < 14.6) return PST_8_L;
}
return PST_UNKNOWN;
}
```
---
## 三、NAPI 接口设计
### 3.1 接口列表
| 函数名 | 功能 | 输入 | 输出 |
|--------|------|------|------|
| sayHello | 试纸识别 | ArrayBuffer(YUV), width, height, format | Object |
| getPaperData | 获取裁剪试纸图 | 无 | Object |
| add | 测试用 | num1, num2 | sum |
| analysisImage | 测试用 | PixelMap | PixelMap |
### 3.2 sayHello 详细设计
#### 3.2.1 输入参数
```javascript
// ArkTS 调用示例
let result = nativeModule.sayHello(
yuvBuffer, // ArrayBuffer: NV21格式的YUV数据
width, // number: 图像宽度
height, // number: 图像高度
format // number: 格式代码 (8)
);
```
#### 3.2.2 处理流程
```cpp
static napi_value SayHello(napi_env env, napi_callback_info info) {
// 1. 解析参数
napi_get_arraybuffer_info(env, args[0], &inputBuffer, &length);
napi_get_value_int32(env, args[1], &width);
napi_get_value_int32(env, args[2], &height);
// 2. YUV -> RGBA
cv::Mat yuv_mat(height + height/2, width, CV_8UC1, inputBuffer);
cv::cvtColor(yuv_mat, t, cv::COLOR_YUV2RGBA_NV21);
cv::rotate(t, rgb_mat, cv::ROTATE_90_CLOCKWISE);
// 3. 调用识别器
cvtColor(rgb_mat, bgra_mat, COLOR_RGBA2BGRA);
RecognitionResult recResult = g_paperRecognizer.recognize(bgra_mat);
// 4. 处理结果
if (recResult.success) {
// 读取颜色(白平衡)
// 自适应ROI采样
// 生成JSON字符串
}
// 5. 封装返回对象
napi_create_object(env, &object);
napi_set_named_property(env, object, "byteLength", ...);
napi_set_named_property(env, object, "buffer", ...);
napi_set_named_property(env, object, "width", ...);
napi_set_named_property(env, object, "height", ...);
napi_set_named_property(env, object, "strLength", ...);
napi_set_named_property(env, object, "strBuffer", ...);
napi_set_named_property(env, object, "statusCode", ...);
return object;
}
```
#### 3.2.3 输出格式
```javascript
{
byteLength: 123456, // 标注图像数据长度
buffer: ArrayBuffer, // 标注图像数据 (RGBA)
width: 1920, // 图像宽度
height: 1080, // 图像高度
strLength: 567, // 颜色JSON字符串长度
strBuffer: ArrayBuffer, // 颜色JSON字符串
statusCode: 0 // 状态码
}
```
#### 3.2.4 颜色JSON格式
```json
[
{"id":0, "value":"52.0,255.0,179.0,163.0,-3.0,68.0"},
{"id":1, "value":"42.0,58.0,175.0,172.0,0.0,16.0"},
...
]
// value格式: H,S,V,L,A,B
```
### 3.3 getPaperData 详细设计
```cpp
static napi_value GetPaperData(napi_env env, napi_callback_info info) {
// 获取裁剪后的试纸图片(RGBA格式)
cv::Mat paperMat = g_paperRecognizer.getPaperImg();
// 封装返回
napi_create_object(env, &object);
napi_set_named_property(env, object, "byteLength", paperMat.total()*4);
napi_set_named_property(env, object, "buffer", ...);
napi_set_named_property(env, object, "width", paperMat.cols);
napi_set_named_property(env, object, "height", paperMat.rows);
return object;
}
```
---
## 四、数据流程图
```
┌─────────────────────────────────────────────────────────────────┐
│ 上层应用 (ArkTS) │
│ ┌────────────────┐ │
│ │ 摄像头采集 │ → NV21数据 │
│ └────────────────┘ │
└────────────────────────────┬────────────────────────────────────┘
│ N-API
▼
┌─────────────────────────────────────────────────────────────────┐
│ napi_init.cpp │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ SayHello │ │
│ │ 1. 解析NV21 → RGBA │ │
│ │ 2. 调用 PaperRecognizer │ │
│ │ 3. 读取颜色 (ColorReader) │ │
│ │ 4. 封装返回结果 │ │
│ └────────────────────────────────────────────────────────┘ │
└────────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ PaperRecognizer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 图像预处理 │→│ 定位块检测 │→│ 规格匹配 │→│ 色块计算 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ 高斯滤波 轮廓检测 distRatio 中心点坐标 │
│ 颜色转换 多试纸处理 areaRatio │
│ 颜色判断 │
└────────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ ColorReader │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 白平衡 │→│ ROI采样 │→│ 颜色转换 │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ 灰度世界 自适应大小 HSV + LAB │
└────────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 返回结果 │
│ { │
│ statusCode: 0, │
│ buffer: 标注图像(RGBA), │
│ strBuffer: [{id:0, value:"H,S,V,L,A,B"}, ...] │
│ } │
└─────────────────────────────────────────────────────────────────┘
```
---
## 五、错误处理
### 5.1 错误码定义
```cpp
// napi_init.cpp
// ========== 错误码定义 ==========
// 0 - 成功
// 1 - 未检测到定位块
// 2 - 定位块颜色识别失败
// 3 - 定位块配对失败(一大一小)
// 4 - 试纸规格匹配失败
// 5 - 色块位置计算失败
// 6 - 检测到多条试纸
// 7 - 图像处理错误
// 8 - 输入图像为空
// 9 - 试纸太小/杂物(试纸高度<30px)
// 10 - 场景杂乱(候选定位块>15个)
// 100 - 未知错误
// ===============================
```
### 5.2 错误处理策略
| 错误场景 | 处理方式 | 返回内容 |
|----------|----------|----------|
| 未检测到定位块 | 返回原图 + statusCode=1 | buffer=原图, strBuffer=空 |
| 多条试纸 | 返回原图 + statusCode=6 | 提示用户单独拍摄 |
| 规格不匹配 | 返回原图 + statusCode=4 | 可能是非标准试纸 |
| 试纸太小/杂物 | 返回原图 + statusCode=9 | 提示用户靠近拍摄 |
| 场景杂乱 | 返回原图 + statusCode=10 | 提示用户简化背景 |
| 其他错误 | 返回原图 + statusCode=100 | 检查日志 |
---
## 六、关键算法参数
### 6.1 定位块检测参数
```cpp
// 面积过滤
const double MIN_LOCATOR_AREA = 100;
const double MAX_LOCATOR_AREA = 10000;
// 宽高比
const double BIG_LOCATOR_RATIO_SHORT = 2.0; // 10mm
const double BIG_LOCATOR_RATIO_LONG = 3.0; // 15mm
const double SMALL_LOCATOR_RATIO = 1.667;
const double ASPECT_RATIO_TOLERANCE = 0.35; // 收紧容差(原为0.5)
const double MAX_ASPECT_RATIO = 4.0; // 最大宽高比限制(新增)
// 面积比
const double AREA_RATIO_SHORT = 3.33; // 10mm大定位块
const double AREA_RATIO_LONG = 5.0; // 15mm大定位块
const double AREA_RATIO_TOLERANCE = 1.0;
// 颜色距离阈值
const double COLOR_DISTANCE_THRESHOLD = 20.0;
// 杂物检测阈值(新增)
const double MIN_PAPER_HEIGHT = 30.0; // 最小试纸高度(像素)
const size_t MAX_CANDIDATE_COUNT = 15; // 最大候选定位块数量
```
### 6.2 清晰度评估参数(新增)
```cpp
// Laplacian 方差法阈值
const double BLUR_THRESHOLD_NONE = 300; // >300: 清晰
const double BLUR_THRESHOLD_SLIGHT = 100; // 100-300: 轻微模糊
// <100: 严重模糊
const double BLUR_ROI_EXPAND_RATIO = 0.15; // ROI外扩15%
```
### 6.3 颜色判断阈值
```cpp
// RGB 阈值
const int RED_MARGIN = 20; // R > G+20 && R > B+20
const int GREEN_MARGIN = 10; // G > R+10 && G > B+10
const int BLUE_MARGIN = 15; // B > R+15 && B > G+15 (降低处理深蓝)
// HSV 范围
// 红色: H < 10 或 H > 170
// 绿色: 35 < H < 85
// 蓝色: H >= 95
```
### 6.4 自适应ROI参数
```cpp
// ROI大小 = 定位块高度 × 0.6
// 范围: 5×5 到 15×15 像素
// 对应 ROI: 11×11 到 31×31 像素
```
### 6.5 清晰度评估算法(新增)
**算法**:Laplacian 方差法
**步骤**:
1. 提取定位块 ROI(外扩15%)
2. 计算 Laplacian 算子
3. 计算方差(标准差的平方)
4. 根据阈值判断清晰度等级
**优势**:
- 只在定位块局部区域计算,不受图像大小影响
- 计算量小,实时性好
- 对运动模糊敏感
---
## 七、性能优化
### 7.1 已实现的优化
1. **早期过滤**
- 正方形轮廓早期排除(宽高比0.9-1.1)
- 面积过小/过大早期排除
2. **延迟计算**
- 颜色计算延迟到候选确定后
- 从N次减少到2次
3. **位置排序策略**
- 按X坐标排序,只取最左最右
- 中间轮廓不参与定位
### 7.2 内存管理
- 使用引用避免不必要的拷贝
- 及时释放中间变量
- `cv::Mat` 使用 `clone()` 显式拷贝
---
## 八、测试与验证
### 8.1 Windows测试程序
```bash
# 编译
cd entry/src/main/cpp/test/build
cmake --build . --config Debug
# 运行
.\bin\Debug\urine_test.exe ..\..\images\14red_1.png
```
### 8.2 输出文件
| 文件 | 说明 |
|------|------|
| *_annotated.jpg | 标注图(定位块框+色块圈+编号)|
| *_paper.jpg | 裁剪的试纸图 |
| *_colors.txt | 颜色结果文本 |
| *_restored_no_wb.jpg | 无白平衡还原图 |
| *_restored_with_wb.jpg | 有白平衡还原图 |
| *_colors_no_wb.json | 无白平衡颜色JSON |
| *_colors_with_wb.json | 有白平衡颜色JSON |
### 8.3 鸿蒙HAP构建
```powershell
$env:DEVECO_SDK_HOME = "D:\DevEco Studio\sdk"
cd E:\Qoder\urologist
& "D:\DevEco Studio\tools\hvigor\bin\hvigorw.bat" assembleHap --mode module -p product=default --no-daemon
```
---
## 九、附录
### A. 文件依赖关系
```
napi_init.cpp
├── PaperRecognizer.h
│ ├── Types.h
│ ├── PaperConfig.h
│ └── ColorReader.h
│ └── Types.h
└── OpenCV
```
### B. CMakeLists.txt 配置
```cmake
add_library(
entry
SHARED
napi_init.cpp
PaperRecognizer.cpp
PaperConfig.cpp
ColorReader.cpp
)
target_link_libraries(entry PUBLIC
libace_napi.z.so
libhilog_ndk.z.so
libpixelmap_ndk.z.so
${OpenCV_LIBS}
)
```
### C. 版本历史
| 版本 | 日期 | 变更说明 |
|------|------|----------|
| v1.0 | 2026-03-31 | 初始设计 |
| v2.0 | 2026-03-30 | NAPI集成完成,多试纸处理,色块编号修正 |
---
*文档结束*