MapDocument (arcpy.mapping)

Резюме

Обеспечивает доступ к свойствам и методам документа карты (.mxd). Ссылка на этот объект существенна для большинства операций создания скриптов для карты.

Обсуждение

Объект MapDocument является одним из первых объектов, на которые ссылается создаваемый автоматизирующий карту скрипт, поскольку это требуемый параметр для многих функций arcpy.mapping. Через использование объекта MapDocument вы можете ультимативно получить доступ практически ко всем другим объектам внутри документа карты (например, к фреймам данных, слоям, элементам компоновок страниц). Объект MapDocument обеспечивает доступ к большинству свойств документа карты через диалоговое окно Свойства документа карты (Map Document Properties) в ArcMap (Файл (File) > Свойства документа карты (Map Document Properties)). Данный объект также содержит методы для управления образцами документа карты и методами сохранения документов карты, которые можно найти в меню Файл (File) ArcMap.

Существует два способа создания объекта MapDocument с помощью функции MapDocument. Первый и наиболее рекомендуемый метод – указание системного пути к расположению документа карты (.mxd) на диске. Этот способ наиболее универсален, так как такой скрипт можно будет запускать вне приложения ArcGIS. Указание ссылки на документ карты на диске предоставляет больше возможностей для управления с точки зрения запуска скрипта, так как данный скрипт может работать не со всеми документами карты.

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

Инструменты скрипта, использующие ключевое слово CURRENT, должны запускаться в ArcMap (из пользовательского меню или окна Каталог). Инструменты скриптов, использующие CURRENT, будут работать неправильно при запуске из приложения ArcCatalog. По этой же причине, если у инструмента есть скрипт проверки со ссылкой на CURRENT, при попытке изменения скрипта проверки в ArcCatalog может возникнуть ошибка. Обязательно измените код проверки в окне Каталога ArcMap.

Чтобы использовать ключевое слово CURRENT в инструменте-скрипте, необходимо отключить фоновую обработку. При фоновой обработке все скрипты выполняются так, будто автономные скрипты за пределами приложения ArcGIS, поэтому CURRENT не будет работать с включенной фоновой обработкой. Доступна новая опция для инструмента-скрипта, Всегда выполнять не в фоновом режиме (Always run in foreground), которая гарантирует, что инструмент будет всегда работать в активном режиме, даже если включена фоновая обработка.

Очень важно понимать, как переменные ссылаются на объекты MapDocument в среде написания скриптов, особенно когда вы сохраняете ваши результаты в новом файле. Вы должны понимать, что, когда вы первоначально создаёте переменную, которая ссылается на объект MapDocument, она всегда будет указывать на исходный документ на диске или в текущий момент в памяти (посредством CURRENT). В приложении ArcMap, если вы выполните Сохранить как (SaveAs) в новое местоположение, то все последующие изменения будут направлены в новый файл. Это является невозможным в среде написания скриптов и, следовательно, метод Сохранить как (SaveAs) не поддерживается. Класс MapDocument обладает методами save (сохранить) и saveACopy (сохранить копию) для управления модификациями документа карты.

Если написание скрипта используется для модификации отображения некоторых элементов документа карты при использовании документа карты CURRENT (например, изменение имени слоя, экстента фрейма данных и т.п.), то карта может не обновляться автоматически при выполнении каждой строки кода. Чтобы обновить документ карты с отображением изменений, используйте либо функцию RefreshActiveView, либо функцию RefreshTOC. Данные функции будут обновлять отображение карты или компоновки страницы, и таблицу содержания, соответственно. Функции обновления необходимы только тогда, когда вы хотите видеть ваше приложение обновлённым. Функции arcpy.mapping export, save и printing будут генерировать ожидаемые обновлённые результаты без использования данных функций.

Некоторые слои документа карты или файла слоя могут иметь защиту паролем, поскольку имя пользователя и пароль не хранятся вместе с файлом слоя или документом карты. Документы карты, содержащие такие слои, требуют ввода пароля при открытии. В среде скриптов arcpy.mapping, по умолчанию, эти диалоговые окна не отображаются, но это означает, что слои будут рассматриваться как имеющие поврежденные источники данных. Другими словами, защищенные слои не будут отображаться в выходных данных. Если необходимо, чтобы эти слои отображались правильно, можно использовать несколько опций. Сначала, сохраните имя пользователя и пароль вместе со слоем. Затем, функция геообработки CreateArcSDEConnectionFile позволит создать подключение, которое будет находиться в памяти. Если эта команда используется до открытия документа карты (.mxd) с помощью функции MapDocument или файла слоя с помощью Layer, слои SDE будут отображаться правильно. На данный момент, другого способа для защищенных веб-сервисов нет.

Переменная, которая ссылается на объект MapDocument, включает блокировку файла документа карты. Рекомендуется удалять ссылку на объект MapDocument, используя команду Python del в конце скрипта или в выражении Python try/except.

Изменение источников данных в документе карты – это общее требование. Существуют два метода для объекта MapDocument, которые помогают это сделать. Метод findAndReplaceWorkspacePaths предназначен для замены части или всего пути рабочей области слоя или таблицы. Метод replaceWorkspaces позволяет изменить не только путь, но также и тип рабочей области. Более подробное описание, сведения о параметрах, сценарии и примеры кода см. в разделе справки Обновление и фиксирование источников данных с помощью модуля arcpy.mapping.

Синтаксис

MapDocument (mxd_path)

Параметр	Объяснение	Тип данных
mxd_path	Строка, включающая полный путь и имя файла существующего документа карты (.mxd) или строка, содержащая ключевое слово CURRENT.	String

Свойства

Свойство	Объяснение	Тип данных
activeDataFrame (только чтение)	Возвращает объект DataFrame, содержащий активный в текущий момент фрейм данных документа карты (.mxd). Свойство activeDataFrame возвращает подходящий фрейм данных, даже если документ карты находится в режиме вида компоновки. Если вы хотите установить активный фрейм данных, используйте свойство activeView.	DataFrame
activeView (чтение и запись)	Обеспечивает возможность установки или получения активного вида документа карты – как вида данных, так и компоновки страницы. Свойство работает со строкой, содержащей имя активного фрейма данных или кодовым словом PAGE_LAYOUT. Если значением свойства activeView является PAGE_LAYOUT и документ карты сохраняется, в следующий раз документ карты будет открыт в режиме компоновки. Если для activeView установлено имя фрейма данных и документ карты сохраняется, в следующий раз документ карты будет открыт в режиме вида данных, а активным будет конкретный фрейм данных.	String
author (чтение и запись)	Позволяет получить или указать информацию об авторе документа карты.	String
credits (чтение и запись)	Дает возможность получать или задавать информацию об авторах документа карты и правовую информацию.	String
dataDrivenPages (только чтение)	Возвращает объект DataDrivenPages, который может использоваться для управления страницами многостраничной компоновки документа карты.	DataDrivenPages
dateExported (только чтение)	Возвращает объект datetime Python, определяющий дату последнего экспорта документа карты. Текущее значение будет получено только в том случае, если документ карты был сохранен после экспорта карты.	DateTime
datePrinted (только чтение)	Возвращает объект datetime Python, определяющий дату последней печати документа карты. Текущее значение будет получено только в том случае, если документ карты был сохранен после экспорта карты.	DateTime
dateSaved (только чтение)	Возвращает объект datetime Python, определяющий дату последнего сохранения документа карты.	DateTime
description (чтение и запись)	Позволяет получить или указать описательную информацию документа.	String
filePath (только чтение)	Возвращает строковое значение, содержащее полное имя и путь к документу карты.	String
hyperlinkBase (чтение и запись)	Позволяет получить или указать базовый путь или URL для основанных на полях гиперссылок на документы или URL.	String
isDDPEnabled (только чтение)	Возвращает True (Истина), если в документе карты включена многостраничная компоновка.	Boolean
pageSize (только чтение)	Позволяет получить размер страницы компоновки. Возвращает именованный кортеж со свойствами width (ширина) и height (высота). Следующий скрипт показывает использование нескольких вариантов высоты и ширины страницы документа карты для печати. mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd") print mxd.pageSize print mxd.pageSize.width; print mxd.pageSize.height pageWidth, pageHeight = mxd.pageSize print pageWidth, pageHeight	tuple
relativePaths (чтение и запись)	Позволяет контролировать, хранит ли документ карты относительные пути к источникам данных. Значение True (Истина) устанавливает относительные пути; а False (Ложь) – абсолютные пути к источникам данных.	Boolean
summary (чтение и запись)	Позволяет получать или вводить итоговую информацию о документе карты.	String
tags (чтение и запись)	Позволяет получить или указать информацию о тегах документа карты. Разделите теги запятой (,).	String
title (чтение и запись)	Позволяет получить или указать информацию о заголовке документа карты.	String

Обзор метода

Метод	Объяснение
deleteThumbnail ()	Удаляет иконку документа карты (.mxd)
findAndReplaceWorkspacePaths (find_workspace_path, replace_workspace_path, {validate})	Находит старые пути к рабочим областям и заменяет их новыми для всех слоев и таблиц документа карты (.mxd)
makeThumbnail ()	Создает иконку документа карты (.mxd)
replaceWorkspaces (old_workspace_path, old_workspace_type, new_workspace_path, new_workspace_type, {validate})	Заменяет старую рабочую область новой для всех слоев и таблиц документа карты (.mxd); также позволяет переключать типы рабочих областей (например, заменяет источник данных файловой базы геоданных на источник данных SDE)
save ()	Сохраняет документ карты (.mxd)
saveACopy (file_name, {version})	Предоставляет возможность сохранить документ карты (.mxd) в новый файл и, дополнительно, в формате предыдущей версии.

Методы

deleteThumbnail ()

Осуществляет то же действие, которое происходит при нажатии на кнопку Удалить образец (Delete Thumbnail) в диалоговом окне Файл (File) > Свойства документа карты (Map Document Properties) в ArcMap.

findAndReplaceWorkspacePaths (find_workspace_path, replace_workspace_path, {validate})

Параметр	Объяснение	Тип данных
find_workspace_path	Строка, содержащая путь к искомым рабочей области или файлу подключения. Если передана пустая строка, все пути рабочих областей будут заменены, при этом параметр replace_workspace_path будет зависеть от значения параметра проверить.	String
replace_workspace_path	Строка, в которой представлен путь рабочей области или файл подключения, который необходимо заменить.	String
validate	Если задано значение True, рабочая область обновляется, только если значением replace_workspace_path является допустимая рабочая область. Если значение недопустимо, рабочая область не заменяется. Если задано значение Ложь (False), метод задает все рабочие области как replace_workspace_path независимо от ее наличия соответствий. В этом случае, если соответствий нет, это означает, что слой и источник данных таблицы повреждены. (Значение по умолчанию — True)	Boolean

Более подробное описание, сведения о параметрах, сценарии и примеры кода см. в разделе справки Обновление и фиксирование источников данных с помощью модуля arcpy.mapping.

makeThumbnail ()

Осуществляет то же действие, которое происходит при нажатии на кнопку Создать образец (Make Thumbnail) в диалоговом окне Файл (File) > Свойства документа карты (Map Document Properties) в ArcMap.

replaceWorkspaces (old_workspace_path, old_workspace_type, new_workspace_path, new_workspace_type, {validate})

Параметр	Объяснение	Тип данных
old_workspace_path	Строка, содержащая искомые путь к рабочей области или файлу подключения. Если передана пустая строка, все пути рабочих областей будут заменены, при этом параметр new_workspace_path будет зависеть от значения параметра validate.	String
old_workspace_type	Ключевое слово, представляющее тип рабочей области заменяемых старых данных. Если передана пустая строка, можно перенаправить несколько рабочих областей в одну рабочую область. ACCESS_WORKSPACE — Персональная база геоданных или рабочая область Access ARCINFO_WORKSPACE — Рабочая область покрытия ArcInfo CAD_WORKSPACE —Рабочая область файла САПР EXCEL_WORKSPACE —Рабочая область файла Excel FILEGDB_WORKSPACE —Рабочая область файловой базы геоданных Нет сжатия (NONE) —Используется для пропуска параметра OLEDB_WORKSPACE —Рабочая область базы данных OLE PCCOVERAGE_WORKSPACE —Рабочая область покрытия PC ARC/INFO RASTER_WORKSPACE —Рабочая область растра SDE_WORKSPACE —Рабочая область базы геоданных SDE SHAPEFILE_WORKSPACE —Рабочая область шейп-файла TEXT_WORKSPACE —Рабочая область текстового файла TIN_WORKSPACE —Рабочая область TIN VPF_WORKSPACE —Рабочая область VPF	String
new_workspace_path	Строка, в которой представлен новый путь рабочей области или файл подключения.	String
new_workspace_type	Строковое ключевое слово, представляющее тип рабочей области, который заменит old_workspace_type. ACCESS_WORKSPACE — Персональная база геоданных или рабочая область Access ARCINFO_WORKSPACE — Рабочая область покрытия ArcInfo CAD_WORKSPACE —Рабочая область файла САПР EXCEL_WORKSPACE —Рабочая область файла Excel FILEGDB_WORKSPACE —Рабочая область файловой базы геоданных OLEDB_WORKSPACE —Рабочая область базы данных OLE PCCOVERAGE_WORKSPACE —Рабочая область покрытия PC ARC/INFO RASTER_WORKSPACE —Рабочая область растра SDE_WORKSPACE —Рабочая область базы геоданных SDE SHAPEFILE_WORKSPACE —Рабочая область шейп-файла TEXT_WORKSPACE —Рабочая область текстового файла TIN_WORKSPACE —Рабочая область TIN VPF_WORKSPACE —Рабочая область VPF	String
validate	Если задано значение True, рабочая область обновляется, только если значением new_workspace_path является допустимая рабочая область. Если значение недопустимо, рабочая область не заменяется. Если задано значение False, метод задает все рабочие области как new_workspace_path независимо от ее наличия соответствий. В этом случае, если соответствий нет, источники данных повреждены. (Значение по умолчанию — True)	Boolean

Более подробное описание, сведения о параметрах, сценарии и примеры кода см. в разделе справки Обновление и фиксирование источников данных с помощью модуля arcpy.mapping.

save ()

Операция идентична команде меню Файл (File) > Сохранить (Save) в ArcMap.

saveACopy (file_name, {version})

Параметр	Объяснение	Тип данных
file_name	Строка, которая включает расположение и имя выходного документа карты (.mxd).	String
version	Строка, задающая номер выходной версии. Значение по умолчанию будет использовать текущую версию. 10.1 —Версия 10.1 10.0 —Версия 10.0 8.3 —Версия 8.3 9.0 —Версия 9.0/9.1 9.2 —Версия 9.2 9.3 —Версия 9.3 (Значение по умолчанию — None)	String

При этом выполняется та же операция, что и Файл (File) > SaveACopy в ArcMap. Объекты, которые не поддерживаются в предыдущих версиях программного обеспечения, будут удалены из нового сохраненного документа карты.

Пример кода

MapDocument, пример 1

Следующий скрипт создает отдельный MXD-файл для каждого фрейма данных в документе карты. Выходные документы карты будут сохранены в режиме просмотра данных, так что при открывании каждого документа карты, соответствующий фрейм данных будет активным. Этот скрипт также задает свойство заголовка каждого выходного документа карты. Поскольку этот скрипт использует системный путь к документу карты, его можно запускать вне приложения ArcMap. Примечание: строка Python не может заканчиваться обратной косой чертой, даже если перед строкой стоит r. Необходимо использовать двойную обратную косую черту. Это важно в тех случаях, когда к пути к папке присоединяются динамические имена файлов.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
for df in arcpy.mapping.ListDataFrames(mxd):
    mxd.activeView = df.name
    mxd.title = df.name
    mxd.saveACopy(r"C:\Project\Output\\" + df.name + ".mxd")
del mxd

MapDocument, пример 2

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

mxd = arcpy.mapping.MapDocument("CURRENT")
arcpy.mapping.ListDataFrames(mxd)[0].name = "New Data Frame Name"
arcpy.RefreshTOC()
del mxd

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

>>> mxd = arcpy.mapping.MapDocument("CURRENT")
... arcpy.mapping.ListDataFrames(mxd)[0].name = "New Data Frame Name"
... arcpy.RefreshTOC()
... del mxd
...

MapDocument, пример 3

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

mxd = arcpy.mapping.MapDocument("CURRENT")
for lyr in arcpy.mapping.ListLayers(mxd):
    print lyr.name
del mxd

При вставке в интерактивное окно, он выглядит так. Снова нажмите клавишу Ввод, чтобы выполнить линии.

>>> mxd = arcpy.mapping.MapDocument("CURRENT")
... for lyr in arcpy.mapping.ListLayers(mxd):
...     print lyr.name
... del mxd
...

MapDocument, пример 4

Следующий скрипт позволяет правильно отобразить защищенные слои, с помощью создания подключения SDE в памяти перед открытием документа карты, для которого требуется пароль. Этот скрипт просто задает информацию о подключении и экспортирует документ карты в файл PDF. Рекомендуется удалить эту ссылку из памяти до закрытия скрипта.

import arcpy, os

#Remove temporary connection file if it already exists
sdeFile = r"C:\Project\Output\TempSDEConnectionFile.sde"
if os.path.exists(sdeFile):
    os.remove(sdeFile)

#Create temporary connection file in memory
arcpy.CreateArcSDEConnectionFile_management(r"C:\Project\Output", "TempConnection", "myServerName", "5151", "myDatabase", "DATABASE_AUTH", "myUserName", "myPassword", "SAVE_USERNAME", "myUser.DEFAULT", "SAVE_VERSION")

#Export a map document to verify that secured layers are present
mxd = arcpy.mapping.MapDocument(r"C:\Project\SDEdata.mxd")
arcpy.mapping.ExportToPDF(mxd, r"C:\Project\output\SDEdata.pdf")

os.remove(sdeFile)
del mxd