11 地图脚本 map scripting

11.1 介绍

本章介绍 ArcPy 映射模块，也称为 arcpy.mp。该模块的主要目的是操作现有项目 (.aprx) 和图层文件 (.lyrx) 的内容。这包括使用地图、图层和表格；应用符号学；和管理布局。
注意：尽管该模块被称为“映射”模块，但这个名称可能会造成混淆。 ArcGIS Desktop 10.x 中 ArcPy 中的模块称为 arcpy.mapping，但 ArcGIS Pro 的功能变化很大，该模块被替换为 arcpy.mp 模块。然而，更一般地说，该模块的目的是相同的——即自动化映射任务。因此，它仍然被称为“映射”模块，尽管实际名称是 arcpy.mp。
映射模块包含许多函数和类。需要非常熟悉 ArcGIS Pro 中与地图相关的任务才能利用 Python 的地图模块，因为许多函数和类复制了 ArcGIS Pro 应用程序中的典型工作流。

11.2 使用 ArcPy mapping模块

ArcPy 制图模块自动化 ArcGIS Pro 工作流以加快重复性任务。 ArcPy 映射模块的一些典型使用示例如下：

查找具有特定数据源的图层并将其替换为另一个数据源

在多个地图中修改特定图层的显示属性

生成描述项目内容的报告，包括地图、图层、表格和布局

搜索和替换文本项目中多个布局中的字符串

高度可视化的 ArcGIS Pro 环境是用于创建新工程以及在工程中创建地图、图层和布局的推荐应用程序。但是，一旦创建它们，ArcPy 映射模块就可以自动执行某些映射任务，尤其是跨多个元素的重复性任务。
ArcPy 制图模块允许您自动执行通常使用 ArcGIS Pro 执行的许多任务。
使用 ArcPy 制图模块遵循 ArcGIS Pro 会话中使用的工作流。
例如，典型的工作流程包括打开项目、修改地图属性、添加图层、修改该图层的属性、更改布局的多个元素，然后将该布局导出到 PDF 文件。使用 ArcPy 映射模块的函数和类的脚本会自动执行这些步骤。

11.3 参考项目

ArcGIS Pro 中的工程以 .aprx 文件的形式存储在磁盘上，例如 C:\Mapping\Study.aprx。除了包含单个图层属性的图层文件 (.lyrx) 之外，ArcPy 映射模块还允许您引用和操作 .aprx 文件。
使用 ArcPy 映射模块开始处理工程的方法有两种：(1) 引用存储在磁盘上的现有 .aprx 文件，或 (2) 使用当前 ArcGIS Pro 会话中的工程。 arcpy.mp.ArcGISProject() 函数实现了这两者。这个函数的语法是：

arcpy.mp.ArcGISProject(aprx_path)

aprx_path 参数是一个字符串，表示磁盘上 .aprx 文件的完整路径。以下代码引用了一个 ArcGIS Pro 工程：

aprx = arcpy.mp.ArcGISProject("C:/Mapping/Study.aprx")

此处选择的变量名与文件扩展名相同，但不需要这种命名方式。你可以给它起任何其他的名字（例如，project 或 myproject），但是 aprx 简短而清晰，因此你会在许多示例脚本中看到它，包括在本书中。

这种方法是通用的，因为它既适用于 ArcGIS Pro 应用程序，也适用于独立脚本。因此，这种语法是最广泛使用和推荐的方法。

要在 ArcGIS Pro 中使用当前工程，请使用关键字 CURRENT（全部大写）：

aprx = arcpy.mp.ArcGISProject("CURRENT")

要使用 CURRENT 关键字，ArcGIS Pro 必须正在运行，并且此方法只能在 ArcGIS Pro 应用程序中使用。这包括在 ArcGIS Pro 的 Python 窗口中运行代码或运行脚本工具。 CURRENT 关键字不适用于独立脚本，因为 ArcGIS Pro 应用程序在运行时无法识别。
使用现有 .aprx 文件时，脚本可以独立于 ArcGIS Pro 运行。建议使用系统路径打开 ArcGIS Pro 工程，因为它可以使您的代码更加通用，并且可以更好地控制脚本的运行方式。尽管如此，使用 CURRENT 关键字对于在 Python 窗口中快速测试代码很有用。每当您看到示例脚本中使用的 CURRENT 关键字时，通常可以将其替换为 .aprx 文件的完整路径。

ArcGISProject() 函数返回一个 ArcGISProject 对象。换句话说，ArcGISProject 既是 arcpy.mp 模块的一个函数，也是一个类。 ArcGISProject 类提供对项目的许多不同属性和方法的访问。该类还提供对项目中其他对象的访问。例如，要获取地图、图层或布局，您必须首先引用 ArcGISProject 对象。因此，ArcGISProject 对象通常是在映射脚本中创建的第一个对象引用。

一旦创建了 ArcGISProject 对象，就可以读取和修改项目的属性。在查看这些更改是如何进行的之前，首先要考虑它们是如何保存的。如果您在 ArcGIS Pro 中处理工程并进行更改（例如添加图层），则有两种方法可以保存 .aprx 文件：保存和另存为。使用 Save 时，更改将保存到同一个 .aprx 文件；当使用另存为时，更改将保存到您指定的新 .aprx 文件中。在脚本环境中，ArcGISProject 对象使用 save() 和 saveACopy() 方法。 saveACopy() 方法的作用与 ArcGIS Pro 应用程序中的另存为选项相同。

在脚本中引用 ArcGISProject 对象时，.aprx 文件将被锁定。此锁可防止其他应用程序对文件进行更改。因此，当脚本中不再需要对项目的引用时，最好使用 Python del 语句删除对项目的引用。此语句不会删除实际的 .aprx 文件，只会删除对内存中对象的引用。因此，映射脚本通常具有如下结构：

import arcpy
aprx = arcpy.mp.ArcGISProject("C:/Mapping/Study.aprx")
<code that modifies project properties>
aprx.save()
del aprx

当脚本完成运行时，Python 会自动删除对对象的引用，因此 del 语句不是必需的，但仍会减少不必要的锁定的可能性。
本章中的大多数示例代码都引用了磁盘上的 .aprx 文件，而不是使用 CURRENT 关键字。尽管如此，大多数示例也可以使用 CURRENT 关键字在 Python 窗口中运行。

要引用磁盘上的 .aprx 文件，您必须提供完整路径，例如 C:\Mapping\Study.aprx。
与使用数据集和其他文件相反，为 .aprx 文件设置工作区是不够的。
考虑以下代码：

import arcpy
arcpy.env.workspace = "C:/Mapping"
aprx = arcpy.mp.ArcGISProject("Study.aprx")

除非脚本与 .aprx 文件位于同一文件夹中，否则设置工作区无效并产生错误。换句话说，诸如 arcpy.mp.ArcGISProject("Study .aprx") 之类的引用仅在脚本和 .aprx 文件位于同一文件夹中时才有效。否则，您必须提供完整路径。但是，许多脚本出于其他原因使用工作区。如果 .aprx 文件位于同一工作区中，您可以使用以下代码来引用完整路径：

import arcpy
import os
ws = "C:/Mapping"
arcpy.env.workspace = ws
aprxpath = os.path.join(ws, "Study.aprx")
aprx = arcpy.mp.ArcGISProject(aprxpath)

本章中的示例通常对完整路径进行硬编码

11.4 访问项目属性和方法

ArcGISProject 对象的属性包括基本的描述性属性，例如 activeMap（与焦点视图关联的地图）、dateSaved（上次保存项目的日期）、documentVersion（上次保存时的文档版本）和 filePath （完整的项目路径和文件名）。
这些属性都是只读的。其他几个属性是可读写的，包括 defaultGeodatabase（项目的默认地理数据库位置）、defaultToolbox（项目的默认工具箱）和 homeFolder（项目的主文件夹位置）。
例如，以下代码打印一些只读属性：

import arcpy
aprx = arcpy.mp.ArcGISProject("C:/Mapping/Demo.aprx")
print(aprx.documentVersion)
print(aprx.filePath)
del aprx

del 语句确保删除项目锁定。
脚本的打印输出如下：

2.5.0
C:/Mapping/Demo.aprx

要更改其中一个读写属性，必须为该属性分配一个新值，并且必须保存项目，如下所示：

import arcpy
aprx = arcpy.mp.ArcGISProject("C:/Mapping/Demo.aprx")
aprx.defaultGeodatabase = "C:/Mapping/Data.gdb"
aprx.save()
del aprx

尽管第三行代码看起来像一个简单的赋值语句，但该代码验证了地理数据库的完整路径和文件名。如果地理数据库不存在，则赋值语句会导致错误。
当您查看这些示例时，请记住它们可用于自动化更复杂的任务，例如更改多个项目而不仅仅是一个项目。

除了属性之外，ArcGISProject 对象还提供了几个方法，包括已经提到的 save() 和 saveACopy() 方法，以及处理项目内容的方法。
这些方法在这里进行了一些详细的回顾。

importDocument() 方法可以将地图文档（.mxd 文件）、globe 文档（.3dd 文件）和场景文档 (.sxd) 导入到工程中。 ArcGIS Desktop 10.x 使用单独的应用程序来处理这些文档，即分别为 ArcMap、ArcGlobe 和 ArcScene。这些应用程序的功能已集成到 ArcGIS Pro。您还可以导入地图文件 (.mapx)、布局文件 (.pagx) 和报告文件 (.rptx) 的内容。该方法的语法如下：

ArcGISProject.importDocument(document_path, {include_layout},
                                    {reuse_existing_maps})

document_path 变量由一个字符串组成，该字符串表示文档的完整路径和名称。
您一次只能导入一个文档，因此要导入多个文档，您必须重复该方法。地图文档始终包含布局，而globe 文档和场景文档不包含。可选的 include_layout 参数是一个布尔值，用于指示是否要导入布局。默认值为真。如果此参数设置为 False，则仅将地图文档的数据框导入为地图，而不是布局。可选的reuse_existing_maps 参数是一个布尔值，以避免在导入布局文件(.pagx) 时复制地图。以下示例说明了如何导入地图文档：

import arcpy
aprx = arcpy.mp.ArcGISProject("C:/Mapping/Demo.aprx")
aprx.importDocument("C:/Mapping/Austin.mxd")
aprx.saveACopy("C:/Mapping/Demo_copy.aprx")
del aprx

地图文档由一个或多个数据框和一种布局组成。原始数据框和布局将转换为 ArcGIS Pro 地图和布局格式。在 Python 中使用此方法导入地图文档类似于在 ArcGIS Pro 中执行相同的任务。在 ArcGIS Pro 的目录窗格中，导航到 .mxd 文件，单击鼠标右键，然后单击导入并打开。 arcpy.mp 模块尝试在 ArcGIS Pro 中复制其中一些映射工作流，但存在差异。在这种情况下，importDocument() 方法为您提供排除布局的选项（在 ArcGIS Pro 中使用 Import and Open 是不可能的），而在 ArcGIS Pro 中使用 Import and Open 会打开其中一个地图或视图中的布局（这 importDocument() 不这样做）。

导入地图文档时，识别您正在导入的内容非常重要。 .mxd 文件中的每个数据框都成为 .aprx 文件中的地图。此地图包括所有图层及其符号系统。 .mxd 文件中的唯一布局成为 .aprx 文件中的布局。此布局包括所有布局元素，包括比例尺、图例等。您没有导入任何数据文件。图层继续引用相同的数据源，并且不会复制任何数据文件。

ArcGISProject 类包括两种处理损坏数据源的方法：
listBrokenDataSources() 和 updateConnectionProperties()。 ArcGISProject 类的其余方法用于列出项目的内容。这些方法包括以下内容：
listColorRamps()—返回 ColorRamp 对象列表
listLayouts()—返回 Layout 对象列表
listMaps()—返回 Map 对象列表
listReports()—返回 Report 对象列表

这些方法返回一个对象列表，因此其工作方式类似于 ArcPy 中的列表函数。但是，它们不是 arcpy.mp 的函数，而是 ArcGISProject 对象的方法。这些方法返回一个对象列表，每种类型的对象对应于 arcpy.mp 模块的一个类。以下部分介绍如何使用这些方法和生成的对象。

arcpy.mp 模块的限制之一是它不能用于从头开始创作新项目，您只能使用现有项目。同样，您不能创建项目的许多其他典型元素，包括地图、布局和布局元素。一个例外是 GraphicElement 和 TextElement 对象都有一个 clone() 方法来在布局上创建这些元素的副本。 arcpy.mp 模块的设计原则是使用 ArcGIS Pro 应用程序创作项目及其内容，然后使用 arcpy.mp 自动执行重复性任务，例如修改地图属性、添加图层、应用符号系统和导出布局.

如果您需要在脚本中从头开始一个新工程，一种解决方法是在 ArcGIS Pro 中创作一个基本模板工程。该项目将仅包含最少的元素，即至少一张地图和一种布局，然后您可以使用 arcpy.mp 操作内容。

11.5 Working with maps

ArcGIS Pro 中的地图表示符号化地理数据图层和表格数据的集合。一个项目包含一个或多个地图，每个地图通常包含一个或多个图层和或表格。
地图、图层和表格是在列表中使用的完美对象，可以帮助自动执行任务。
要在 ArcGIS Pro 中可视化地图的内容，请打开地图视图或将地图框添加到布局中。
同一张地图可以显示在多个地图视图或地图框中。更改地图的图层也会更改引用该地图的所有地图视图和地图框。使用 ArcGISProject 类的 listMaps() 方法访问地图。此方法返回项目中的 Map 对象列表。语法是：

ArcGISProject.listMaps({wild_card})

该方法可以简称为 listMaps() 而不是 ArcGISProject.listMaps()。
但是，映射模块有几个类，每个类都有几个方法。其中一些方法具有相同的名称，而另一些则非常相似。为避免混淆，本章中对方法的引用在解释语法时使用