MapSeries

Краткая информация

Объект MapSeries предоставляет доступ к свойствам и методам управления пространственными сериями карт.

Обсуждение

На существующую пространственную серию карт можно ссылаться, используя свойство mapSeries объекта Layout или используя метод createSpatialMapSeries. Вы передаете в объект MapFrame значение index_layer, значение name_field и другие дополнительные параметры для создания пространственной серии карт.

Примечание:

Arcpy.mp поддерживает два типа серий карт: пространственные и закладки. Класс mapSeries представляет пространственные серии карт. Свойство mapSeries объекта Layout возвращает объект MapSeries, если присутствует пространственная серия карт, объект BookmarkMapSeries или значение NoneType, если серия карт отсутствует.

Класс MapSeries можно использовать для доступа к отдельным страницам пространственной серии карт для настройки. Например, если строковая информация текстового элемента должна быть отформатирована с использованием пользовательской логики, можно ссылаться на серию пространственных карт и arcpy.mp может обрабатывать требования к строкам пользовательского текстового элемента при обработке каждой страницы, поскольку скрипт управляет тем, как выполнять итерацию по страницам. Еще одним примером является экспорт пространственной серии карт в выходной формат, отличный от PDF, например PNG. См. ниже второй пример кода, который показывает, как пройти через каждую страницу в серии карт и экспортировать их в файл .png.

Страницы в пространственной серии карт можно экспортировать в PDF, используя метод exportToPDF. При экспорте пространственной серии карт поддерживаются все связанные с ней динамические элементы. Например, динамические текстовые элементы, такие как название страницы, номер страницы, атрибуты и многое другое, будут автоматически обновляться. Если зарамочное оформление карты — например, легенда, фреймы таблиц и фреймы диаграмм — настроено на использование ограничений серии карт, эти элементы также будут динамически обновляться. Выходной PDF можно добавить или вставить в другие PDF-файлы с помощью класса PDFDocument. См. раздел PDFDocument для получения дополнительной информации и примеров кода.

Объекты, отображаемые в пространственной серии карт, можно дополнительно фильтровать с помощью запросов к странице, где значения в заданном поле слоя сопоставляются с именем текущей страницы серии карт. Фильтр применяется, только если включены серии карт. Класс Layer обеспечивает доступ к свойству pageQuery и методу setPageQuery.

Методы getDefinition и setDefinition предоставляют доступ к свойствам CIM, которые не доступны объекту MapSeries. Дополнительные сведения и примеры кода приведены в разделе справки Доступ к 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

Обзор метода

МетодОписание
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})

Экспортирует выбранный поднабор страниц в файл формата 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}, {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.

  • ALLAll pages are exported.
  • CURRENTThe active or current page is exported.
  • RANGEOnly pages listed in the page_range_string parameter are exported.
  • SELECTEDSelected 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_NAMEExport 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_NUMBERExport 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_FILEExport 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.

  • BESTAn output image quality resample ratio of 1
  • BETTERAn output image quality resample ratio of 2
  • NORMALAn output image quality resample ratio of 3
  • FASTERAn output image quality resample ratio of 4
  • FASTESTAn 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.

  • ADAPTIVEAutomatically 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.
  • JPEGA lossy data compression.
  • JPEG2000Offers higher quality compression with smaller file size than JPEG. This compression is lossless if jpeg_compression_quality is set to 100.
  • DEFLATEA lossless data compression.
  • LZWLempel-Ziv-Welch, a lossless data compression.
  • NONECompression is not applied.
  • RLERun-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_ONLYExport PDF layers only.
  • LAYERS_AND_ATTRIBUTESExport PDF layers and feature attributes.
  • NONENo 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 формат создан с учетом возможности просмотра и печати файлов на разных платформах. Эти файлы часто используются для распространения документов через Интернет и становятся стандартным форматом для обмена документацией. Файлы PDF можно редактировать во многих графических приложениях, здесь сохраняются аннотации, надписи и атрибутивные данные для слоев карты. Экспорт PDF поддерживает встроенные шрифты, поэтому, даже если у пользователей не установлены шрифты Esri, символы все равно будут отображаться корректно.

getDefinition (cim_version)
ПараметрОписаниеТип данных
cim_version

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

  • V2The 2.x version of the CIM will be used.
  • V3The 3.x version of the CIM will be used.
String
Возвращаемое значение
Тип данныхОписание
Object

Возвращает определение CIM для MapSeries.

Более подробно о работе с 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 для изменения некоторых свойств CIM, которые не доступны объекту MapSeries. Примерами являются настройка номера начальной страницы, округление масштаба и вырезание данных в объект индекса карт. Наконец, скрипт экспортирует серии карт в документ 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.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')