Files
Ubuntu 32b43f85bd a
2026-07-03 16:58:28 +08:00

26 KiB
Raw Permalink Blame History

尿检试纸识别系统 - 详细设计文档

文档创建时间: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 主流程

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 方差法

步骤:

  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测试程序

# 编译
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集成完成,多试纸处理,色块编号修正

文档结束