Руководство по использованию arcpy.mp

В этом разделе приведены рекомендации по работе с модулем arcpy.mp. Здесь также дается представление о конструкции API arcpy.mp и предлагается стратегии для различных сценариев.

Работа должна проводится с существующими проектами

Модуль arcpy.mp не может создавать проекты. Он был разработан в первую очередь для изменения объектов в существующих проектах (.aprx) или файлах слоев (.lyr или .lyrx) с целью автоматизации карт или данных. Поскольку API продолжает расширяться в ArcGIS Pro, вводятся новые функции конструктора. Например, класс ArcGISProject имеет методы createMap и createLayout и ряд других методов-конструкторов. Не все можно создать в проекте, поэтому вам все равно может потребоваться заранее создать проект с элементами, которыми вы собираетесь манипулировать, используя arcpy.mp.

Ниже приведены несколько примеров того, как можно использовать arcpy.mp:

• Замена источника данных слоя.
• Итерация по последовательности экстентов, поиск и замена текстовых значений, экспорт компоновки страницы в PDF.
• Создание полного атласа за счет добавления документов PDF в конечный продукт.

Примечание:

Можно внести изменения в существующие проекты или файлы слоев, а затем сохранить изменения в новом файле с помощью метода saveACopy для объектов ArcGISProject или Layer.

Ссылка на проект на диске или использование ключевого слова CURRENT

Существует два способа ссылки на проект с помощью функции ArcGISProject. Первый и рекомендуемый метод - указать системный путь к местоположению проекта (.aprx) на диске. Этот метод наиболее универсален, поскольку скрипт можно запускать вне приложения. Указание ссылки на конкретный проект на диске предоставляет больше возможностей для контроля за запуском скрипта, так как данный скрипт может работать не со всеми проектами.

Пример указания полного пути к проекту:

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")

Второй метод использует ключевое слово CURRENT в качестве входного параметра для функции ArcGISProject. Этот метод работает только внутри приложения, так как объект ArcGISProject ссылается на проект, загруженный в данный момент в приложении. Использование CURRENT полезно при быстром тестировании и изучении возможностей скриптов и синтаксиса команд в окне Python. Можно приступить к изучению синтаксиса в окне Python и начинать добавлять эти строки кода в постоянные, более сложные скрипты, сохраняемые на диск. Инструменты-скрипты, использующие ключевое слово CURRENT, также требуют запуска из приложения.

Пример использования ключевого слова CURRENT.

aprx = arcpy.mp.ArcGISProject('current')

Добавление слоев и работа с шаблонами проектов

Как было указано в предыдущем разделе, arcpy.mp не позволяет полностью создавать новые проекты. Однако вы можете заранее создать проекты шаблонов со всеми соответствующими элементами, размерами страниц, ориентациями и т.д. и использовать arcpy.mp для обработки содержания.

Распространенным сценарием является создание шаблона проекта без слоев и использование методов addLayer, addLayerToGroup или insertLayer для объекта Map при добавлении слоев на карту в проекте.

Другой распространенный сценарий касается атласов с разворотами. Левая и правая страницы содержат разные смещения для связывания. Этот сценарий включает две компоновки в отдельном проекте: одна компоновка для левых страниц и другая для правых. Логика скриптов arcpy.mp используется для объединения всех отдельных страниц в итоговый многостраничный файл PDF.

Создание всех объектов с уникальными именами

Чтобы легко ссылаться на элемент в компоновке, чтобы к нему можно было получить доступ и изменить его, элемент должен иметь уникальное имя. Большая часть функций списка arcpy.mp например, listLayouts, listMaps, listBookmarks, listTables, listLayers, listLabelClasses и listElements содержат параметр wildcard, который позволяет фильтровать результаты по свойству имя. Эти функции списков всегда возвращают объект списка Python. Чтобы сослаться на элемент из списка Python, вы можете либо пройтись по списку с помощью цикла, либо добавить номер индекса в конце функции. При использовании параметра wildcard и указании уникального имени, полученный список Python всегда будет содержать один элемент, к которому можно обращаться, используя индекс 0.

В следующем коде продемонстрирован пример ссылки на текстовый элемент компоновки, используя его свойство name.

aprx = arcpy.mp.ArcGISProject('CURRENT')
lyt = aprx.listLayouts('Main Attractions')[0]
title = lyt.listElements('TEXT_ELEMENT', 'title')[0]

В идеале у каждого слоя или таблицы одного проекта должно быть свое уникальное имя, но это не всегда возможно. Если требуется использовать дублирующиеся имена для слоев и таблиц на карте, но иметь возможность изолировать одно от другого, необходимо создать элемент таким образом, чтобы его можно было отличать с помощью других свойств, например, с помощью свойства описания.

Ниже представлен пример кода, показывающий, как слои с одинаковым именем Roads на одной карте Yosemite National Park могут быть изолированы с помощью свойства maxThreshold объекта Layer. Эти слои имеют одинаковый источник данных, но отрисованы по-разному, в зависимости от масштаба просмотра.

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
mp = aprx.listMaps('Yosemite National Park')[0]
for lyr in mp.listLayers():
  if lyr.name == 'Roads':
     if lyr.maxThreshold == 10000:
        lyr.visible = True
     if lyr.maxThreshold == 100000:
        lyr.visible = False
aprx.save()
del aprx

Наилучшей альтернативой для примера выше было бы наименование каждого слоя по-разному, например, Дороги в крупном масштабе и Дороги в мелком масштабе.

Управление видимостью элементов компоновки

Возможна ситуация, когда вы создаете серию карт и на некоторых страницах требуются дополнительные элементы карты, которые нужны не всем страницам, например, дополнительная карта-врезка, дополнительное изображение или текстовые элементы и т.д. Вместо создания отдельных компоновок специально для этих ситуаций, можно создать одну компоновку со всеми возможными элементами компоновки, а затем использовать логику создания скриптов arcpy.mp для управления видимостью каждого элемента. Существует два возможных метода. Первый состоит в присвоении свойству visible элемента значения True или False, в зависимости от настроек отдельной страницы и элемента. Второй – физически удалить элемент со страницы, если он не нужен. Это делается при помощи изменения свойств elementPositionX или elementPositionY. Если элемент не находится в компоновке, при ее печати или экспорте этот элемент не отображается.

В примере ниже компоновка отображает строку масштаба с другим стилем на основе масштаба текущего фрейма данных. Если масштаб меньше 1:25 000, строка масштаба использует метры в качестве единиц измерения. Если масштаб меньше или равен 1:25 000, строка масштаба использует километры в качестве единиц измерения.

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
lyt = aprx.listLayouts("Main Attractions")[0]
m_scale = lyt.listElements("MAPSURROUND_ELEMENT", "m scale bar")[0]
km_scale = lyt.listElements("MAPSURROUND_ELEMENT", "km scale bar")[0]
mf = lyt.listElements("MAPFRAME_ELEMENT", "Yose*")[0]
if mf.camera.scale < 25000:
  m_scale.elementPositionX = 5      #Or m_scale.visible = True (on the page)
  km_scale.elementPostitionX = 15   #Or km_scale.visible = False (off the page)
else:
  m_scale.elementPositionX = 15     #Or m_scale.visible = False (off the page)
  km_scale.elementPostitionX = 5    #Or km_scale.visible = True (on the page)
aprx.save()
del aprx

Один из этих методов может быть проще в использовании, в зависимости от ситуации. Например, если вы предпочитаете использовать visible для управления отображением элемента, вы можете обнаружить, что при этом сложнее управлять составными элементами, которые перекрывают друг друга в компоновке.