第七章：IO 步骤详解

IO 步骤（io.*）负责地理数据的读取和写入，是每个流水线的入口和出口。GeoPipeAgent 内置 4 个 IO 步骤，支持主流矢量和栅格格式。

7.1 步骤总览

7.2 io.read_vector：读取矢量数据

参数

输出（StepResult）

支持格式

示例

# 基础读取
- id: load-vector
  use: io.read_vector
  params:
    path: "data/buildings.shp"

# 指定编码（中文 Shapefile）
- id: load-cn-data
  use: io.read_vector
  params:
    path: "data/roads_cn.shp"
    encoding: "gbk"

# 读取 GeoPackage 的特定图层
- id: load-layer
  use: io.read_vector
  params:
    path: "data/city.gpkg"
    layer: "buildings"

# 使用变量
- id: load-data
  use: io.read_vector
  params:
    path: "${input_path}"

常用引用

# 后续步骤引用读取结果
- id: buffer
  use: vector.buffer
  params:
    input: "$load-data"            # 引用 GeoDataFrame
    distance: 100

# 在 when 中引用统计信息
- id: check
  use: qc.geometry_validity
  params:
    input: "$load-data"
  when: "$load-data.feature_count > 0"  # 有数据时才执行检查

# 引用字段列表（用于 QC 步骤）
outputs:
  columns: "$load-data.columns"

7.3 io.write_vector：写入矢量数据

参数

支持的 format 值

输出（StepResult）

示例

# 保存为 GeoJSON
- id: save-geojson
  use: io.write_vector
  params:
    input: "$buffer"
    path: "output/buffer_result.geojson"
    format: "GeoJSON"

# 保存为 Shapefile
- id: save-shapefile
  use: io.write_vector
  params:
    input: "$dissolve"
    path: "output/dissolved.shp"
    format: "Shapefile"

# 保存为 GeoPackage
- id: save-gpkg
  use: io.write_vector
  params:
    input: "$process"
    path: "output/result.gpkg"
    format: "GPKG"

# 使用变量控制格式
- id: save-result
  use: io.write_vector
  params:
    input: "$process"
    path: "${output_path}"
    format: "${output_format}"

说明

• 自动创建目录：输出路径的父目录不存在时会自动创建（mkdir -p）
• 覆盖行为：若目标文件已存在，默认覆盖
• write_vector 输出：output 字段是字符串（文件路径），而非 GeoDataFrame。outputs 声明中引用此步骤得到的是路径字符串。

7.4 io.read_raster：读取栅格数据

参数

输出（StepResult）

示例

# 读取 GeoTIFF
- id: load-dem
  use: io.read_raster
  params:
    path: "data/dem.tif"

# 后续步骤使用栅格数据
- id: calc-ndvi
  use: raster.calc
  params:
    input: "$load-multispectral"
    expression: "(band4 - band3) / (band4 + band3)"
    output_bands: 1

- id: get-stats
  use: raster.stats
  params:
    input: "$load-dem"

7.5 io.write_raster：写入栅格数据

参数

说明

io.write_raster 通常与 raster.* 步骤配合使用，其中 metadata 参数需要从前置步骤获取：

- id: load-raster
  use: io.read_raster
  params:
    path: "data/dem.tif"

- id: reproject-raster
  use: raster.reproject
  params:
    input: "$load-raster"
    target_crs: "EPSG:3857"

- id: save-raster
  use: io.write_raster
  params:
    input: "$reproject-raster"          # 重投影后的数组
    path: "output/dem_3857.tif"
    metadata: "$reproject-raster.metadata"   # 新的元信息（包含更新后的 transform、crs）

7.6 IO 步骤最佳实践

6.1 始终检查 CRS

读取数据后，及时检查坐标系，避免后续分析因 CRS 不匹配而失败：

- id: load-data
  use: io.read_vector
  params: { path: "data/roads.shp" }

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

- id: reproject
  use: vector.reproject
  params:
    input: "$load-data"
    target_crs: "EPSG:3857"

6.2 先用 geopipe-agent info 了解数据

geopipe-agent info data/roads.shp
# 输出：feature_count, crs, geometry_types, columns, bounds

6.3 Shapefile 中文编码

中国区域数据常见 GBK 编码的 Shapefile：

- id: load-cn-roads
  use: io.read_vector
  params:
    path: "data/roads_china.shp"
    encoding: "gbk"              # 避免属性字段中文乱码

6.4 大文件处理建议

对于大型矢量文件，可以先用 vector.query 过滤需要的数据，减少后续处理量：

- id: load-all
  use: io.read_vector
  params: { path: "data/national_roads.shp" }

- id: filter-major
  use: vector.query
  params:
    input: "$load-all"
    expr: "road_class in ['highway', 'primary']"   # 只保留主要道路

7.7 本章小结

本章详细介绍了 4 个 IO 步骤：

1. io.read_vector：支持 GeoJSON、Shapefile、GPKG 等格式，返回 GeoDataFrame，可查看 feature_count、crs、columns 等统计信息
2. io.write_vector：将 GeoDataFrame 写入文件，支持 GeoJSON/Shapefile/GPKG，自动创建输出目录
3. io.read_raster：读取 GeoTIFF 等栅格文件，返回数组+完整元信息（transform、crs、bands等）
4. io.write_raster：将栅格数组和元信息写入 GeoTIFF

下一章将介绍矢量分析步骤，包括缓冲、裁剪、投影转换等 7 个步骤。

导航：← 第六章：条件执行与错误策略 ｜ 第八章：矢量分析步骤 →