Краткая информация
Объект BookmarkMapSeries предоставляет доступ к свойствам и методам для управления серией карт закладок.
Обсуждение
На существующую серию карт закладок можно ссылаться, используя свойство mapSeries объекта Layout или используя метод createBookmarkMapSeries. Вы передаете объект MapFrame и, необязательно, список объектов Bookmark, которые вы хотите использовать для создания серии карт закладок. Если вы не передадите список закладок, по умолчанию будут использоваться закладки из объекта Map, связанного с объектом MapFrame.
Примечание:
ArcGIS Pro поддерживает два типа серий карт: пространственные и закладки. Класс MapSeries представляет собой серию пространственных карт. Свойство mapSeries объекта Layout вернет объект MapSeries, если включена серия пространственных карт, объект BookmarkMapSeries или значение NoneType, если серия карт отсутствует.
Класс BookmarkMapSeries может использоваться для доступа к отдельным страницам серии карт для настройки. Например, если строковая информация текстового элемента должна быть отформатирована с использованием пользовательской логики, можно сослаться на серию карт, а arcpy.mp может обработать требования к строкам пользовательского текстового элемента при обработке каждой страницы, поскольку скрипт управляет выполнением итерации по страницам. Другой пример - это экспорт серии карт в формат, отличающийся от PDF, например, в PNG. См. второй пример кода ниже, который показывает, как пройти через каждую страницу в серии карт и экспортировать их в файл .png.
Страницы в серии карт можно экспортировать в PDF, используя метод exportToPDF. При экспорте серии карт поддерживаются все динамические элементы, связанные с ней. Например, динамические текстовые элементы, такие как название страницы, номер страницы, название закладки и многое другое, будут обновляться автоматически. Если зарамочное оформление карты, такое как легенды, фреймы таблиц и диаграмм, настроено на использование ограничений серии карт, эти элементы также будут динамически обновляться. Выходной PDF можно добавить или вставить в другие PDF-файлы с помощью класса PDFDocument. Обратитесь к разделу справки PDFDocument для получения дополнительной информации и примеров кода.
Методы getDefinition и setDefinition предоставляют доступ к свойствам CIM, не доступным объекту BookmarkMapSeries. Дополнительные сведения и примеры кода приведены в разделе справки Доступ к Python CIM.
Свойства
| Свойство | Описание | Тип данных |
| bookmarks (чтение и запись) | Список закладок, которые будут использоваться в серии карт закладок. Примечание:Если вы изменяете список закладок, задав новый, необходимо вызвать метод refresh, чтобы страницы серии карт закладок обновились в приложении. | List |
| currentBookmark (только чтение) | Возвращает текущую закладку, отображаемую в серии карт. | Bookmark |
| currentPageNumber (чтение и запись) | Текущий номер страницы, соответствующий странице закладки, отображаемой в серии карт. Таким образом задается соответствующая страница закладки. Если вы не уверены в номере страницы, вы можете получить номер страницы на основе названия закладки, используя метод getPageNumberFromName. Ниже приведен пример задания свойства currentPageNumber, с использованием значения name закладки. | Long |
| enabled (чтение и запись) | Определяет, включена ли серия карт. Подсказка:Убедитесь, что для свойства задано True, перед тем, как изменить свойства серии карт. | Boolean |
| mapFrame (чтение и запись) | Объект MapFrame, связанный с серией карт. Если вы измените фрейм карты на что-то другое, исходные закладки останутся, и вам также потребуется использовать метод refresh. | MapFrame |
| pageCount (только чтение) | Общее число страниц для компоновки с включенной серией карт. Это соответствует общему количеству закладок. | Long |
Обзор метода
| Метод | Описание |
| 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}) | Экспортирует выбранный поднабор страниц в файл формата Portable Document Format (PDF) для компоновки с включенной функцией серии карт. |
| getDefinition (cim_version) | Получает определение CIM для серий карт закладок. |
| getPageNumberFromName (page_name) | Возвращает номер страницы, соответствующий названию отображаемой в данный момент страницы серии карт закладок. |
| refresh () | Обновляет существующую серию карт закладок. |
| setDefinition (definition_object) | Задает определение CIM для закладок серий карт. |
Методы
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) | 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_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) | 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) | 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) | 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 формат создан с учетом возможности просмотра и печати файлов на разных платформах. Эти файлы часто используются для распространения документов через Интернет и становятся стандартным форматом для обмена документацией. Файлы PDF можно редактировать во многих графических приложениях, здесь сохраняются аннотации, надписи и атрибутивные данные для слоев карты. Экспорт PDF поддерживает встроенные шрифты, поэтому даже если у пользователей не установлены шрифты Esri, символы все равно будут отображаться корректно.
getDefinition (cim_version)
| Параметр | Описание | Тип данных |
cim_version | A string that represents the major version of the CIM that will be used.
| String |
| Тип данных | Описание |
| Object | Возвращает определение CIM для BookmarkMapSeries. |
Более подробно о работе с 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 = pageNumberrefresh ()
Если в какую-либо из закладок внесены изменения или изменен их порядок, используйте метод refresh для обновления страниц серии карт закладок в приложении.
setDefinition (definition_object)
| Параметр | Описание | Тип данных |
definition_object | A modified CIM definition object originally retrieved using getDefinition. | Object |
Более подробно о работе с CIM и примеры использования см. в разделе Доступ к Python CIM.
Пример кода
Следующий скрипт проверяет наличие серий карт закладок и экспортирует две страницы в 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")Следующий скрипт экспортирует каждую страницу серии карт в отдельный файл .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")Следующий скрипт создает объект Map, объект Layout и объект MapFrame. Затем он добавляет файл слоя на карту и выполняет итерацию по каждому объекту, чтобы задать экстент фрейма карты перед созданием закладки. Затем он создает серию карт закладок и использует Python CIM access для изменения некоторых свойств CIM, не доступных объекту BookmarkMapSeries. Примерами являются задание номера начальной страницы и округление масштаба. Наконец, скрипт экспортирует серии карт в документ 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'))Следующий скрипт сортирует закладки карты после обращения к существующей серии карт закладок. Необходимо вызвать метод обновления для подтверждения того, что страницы закладок переупорядочены в приложении.
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")Следующий скрипт экспортирует все страницы из пространственной серии карт в один 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')