# 尿检试纸识别系统 - 详细设计文档 > 文档创建时间: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 // 色块中心点 │ │ - 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> │ │ - 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 readColors( const cv::Mat& image, const std::vector& 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 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(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集成完成,多试纸处理,色块编号修正 | --- *文档结束*