7.1 ArcPy：把叠加流水线写成脚本

7.1 ArcPy：把叠加流水线写成脚本

本节摘要：ArcPy 是随 ArcGIS 安装的 Python 站点包，把工具箱里的每一个地理处理工具都变成一个可调用的函数。本节讲清它的模块地图、两种调用风格与脚本的结构化写法（环境、参数、日志、异常），并把第 5 章的超市选址链完整改写成一份可反复执行的参数化脚本，最后鸟瞰 ArcGIS 的开发体系，知道除了 Python 还有哪几扇门。

从二十次点击到一次执行

第 5 章结束时，超市选址的分析链由大约二十次工具箱操作组成。它能跑通，但存在一个隐患：参数记在分析师的脑子里。三个月后人口格网更新、竞品新开两家店，业务方要求重跑——如果链条只是点击，重跑等于把二十个对话框重新填一遍，任何一个参数记错，结果就悄悄偏离，而且没人能发现。

把链条写成脚本，改变的不只是速度。脚本是一份可审计的参数记录：谁在什么时间、用什么数据、按什么条件算出的结果，全部落在代码里。评审者不必追问"缓冲半径到底是 200 还是 300"，读一行代码就有答案。这是本章"第一层放大"的实质：分析能力从个人技能变成组织资产。

ArcPy 之所以能承担这个角色，源于它的出身：它不是外挂的第三方库，而是 ArcGIS 官方随软件一起安装的 Python 站点包。你在工具箱对话框里点下的每一个工具，在 ArcPy 里都有一个同名函数——工具的参数表就是函数的参数表，工具的联机帮助就是函数文档。会点工具箱的人，离会写脚本只差一层语法窗户纸。

模块地图：四个常用的门牌

ArcPy 的函数按职能分住在几个命名空间里，记住门牌号就不会迷路：

arcpy.management.*    数据管理：复制、筛选、字段增删、索引、投影定义
arcpy.analysis.*      叠加分析：缓冲、相交、擦除、空间连接、近邻
arcpy.sa.*            空间分析扩展：地图代数、重分类、栅格计算器
arcpy.mp.*            地图工程自动化：批量操作布局、图层、导出出图

调用风格一（模块式，推荐）:
  arcpy.analysis.Buffer("roads", "road_buf", "200 Meters")
调用风格二（通用入口式）:
  arcpy.Buffer_analysis("roads", "road_buf", "200 Meters")
  两者是同一工具的两种写法；模块式参数含义更醒目，本教程统一用它
​

第 6 章的地图代数在 arcpy.sa 里兑现为算子语法——Raster("slope") * 3 + Raster("landuse_score") 这样的表达式可以直接写进脚本，与矢量工具混排成一条完整的流水线。arcpy.mp 则是制图师的批量助手：一晚上给三十个乡镇各导出一张标准布局的图，靠的是它而不是加班。

工具函数的返回值是一个 Result 对象，这是新手常踩的第一个坑：GetCount 返回的不是数字，要再取一层输出才是。

import arcpy
arcpy.env.workspace = r"K:/gisdata/site_select.gdb"
# Result 对象的正确取值姿势
res = arcpy.management.GetCount("final_clean")
n = int(res.getOutput(0))          # getOutput(0) 才是真正的计数字符串
print("候选地块数:", n)             # 输出: 候选地块数: 7
# 直接 print(res) 也能看到值，但参与运算前务必显式转换类型
​

一份像样的脚本长什么样

能跑的脚本和能交接的脚本之间，隔着四样东西：环境声明、参数化、日志、异常处理。下面这份骨架是本教程所有脚本的模板：

import arcpy
import datetime

def run_site_select(gdb, min_area, max_area, own_buf_m, comp_buf_m):
    """选址链 v2：参数全部显式传入，杜绝散落在对话记录里的魔法数字"""
    log = lambda msg: print(f"[{datetime.datetime.now():%H:%M:%S}] {msg}")
    arcpy.env.workspace = gdb
    arcpy.env.overwriteOutput = True
    try:
        log(f"开始，面积区间 {min_area}-{max_area} 平米")
        arcpy.management.SelectLayerByAttribute(
            "parcels", "NEW_SELECTION",
            f"面积_平米 >= {min_area} AND 面积_平米 <= {max_area} AND 用地类型 IN ('居住','商服')")
        arcpy.management.CopyFeatures("parcels", "cand_pool")
        n = int(arcpy.management.GetCount("cand_pool").getOutput(0))
        log(f"候选池 {n} 块")
        if n == 0:
            raise ValueError("候选池为空，请检查面积区间与用地类型字段")
        # ...中间各段与 5.4 节相同，此处从略
        return "final_clean"
    except arcpy.ExecuteError:
        # 地理处理工具报的错走这里：带工具名与错误码，直接透传
        print("GP错误:", arcpy.GetMessages(2))
        raise
    except Exception as e:
        print("脚本错误:", e)
        raise

if __name__ == "__main__":
    run_site_select(r"K:/gisdata/site_select.gdb", 1500, 5000, 1200, 400)
​

四个结构各有用处。环境声明放在函数体开头，workspace 决定相对路径指向哪、overwriteOutput 决定中间结果能否覆盖——不声明它们，脚本换个机器就出灵异故障。参数化把 5.4 节里写死的 1200 米、400 米变成入参：变式测试从"改五处代码"变成"传一组新参数"。日志让长时间任务有进度可看，也让事后排查有时间线。异常分层把工具错误（ExecuteError，带 GP 错误码）与普通逻辑错误分开，前者透传 ArcGIS 的详细消息，后者给出业务语义。

再进一步，把硬编码的路径换成 arcpy.GetParameterAsText(0)，脚本就能挂进工具箱变成带界面的自定义工具，同事双击填框即可使用——这是脚本资产化的最后一公里。

图：一份结构化脚本的分层 anatomy

完整演练：选址链三个月后的重跑

场景回到本章开头：人口格网更新到 v2，竞品层补录两家新店，重跑选址。参数化脚本此时的价值直接兑现——两次调用、两个版本的结果并排放在库里：

import arcpy
res = run_site_select(r"K:/gisdata/site_select.gdb", 1500, 5000, 1200, 400)
# 日志输出节选:
# [09:12:03] 开始，面积区间 1500-5000 平米
# [09:12:41] 候选池 217 块          （地块层并入一块新出让居住用地）
# [09:13:26] 五关全过: 6 块         （竞品补录后 G-041 被新店 400 米圈擦除）
# [09:14:02] 净化后: 6 块
# 与上一版差异: G-041 出局，G-112 仍以 9.35 分居首，领先幅度扩大
arcpy.management.CopyFeatures(res, "result_2026q3")
# 结果留在 result_2026q3，与三个月前的 result_2026q2 并存，评审可对比
​

这次重跑用了不到两分钟，且每一步的差异都有日志可查。对比 5.4 节的手工执行，这才是"分析能力沉淀为资产"的样子：数据在变，链条不动，结论可追溯版本。

顺带鸟瞰：ArcGIS 开发体系的全景

ArcPy 之外，ArcGIS 还为不同角色开了别的门。选错门是常见的时间浪费——用桌面自动化思路去写 Web 应用，或用前端框架调地理处理，都会事倍功半：

判断口径只有一条：先定消费场景，再选开发入口。结果给分析师自己用，ArcPy；结果给组织全员在浏览器里用，走下一节的上云链路，前端用 JS API；要把 ArcGIS 能力嵌进既有业务系统，REST 是通用语言。本节把桌面这一扇门推开，下一节推开云端那扇。

本节要点回顾

• 资产化动机：脚本把参数从人脑搬进代码，评审可审计、三个月后可重跑
• 模块门牌：management 管数据、analysis 管叠加、sa 管栅格代数、mp 管制图自动化
• 两种调用风格：模块式与通用入口式是同一工具的两种拼写，本册统一模块式
• Result 对象：返回值要 getOutput 取出再显式转型，新手第一坑
• 四层结构：参数、环境、工具调用、日志异常——能跑与可交接的分界线
• 入口选型：先定消费场景再选开发入口，桌面自动化只回答桌面的问题