返回顶部

MapSeries

在本主题中

  1. 摘要
  2. 说明
  3. 属性
  4. 方法概述
  5. 方法
  6. 代码示例

摘要

通过 MapSeries 对象，可以访问用于管理空间地图系列的属性和方法。

说明

可以使用 Layout 对象的 mapSeries 属性或 createSpatialMapSeries 方法引用现有空间地图系列。 您将传入 MapFrame 对象、index_layer 值、name_field 值和其他可选参数以创建空间地图系列。

注：

Arcpy.mp 支持两种类型的地图系列：空间和书签。 mapSeries 类表示空间地图系列。 如果存在空间地图系列，则 Layout 对象的 mapSeries 属性将返回 MapSeries 对象，如果未显示地图系列，则会返回 BookmarkMapSeries 对象或 NoneType 值。

可以使用 MapSeries 类访问空间地图系列中的单个页面以进行自定义。 例如，如果需要使用自定义逻辑对文本元素的字符串信息进行格式化，则可以引用空间地图系列，arcpy.mp 可在处理每个页面时处理自定义文本元素字符串的要求，因为脚本可以控制如何遍历页面。 另一个示例是将空间地图系列导出至 PDF 之外的输出格式（例如 PNG）。 请参阅下面的第二个代码示例，其中展示了如何循环遍历空间地图系列中的每个页面并导出为 .png 文件。

可以使用 exportToPDF 方法将空间地图系列中的页面导出为 PDF。 导出空间地图系列时，将支持与空间地图系列关联的所有动态元素。 例如，动态文本元素（如页面名称、页码、属性等）将自动更新。 如果图例、表格框和图表框等地图整饰要素已设置为使用地图系列约束，则这些元素也会动态更新。 可以使用 PDFDocument 类将输出 PDF 追加或插入到其他 PDF 中。 有关详细信息和代码示例，请参阅 PDFDocument 主题。

在空间地图系列中，可以使用页面查询进一步过滤显示的要素，方法是将图层的指定字段值与当前地图系列页面的名称相匹配。 仅在启用地图系列时才应用过滤器。 Layer 类提供了对 pageQuery 属性和 setPageQuery 方法的访问。

通过 getDefinition 和 setDefinition 方法可以访问未向 MapSeries 对象暴露的 CIM 属性。 有关详细信息和代码示例，请参阅 Python CIM 访问帮助主题。

属性

属性说明数据类型
clipToIndexFeature
(可读写)

如果设置为 True，Map clipLayers 设置将应用于当前索引要素。 要在地图上修改或清除 clipLayers，clipToIndexFeature 必须设置为 False。

Boolean
currentPageNumber
(可读写)

表示已启动地图系列的布局的活动页面或当前页面。

注：

如果使用字符串定义的字段来设置页码，则可以将 currentPageNumber 设置为字符串，例如 currentPageNumber ='iv'。

Long
enabled
(可读写)

表示地图系列的启动状态。

提示：

在更改地图系列属性之前，应检查已启用是否设置为 True。

Boolean
indexLayer
(只读)

返回对启用了地图系列的布局中索引图层的引用。

Layer
mapFrame
(可读写)

对包含索引图层的 MapFrame 的引用，该图层用于驱动地图系列。 如果您更改了地图框，则可能还需要重置索引图层，并且还应调用 refresh 方法

MapFrame
pageCount
(只读)

返回已启用地图系列的布局的总页数。 这与索引图层中的要素数量相对应。

Long
pageNameField
(只读)

返回字段对象，它表示设置地图系列时在索引要素类中使用的字段。

Field
pageRow
(只读)

返回提供当前索引要素属性的访问权限的 Row 对象。 要返回属性值，请输入一个点，后跟字段名称。 例如，value = lyt.mapSeries.pageRow.FIELD_NAME。

Row
selectedIndexFeatures
(只读)

返回排序页码的 Python 列表，它们表示启用了地图系列的布局中选定的索引图层要素。

List

方法概述

方法说明
export (export_format, {mapseries_export_options})

export 方法可使用指定的导出格式导出 MapSeries，还可以选择性地使用不同的 mapseries_export_options。

exportToPDF (out_pdf, {page_range_type}, {page_range_string}, {multiple_files}, {resolution}, {image_quality}, {compress_vector_graphics}, {image_compression}, {embed_fonts}, {layers_attributes}, {georef_info}, {jpeg_compression_quality}, {clip_to_elements}, {show_selection_symbology}, {output_as_image}, {embed_color_profile}, {pdf_accessibility}, {show_export_count}, {keep_layout_background}, {convert_markers}, {simulate_overprint})

将启用了地图系列的布局的一组指定页面导出为便携式文档格式 (PDF) 文件。

getDefinition (cim_version)

用于返回空间地图系列的 CIM 定义。

getPageNumberFromName (page_name)

基于页面名称返回“地图系列”页码。

refresh ()

刷新现有地图系列

setDefinition (definition_object)

设置空间地图系列的 CIM 定义。

方法

export (export_format, {mapseries_export_options})
参数说明数据类型
export_format

The supported export format object is PDFFormat.

Object
mapseries_export_options

The MapSeriesExportOptions object that includes changes to default property values.

Object

有关更多详细信息和代码示例，请参阅 MapSeriesExportOptions 帮助主题。

exportToPDF (out_pdf, {page_range_type}, {page_range_string}, {multiple_files}, {resolution}, {image_quality}, {compress_vector_graphics}, {image_compression}, {embed_fonts}, {layers_attributes}, {georef_info}, {jpeg_compression_quality}, {clip_to_elements}, {show_selection_symbology}, {output_as_image}, {embed_color_profile}, {pdf_accessibility}, {show_export_count}, {keep_layout_background}, {convert_markers}, {simulate_overprint})
参数说明数据类型
out_pdf

A string that represents the path and file name of the output export file.

String
page_range_type

The string value that designates how the pages will be printed.

  • ALL—All pages are exported.
  • CURRENT—The active or current page is exported.
  • RANGE—Only pages listed in the page_range_string parameter are exported.
  • SELECTED—Selected index layer features/pages are exported.

(默认值为 ALL)

String
page_range_string

A string that identifies the pages to be exported if the RANGE option in the page_range_type parameter is used (for example, 1, 3, 5-12). If any other page_range_type value is used, the page_range_string value will be ignored.

String
multiple_files

A string that controls how the output PDF file is created. By default, all pages are exported into a single, multipage document. The default is PDF_SINGLE_FILE.

  • PDF_MULTIPLE_FILES_PAGE_NAME—Export each map series page to an individual file and append the page name to the file name. For example, Output.PDF will become Output_LakeErie.PDF
  • PDF_MULTIPLE_FILES_PAGE_NUMBER—Export each map series page to an individual file and append the page number to the file name. For example, Output.PDF will become Output_1.PDF
  • PDF_SINGLE_FILE—Export into a multipage, single file document.

(默认值为 PDF_SINGLE_FILE)

String
resolution

An integer that defines the resolution of the export file in dots per inch (dpi).

(默认值为 96)

Integer
image_quality

A string that defines output image quality.

  • BEST—An output image quality resample ratio of 1
  • BETTER—An output image quality resample ratio of 2
  • NORMAL—An output image quality resample ratio of 3
  • FASTER—An output image quality resample ratio of 4
  • FASTEST—An output image quality resample ratio of 5

(默认值为 BEST)

String
compress_vector_graphics

A Boolean that controls the 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—Automatically selects the best compression type for each image on the page. JPEG will be used for large images with many unique colors. DEFLATE will be used for all other images.
  • JPEG—A lossy data compression.
  • JPEG2000—Offers higher quality compression with smaller file size than JPEG. This compression is lossless if jpeg_compression_quality is set to 100.
  • DEFLATE—A lossless data compression.
  • LZW—Lempel-Ziv-Welch, a lossless data compression.
  • NONE—Compression is not applied.
  • RLE—Run-length encoded compression.

(默认值为 ADAPTIVE)

String
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 the inclusion of PDF layers and PDF object data (attributes) in the export file.

  • LAYERS_ONLY—Export PDF layers only.
  • LAYERS_AND_ATTRIBUTES—Export PDF layers and feature attributes.
  • NONE—No setting is applied.

(默认值为 LAYERS_ONLY)

String
georef_info

A Boolean that enables the export of coordinate system information for each map frame into the output PDF file.

(默认值为 True)

Boolean
jpeg_compression_quality

A number that controls the compression quality value when image_compression is set to ADAPTIVE or JPEG. The valid range is 1 through 100. A jpeg_compression_quality of 100 provides the best quality images but creates large export files. The recommended range is 70 through 90.

(默认值为 80)

Integer
clip_to_elements

If set to True, the layout is clipped to the smallest bounding box that includes all layout elements.

(默认值为 False)

Boolean
show_selection_symbology

A Boolean that controls whether the selection symbology should be displayed in the output.

(默认值为 False)

Boolean
output_as_image

If set to True, vector content can be saved as an image. Selecting this option for maps or layouts that contain vector layers with a high density of vertices can reduce the output file size. When exporting to PDF and this option is set to True, you cannot view PDF layers in the output.

(默认值为 False)

Boolean
embed_color_profile

If set to True, color profile information is embedded in the image's metadata.

(默认值为 True)

Boolean
pdf_accessibility

Output a tagged PDF file where text can be read by screen readers or other assistive technology. A tagged PDF file can include alt text—a text description of a graphic element that a screen reader uses to describe the element—for map frames, pictures, and chart frames. Alt text is added in the Element Pane for each element.

(默认值为 False)

Boolean
show_export_count

If set to True, you will see the status of each page being exported displayed in the Python shell.

(默认值为 False)

Boolean
keep_layout_background

If set to True, the white background will be included in the export.

(默认值为 True)

Boolean
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
simulate_overprint

Sometimes called soft proofing, simulating overprinting shows a representation of how overlapping areas of ink will appear when printed on a page. You set up overprinting on symbol layers.

(默认值为 False)

Boolean

PDF 文件可跨不同平台实现一致的查看和打印效果。 它们通常用于在 Web 上分发文档，并且此格式现在为内容传送的标准交换格式。 PDF 文件在许多图形应用程序中均可编辑，并且它还保留了地图图层的注记、标注和属性数据。 PDF 导出支持字体嵌入，即使在用户尚未安装 Esri 字体时，也可以正确显示符号系统。

getDefinition (cim_version)
参数说明数据类型
cim_version

A string that represents the major version of the CIM that will be used.

  • V2—The 2.x version of the CIM will be used.
  • V3—The 3.x version of the CIM will be used.
String
返回值
数据类型说明
Object

返回 MapSeries 的 CIM 定义。

有关使用 CIM 和代码示例的详细信息，请参阅 Python CIM 访问。

getPageNumberFromName (page_name)
参数说明数据类型
page_name

与用于设置“地图系列”的 Name 字段对应的索引图层中的页码。

String

许多“地图系列”属性和方法都使用页码值，而不使用用于创建索引图层的页面文字名称。getPageNumberFromName 方法提供了一种用于获取给定页面名称的页码的机制。


ms = layout.mapSeries
pageNumber = ms.getPageNumberFromName("HarborView")
ms.currentPageNumber = pageNumber
refresh ()

如果发生以下任何一种情况，请使用 refresh 方法：

  • 在索引图层中添加了或删除了要素。
  • 对索引字段值进行了更新。
  • 数据框范围因缩放、平移或更改地图比例而发生了变化。
地图系列将保留原始设置，直到执行了 refresh 方法，或工程被保存并重新打开。

setDefinition (definition_object)
参数说明数据类型
definition_object

A modified CIM definition object originally retrieved using getDefinition.

Object

有关使用 CIM 和示例的详细信息，请参阅 Python CIM 访问。

代码示例

MapSeries 示例 1

以下脚本可检查是否存在空间地图系列，然后根据页面名称将其中的两个单独的页面导出至 PDF。

import arcpy, os, sys
relpath = os.path.dirname(sys.argv[0])

p = arcpy.mp.ArcGISProject(os.path.join(relpath, 'GreatLakes', 'GreatLakes.aprx'))
lyt = p.listLayouts('Layout_MS')[0]
sms = lyt.mapSeries
if isinstance(sms, arcpy._mp.MapSeries):
  if sms.enabled:
    sms.currentPageNumber = sms.getPageNumberFromName("Lake Superior") 
    sms.exportToPDF(os.path.join(relpath, 'Output', 'Ex1_LakeSuperior.pdf'),
                                'CURRENT', resolution=300)
    sms.currentPageNumber = sms.getPageNumberFromName("Lake Huron") 
    sms.exportToPDF(os.path.join(relpath, 'Output', 'Ex1_LakeHuron.pdf'),
                                'CURRENT', resolution=300)
print("Finished")
MapSeries 示例 2

以下脚本将空间地图系列的每一页导出到单个 .png 文件中，并将索引要素的页面名称用作输出文件名的一部分。

import arcpy, os, sys
relpath = os.path.dirname(sys.argv[0])

p = arcpy.mp.ArcGISProject(os.path.join(relpath, 'GreatLakes', 'GreatLakes.aprx'))
lyt = p.listLayouts('Layout_MS')[0]
sms = lyt.mapSeries
if ((type(sms).__name__ == 'MapSeries')):
  sms = lyt.mapSeries
  if sms.enabled:
    for pageNum in range(1, sms.pageCount + 1):  #All pages, zero based index
      sms.currentPageNumber = pageNum
      pageName = sms.pageRow.NAME   #NAME = field name in index layer
      print("Exporting {0}".format(pageName))  
      lyt.exportToPNG(os.path.join(relpath,'Output', f'Ex2_{pageName}.png'))
print("Finished")
MapSeries 示例 3

以下脚本可选择索引要素，将所选页面导出为一个多页 PDF，并在运行完成时清除所选内容。

import arcpy, os, sys
relpath = os.path.dirname(sys.argv[0])

p = arcpy.mp.ArcGISProject(os.path.join(relpath, 'GreatLakes', 'GreatLakes.aprx'))
lyt = p.listLayouts('Layout_MS')[0]
sms = lyt.mapSeries
if isinstance(sms, arcpy._mp.MapSeries): 
  if sms.enabled:
    indexLyr = sms.indexLayer
    arcpy.SelectLayerByAttribute_management(indexLyr, 'NEW_SELECTION',
                                            'AREA > 10000')
    sms.exportToPDF(os.path.join(relpath, 'Output',
                                'Ex3_QueriedLakes.pdf'), 'SELECTED')
    arcpy.SelectLayerByAttribute_management(indexLyr, 'CLEAR_SELECTION')
print('Finished')
MapSeries 示例 4

以下脚本可创建一个 Map 对象、一个 Layout 对象和一个 MapFrame 对象。 接下来，脚本将创建一个空间地图系列，并将 clipMapToIndexFeature 设置为 True 以启用地图裁剪。 脚本可使用 Python CIM 访问修改一些未向 MapSeries 对象暴露的 CIM 属性。 例如，设置起始页码、比例的舍入和将数据裁剪至地图索引要素。 最后，脚本会将地图系列导出至单个 PDF。

import arcpy, os, sys
relpath = os.path.dirname(sys.argv[0])

#Function used to create a rectangle where the anchor point is lower left corner
def MakeRec_LL(llx, lly, w, h):
    xyRecList = [[llx, lly], [llx, lly+h], [llx+w,lly+h], [llx+w,lly], [llx,lly]]
    array = arcpy.Array([arcpy.Point(*coords) for coords in xyRecList])
    rec = arcpy.Polygon(array)
    return rec

p = arcpy.mp.ArcGISProject(os.path.join(relpath, 'GreatLakes', 'GreatLakes.aprx'))

#Create a new map and add index layer
m = p.createMap('New Map', 'MAP')
lyrFile = arcpy.mp.LayerFile(os.path.join(relpath, 'GreatLakes', 'GreatLakes.lyrx'))
lyr = m.addLayer(lyrFile)[0]

#Create a layout and map frame
lyt = p.createLayout(8.5, 11, 'INCH')
mf = lyt.createMapFrame(MakeRec_LL(0.5,5.5,7.5,5), m, "New Map Frame")

#Create and export a spatial map series
sms = lyt.createSpatialMapSeries(mf, lyr, 'NAME')
sms.clipToIndexFeature = true

#Modify CIM properties
sms_cim = sms.getDefinition('V3')
sms_cim.startingPageNumber = 2
sms_cim.scaleRounding = 10000
sms.setDefinition(sms_cim)

#Export to PDF
sms.exportToPDF(os.path.join(relpath, 'Output', 'Ex4_NewSMS.pdf'))
MapSeries 示例 5

以下脚本将空间地图系列中的所有页面导出为单个 PDF，将书签地图系列中的所有页面导出为另一个 PDF，然后将生成的两个 PDF 组合成单个新创建的 PDF。

import arcpy, os, sys
relpath = os.path.dirname(sys.argv[0])
arcpy.env.overwriteOutput = True

p = arcpy.mp.ArcGISProject(os.path.join(relpath, 'GreatLakes', 'GreatLakes.aprx'))
#Export spatial map series
sms_lyt = p.listLayouts('Layout_MS')[0]                                  
sms = sms_lyt.mapSeries
if ((type(sms).__name__ == 'MapSeries')):
  if sms.enabled:
      print(os.path.join(relpath, 'Output', 'Temp_sms.pdf'))
      sms.exportToPDF(os.path.join(relpath, 'Output', 'Temp_sms.pdf'))

#Export bookmark map series
bms_lyt = p.listLayouts('Layout_BMS')[0]
bms = bms_lyt.mapSeries
if ((type(bms).__name__ == 'BookmarkMapSeries')): 
  if bms.enabled:
    bms.exportToPDF(os.path.join(relpath, 'Output', 'Temp_bms.pdf'))

#Combine PDFs and remove temporary files
comboPDF = arcpy.mp.PDFDocumentCreate(os.path.join(relpath, 'Output',
                                                   'Ex4_Combo.pdf'))
comboPDF.appendPages(os.path.join(relpath, 'Output', 'Temp_sms.pdf'))
os.remove(os.path.join(relpath, 'Output', 'Temp_sms.pdf'))
comboPDF.appendPages(os.path.join(relpath, 'Output', 'Temp_bms.pdf'))
os.remove(os.path.join(relpath, 'Output', 'Temp_bms.pdf'))
comboPDF.saveAndClose()
os.startfile(os.path.join(relpath, 'Output','Ex4_Combo.pdf'))
print('Finished')

有关此主题的反馈?

在本主题中
  1. 摘要
  2. 说明
  3. 属性
  4. 方法概述
  5. 方法
  6. 代码示例