河流中心线生成工具

本仓库提供一个独立脚本 river_centerline.py，用于从河流水面 polygon 中生成主航道中心线。脚本重点面向存在岛屿、内环或副汊水体的河段：先裁掉非主航道侧水体，得到主航道面，再基于主航道面重新生成中心线。

适用场景

• 河流面中存在岛屿、内环或副汊。
• 已有上游点和下游点，可用于确定河段方向。
• 希望输出主航道面、中心线、中心点、横断面和 QA 报告。
• 输入数据使用投影坐标系，距离单位可按米理解。

如果河流面没有岛屿或副汊，也可以运行该脚本；在没有可用岛区诊断报告时，脚本会直接基于输入面生成中心线主路径，不执行副汊裁剪。

环境要求

脚本依赖 ArcGIS Pro 的 arcpy，请在能够导入 arcpy 的 Python 环境中运行。

可先执行：

python river_centerline.py --help

如果提示无法导入 arcpy，说明当前 Python 环境不满足要求，需要切换到 ArcGIS Pro 配套 Python。

输入数据

河流面

参数：

--input-polygon

要求：

• polygon SHP 或 ArcGIS 要素类。
• 表示完整河流水面。
• 坐标系建议为投影坐标系。

上下游端点

参数：

--endpoint-points

要求：

• point SHP 或 ArcGIS 要素类。
• 必须包含 RoleCode 字段。
• RoleCode 中应分别有一个 UPSTREAM 和一个 DOWNSTREAM。

岛区诊断报告

参数：

--island-report

可选 JSON 文件。若报告中包含 island_diag 和 sample_lines，脚本会据此构造副汊裁剪面。若不提供该参数，脚本不会裁副汊，只基于输入河流面生成中心线。

左右岸点

参数：

--bank-points

可选点层。若提供，脚本会优先用该点层重新采样并诊断岛区。点层应包含岸线顺序、岸别和端点角色等字段，例如 BankCode、BankSeq、RoleCode。

基本运行

python river_centerline.py `
  --input-polygon <river_polygon.shp> `
  --endpoint-points <endpoint_points.shp> `
  --out-dir <output_directory>

带岛区诊断报告运行：

python river_centerline.py `
  --input-polygon <river_polygon.shp> `
  --endpoint-points <endpoint_points.shp> `
  --island-report <island_report.json> `
  --out-dir <output_directory>

如果希望允许裁剪证据较弱但可由左右侧累计宽度推断的岛区，可增加：

--include-weak-islands

如果需要生成 QA 总览图和岛区局部图，可增加：

--emit-maps

主要参数

--buffer-m

副汊裁剪面缓冲距离，默认 18.0 米。增大后可减少裁剪条带之间的窄缝，但过大可能误裁主航道。

--include-weak-islands

允许裁剪诊断证据较弱的岛区。新数据建议先不开启，检查报告中的 skipped_islands 后再决定。

--sample-step-m

左右岸重采样步长。步长越小，中心线点越密，运行时间越长。

--max-station-gap-m

横断面匹配时，对岸候选点累计距离差上限。

--max-width-ratio

单条横断面相对参考宽度的最大倍数，用于排除异常长横断面。

--max-width-jump-ratio

相邻横断面宽度跳变允许的最大倍数。

--centerline-smooth-iterations

中心线平滑迭代次数。平滑用于减少局部抖动，不应用来掩盖明显错误的裁剪方向。

--min-island-clearance-m

中心线点到岛环的最小距离约束，默认 1.0 米。

输出结果

脚本会在 --out-dir 下创建分阶段目录：

01_input/           输入数据快照
02_side_channels/   被裁掉的副汊水体面
03_main_channel/    主航道面
04_centerline/      中心线、中心点、横断面和源岸点
05_boundary_nodes/  原水面、主航道面和其他水体边界节点
06_qa/              几何检查、JSON 报告和可选验收图
scratch.gdb/        临时工作库

最常用成果：

03_main_channel/<input_name>_main_channel_polygon_repaired.shp
04_centerline/<input_name>_main_centerline.shp
04_centerline/<input_name>_main_centerline_midpoints.shp
04_centerline/<input_name>_bank_method_sections.shp
06_qa/main_channel_centerline_report.json

QA 检查

优先查看：

06_qa/main_channel_centerline_report.json

重点字段：

• cut_polygon_count：实际裁掉的副汊面数量。
• cut_area_sum：副汊裁剪面积。
• main_centerline_count：最终中心线数量，通常应为 1。
• center_point_outside_count：中心点落在主航道面外的数量，应为 0。
• centerline_outside_length：中心线在主航道面外的长度，应接近 0。
• island_clearance：中心点到岛环的最小距离统计。
• check_geometry：主要输出的 ArcGIS 几何错误数。
• skipped_islands：未裁剪岛区及其原因。

建议在 ArcGIS Pro 中叠加查看完整水面、副汊裁剪面、主航道面、最终中心线、横断面和边界节点。验收重点是副汊裁剪方向是否正确、主航道面是否连续、中心线是否位于面内、岛区附近是否贴岛或绕错侧。

常见问题

无法导入 arcpy

当前 Python 环境不包含 ArcGIS Pro 的 arcpy。请切换到 ArcGIS Pro 配套 Python 后再运行。

没有裁掉副汊

查看报告中的 skipped_islands.reason。常见原因是有效采样线不足、没有可靠 main_channel_side，或未开启 --include-weak-islands。

中心线落到面外

检查主航道面几何、横断面图层、center_point_outside_count 和 centerline_outside_length。如果主航道面已经被误裁，应先修正裁剪方向。

中心线贴近岛环

检查 island_clearance、--buffer-m 和 --min-island-clearance-m。如果裁剪方向错误，单纯调大平滑参数不会得到可信结果。

运行较慢

先关闭 --emit-maps 和 --emit-island-debug，再适当增大 --sample-step-m。