Краткая информация
Объект BookmarkMapSeries предоставляет доступ к свойствам и методам для управления серией карт закладок.
Обсуждение
Модуль arcpy.mp поддерживает два типа серий карт: пространственные и закладки. Свойство mapSeries объекта Layout вернет объект mapSeries, если присутствует пространственная серия карт; объект BookmarkMapSeries, если присутствует серия карт закладок, или значение NoneType, если серия карт отсутствует или отключена. Класс BookmarkMapSeries можно использовать для настройки отдельных страниц серии карт во время экспорта. Одним из примеров является разворот, где четные страницы смещены иначе, чем нечетные, чтобы обеспечить место для переплета.
С помощью метода createBookmarkMapSeries можно создать новую серию карт закладок, передав объект MapFrame и, при необходимости, список объектов Bookmark, используемых для создания каждой страницы серии карт закладок. Если вы не передадите список закладок, по умолчанию будут использоваться закладки из объекта Map, связанного с объектом MapFrame. Свойство bookmarks представляет собой список закладок в серии карт. Список закладок можно изменять различными способами и возвращаться к серии карт закладок для управления порядком страниц, отображаемых в приложении или во время экспорта.
Аналогично приложению, с помощью метода export можно экспортировать серию карт в форматы файлов JPEG, PDF, PNG и TIFF. Эти форматы также можно дополнительно настроить с помощью объекта MapSeriesExportOptions, если требуются значения, отличные от значений по умолчанию. При экспорте серии карт поддерживаются все динамические элементы, связанные с ней. Например, динамические текстовые элементы, такие как название страницы, номер страницы, название закладки и многое другое, будут обновляться автоматически. Если зарамочное оформление карты, такое как легенды, фреймы таблиц и диаграмм, настроено на использование ограничений серии карт, эти элементы также будут динамически обновляться.
Примечание:
Экспорт серий карт может быть ограничен перечисленными выше форматами и дополнительно настроен с помощью MapSeriesExportOptions, но это не значит, что вы не можете имитировать экспорт серии карт в другой формат. Процедура заключается в обновлении макета с использованием текущей страницы серии карт и экспорте макета вместо серии карт. Второй пример кода ниже демонстрирует, как это сделать.
Методы 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 |
Обзор метода
| Метод | Описание |
| export (export_format, {mapseries_export_options}, {display_options}) |
Метод export экспортирует BookmarkMapSeries, используя указанный export_format и, дополнительно, различные mapseries_export_options или display_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}) | Экспортирует выбранный поднабор страниц в файл формата Portable Document Format (PDF) для компоновки с включенной функцией серии карт. Прежние версии:Этот метод заменен на export в версии 3.4 ArcGIS Pro и остается для использования только в устаревших скриптах. Все усовершенствования и будущие разработки будут осуществляться только методом экспорта. |
| getDefinition (cim_version) | Получает определение CIM для серий карт закладок. |
| getPageNumberFromName (page_name) | Возвращает номер страницы, соответствующий названию отображаемой в данный момент страницы серии карт закладок. |
| refresh () | Обновляет существующую серию карт закладок. |
| setDefinition (definition_object) | Задает определение CIM для закладок серий карт. |
Методы
export (export_format, {mapseries_export_options}, {display_options})| Параметр | Описание | Тип данных |
export_format | The supported export_format objects are JPEGFormat, PDFFormat, PNGFormat, and TIFFFormat. | Object |
mapseries_export_options | The MapSeriesExportOptions object is only needed if there are changes to its default property values. | Object |
display_options | The DisplayOptions object that includes changes to the default antialiasing property values. | Object |
Более подробную информацию и примеры кода можно найти в разделе справки MapSeriesExportOptions и DisplayOptions.
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 | Строка, представляющая путь и имя выходного файла для экспорта. | String |
page_range_type | Строковое значение, описывающее, каким образом страницы будут напечатаны.
(Значение по умолчанию — ALL) | String |
page_range_string | Строка, определяющая экспортируемые страницы, если используется опция RANGE в параметре page_range_type (например, 1, 3, 5-12). Если используется любое другое значение page_range_type, параметр page_range_string будет игнорироваться. | String |
multiple_files | Строка для управления созданием выходного PDF. По умолчанию все страницы экспортируются в один многостраничный документ.
(Значение по умолчанию — PDF_SINGLE_FILE) | String |
resolution | Целое число, определяющее разрешение файла для экспорта в точках на дюйм (dpi). (Значение по умолчанию — 96) | Integer |
image_quality | Строка, определяющая качество выходного изображения.
(Значение по умолчанию — BEST) | String |
compress_vector_graphics | Логический параметр, управляющий сжатием векторных и текстовых частей выходного файла. Сжатие изображения определяется отдельно. (Значение по умолчанию — True) | Boolean |
image_compression | Строка, которая определяет схему сжатия, используемую для сжатия изображения или растровых данных в выходном файле.
(Значение по умолчанию — ADAPTIVE) | String |
embed_fonts | Логический параметр, управляющий внедрением шрифтов в файле для экспорта. Внедрение шрифтов позволяет правильно отображать текстовые и символьные маркеры при просмотре документа на компьютере без установленных шрифтов. (Значение по умолчанию — True) | Boolean |
layers_attributes | Строка, управляющая включением слоев PDF и данных объектов PDF (атрибутов) в файл для экспорта.
(Значение по умолчанию — LAYERS_ONLY) | String |
georef_info | Логический параметр, позволяющий экспортировать информацию о системе координат каждого фрейма карты в выходной файл PDF. (Значение по умолчанию — True) | Boolean |
jpeg_compression_quality | Число, управляющее качеством сжатия, если image_compression задано для параметра ADAPTIVE или JPEG. Допустимым является диапазон от 1 до 100. Если значение jpeg_compression_quality равно 100, это обеспечивает наилучшее качество изображений, но при экспорте создаются крупные файлы. Рекомендованный диапазон находится между 70 и 90. (Значение по умолчанию — 80) | Integer |
clip_to_elements | Если задано значение True, то компоновка вырезается по наименьшей ограничивающей рамке, включающей все элементы компоновки. (Значение по умолчанию — False) | Boolean |
output_as_image | Если установлено на True, векторные данные будут сохранены как изображение. Выбор этого параметра для карт или компоновок, содержащих векторные слои с высокой плотностью вершин, может значительно уменьшить размер выходного файла. Если выбран экспорт в PDF и опция установлена на True, вы не сможете просматривать слои PDF в выходных данных. (Значение по умолчанию — False) | Boolean |
embed_color_profile | Если задан как True, то информация о цвете профиля будет встроена в метаданные изображения. (Значение по умолчанию — True) | Boolean |
pdf_accessibility | Выведите файл PDF с тегами, в котором текст может быть прочитан программами чтения с экрана или другими вспомогательными технологиями. Файл PDF с тегами может включать альтернативный текст - текстовое описание графического элемента, который программа чтения с экрана использует для описания элемента - для фреймов карты, изображений и фреймов диаграммы. Альтернативный текст добавляется на Панель элементов для каждого элемента.
(Значение по умолчанию — False) | Boolean |
show_export_count | Если установлено значение True, вы увидите статус каждой экспортируемой страницы, отображаемый в Python shell. (Значение по умолчанию — False) | Boolean |
keep_layout_background | Если задан как True, белый цвет фона будет включен в экспорт. (Значение по умолчанию — True) | Boolean |
convert_markers | Логическое значение, управляющее преобразованием маркерных символов в полигоны. Это позволяет символам отображаться корректно, если шрифт символа недоступен или не может быть встроен. Однако установка этого параметра в значение True отключает встраивание шрифтов для всех символов-маркеров, что может привести к изменению их внешнего вида. (Значение по умолчанию — False) | Boolean |
simulate_overprint | Иногда называемая мягкой пробной печатью, имитация впечатывания показывает представление того, как накладывающиеся области чернил проявляются при печати на странице. Вы можете настроить впечатывание в слоях символов. (Значение по умолчанию — False) | Boolean |
PDF формат создан с учетом возможности просмотра и печати файлов на разных платформах. Эти файлы часто используются для распространения документов через Интернет и становятся стандартным форматом для обмена документацией. Файлы PDF можно редактировать во многих графических приложениях, здесь сохраняются аннотации, надписи и атрибутивные данные для слоев карты. Экспорт PDF поддерживает встроенные шрифты, поэтому даже если у пользователей не установлены шрифты Esri, символы все равно будут отображаться корректно.
Прежние версии:
Этот метод заменен на export в версии 3.4 ArcGIS Pro и остается для использования только в устаревших скриптах. Все усовершенствования и будущие разработки будут осуществляться только методом экспорта.
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 на основе имен закладок. Поскольку он экспортирует по одному PDF-файлу за раз, класс MapSeriesExportOptions настроен на экспорт страницы CURRENT. Объект PDFFormat необходимо создать только один раз, поскольку свойство filePath изменяется между экспортами.
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
#Create a new PDF format and change the resolution from its default value of 96
pdf = arcpy.mp.CreateExportFormat('PDF')
pdf.resolution = 300
#Modify map series export options to export only the current page
msOpt = arcpy.mp.CreateExportOptions('MAPSERIES')
msOpt.setExportPages('CURRENT')
if isinstance(bms, arcpy._mp.BookmarkMapSeries):
if bms.enabled:
bms.currentPageNumber = bms.getPageNumberFromName("Lake Superior")
pdf.filePath = os.path.join(relpath, 'Output', 'Ex1_LakeSuperior.pdf')
bms.export(pdf, msOpt)
bms.currentPageNumber = bms.getPageNumberFromName("Lake Huron")
pdf.filePath = os.path.join(relpath, 'Output', 'Ex1_LakeHuron.pdf')
bms.export(pdf, msOpt)Следующий скрипт экспортирует каждую страницу серии карт в отдельные файлы .bmp и использует имя закладки как часть имени выходного файла.
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
#Create a new PNG format that uses only defaults
bmp = arcpy.mp.CreateExportFormat('BMP')
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(f"Exporting {bkmkName}")
bmp.filePath =os.path.join(relpath,'Output', f'Ex2_{bkmkName}.bmp')
lyt.export(bmp)Следующий скрипт создает объект 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 bookmark 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
pdf = arcpy.mp.CreateExportFormat('PDF', os.path.join(relpath, 'Output', 'Ex3_NewBMS.pdf'))
bms.export(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_cim = bms.getDefinition('V3')
sortList = sorted(bms_cim.pages, key=lambda CIMBookmarkMapSeriesPage: CIMBookmarkMapSeriesPage.bookmarkName)
bms_cim.pages = sortList
bms.setDefinition(bms_cim)
pdf = arcpy.mp.CreateExportFormat('PDF', os.path.join(relpath, 'Output', 'Ex4_Sorted.pdf'))
bms.export(pdf)Следующий скрипт экспортирует все страницы из пространственной серии карт в один 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:
pdf = arcpy.mp.CreateExportFormat('PDF', os.path.join(relpath, 'Output', 'Temp_sms.pdf'))
sms.export(pdf)
#Export bookmark map series
bms_lyt = p.listLayouts('Layout_BMS')[0]
bms = bms_lyt.mapSeries
if ((type(bms).__name__ == 'BookmarkMapSeries')):
if bms.enabled:
pdf = arcpy.mp.CreateExportFormat('PDF', os.path.join(relpath, 'Output', 'Temp_bms.pdf'))
bms.export(pdf)
#Combine PDFs and remove temporary files
comboPDF = arcpy.mp.PDFDocumentCreate(os.path.join(relpath, 'Output', 'Ex5_Combo.pdf'))
comboPDF.appendPages(os.path.join(relpath, 'Output', 'Temp_sms.pdf'))
comboPDF.appendPages(os.path.join(relpath, 'Output', 'Temp_bms.pdf'))
comboPDF.saveAndClose()
os.remove(os.path.join(relpath, 'Output', 'Temp_sms.pdf'))
os.remove(os.path.join(relpath, 'Output', 'Temp_bms.pdf'))