第十二章：数据质检（QC）步骤详解

数据质检步骤（qc.*）是 GeoPipeAgent 中最丰富的步骤类别，共 10 个，覆盖矢量几何检查、属性检查和栅格质量检查。

12.1 QC 步骤的核心机制

“检查并透传”模式

所有 QC 步骤都遵循同一个模式：

输入数据 → 检查逻辑 → 输出 = 原始数据（透传）
                   ↓
              issues 问题列表
              issues_gdf 问题要素 GeoDataFrame

output：等于输入数据（透传，或 auto_fix=true 时为修复后数据）
issues：QcIssue 对象列表（通过 StepResult.issues 访问）
stats.issues_count：问题数量（可在 when 条件中引用）
metadata.issues_gdf：问题要素的 GeoDataFrame（通过 $step.issues_gdf 引用）

这种设计允许多个 QC 步骤串联，每步检查不同规则，最后汇总所有问题。

QcIssue 数据结构

@dataclass
class QcIssue:
    rule_id: str          # 规则 ID（如 "geometry_validity"）
    severity: str         # 严重级别："error" / "warning" / "info"
    feature_index: int    # 问题要素的行索引（None 表示数据集级问题）
    message: str          # 问题描述（如 "Feature 42: Self-intersection at (120.5, 31.2)"）
    geometry: Any         # 问题位置几何（可选，用于可视化）
    details: dict         # 规则特定的详细信息

12.2 步骤总览

步骤 ID	名称	检查内容
`qc.geometry_validity`	几何有效性检查	自相交、空几何、环方向错误
`qc.crs_check`	坐标参考系检查	CRS 缺失、与预期不符
`qc.topology`	拓扑关系检查	缝隙、重叠、悬挂线
`qc.attribute_completeness`	属性完整性检查	必填字段缺失或为空
`qc.attribute_domain`	属性值域检查	枚举值/正则模式不合规
`qc.value_range`	数值范围检查	数值字段超出指定范围
`qc.duplicate_check`	重复要素检查	几何或属性重复
`qc.raster_nodata`	NoData 一致性检查	NoData 设置及占比
`qc.raster_resolution`	分辨率一致性检查	像元大小是否符合预期
`qc.raster_value_range`	栅格值域检查	像素值超出预期范围

12.3 矢量 QC 步骤详解

`qc.geometry_validity`：几何有效性检查

参数	类型	必填	默认值	说明
`input`	geodataframe	✅	—	输入矢量数据
`auto_fix`	boolean	❌	`false`	是否自动修复（buffer(0) 方法）
`severity`	string	❌	`error`	问题严重级别

检测的问题类型：自相交（Self-intersection）、空几何（Empty geometry）、NULL 几何（Null geometry）、环方向错误。

- id: check-geo
  use: qc.geometry_validity
  params:
    input: "$load-data"
    auto_fix: false
    severity: "error"

- id: fix-geo
  use: qc.geometry_validity
  params:
    input: "$load-data"
    auto_fix: true
  when: "$check-geo.issues_count > 0"

`qc.crs_check`：坐标参考系检查

参数	类型	必填	默认值	说明
`input`	geodataframe	✅	—	输入矢量数据
`expected_crs`	string	❌	—	期望的 CRS（如 `"EPSG:4326"`）；不指定则只检查是否有 CRS

检测：CRS 为空（无坐标系信息）、与 expected_crs 不一致。

- id: check-crs
  use: qc.crs_check
  params:
    input: "$load-data"
    expected_crs: "EPSG:4326"
  on_error: skip   # CRS 问题不阻断流程，但会记录

- id: reproject-if-needed
  use: vector.reproject
  params:
    input: "$load-data"
    target_crs: "EPSG:4326"
  when: "$check-crs.issues_count > 0"

`qc.topology`：拓扑关系检查

参数	类型	必填	默认值	说明
`input`	geodataframe	✅	—	输入矢量数据
`rules`	list	❌	`["no_overlaps"]`	拓扑规则列表
`tolerance`	number	❌	`0.0`	几何容差

支持的规则：

规则	适用类型	说明
`no_overlaps`	Polygon	多边形不得重叠
`no_gaps`	Polygon	多边形之间不得有缝隙
`no_dangles`	LineString	线不得有悬挂端（端点不与其他线连接）
`no_self_intersections`	LineString	线不得自相交

- id: check-topo
  use: qc.topology
  params:
    input: "$load-parcels"
    rules: ["no_overlaps", "no_gaps"]
    tolerance: 0.001

`qc.attribute_completeness`：属性完整性检查

参数	类型	必填	默认值	说明
`input`	geodataframe	✅	—	输入矢量数据
`required_fields`	list	✅	—	必填字段名列表
`severity`	string	❌	`error`	问题严重级别

检测：字段不存在、字段值为 NULL/空字符串/空列表。

- id: check-completeness
  use: qc.attribute_completeness
  params:
    input: "$load-buildings"
    required_fields: ["name", "height", "use_type", "build_year"]
    severity: "warning"

`qc.attribute_domain`：属性值域检查

参数	类型	必填	默认值	说明
`input`	geodataframe	✅	—	输入矢量数据
`field`	string	✅	—	检查的字段名
`allowed_values`	list	❌	—	允许的枚举值列表
`pattern`	string	❌	—	允许的正则表达式模式
`severity`	string	❌	`error`	问题严重级别

# 枚举值检查
- id: check-type
  use: qc.attribute_domain
  params:
    input: "$load-buildings"
    field: "use_type"
    allowed_values: ["residential", "commercial", "industrial", "public", "mixed"]

# 正则模式检查（邮政编码格式）
- id: check-postcode
  use: qc.attribute_domain
  params:
    input: "$load-addresses"
    field: "postcode"
    pattern: "^\\d{6}$"     # 6 位数字
    severity: "warning"

`qc.value_range`：数值范围检查

参数	类型	必填	默认值	说明
`input`	geodataframe	✅	—	输入矢量数据
`field`	string	✅	—	检查的数值字段名
`min`	number	❌	—	最小值（含）
`max`	number	❌	—	最大值（含）
`severity`	string	❌	`error`	问题严重级别

- id: check-height
  use: qc.value_range
  params:
    input: "$load-buildings"
    field: "height"
    min: 0
    max: 600      # 上海中心大厦约 632 米，超过 600 可能是异常值
    severity: "warning"

`qc.duplicate_check`：重复要素检查

参数	类型	必填	默认值	说明
`input`	geodataframe	✅	—	输入矢量数据
`check_geometry`	boolean	❌	`true`	是否检查几何重复
`check_fields`	list	❌	—	检查属性重复的字段列表
`severity`	string	❌	`error`	问题严重级别

- id: check-dup
  use: qc.duplicate_check
  params:
    input: "$load-poi"
    check_geometry: true           # 检查几何完全相同的要素
    check_fields: ["name", "type"] # 同时检查名称+类型完全相同的要素

12.4 栅格 QC 步骤详解

`qc.raster_nodata`：NoData 一致性检查

参数	类型	必填	默认值	说明
`input`	raster_info	✅	—	输入栅格数据
`expected_nodata`	number	❌	—	期望的 NoData 值
`max_nodata_ratio`	number	❌	`0.5`	允许的最大 NoData 比例（0-1）
`severity`	string	❌	`error`	问题严重级别

- id: check-nodata
  use: qc.raster_nodata
  params:
    input: "$load-dem"
    expected_nodata: -9999
    max_nodata_ratio: 0.2    # NoData 比例不超过 20%

`qc.raster_resolution`：分辨率一致性检查

参数	类型	必填	默认值	说明
`input`	raster_info	✅	—	输入栅格数据
`expected_x_res`	number	❌	—	期望的 X 方向分辨率
`expected_y_res`	number	❌	—	期望的 Y 方向分辨率
`tolerance`	number	❌	`0.01`	允许的误差比例（0-1）
`severity`	string	❌	`error`	问题严重级别

- id: check-resolution
  use: qc.raster_resolution
  params:
    input: "$load-satellite"
    expected_x_res: 30     # Landsat 30 米分辨率
    expected_y_res: 30
    tolerance: 0.05        # 允许 5% 误差

`qc.raster_value_range`：栅格值域检查

参数	类型	必填	默认值	说明
`input`	raster_info	✅	—	输入栅格数据
`min`	number	❌	—	最小像素值
`max`	number	❌	—	最大像素值
`severity`	string	❌	`error`	问题严重级别

- id: check-ndvi-range
  use: qc.raster_value_range
  params:
    input: "$calc-ndvi"
    min: -1.0
    max: 1.0
    severity: "warning"    # NDVI 理论范围 -1 到 1

12.5 完整矢量数据质检流水线

pipeline:
  name: "建筑物数据入库前全量质检"
  description: "对建筑物矢量数据进行完整质检：几何、坐标系、拓扑、属性"

  variables:
    input_path: "data/buildings.shp"
    expected_crs: "EPSG:4326"

  steps:
    - id: load-data
      use: io.read_vector
      params: { path: "${input_path}" }

    - id: check-crs
      use: qc.crs_check
      params:
        input: "$load-data"
        expected_crs: "${expected_crs}"
      on_error: skip

    - id: check-geometry
      use: qc.geometry_validity
      params:
        input: "$load-data"
        severity: "error"

    - id: check-topology
      use: qc.topology
      params:
        input: "$load-data"
        rules: ["no_overlaps", "no_gaps"]
        tolerance: 0.0001
      on_error: skip

    - id: check-completeness
      use: qc.attribute_completeness
      params:
        input: "$load-data"
        required_fields: ["name", "height", "build_year", "use_type"]
        severity: "warning"
      on_error: skip

    - id: check-type-domain
      use: qc.attribute_domain
      params:
        input: "$load-data"
        field: "use_type"
        allowed_values: ["R", "C", "I", "P"]   # 住宅/商业/工业/公共
        severity: "warning"
      on_error: skip

    - id: check-height-range
      use: qc.value_range
      params:
        input: "$load-data"
        field: "height"
        min: 0
        max: 700
        severity: "warning"
      on_error: skip

    - id: check-duplicates
      use: qc.duplicate_check
      params:
        input: "$load-data"
        check_geometry: true
        check_fields: ["name"]
      on_error: skip

    # 保存几何问题要素
    - id: save-geo-issues
      use: io.write_vector
      params:
        input: "$check-geometry.issues_gdf"
        path: "output/geometry_issues.geojson"
        format: "GeoJSON"
      when: "$check-geometry.issues_count > 0"
      on_error: skip

  outputs:
    crs_issues: "$check-crs.issues_count"
    geometry_issues: "$check-geometry.issues_count"
    topology_issues: "$check-topology.issues_count"
    completeness_issues: "$check-completeness.issues_count"
    domain_issues: "$check-type-domain.issues_count"
    range_issues: "$check-height-range.issues_count"
    duplicate_issues: "$check-duplicates.issues_count"

12.6 本章小结

本章详细介绍了 10 个 QC 步骤：

矢量 QC（7个）：

qc.geometry_validity：几何有效性，支持 auto_fix
qc.crs_check：坐标系验证
qc.topology：拓扑关系（重叠、缝隙、悬挂线）
qc.attribute_completeness：必填字段完整性
qc.attribute_domain：枚举值/正则模式检查
qc.value_range：数值范围检查
qc.duplicate_check：重复要素检查

栅格 QC（3个）：

qc.raster_nodata：NoData 设置与比例
qc.raster_resolution：分辨率一致性
qc.raster_value_range：像素值域检查

关键模式：$step.issues_count 用于条件判断，$step.issues_gdf 保存问题要素。

导航：← 第十一章：网络分析步骤｜第十三章：流水线引擎 →

第十二章：数据质检（QC）步骤详解

12.1 QC 步骤的核心机制

“检查并透传”模式

QcIssue 数据结构

12.2 步骤总览

12.3 矢量 QC 步骤详解

qc.geometry_validity：几何有效性检查

qc.crs_check：坐标参考系检查

qc.topology：拓扑关系检查

qc.attribute_completeness：属性完整性检查

qc.attribute_domain：属性值域检查

qc.value_range：数值范围检查

qc.duplicate_check：重复要素检查