DataDrivenPages (arcpy.mapping)
摘要
用于提供对已启用“数据驱动页面”的地图文档内管理各个页面的方法和属性的访问。
讨论
可使用 ArcMap 内的数据驱动页面 工具条来创建系列地图，而无需编写任何脚本。反之亦然：可使用 arcpy.mapping 编写系列地图的全部脚本，而无需使用 ArcMap 中的“数据驱动页面”用户界面，但将两种方法相结合的效果更优。ArcMap 的“数据驱动页面”工具条可能没有足够的选项来创建“完美的”系列地图，但启用了“数据驱动页面”的地图文档可利用其固有行为省去多行代码，例如地图文档可自动管理页面范围、比例和动态文本等内容，所以不必写入相应代码。
当文本元素的字符串信息需要使用自定义逻辑进行格式化或需要构建多个字段时，即属上述情形之一。不必为这样一个简单的自定义需求在 arcpy.mapping 中执行所有操作。可通过启用“数据驱动页面”制作地图文档，然后利用 arcpy.mapping 处理自定义的文本元素字符串需求。具体的代码示例如下。
首先必须使用 ArcMap 中的“数据驱动页面”工具条在地图文档 (.mxd) 内启用和制作数据驱动页面，然后才能通过 arcpy.mapping 引用“数据驱动页面”。
DataDrivenPages 类只有一个单独的 exportToPDF 方法，但这并不意味着不能创建其他导出文件。请参阅下面的第一个代码示例。
有关“数据驱动页面”的详细信息，请参阅以下主题：
属性
| 属性 | 说明 | 数据类型 |
| currentPageID (读写) |
The currentPageID property represents the active or current page for a map document (.mxd) that has Data Driven Pages enabled. This value is displayed in the Data Driven Pages toolbar when Show Page is selected; it represents the x of x of y. | Long |
| dataFrame (只读) |
Returns a reference to the data frame the index layer resides within a Data Driven Pages enabled map document. | DataFrame |
| indexLayer (只读) |
Returns a reference to the index layer in a Data Driven Pages enabled map document. | Layer |
| pageCount (只读) |
The pageCount property returns the total page count for a map document (.mxd) that has Data Driven Pages enabled. This value is displayed in the Data Driven Pages toolbar when Show Page is selected; it represents the y of x of y. | Long |
| pageNameField (只读) |
Returns a field object that represents the field used in the index feature class when setting up Data Driven Pages. | Field |
| pageRow (只读) |
Use pageRow to return the index layer's row object for the active or current page. The index layer fields can then be read and/or modified as necessary. | Row |
| selectedPages (只读) |
Returns a Python list of index numbers that represent selected index layer features in a Data Driven Pages enabled map document. | List |
方法概述
| 方法 | 说明 |
| exportToPDF (out_pdf, {page_range_type}, {page_range_string}, {multiple_files}, {resolution}, {image_quality}, {colorspace}, {compress_vectors}, {image_compression}, {picture_symbol}, {convert_markers}, {embed_fonts}, {layers_attributes}, {georef_info}, {jpeg_compression_quality}, {show_selection_symbology}) |
将启用了“数据驱动页面”的地图文档 (.mxd)的一组指定页面导出为多页面的 PDF 文档 |
| getPageIDFromName (page_name) |
Returns a Data Driven Pages index value based on the name of the page |
| printPages ({printer_name}, {page_range_type}, {page_range_string}, {out_print_file}, {show_selection_symbology}) |
以特定打印机打印启用数据驱动页面的地图文档 (.mxd) 中的特定页面 |
| refresh () |
Refreshes an existing Data Driven Pages series |
方法
| 参数 | 说明 | 数据类型 |
out_pdf |
A string that represents the path and file name for the output export file. | String |
page_range_type |
The string value that designates how the pages will be printed, similar to the Pages tab within the ArcMap Export Map dialog box for PDF documents.
(默认值为 ALL) | String |
page_range_string |
A string that identifies the pages to be printed if the RANGE option in the page_range_type parameter is used (for example, 1, 3, 5-12). | String |
multiple_files | An option to control how the output PDF is created. By default, all pages are exported into a single, multipage document. You can also specify that individual, single-page PDF documents be exported using two different options.
(默认值为 PDF_SINGLE_FILE) | String |
resolution |
An integer that defines the resolution of the export file in dots per inch (dpi). (默认值为 300) | Integer |
image_quality |
A string that defines output image quality.
(默认值为 BEST) | String |
colorspace |
A string that defines the color space of the export file.
(默认值为 RGB) | String |
compress_vectors |
A Boolean that controls compression of vector and text portions of the output file. Image compression is defined separately. (默认值为 True) | Boolean |
image_compression |
A string that defines the compression scheme used to compress image or raster data in the output file.
(默认值为 ADAPTIVE) | String |
picture_symbol |
A string that defines whether picture markers and picture fills will be converted to vector or rasterized on output.
(默认值为 RASTERIZE_BITMAP) | String |
convert_markers |
A Boolean that controls the conversion of character-based marker symbols to polygons. This allows the symbols to appear correctly if the symbol font is not available or cannot be embedded. However, setting this parameter to True disables font embedding for all character-based marker symbols, which can result in a change in their appearance. (默认值为 False) | Boolean |
embed_fonts |
A Boolean that controls the embedding of fonts in an export file. Font embedding allows text and character markers to be displayed correctly when the document is viewed on a computer that does not have the necessary fonts installed. (默认值为 True) | Boolean |
layers_attributes |
A string that controls inclusion of PDF layer and PDF object data (attributes) in the export file.
(默认值为 LAYERS_ONLY) | String |
georef_info |
A Boolean that enables exporting of coordinate system information for each data frame into the output PDF file. (默认值为 True) | Boolean |
jpeg_compression_quality | A number that controls compression quality value when image_compression is set to ADAPTIVE or JPEG. The valid range is 1 to 100. A jpeg_compression_quality of 100 provides the best quality images but creates large export files. The recommended range is between 70 and 90. (默认值为 80) | Integer |
show_selection_symbology |
A Boolean that controls whether the selection symbology should be displayed in the output. (默认值为 False) | Boolean |
数据驱动页面导出为多页面的 PDF 文档。地图文档必须已启用“数据驱动页面”。PDF 文件可在不同的平台中查看和打印，并且格式始终如一。通常用于在 Web 上分发文档，此格式现在为内容传送的标准交换格式。ArcMap PDF 在许多图形应用程序中均可编辑，并会保留 ArcMap 内容列表中的注记、标注和属性数据。从 ArcMap 中导出的 PDF 支持嵌入字体，因此即使用户尚未安装 Esri 字体也可以正确地显示符号。从 ArcMap 中导出的 PDF 可以通过 CMYK 值或 RGB 值定义颜色。
有关导出地图的详细信息，请参阅 ArcGIS for Desktop 帮助中的导出地图主题。
| 参数 | 说明 | 数据类型 |
page_name |
A value in the index layer that corresponds to the Name field that was used to set up Data Driven Pages | String |
Many of the Data Driven Pages properties and methods use an internal index value rather than the literal names of the pages used to create the index layer. The index values are automatically generated based on the Name and Sort fields. It may not be obvious which index value represents a specific page. The getPageIDFromName method provides a mechanism for this translation.
pageID = mxd.dataDrivenPages.getPageIDFromName("HarborView")
mxd.dataDrivenPages.currentPageID = pageID
| 参数 | 说明 | 数据类型 |
printer_name |
A string that represents the name of a printer on the local computer. (默认值为 None) | String |
page_range_type |
The string value that designates how the pages will be printed, similar to the Pages tab within the ArcMap Export Map dialog box for PDF documents.
(默认值为 ALL) | String |
page_range_string |
A string that identifies the pages to be printed if the RANGE option in the page_range_type parameter is used (for example, 1, 3, 5-12). | String |
out_print_file |
A path that includes the name of an output print file. The format created is dependent on the printer. If you're using a PostScript printer, the format will be PostScript, and it is recommended that a .ps extension be provided. If you're using a Windows printer, use a .prn extension. (默认值为 None) | String |
show_selection_symbology |
A Boolean that controls whether the selection symbology should be displayed in the output. (默认值为 False) | Boolean |
ListPrinterNames() 函数是获得 printer_name 参数字符串的一种简单方法。
注:ArcGIS for Server 不支持基于驱动程序进行打印。对于作为地理处理服务的“数据驱动页面”打印任务，请在 DataDrivenPages 类中使用 exportToPDF 函数。有关在 Web 应用程序中进行常规打印的详细信息，请参阅在 Web 应用程序中打印。
以下脚本采用本地打印机打印一组特定“数据驱动页面”：
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\ParcelAtlas.mxd")
mxd.dataDrivenPages.printPages(r"\\olyfile\OLYCanon", "RANGE", "1,3,5-12")
You will want to use the refresh method if one of the following occurs: (1) features are added to or deleted from your index layer; (2) edits are made to the Sort or Name field values; (3) the data frame extent is changed due to zooming, panning, or change to map scale; or (4) edits are made to any field being used by Data Driven Pages for an index layer feature that is driving the current geographic extent. Data Driven Pages will retain the original settings in these cases until the refresh method is executed.
代码实例
以下脚本将“数据驱动页面”系列的每一页导出到单个 PNG 文件中。
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\ParcelAtlas.mxd")
for pageNum in range(1, mxd.dataDrivenPages.pageCount + 1):
mxd.dataDrivenPages.currentPageID = pageNum
print "Exporting page {0} of {1}".format(str(mxd.dataDrivenPages.currentPageID), str(mxd.dataDrivenPages.pageCount))
arcpy.mapping.ExportToPNG(mxd, r"C:\Project\OutPut\ParcelAtlas_Page" + str(pageNum) + ".png")
del mxd
以下脚本将使用页面名称列表打印一组地图页面，并使用自定义逻辑代码修改文本元素地图标题信息，该自定义逻辑只能在脚本环境中完成（也就是说，标题字符串是基于属性值自定义构建的）。脚本在各已命名页面间循环，并设置相应的 currentPageID。然后从名为 TRS 的索引图层的字段中提取值。接下来，脚本将分析这些值、去掉前导零、重新构建文本元素标题字符串，并将结果发送给打印机。
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\ParcelAtlas.mxd")
pageNameList = ["MPB", "PJB", "AFB", "ABB"]
for pageName in pageNameList:
pageID = mxd.dataDrivenPages.getPageIDFromName(pageName)
mxd.dataDrivenPages.currentPageID = pageID
fieldValue = mxd.dataDrivenPages.pageRow.TSR #example values from a field called TSR are "080102", "031400"
TRSTitle = arcpy.mapping.ListLayoutElements(MXD, "TEXT_ELEMENT", "TRSTitle")[0]
township, range, section = fieldValue[:2].strip("0"), fieldValue[2:-2].strip("0"), fieldValue[-2:].strip("0")
if section != "":
TRSTitle.text = "Section {0} T.{1}N. R.{2}W. W.M.".format(section, township, range)
else:
TRSTitle.text = "T.{0}N. R.{1}W. W.M.".format(township, range)
mxd.dataDrivenPages.printPages(r"\\olyfile\SUITE_303", "CURRENT")
del mxd
以下脚本仅将所选的索引页面（页面 1-10）导出到各个 PDF 文件中。生成的 PDF 文件会将索引号追加到输出文件名中。
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\ParcelAtlas.mxd")
ddp = mxd.dataDrivenPages
indexLayer = ddp.indexLayer
arcpy.SelectLayerByAttribute_management(indexLayer, "NEW_SELECTION",
'"PageNumber" >= 1 AND "PageNumber" <= 10')
for indexPage in ddp.selectedPages:
ddp.currentPageID = indexPage
ddp.exportToPDF(r"C:\Project\Output\Page" + str(indexPage) + ".pdf", "CURRENT")
del mxd