Руководство: Начало работы с arcpy.mp

В этом руководстве описываются основные рабочие процессы модуля Mapping, а также важные концепции. Оно направлено на помощь пользователям, которые впервые работают с написанием скриптов Python и модулем arcpy.mp, но имеют базовое понимание ArcGIS Pro. Действия, описанные здесь, подходят для работы с любыми данными и всеми уровнями лицензии.

Из этого урока вы узнаете, как выполнить следующее:

• Обращаться к проекту, изменять его базу геоданных по умолчанию и сохранять изменения.
• Обращаться к карте и добавлять файл слоя (*.lyrx).
• Обращаться к компоновке и менять строку текстового элемента.
• Обращаться к фрейму карты в компоновке и изменять его экстент на экстент добавленного слоя.
• Экспортировать компоновку в PDF.
• Сохранять ваш код в файл Python (*.py).

Предполагаемое время: 60 минут

Примечание:

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

Создание простого проекта

Прежде чем вы сможете начать писать код arcpy.mp, нужно создать простой проект, который содержит одну карту и компоновку с фреймом карты и текстовым элементом.

1. Откройте новый пустой проект.
2. На вкладке Вставка в группе Проект щелкните ниспадающее меню Новая карта и выберите Новая карта.
3. Назовите новую карту Учебная карта.

   Далее вы будете обращаться к карте по этому имени, чтобы добавить файл слоя.

4. На вкладке Вставка щелкните Новая компоновка и выберите компоновку из галереи.
5. Назовите новую компоновку Учебная компоновка.

   Вы будете обращаться к компоновке по этому имени, чтобы изменить элементы компоновки и экспортировать компоновку в PDF.

6. На вкладке Вставка в группе Фреймы карты выберите ниспадающее меню Фрейм карты и выберите фрейм карты, который включает экстент с соответствующим масштабом, и добавьте его в компоновку.
7. Назовите новый элемент фрейма карты Учебная карта MapFrame.

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

8. На вкладке Вставка в группе Графика и текст выберите элемент управления Прямой текст из галереи инструментов и вставьте текстовый элемент в компоновку.

   Оставьте значение строки и размер текста по умолчанию без изменений; позже они будут изменены с помощью кода.

9. Назовите новый текстовый элемент Заголовок.

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

10. На вкладке Проект щелкните Сохранить.

    В зависимости от того, как вы создали проект, может потребоваться сохранить его в определенном местоположении.

Использовать окно Python

Вы можете начать изучение arcpy.mp в окне Python. Это позволит вам выполнять небольшие рабочие процессы на основе Python и разобраться в концепциях непосредственно в приложении, перед тем, как настраивать скрипты больших размеров. Окно Python является частью приложения ArcGIS Pro и предоставляет возможности автозавершения и синтаксиса команд, чтобы вы могли легко вводить соответствующую информацию для параметров в нужном порядке. Более подробную информацию см. в разделе справки Окно Python.

1. На вкладке Вид щелкните Окно Python.

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

   Окно Python включает разделы командной строки и расшифровки. Командная строка располагается внизу окна, в ней записывается и вводится код. Расшифровка находится над командной строкой и в ней содержится запись раннее введенного кода Python.

2. Щелкните в разделе командной строки, где указано Введите код Python здесь.

   Мигающий курсор появится в том месте, где вы будете вводить код.

Примечание:

Это руководство написано для работы в окне Python с использованием одной командной строки. Вы также можете использовать опцию Блокнот Python в приложении, но имейте в виду, что код нужно запускать из одной ячейки, чтобы повторить шаги руководства. Чтобы открыть блокнот Python, выберите вкладку Анализ, щелкните ниспадающее меню Python и выберите Блокнот Python. Более подробно см. в разделе справки Блокноты ArcGIS Pro.

Ссылка на существующий проект

Обычно одной из первых операций со скриптом arcpy.mp, является обращение к существующему проекту (.aprx) или файлу слоя (.lyrx или .lyr), с которым требуется что-то сделать. В этом разделе вы будете обращаться к проекту.

Существует два способа ссылаться на проект. Первый – обращаться к нему на диске, указывая путь к файлу .aprx. Если вы создаете скрипт, который будет выполняться за пределами среды ArcGIS, ссылку на проект необходимо указать с помощью полного системного пути. Второй – обращаться к проекту, загруженному в ArcGIS Pro. При работе в окне Python обращение к загруженному проекту более удобно, так как внесенные в него изменения можно видеть непосредственно в приложении. Следующие шаги показывают, как обратиться к проекту, загруженному в ArcGIS Pro.

1. В окне Python введите следующую строку кода и нажмите клавишу Enter.

   aprx = arcpy.mp.ArcGISProject("CURRENT")

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

2. В окне Python введите следующее:

   aprx.

   После ввода точки вы увидите длинный список методов и свойств, доступных для объекта ArcGISProject.

Примечание:

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

3. В окне Python продолжайте вводить следующее и нажмите клавишу Enter. Укажите путь к существующей базе геоданных.

   aprx.defaultGeodatabase = r"path to a geodatabase"

   Например, введите:

   aprx.defaultGeodatabase = r"C:\Projects\YosemiteNP\Data\Yosemite.gdb"

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

   Примечание:

   Обратите внимание на то, что в начале строки пути размещен символ r в нижнем регистре. Это специальный символ Python, который обозначает необработанные данные. Он указывает, что строку необходимо обрабатывать так, как она представлена, при этом игнорировать любые другие специальные символы в строке. Символ в нижнем регистре r используется потому, что строка пути содержит обратные косые черты. Обратные косые черты в Python являются специальными управляющими символами. Например, \t в строке преобразуется в символ табуляции, а \n преобразуется в новую строку. В приведенном выше примере интерпретация специальных символов нежелательна, так как это может сделать путь некорректным; нужна необработанная строка без каких-либо преобразований. Существует два других эквивалентных способа ввода одинакового пути в Python. Первый – использовать прямые косые черты (например, "C:/Projects/YosemiteNP/Data/Yosemite.gdb"); Python хорошо работает с прямыми косыми чертами; они являются кроссплатформенным стандартом. Второй – использовать двойные обратные косые черты (например, "C:\\Projects\\YosemiteNP\\Data\\Yosemite.gdb"). Первая обратная косая черта отменяет вторую. Важно помнить о способе использования строчной r, потому что при копировании системных путей на платформе Windows с помощью команды Копировать как путь включаются обратные косые черты, поэтому можно добавить r вместо изменения обратных косых черт.

4. Чтобы увидеть изменения, внесенные в проект, щелкните вкладку Проект и выберите Опции.

   Панель Текущие настройки отображает изменение, которое вы внесли в настройку База геоданных по умолчанию.

5. Щелкните Отмена.

   Для проверки изменения базы геоданных по умолчанию можно воспользоваться другим способом — раскрыть подключение Базы данных в панели Каталог. В списке отобразится новая база геоданных, и рядом с ней появится значок дома.

6. В окне Python введите следующий код и нажмите клавишу Enter:

   aprx.save()

   У метода save() нет параметров, но так как это метод, нужно указывать круглые скобки. Теперь подтвердите, что путь корректный. Проверьте, что временная метка в вашем файле проекта обновлена на текущие дату и время.

   Примечание:

   Если сохранение изменений напрямую в текущий проект нежелательно, можно воспользоваться методом aprx.saveACopy(file_name) для сохранения изменений в новом месте, однако переменные Python все равно будут ссылаться на текущий проект.

7. В окне Python введите следующий код и нажмите клавишу Enter:

   print(aprx.filePath)

   Путь к вашему проекту будет выведен в раздел транскрипции.

Добавить файл слоя на карту

Теперь, когда вы обращаетесь к проекту, вы добавите файл слоя (.lyr или .lyrx) на карту, добавленную ранее.

Примечание:

Для следующих шагов нужно подготовить файл векторного слоя, содержащий только один слой.

1. В окне Python введите следующий код и нажмите клавишу Enter:

   m = aprx.listMaps("Tutorial Map")[0]

   Все функции списка arcpy возвращают объекты списка Python. Индекс элементов, возвращаемых в списке, начинается с нуля, что означает, что первый объект списка содержит значение 0, второй 1 и т.д. Так как требуется, чтобы переменная m обращалась к объекту Map, а не к объекту списка Python, необходимо добавить номер индекса после функции. При добавлении в конец функции [0] будет возвращена первая карта в списке. В этом случае в списке будет содержаться только карта, так как в параметре wildcard указано ее уникальное имя. При использовании уникальных имен карт в проекте и соответствующего значения wildcard для изоляции элемента, в списке отобразится только один элемент, и индекс [0] сработает.

2. В окне Python введите следующее:

   m.

   После ввода точки в этот раз вы увидите длинный список методов и свойств, доступных для объекта Map.

   Прежде чем вы сможете использовать метод addLayer для объекта Map, вы должны обратиться к файлу слоя. Процесс обращения к файлу слоя аналогичен обращению к проекту, за исключением использования метода LayerFile.
3. В окне Python используйте клавишу Backspace для удаления m. или любого другого текста, затем введите следующий код и нажмите Enter:

   lyrFile = arcpy.mp.LayerFile(r"path to a layer file")

   Например, введите:

   lyrFile = arcpy.mp.LayerFile(r"C:\Projects\YosemiteNP\LYRS\Boundary.lyrx")

   В приведенном выше шаге была создана ссылка на существующий файл слоя, и эта ссылка сохранена в переменной с именем lyrFile.

4. В окне Python введите следующее:

   lyr = m.addLayer(

   Автозаполнение показывает, что используется один обязательный параметр с именем add_layer_or_layerfile и один дополнительный параметр (выделенный фигурными скобками { }) с именем add_position. Первый параметр может ссылаться на существующий слой в проекте или в файле слоя. Второй параметр не является обязательным и управляет расположением слоя в панели Содержание.

5. В окне Python введите следующий код и нажмите клавишу Enter:

   lyr = m.addLayer(lyrFile)[0]

   Ваш слой добавлен на карту, и на него ссылается переменная lyr, при этом по умолчанию используется значение add_position.

   Файл слоя может содержать один или несколько слоев. По этой причине метод addLayer возвращает список Python, содержащий слои, даже если слой только один. Чтобы обратиться к конкретному объекту Layer, нужен номер индекса. Значение индекса [0] будет возвращать первый слой.

Изменение существующих элементов компоновки

Все элементы в компоновке можно получить через метод listElements объекта Layout. Набор свойств и методов будет различаться в зависимости от типа элемента. В этом разделе вы сначала обновите строку, связанную с текстовым элементом, а затем измените экстент элемента фрейма карты так, чтобы он основывался на экстенте добавленного вами слоя.

1. В окне Python введите следующий код и нажмите клавишу Enter:

   lyt = aprx.listLayouts("Tutorial Layout")[0]

   Приведенный выше код использует ту же логику, что и при обращении к карте, но вместо этого использует метод listLayouts объекта ArcGISProject.

   Теперь, когда у вас есть ссылка на объект Layout с переменной lyt, вы можете обращаться к элементам компоновки.

2. В окне Python введите следующий код и нажмите клавишу Enter:

   title = lyt.listElements("TEXT_ELEMENT", "Title")[0]

   Следует помнить, что все функции списка arcpy возвращают объекты списка Python, поэтому важно указывать номер индекса. Метод listElements принимает два необязательных параметра для фильтрации полученного списка. Первый параметр называется element_type и принимает только значение из списка констант. В данном случае он использует TEXT_ELEMENT. Второй параметр называется wildcard и работает аналогично предыдущим функциям списка. Если вы правильно назвали текстовый элемент, вы сможете корректно обратиться к единственному текстовому элементу.

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

3. В окне Python введите следующий код и нажмите клавишу Enter после каждой строки:

   title.text = "My first arcpy.mp title"
   title.textSize = 36

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

   Используя технику, аналогичную приведенной выше, можно обратиться к фрейму карты на компоновке.

4. В окне Python введите следующий код и нажмите клавишу Enter:

   mf = lyt.listElements("MapFrame_Element", "*frame")[0]

   Приведенный выше код также использует функцию listElements, но обратите внимание на несколько вариантов использования синтаксиса. Во-первых, обратите внимание, что строка element_type имеет смешанный регистр. Большинство ключевых слов arcpy в списках констант нечувствительны к регистру. Во-вторых, обратите внимание, что в параметре wildcard используется специальный подстановочный символ "*". Когда используется подстановочный символ, вся строка нечувствительна к регистру; в противном случае строка должна точно совпадать с регистром. В этом примере переменная mf корректно обращается к фрейму карты с именем Tutorial Map MapFrame, так как имя оканчивается на frame. Подстановочный символ можно использовать разными способами.

   Теперь, когда у вас есть ссылка на слой и элемент фрейма карты, вы можете изменять его экстент, используя экстент, основанный на слое.

5. В окне Python введите следующий код и нажмите клавишу Enter после каждой строки:

   ext = mf.getLayerExtent(layer = lyr, selection_only = False)
   mf.camera.setExtent(ext)
   mf.camera.scale = mf.camera.scale * 1.1

   Первая строка использует метод getLayerExtent объекта MapFrameElement. Первый параметр — это ссылка на слой, а второй параметр определяет, основан ли экстент на всех объектах или только на выбранных объектах. Вторая строка задает экстент фрейма карты равным объекту экстента, возвращенному первой строкой. Последняя строка изменяет масштаб на 10 процентов, чтобы объекты не прилегали вплотную к границам фрейма карты.

Экспорт компоновки в PDF

Экспорт компоновки в PDF требует нескольких строк кода. Вы должны создать формат экспорта, который хотите получить, и затем экспортировать компоновку в этот формат. Компоновка, которую вы собираетесь экспортировать, уже связана с переменной lyt.

1. В окне Python введите следующий код и нажмите клавишу Enter после каждой строки:

   pdf = arcpy.mp.CreateExportFormat("PDF", r"C:\Temp\Yosemite.pdf")
   lyt.export(pdf)

   Первый параметр функции CreateExportFormat называется format и поддерживает 11 вариантов форматов файлов. Второй параметр позволяет указывать местоположение экспорта.

   Файл будет создаваться в указанном вами местоположении.

Сохранение кода в файл Python

Все, что отображается в области вывода окна Python, может быть сохранено в файл Python (*.py). Это может быть действительно полезно, если вы довольны кодом, с которым экспериментировали, и хотите сохранить его. Недостаток в том, что он также включает все ваши опечатки и строки кода, которые могли вызвать ошибку. Эти строки, возможно, потребуется удалить из результата.

1. В окне Python щелкните в области вывода, щелкните правой кнопкой мыши и выберите Save Transcript.
2. Перейдите в местоположение, чтобы сохранить файл как ArcPyMP_Tutorial.py.

   Файл Python может быть открыт в интегрированной среде разработки (IDE), например в Visual Studio Code, PyCharm, Notepad++ и других. Если Python установлен с ArcGIS Pro, у вас есть интегрированная среда разработки под названием IDLE. На следующем шаге предполагается, что IDLE доступен через контекстное меню; в противном случае необходимо открыть файл с помощью интегрированной среды разработки.

3. В File Explorer щелкните файл правой кнопкой мыши и в контекстном меню выберите Редактировать в IDLE (ArcGIS Pro).

Так будет выглядеть содержимое файла Python, если по ходу работы не сделаны ошибки. При экспорте в файл Python первая строка вставляется автоматически.

# coding: utf-8
aprx = arcpy.mp.ArcGISProject("CURRENT")
aprx.defaultGeodatabase = r"C:\Projects\YosemiteNP\Data\Yosemite.gdb"
aprx.save()
print(aprx.filePath)
# C:/Temp/Tutorial/Turorial.aprx
m = aprx.listMaps("Tutorial Map")[0]
lyrFile = arcpy.mp.LayerFile(r"C:\Projects\YosemiteNP\LYRS\Boundary.lyrx")
lyr = m.addLayer(lyrFile)[0]
lyt = aprx.listLayouts("Tutorial Layout")[0]
title = lyt.listElements("TEXT_ELEMENT", "Title")[0]
title.text = "My first arcpy.mp title"
mf = lyt.listElements("MapFrame_Element", "*frame")[0]
ext = mf.getLayerExtent(layer = lyr, selection_only = False)
mf.camera.setExtent(ext)
mf.camera.scale = mf.camera.scale * 1.1
pdf = arcpy.mp.CreateExportFormat("PDF", r"C:\Temp\Yosemite.pdf")
lyt.export(pdf)

В этом руководстве было объяснено, как выполняются основные рабочие процессы с использованием модуля Mapping. Следующим шагом является применение этих основных рабочих процессов к вашим проектам, картам, слоям и другим объектам. Модуль arcpy.mp содержит более 60 типов объектов и классов, каждый из которых содержит набор уникальных свойств и методов. Разделы справки по классам содержат несколько примеров кода, которые могут помочь создавать эффективные скрипты автоматизации.