Краткая информация
Обеспечивает доступ к свойствам и методам документа карты (.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 (высота). Следующий скрипт показывает использование нескольких вариантов высоты и ширины страницы документа карты для печати. | 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 | Ключевое слово, представляющее тип рабочей области заменяемых старых данных. Если передана пустая строка, можно перенаправить несколько рабочих областей в одну рабочую область.
| String |
new_workspace_path | Строка, в которой представлен новый путь рабочей области или файл подключения. | String |
new_workspace_type | Строковое ключевое слово, представляющее тип рабочей области, который заменит old_workspace_type.
| 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 | Строка, задающая номер выходной версии. Значение по умолчанию будет использовать текущую версию.
(Значение по умолчанию — None) | String |
При этом выполняется та же операция, что и Файл (File) > SaveACopy в ArcMap. Объекты, которые не поддерживаются в предыдущих версиях программного обеспечения, будут удалены из нового сохраненного документа карты. При вызове saveACopy в автономном скрипте "разбухание"документа не будет удалено. Это происходит потому, что автономные скрипты Python обращаются к документу карты не так, как если бы это происходило из приложения.
Пример кода
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