26 KiB
26 KiB
尿检试纸识别系统 - 详细设计文档
文档创建时间:2026-03-30 最后更新:2026-04-03 版本:v1.1 适用范围:PaperRecognizer、ColorReader、PaperConfig、NAPI接口
一、系统概述
1.1 功能描述
尿检试纸识别系统用于从拍摄的试纸图片中自动识别:
- 定位块:试纸两端的红色/绿色/蓝色定位块
- 试纸规格:根据定位块特征判断8/11/14联及S/L型
- 反应色块位置:计算每个反应色块的精确中心坐标
- 颜色数据:读取每个反应色块的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 主流程
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 定位块颜色判断
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] 始终靠近小定位块
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 类设计
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 白平衡算法
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
// 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 配置参数
struct PaperConfig {
PaperSpatialType type; // 试纸类型
BlockItems blockItems; // 联数
BigLocatorType locatorType; // 大定位块类型
int itemsNum; // 反应色块数量
int slicesNum; // 最小分割单位数量
double firstPos; // 第一个色块位置倍数
double step; // 步长倍数
};
2.3.2 规格匹配
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 输入参数
// ArkTS 调用示例
let result = nativeModule.sayHello(
yuvBuffer, // ArrayBuffer: NV21格式的YUV数据
width, // number: 图像宽度
height, // number: 图像高度
format // number: 格式代码 (8)
);
3.2.2 处理流程
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 输出格式
{
byteLength: 123456, // 标注图像数据长度
buffer: ArrayBuffer, // 标注图像数据 (RGBA)
width: 1920, // 图像宽度
height: 1080, // 图像高度
strLength: 567, // 颜色JSON字符串长度
strBuffer: ArrayBuffer, // 颜色JSON字符串
statusCode: 0 // 状态码
}
3.2.4 颜色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 详细设计
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 错误码定义
// 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 定位块检测参数
// 面积过滤
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 清晰度评估参数(新增)
// 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 颜色判断阈值
// 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参数
// ROI大小 = 定位块高度 × 0.6
// 范围: 5×5 到 15×15 像素
// 对应 ROI: 11×11 到 31×31 像素
6.5 清晰度评估算法(新增)
算法:Laplacian 方差法
步骤:
- 提取定位块 ROI(外扩15%)
- 计算 Laplacian 算子
- 计算方差(标准差的平方)
- 根据阈值判断清晰度等级
优势:
- 只在定位块局部区域计算,不受图像大小影响
- 计算量小,实时性好
- 对运动模糊敏感
七、性能优化
7.1 已实现的优化
-
早期过滤
- 正方形轮廓早期排除(宽高比0.9-1.1)
- 面积过小/过大早期排除
-
延迟计算
- 颜色计算延迟到候选确定后
- 从N次减少到2次
-
位置排序策略
- 按X坐标排序,只取最左最右
- 中间轮廓不参与定位
7.2 内存管理
- 使用引用避免不必要的拷贝
- 及时释放中间变量
cv::Mat使用clone()显式拷贝
八、测试与验证
8.1 Windows测试程序
# 编译
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构建
$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 配置
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集成完成,多试纸处理,色块编号修正 |
文档结束