BookmarkMapSeries—ArcGIS Pro

摘要

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

说明

可以使用 Layout 对象的 mapSeries 属性或 createBookmarkMapSeries 方法引用现有书签地图系列。可传入要用于创建书签地图系列的 MapFrame 对象，也可以选择传入一个 Bookmark 对象列表。如果您未传入书签列表，则会默认使用与 MapFrame 对象关联的 Map 对象中的书签。

注：

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

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

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

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

属性

属性	说明	数据类型
bookmarks (可读写)	将用于书签地图系列的书签列表。注：如果您通过设置一列新书签修改了书签列表，您需要调用 refresh 方法，以在应用程序中更新书签地图系列页面。	List
currentBookmark (只读)	返回地图系列中显示的当前书签。	Bookmark
currentPageNumber (可读写)	地图系列中显示的书签页面对应的当前页码。您将通过此方式设置适用的书签页面。如果您不确定页码，则可以使用 getPageNumberFromName 方法根据书签名称获取页码。以下是使用书签 name 值设置 currentPageNumber 属性的示例。 `bms.currentPageNumber = bms.getPageNumberFromName('Fenway')`	Long
enabled (可读写)	指定是否启用地图系列。提示：更改地图系列属性之前，请确认此属性已设置为 True。	Boolean
mapFrame (可读写)	与地图系列关联的 MapFrame 对象。如果您更改了地图框，原始书签保持不变，则还应使用 refresh 方法。	MapFrame
pageCount (只读)	已启用地图系列的布局的总页数。此值对应于书签总数。	Long

方法概述

方法	说明
export (export_format, {mapseries_export_options})	export 方法可使用指定的导出格式导出 BookmarkMapSeries，还可以选择性地使用不同的 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}, {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}, {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—Does not apply to bookmark map series. 注： This option can only be used for a spatial map series in which index features can be selected. If it is used with a bookmark map series, all pages will be 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. 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
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	返回 BookmarkMapSeries 的 CIM 定义。

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

getPageNumberFromName (page_name)

参数	说明	数据类型
page_name	The name of the Bookmark based on the Name field that was used to set up the map series.	String

许多地图系列属性和方法使用页码值而非页面的文本名称。 getPageNumberFromName 方法提供了一种用于根据页面名称获取页码的机制。

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

refresh ()

如果对任何书签进行更改或者修改其顺序，请使用 refresh 方法刷新应用程序中的书签地图系列页面。

setDefinition (definition_object)

参数	说明	数据类型
definition_object	A modified CIM definition object originally retrieved using getDefinition.	Object

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

代码示例

BookmarkMapSeries 示例 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_BMS')[0]
bms = lyt.mapSeries
if isinstance(bms, arcpy._mp.BookmarkMapSeries):
  if bms.enabled:
    bms.currentPageNumber = bms.getPageNumberFromName("Lake Superior") 
    bms.exportToPDF(os.path.join(relpath, 'Output', 'Ex1_LakeSuperior.pdf'),
                                'CURRENT', resolution=300)
    bms.currentPageNumber = bms.getPageNumberFromName("Lake Huron") 
    bms.exportToPDF(os.path.join(relpath, 'Output', 'Ex1_LakeHuron.pdf'),
                                'CURRENT', resolution=300)
print("Finished")

BookmarkMapSeries 示例 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_BMS')[0]
bms = lyt.mapSeries
if ((type(bms).__name__ == 'BookmarkMapSeries')):
  if bms.enabled:
    for pageNum in range(1, bms.pageCount + 1):  #All pages, zero based index
      bms.currentPageNumber = pageNum
      bkmkName = bms.currentBookmark.name
      print("Exporting {0}".format(bkmkName))  
      lyt.exportToPNG(os.path.join(relpath,'Output', f'Ex2_{bkmkName}.png'))
print("Finished")

BookmarkMapSeries 示例 3

以下脚本可创建一个 Map 对象、一个 Layout 对象和一个 MapFrame 对象。接下来，脚本将向地图添加一个图层文件，并在创建书签之前遍历各个要素以设置地图框范围。接下来，它将创建一个书签地图系列，并使用 Python CIM 访问修改未向 BookmarkMapSeries 对象暴露的一些 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, layout, and map frame
m = p.createMap('New Map', 'MAP')
lyt = p.createLayout(8.5, 11, 'INCH', 'New Layout')
mf = lyt.createMapFrame(MakeRec_LL(0.5,5.5,7.5,5), m, "New Map Frame")

#Add a layer file and zoom to each feature and create a bookmark and add to list
lyrFile = arcpy.mp.LayerFile(os.path.join(relpath, 'GreatLakes', 'GreatLakes.lyrx'))
lyr = m.addLayer(lyrFile)[0]
bkmkList = []
for row in arcpy.da.SearchCursor(lyr, ['SHAPE@', 'NAME']):
  mf.camera.setExtent(row[0].extent)
  mf.camera.scale = mf.camera.scale * 1.1 #add a slight buffer
  bkmkList.append(mf.createBookmark(row[1]))

#Create and export a spatial map series
bms = lyt.createBookmarkMapSeries(mf, bkmkList)

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

#Export to PDF
bms.exportToPDF(os.path.join(relpath, 'Output', 'Ex3_NewBMS.pdf'))                                        
os.startfile(os.path.join(relpath, 'Output', 'Ex3_NewBMS.pdf'))

BookmarkMapSeries 示例 4

以下脚本可在引用现有书签地图系列后对地图的书签进行排序。必须调用刷新方法以确认书签页面在应用程序中已重新排序。

p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts('Layout_BMS')[0]
bms = lyt.mapSeries
if isinstance(bms, arcpy._mp.BookmarkMapSeries):
  if bms.enabled:
    m = bms.mapFrame.map
    m_cim = m.getDefinition('V3')
    sortList = sorted(m_cim.bookmarks, key=lambda Bookmark: Bookmark.name)
    m_cim.bookmarks = sortList
    m.setDefinition(m_cim)
    bms.refresh()
    bms.exportToPDF(r'C:\temp\Ex4_Sorted.pdf')
os.startfile(r'C:\temp\Ex4_Sorted.pdf')
print("Finished")

BookmarkMapSeries 示例 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')

有关此主题的反馈?

摘要

说明

注：

属性

注：

提示：

方法概述

方法

注：

代码示例

在本主题中