质控因子等级评判测试使用说明

一、概述

QualityLevelEvaluationTest 是一个基于质控因子等级的影像质量评判测试用例。与原有的简单通过/不通过评判不同，本测试使用五个质量等级对影像质量进行精细化的评判，并生成详细的质控报告文件。

二、质量等级说明

测试使用以下五个质量等级进行评判：

等级	分数	描述	是否否决项
EXCELLENT (优秀)	5分	图像清晰可辨，能为诊断提供高质量依据	否
GOOD (良好)	4分	图像清晰明确，略有瑕疵但不影响诊断	否
MEDIUM (中等)	3分	图像清晰度一般，瑕疵较多，勉强能为诊断提供依据	否
POOR (差)	2分	图像清晰度很差，瑕疵非常多，不能为诊断提供依据	是
TERRIBLE (极差)	1分	图像清晰度极差，有全黑、全白等无效影像	是

三、评判逻辑

3.1 图像指标分析

测试会分析以下图像指标：

亮度 (brightness): 图像的平均亮度值 (0-255)
对比度 (contrast): 图像的对比度值 (0-100)
清晰度/锐度 (sharpness): 图像的锐度值 (0-150)
标准差 (stdDev): 像素值的标准差 (0-60)
伪影比率 (artifactRatio): 伪影占图像的比例 (0-1.0)

3.2 等级判定规则

EXCELLENT (优秀) - 5分

亮度: 20-235
对比度: ≥50
清晰度: ≥100
标准差: ≥40
伪影比率: ≤0.05

GOOD (良好) - 4分

亮度: 15-240
对比度: ≥40
清晰度: ≥80
标准差: ≥30
伪影比率: ≤0.10

MEDIUM (中等) - 3分

亮度: 12-243
对比度: ≥30
清晰度: ≥60
标准差: ≥25
伪影比率: ≤0.15

POOR (差) - 2分 (否决项)

亮度: 10-245
对比度: ≥20
清晰度: ≥40
标准差: ≥20
伪影比率: ≤0.20

TERRIBLE (极差) - 1分 (否决项)

不满足上述任一等级的条件

四、使用方法

4.1 配置测试参数

在测试类中修改以下配置：

/**
 * 测试影像文件路径
 */
private static final String DICOM_FILE_PATH =
    "/Users/geng/qconline/dicom/INST011/1.2.156.14702.1.1005.128.0.20210128094934016/";

/**
 * 质控报告输出目录
 */
private static final String REPORT_OUTPUT_DIR =
    System.getProperty("user.home") + "/qc_reports/";

4.2 运行测试

在 IDEA 中：

打开 QualityLevelEvaluationTest.java
右键点击 testQualityLevelEvaluation() 方法
选择 "Run 'testQualityLevelEvaluation()'"

或者在命令行中：

mvn test -Dtest=QualityLevelEvaluationTest#testQualityLevelEvaluation

4.3 查看结果

测试完成后会：

控制台输出：实时显示测试过程和结果
报告文件：在 ~/qc_reports/ 目录下生成详细的质控报告文件

报告文件命名格式：qc_report_YYYYMMDD_HHMMSS.txt

五、测试流程

步骤 1: 解析 DICOM 影像文件

═══════════════════════════════════════════════════════════════════════════════════
步骤 1: 解析 DICOM 影像文件
═══════════════════════════════════════════════════════════════════════════════════

解析结果：
  - 模态 (Modality): CT
  - 检查部位 (Body Part): HEAD
  - 检查项目 (Exam Item): 头颅平扫
  - 体位 (Position): SUPINE
  - 检查描述 (Description): 颅脑CT

步骤 2: 自动匹配质控标准

═══════════════════════════════════════════════════════════════════════════════════
步骤 2: 自动匹配质控标准
═══════════════════════════════════════════════════════════════════════════════════

✅ 找到匹配的质控标准：
  - 标准ID: STD_001
  - 标准代码: CT_HEAD
  - 标准名称: CT头颅平扫
  - 模态: CT
  - 检查部位: HEAD
  - 合格分数: 80 分

步骤 3: 获取质控因子列表

═══════════════════════════════════════════════════════════════════════════════════
步骤 3: 获取质控因子列表
═══════════════════════════════════════════════════════════════════════════════════

共找到 7 个质控因子：
  1. BASIC_4_1 - 有效图像 (权重: 10, 必需: 是)
  2. BASIC_4_2 - 真实人体图像 (权重: 10, 必需: 是)
  3. BASIC_4_3 - 原始完整图像 (权重: 10, 必需: 是)
  4. CT_5_3_1 - CT图像信息完整性 (权重: 15, 必需: 是)
  5. CT_5_4_1_1_1 - 检查范围（颅脑） (权重: 20, 必需: 是)
  6. CT_5_4_1_1_2 - 图像偏中心 (权重: 15, 必需: 否)
  7. CT_5_4_1_1_3 - 重建参数 (权重: 20, 必需: 否)

步骤 4: 基于等级的质控评判

═══════════════════════════════════════════════════════════════════════════════════
步骤 4: 基于等级的质控评判
═══════════════════════════════════════════════════════════════════════════════════

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
检查因子: 有效图像
因子代码: BASIC_4_1
数据源: image_quality
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

图像指标分析完成:
{
  "brightness": 125.5,
  "contrast": 65.2,
  "sharpness": 105.8,
  "stdDev": 42.3,
  "artifactRatio": 0.03
}

等级判定: EXCELLENT - 5分

评判结果:
  - 质量等级: EXCELLENT
  - 等级分数: 5 分
  - 是否否决项: 否
  - 评判依据: 图像清晰可辨，能为诊断提供高质量依据

步骤 5: 质控结果汇总

═══════════════════════════════════════════════════════════════════════════════════
步骤 5: 质控结果汇总
═══════════════════════════════════════════════════════════════════════════════════

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
质控结果汇总
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
质控标准: CT头颅平扫
合格分数: 80 分
实际得分: 92.50 分
质控结果: ✅ 通过 PASS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

等级分布：
  - 优秀 (EXCELLENT): 3 个
  - 良好 (GOOD): 2 个
  - 中等 (MEDIUM): 1 个
  - 差 (POOR): 1 个
  - 极差 (TERRIBLE): 0 个

步骤 6: 生成质控报告文件

═══════════════════════════════════════════════════════════════════════════════════
步骤 6: 生成质控报告文件
═══════════════════════════════════════════════════════════════════════════════════

✅ 质控报告已生成: /Users/geng/qc_reports/qc_report_20260126_143522.txt

六、报告文件示例

质控报告文件包含以下内容：

╔════════════════════════════════════════════════════════════════════════════════════╗
║                      医学影像质控系统 - 质控因子等级评判报告                      ║
╚════════════════════════════════════════════════════════════════════════════════════╝

报告生成时间: 2026-01-26 14:35:22

═══════════════════════════════════════════════════════════════════════════════════
步骤 1: 解析 DICOM 影像文件
═══════════════════════════════════════════════════════════════════════════════════

影像解析结果：
  - 模态 (Modality): CT
  - 检查部位 (Body Part): HEAD
  - 检查项目 (Exam Item): 头颅平扫
  - 体位 (Position): SUPINE
  - 检查描述 (Description): 颅脑CT

... (详细的质控过程和结果)

═══════════════════════════════════════════════════════════════════════════════════
报告结束
═══════════════════════════════════════════════════════════════════════════════════

报告文件路径: /Users/geng/qc_reports/qc_report_20260126_143522.txt

七、与原有测试的对比

特性	AutoQcStandardMatchTest	QualityLevelEvaluationTest
评判方式	通过/不通过（二元）	五级质量等级
评分	简单的权重计算	加权平均 + 等级评分
否决项	不支持	支持（POOR和TERRIBLE为否决项）
图像分析	基本检查	详细的图像指标分析
结果输出	仅控制台	控制台 + 详细报告文件
过程记录	简单日志	详细的过程日志和评判依据

八、常见问题

Q1: 如何修改质量等级的阈值？

A: 在 QualityLevelEvaluationTest.java 的 determineQualityLevel() 方法中修改对应的阈值条件。

Q2: 如何添加新的图像指标？

A: 在 analyzeImageMetrics() 方法中添加新的指标计算逻辑。

Q3: 报告文件在哪里？

A: 默认在用户主目录下的 qc_reports/ 文件夹中，可以通过修改 REPORT_OUTPUT_DIR 常量来更改。

Q4: 测试失败怎么办？

A: 检查以下几点：

DICOM 文件路径是否正确
数据库中是否存在对应的质控标准和因子
OpenCV 库是否正确加载

九、后续扩展

集成真实的图像分析：使用 OpenCVImageAnalyzer 进行真实的图像分析，而不是模拟数据
从数据库读取等级配置：从 qc_factor_level_config 表中读取等级配置，而不是硬编码
支持多种报告格式：除了文本文件，还可以生成 HTML、PDF 等格式的报告
图表展示：在报告中添加质量等级分布图表

十、技术支持

如有问题或建议，请联系开发团队。

质控因子等级评判测试说明.md 13 KB História Raw