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

12.1 概述

数据质检步骤（前缀 qc）是 GeoPipeAgent 中数量最多的类别，共 10 个步骤，覆盖矢量和栅格数据的多维度质量检查：

矢量质检步骤

步骤 ID	名称	检查内容
`qc.geometry_validity`	几何有效性检查	自相交、空几何、环方向等
`qc.crs_check`	坐标参考系检查	CRS 是否正确/缺失
`qc.topology`	拓扑关系检查	缝隙、重叠、悬挂线等
`qc.attribute_completeness`	属性完整性检查	必填字段是否缺失/为空
`qc.attribute_domain`	属性值域检查	枚举值或正则表达式约束
`qc.value_range`	数值范围检查	数值字段是否在指定范围内
`qc.duplicate_check`	重复要素检查	几何或属性重复要素

栅格质检步骤

步骤 ID	名称	检查内容
`qc.raster_nodata`	NoData 一致性检查	NoData 值设置及像元比例
`qc.raster_resolution`	分辨率一致性检查	像元大小是否符合预期
`qc.raster_value_range`	栅格值域检查	像素值是否在预期范围内

质检结果结构

所有 QC 步骤的输出均包含：

属性	类型	说明
`issue_count`	int	发现的问题数量
`passed`	bool	是否通过质检（`issue_count == 0`）
`issues`	list	质检问题详情列表，每项包含 `type`/`message`/`fid`（要素ID）等
`summary`	dict	统计摘要（各类问题的数量分布）

12.2 `qc.geometry_validity`

功能说明

检查矢量要素的几何有效性，识别各类几何错误。

检查的几何问题类型

问题类型	说明
`self_intersection`	自相交（多边形边线自己与自己相交）
`empty_geometry`	空几何（geometry 为 None 或空）
`null_geometry`	空值几何
`ring_self_intersection`	环自相交
`invalid_ring_order`	外环方向错误（应为逆时针，但为顺时针）
`multipolygon_overlap`	多部件几何内部重叠

参数说明

参数	类型	必填	说明
`input`	ref	✅	输入 GeoDataFrame

使用示例

- id: check-geom
  use: qc.geometry_validity
  params:
    input: $load

# 在 when 中使用质检结果
- id: fix-geom
  use: vector.buffer
  params:
    input: $load
    distance: 0    # 0 距离缓冲，常用几何修复技巧
  when: "$check-geom.issue_count > 0"

典型质检报告

{
  "issue_count": 3,
  "passed": false,
  "issues": [
    {"type": "self_intersection", "fid": 42, "message": "要素 42 存在自相交"},
    {"type": "empty_geometry", "fid": 88, "message": "要素 88 几何为空"},
    {"type": "self_intersection", "fid": 156, "message": "要素 156 存在自相交"}
  ],
  "summary": {"self_intersection": 2, "empty_geometry": 1}
}

12.3 `qc.crs_check`

功能说明

检查数据的坐标参考系（CRS）是否符合预期，包括缺失 CRS 检测和 CRS 匹配验证。

参数说明

参数	类型	必填	默认值	说明
`input`	ref	✅	—	输入 GeoDataFrame 或栅格数据
`expected_crs`	str	❌	None	期望的 CRS（不设置则只检查 CRS 是否存在）
`allow_equivalent`	bool	❌	`True`	是否允许等价 CRS（如 WGS84 的不同表达形式）

检查的问题类型

问题类型	说明
`missing_crs`	CRS 未定义
`crs_mismatch`	CRS 与期望不符

使用示例

# 检查 CRS 是否存在
- id: check-crs-exists
  use: qc.crs_check
  params:
    input: $load

# 检查是否为特定 CRS
- id: check-crs-wgs84
  use: qc.crs_check
  params:
    input: $load
    expected_crs: "EPSG:4326"

# 与上游步骤的 CRS 对比
- id: check-crs-match
  use: qc.crs_check
  params:
    input: $load-secondary
    expected_crs: $load-primary.crs

12.4 `qc.topology`

功能说明

检查矢量数据的拓扑关系，发现缝隙（gap）、重叠（overlap）、悬挂线（dangling）等拓扑错误。

参数说明

参数	类型	必填	默认值	说明
`input`	ref	✅	—	输入 GeoDataFrame
`checks`	list	❌	全部检查	指定要执行的检查类型列表
`tolerance`	float	❌	0.001	拓扑容差（单位：CRS 坐标单位）

支持的拓扑检查类型

检查类型	说明	适用几何类型
`overlaps`	面要素之间的重叠	Polygon
`gaps`	面要素之间的缝隙	Polygon
`dangles`	悬挂线（只有一端连接的线段）	LineString
`self_overlaps`	多部件要素内部重叠	Polygon

使用示例

# 全面拓扑检查
- id: topology-check
  use: qc.topology
  params:
    input: $load-parcels
    tolerance: 0.01

# 只检查重叠和缝隙
- id: polygon-topology
  use: qc.topology
  params:
    input: $load-landuse
    checks:
      - overlaps
      - gaps
    tolerance: 0.1

# 线网络悬挂检查
- id: line-topology
  use: qc.topology
  params:
    input: $load-roads
    checks:
      - dangles

12.5 `qc.attribute_completeness`

功能说明

检查矢量属性表中必填字段是否缺失（NULL 或空字符串）。

参数说明

参数	类型	必填	说明
`input`	ref	✅	输入 GeoDataFrame
`required_fields`	list	✅	必填字段名称列表

使用示例

# 检查必填字段完整性
- id: check-completeness
  use: qc.attribute_completeness
  params:
    input: $load
    required_fields:
      - name
      - type
      - area
      - admin_code

12.6 `qc.attribute_domain`

功能说明

检查属性字段值是否在允许的值域范围内（枚举值列表或正则表达式）。

参数说明

参数	类型	必填	说明
`input`	ref	✅	输入 GeoDataFrame
`domains`	dict	✅	字段值域约束字典

domains 字典格式：

domains:
  字段名:
    type: enum          # 枚举类型
    values: [A, B, C]  # 允许的值列表
  
  另一字段:
    type: regex         # 正则表达式类型
    pattern: "^[A-Z]{2}\\d{6}$"  # 编码格式约束

使用示例

# 检查土地利用类型字段的枚举值
- id: check-domain
  use: qc.attribute_domain
  params:
    input: $load-landuse
    domains:
      land_type:
        type: enum
        values:
          - "居住用地"
          - "商业用地"
          - "工业用地"
          - "绿地"
          - "公共设施用地"
      admin_code:
        type: regex
        pattern: "^\\d{6}$"    # 6位数字行政区划代码

12.7 `qc.value_range`

功能说明

检查数值字段是否在指定的最小值/最大值范围内。

参数说明

参数	类型	必填	说明
`input`	ref	✅	输入 GeoDataFrame
`ranges`	dict	✅	字段值范围约束字典

使用示例

- id: check-ranges
  use: qc.value_range
  params:
    input: $load
    ranges:
      area:
        min: 0
        max: 1000000    # 面积不超过 100 万平方米
      longitude:
        min: 73.0
        max: 135.0       # 中国境内经度范围
      latitude:
        min: 18.0
        max: 53.0        # 中国境内纬度范围
      floor_count:
        min: 1           # 层数至少 1 层
        max: 200         # 不超过 200 层

12.8 `qc.duplicate_check`

功能说明

检测 GeoDataFrame 中的重复要素，包括几何重复和属性重复。

参数说明

参数	类型	必填	默认值	说明
`input`	ref	✅	—	输入 GeoDataFrame
`check_geometry`	bool	❌	`True`	是否检查几何重复
`check_fields`	list	❌	None	检查属性重复的字段列表（空则不检查属性）
`tolerance`	float	❌	0.0	几何重复的容差

使用示例

# 检查几何重复
- id: check-duplicates
  use: qc.duplicate_check
  params:
    input: $load
    check_geometry: true

# 检查属性重复（按唯一标识符字段）
- id: check-attr-duplicates
  use: qc.duplicate_check
  params:
    input: $load
    check_geometry: false
    check_fields:
      - "parcel_id"    # 宗地编号应唯一

# 综合检查
- id: full-duplicate-check
  use: qc.duplicate_check
  params:
    input: $load
    check_geometry: true
    check_fields:
      - "name"
      - "admin_code"
    tolerance: 0.001

12.9 栅格质检步骤

`qc.raster_nodata`

检查栅格数据的 NoData 设置及 NoData 像元比例：

- id: check-nodata
  use: qc.raster_nodata
  params:
    input: $load-raster
    expected_nodata: -9999      # 期望的 NoData 值
    max_nodata_ratio: 0.3       # 允许最多 30% 的 NoData 像元

检查内容：

NoData 值是否已设置（警告：未设置 NoData）
实际 NoData 值与期望值是否一致
NoData 像元比例是否超过阈值

`qc.raster_resolution`

检查栅格像元分辨率是否符合预期：

- id: check-resolution
  use: qc.raster_resolution
  params:
    input: $load-dem
    expected_resolution: 30.0       # 期望 30 米分辨率
    tolerance_ratio: 0.05           # 允许 5% 的误差

`qc.raster_value_range`

检查栅格像素值是否在预期范围内：

# 检查 DEM 值域是否合理
- id: check-dem-values
  use: qc.raster_value_range
  params:
    input: $load-dem
    band: 1
    min_value: -500       # 海拔最低 -500 米（低于死海）
    max_value: 9000       # 海拔最高 9000 米（珠峰附近）

# 检查 NDVI 值域（应在 -1 到 1 之间）
- id: check-ndvi-range
  use: qc.raster_value_range
  params:
    input: $calc-ndvi
    band: 1
    min_value: -1.0
    max_value: 1.0

12.10 综合质检流水线示例

# cookbook/vector-qc.yaml
name: 矢量数据全面质检
description: 对矢量数据执行完整的质量检查，涵盖几何、CRS、拓扑、属性多个维度

variables:
  input_path: "data/parcels.shp"
  expected_crs: "EPSG:4326"
  required_fields:
    - name
    - type
    - admin_code

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

  # 1. CRS 检查
  - id: qc-crs
    use: qc.crs_check
    params:
      input: $load
      expected_crs: ${expected_crs}
    on_error: skip

  # 2. 几何有效性检查
  - id: qc-geom
    use: qc.geometry_validity
    params:
      input: $load
    on_error: skip

  # 3. 属性完整性检查
  - id: qc-completeness
    use: qc.attribute_completeness
    params:
      input: $load
      required_fields: ${required_fields}
    on_error: skip

  # 4. 属性值域检查
  - id: qc-domain
    use: qc.attribute_domain
    params:
      input: $load
      domains:
        type:
          type: enum
          values: ["居住", "商业", "工业", "绿化", "公共"]
        admin_code:
          type: regex
          pattern: "^\\d{6}$"
    on_error: skip

  # 5. 数值范围检查
  - id: qc-range
    use: qc.value_range
    params:
      input: $load
      ranges:
        area:
          min: 0
          max: 5000000
    on_error: skip

  # 6. 拓扑检查（计算密集，可选执行）
  - id: qc-topology
    use: qc.topology
    params:
      input: $load
      checks:
        - overlaps
        - gaps
      tolerance: 0.01
    on_error: skip

  # 7. 重复检查
  - id: qc-duplicate
    use: qc.duplicate_check
    params:
      input: $load
      check_geometry: true
      check_fields:
        - "admin_code"
    on_error: skip

outputs:
  crs_check: $qc-crs
  geometry_check: $qc-geom
  completeness_check: $qc-completeness
  domain_check: $qc-domain
  range_check: $qc-range
  topology_check: $qc-topology
  duplicate_check: $qc-duplicate

运行后，JSON 报告中的 outputs 字段会包含每项质检的详细结果。

12.11 基于质检结果的自动修复

GeoPipeAgent 可以将质检步骤与修复步骤结合，实现半自动的数据质量改进：

steps:
  - id: load
    use: io.read_vector
    params:
      path: "data/input.shp"

  # 几何质检
  - id: geom-check
    use: qc.geometry_validity
    params:
      input: $load

  # 自动修复无效几何（0 距离缓冲法）
  - id: fix-geometry
    use: vector.buffer
    params:
      input: $load
      distance: 0
    when: "$geom-check.issue_count > 0"   # 只有发现问题时才修复

  # CRS 质检
  - id: crs-check
    use: qc.crs_check
    params:
      input: $fix-geometry
      expected_crs: "EPSG:4326"

  # 自动修复 CRS（重投影）
  - id: fix-crs
    use: vector.reproject
    params:
      input: $fix-geometry
      target_crs: "EPSG:4326"
    when: "$crs-check.passed == false"   # CRS 不对时才重投影

  # 最终保存
  - id: save
    use: io.write_vector
    params:
      input: $fix-crs
      path: "output/cleaned.geojson"

12.12 小结

本章介绍了 GeoPipeAgent 的 10 个数据质检步骤：

矢量质检：

qc.geometry_validity：几何有效性
qc.crs_check：坐标参考系
qc.topology：拓扑关系
qc.attribute_completeness：属性完整性
qc.attribute_domain：属性值域
qc.value_range：数值范围
qc.duplicate_check：重复要素

栅格质检：

qc.raster_nodata：NoData 一致性
qc.raster_resolution：分辨率一致性
qc.raster_value_range：栅格值域

质检步骤可单独使用，也可与 when 条件结合实现自动修复逻辑。

下一章进入引擎篇，将深入解析 GeoPipeAgent 的执行引擎工作原理。

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

12.1 概述

矢量质检步骤

栅格质检步骤

质检结果结构

12.2 qc.geometry_validity

功能说明

检查的几何问题类型

参数说明

使用示例

典型质检报告

12.3 qc.crs_check

功能说明

参数说明

检查的问题类型

使用示例

12.4 qc.topology

功能说明

参数说明

支持的拓扑检查类型

使用示例

12.5 qc.attribute_completeness

功能说明

参数说明

使用示例

12.6 qc.attribute_domain

功能说明

参数说明

使用示例

12.7 qc.value_range

功能说明

参数说明

使用示例

12.8 qc.duplicate_check

功能说明

参数说明

使用示例

12.9 栅格质检步骤

qc.raster_nodata

qc.raster_resolution

qc.raster_value_range

12.10 综合质检流水线示例

12.11 基于质检结果的自动修复

12.12 小结

12.2 `qc.geometry_validity`

12.3 `qc.crs_check`

12.4 `qc.topology`

12.5 `qc.attribute_completeness`

12.6 `qc.attribute_domain`

12.7 `qc.value_range`

12.8 `qc.duplicate_check`

`qc.raster_nodata`

`qc.raster_resolution`

`qc.raster_value_range`