Краткая информация
Класс MapsurroundElement предоставляет доступ к свойствам размера и положения, а также ссылку на связанный фрейм карты.
Обсуждение
MapSurroundElement - это элемент компоновки, который имеет связанный элемент MapFrame и динамически связан с информацией о фрейме карты. Например, стрелка на север является окружением карты и связана с поворотом соответствующего фрейма карты, а шкала масштабирования связана с масштабом карты. Метод listElements для класса Layout возвращает список Python всех возможных элементов компоновки. Чтобы вернуть список только объектов MapSurroundElement, используйте константу MAPSURROUND_ELEMENT для параметра element_type. Значение wildcard также может быть использовано для дальнейшей тонкой настройки поиска на основе значения name элемента. Важно, чтобы у каждого элемента компоновки было свое уникальное имя, чтобы на него можно было ссылаться с использованием скрипта ArcPy.
MapSurroundElement - это универсальный объект с относительно небольшим количеством свойств. Многие свойства связаны с размером и положением карты в компоновке. Свойство mapFrame вернет ссылку на объект MapFrame, и из этого объекта вы сможете получить доступ к фрейму карты map, используя его свойство map.
Ряд элементов макета возвращают значение type MAPSURROUND_ELEMENT. К ним относятся стрелки севера, линейки масштаба, фреймы диаграмм, таблиц и, возможно, другие будущие типы элементов, у которых в настоящее время нет выделенного объекта со специализированными свойствами. Вы можете получить доступ к некоторым из этих специализированных свойств объекта, используя доступ Python CIM. Примеры этого приведены в примерах кода ниже. Одним из примеров окружения карты специализированными методами и свойствами является LegendElement. Он возвращает для элемента type значение LEGEND_ELEMENT.
Внимание:
В дельнейшей разработке объекты с текущим значением type MAPSURROUND_ELEMENT могут быть преобразованы в свой собственный специализированный тип объекта, что потенциально повлияет на значение свойства type элемента и список перечислений element_type, доступный методу компоновки listElements.
Значения elementPositionX и elementPositionY базируются на положении якорной точки элемента, которое установлено на вкладке Формат. Положение по умолчанию зависит от типа окружения карты. Например, якорем стрелки севера по умолчанию является центральная точка, но положением шкалы масштаба по умолчанию является нижний левый угол.
Вы также можете создать окружение карты, используя метод createMapSurroundElement в классе Layout. Используя этот метод, вы ограничены созданием теми типами элементов окружения карты, которые основаны на входном параметре map_surround_type. Также полезно ссылаться на существующий элемент StyleItem во время создания, чтобы управлять отображением элемента в компоновке. Примеры приведены ниже.
Свойства
| Свойство | Описание | Тип данных |
| anchor (только чтение) | Возвращает одно из следующих строковых значений, которые описывают текущую позицию якоря. Чтобы изменить значение, используйте метод setAnchor.
| String |
| elementHeight (чтение и запись) | Высота элемента в единицах страницы. | Double |
| elementPositionX (чтение и запись) | x-положение позиции точки якоря элемента. Единицы измерения задаются или считываются в единицах страницы. | Double |
| elementPositionY (чтение и запись) | y-положение позиции точки якоря элемента. Единицы измерения задаются или считываются в единицах страницы. | Double |
| elementRotation (чтение и запись) | Угол поворота элемента в градусах. Положительные значения поворачивают по часовой стрелке, а отрицательные – против часовой стрелки. Примечание:Это свойство не применяется к стрелкам севера, поскольку их поворот определяется вращением карты. | Double |
| elementWidth (чтение и запись) |
Ширина элемента в единицах страницы. | Double |
| locked (чтение и запись) | Если установлено значение True, элемент нельзя выбрать графически в виде компоновки. | Boolean |
| longName (только чтение) | Полное имя элемента, включая информацию о группе, если она существует. Например, элемент с именем 'North Arrow' в групповом элементе с именем 'Group Element' вернет значение longName, равное 'Group Element\\North Arrow'. Если элемент не входит в группу, longName будет таким же, как и значение name. | String |
| mapFrame (чтение и запись) | Ссылка на связанный MapFrame. | MapFrame |
| name (чтение и запись) | Имя элемента. Важно, чтобы у всех элементов были уникальные имена, благодаря чему на них можно было бы ссылаться с помощью параметра wildcard функции listElements объекта Layout. | String |
| parentGroupElement (только чтение) | Если элемент находится в группе, возвращаемым значением будет GroupElement, в противном случае будет возвращено NoneType. | GroupElement |
| type (только чтение) | Возвращает значение MAPSURROUND_ELEMENT. | String |
| visible (чтение и запись) | Возвращает True, если элемент является видимым в компоновке. Вместо того чтобы удалять ненужные объекты со страницы перед печатью или экспортом, вы можете включать и выключать видимость элементов. | Boolean |
Обзор метода
| Метод | Описание |
| applyStyleItem (style_item) | Применяет StyleItem к MapSurroundElement. |
| getDefinition (cim_version) | Получает определение CIM элемента зарамочного оформления карты. |
| setAnchor (anchor) | Метод setAnchor, управляющий положением якоря для значения MapSurroundElement. |
| setDefinition (definition_object) | Задает определение CIM элемента зарамочного оформления карты. |
Методы
applyStyleItem (style_item)
При привязывании StyleItem с помощью метода listStyleItems для класса ArcGISProject параметр style_class должен быть NORTH_ARROW или SCALE_BAR. Обратитесь к разделу справки StyleItem для получения дополнительной информации и примеров кода.
Примечание:
Перед использованием метода applyStyleItem необходимо добавить стили в проект. Их можно добавить, используя метод updateStyles для класса ArcGISProject.
getDefinition (cim_version)
| Параметр | Описание | Тип данных |
cim_version | A string that represents the major version of the CIM that will be used.
| String |
| Тип данных | Описание |
| Object | Возвращает определение CIM для значения MapsurroundElement. |
Более подробно о работе с CIM и примеры см. Доступ к CIM в Python.
setAnchor (anchor)
| Параметр | Описание | Тип данных |
anchor | A string that specifies the location of the anchor position.
| String |
Задание положения якоря привязки полезно, поскольку с его помощью вы можете контролировать, как элемент будет расширяться при изменении размера. Например, положения якоря по умолчанию для элемента масштабной линейки зарамочного оформления карты - BOTTOM_LEFT_CORNER. Если вы измените положение якоря на TOP_RIGHT_CORNER, изменение значения elementHeight приведет к расширению элемента вниз вместо расширения вверх (по умолчанию), а изменение значения elementWidth - к расширению элемента влево.
setDefinition (definition_object)
| Параметр | Описание | Тип данных |
definition_object | A modified CIM definition object originally retrieved using getDefinition. | Object |
Более подробно о работе с CIM и примеры см. Доступ к CIM в Python.
Пример кода
Скрипт ниже выполняет поиск элемента MapsurroundElement с именем ScaleBar и меняет его положение таким образом, чтобы центр масштабной линейки располагался на 0,5 единиц карты ниже и по центру связанного фрейма карты. Обратите внимание, что для масштабной линейки было задано положение якоря и центральная точка. Для фрейма данных задан якорь местоположения в левом нижнем углу.
import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
lyt = aprx.listLayouts("Points of Interest")[0]
scaleBar = lyt.listElements("MAPSURROUND_ELEMENT", "ScaleBar")[0]
mf = scaleBar.mapFrame
scaleBar.elementPositionX = mf.elementPositionX + (mf.elementWidth / 2)
scaleBar.elementPositionY = mf.elementPositionY - 0.5
aprx.save()
del aprxСледующий скрипт создает стрелку севера в точке расположения в компоновке, используя системный стиль Esri. Затем он использует доступ Python CIM для изменения значения calibrationAngle.
#Page units Centimeters
p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts('Layout')[0]
mf = lyt.listElements('MapFrame_Element', 'Map Frame')[0]
naStyle = p.listStyleItems('ArcGIS 2D', 'North_Arrow', 'Compass North 1')[0]
na = lyt.createMapSurroundElement(arcpy.Point(18.5,18), 'North_Arrow', mf,
nArrowStyle, "Compass North Arrow")
na.elementWidth = 2
#CIM modifications - change calibration angle
lyt_cim = lyt.getDefinition('V3')
for elm in lyt_cim.elements:
if elm.name == "Compass North Arrow":
elm.northType = 'TrueNorth'
elm.calibrationAngle = -2.5
lyt.setDefinition(lyt_cim)Следующий скрипт создает масштабную линейку в компоновке, используя вспомогательную функцию для создания прямоугольника для ее размещения, а также использует системный стиль Esri. Затем он использует доступ Python CIM для изменения делений линейки и округления.
#Helper function to make an envelope from a lower left X, Y, width and height
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('current')
lyt = p.listLayouts('Layout')[0]
mf = lyt.listElements('MapFrame_Element', 'Map Frame')[0]
#Page units Centimeters
sbName = 'Double Alternating Scale Bar 1 Metric'
sbStyle = p.listStyleItems('ArcGIS 2D', 'Scale_bar', sbName)[0]
sbEnv = MakeRec_LL(1.5, 15, 8, 1)
sb = lyt.createMapSurroundElement(sbEnv, 'Scale_bar', mf, sbStyle, 'New Scale Bar')
#CIM modifications - change number of subdivisions and rounding
lyt_cim = lyt.getDefinition('V3')
for elm in lyt_cim.elements:
if elm.name == 'New Scale Bar':
elm.subdivisions = 2
elm.numberFormat.roundingOption = "esriRoundNumberOfSignificantDigits"
elm.numberFormat.roundingValue = 2
lyt.setDefinition(lyt_cim)Следующий скрипт создает в компоновке легенду, используя системный стиль Esri и вспомогательную функцию для создания прямоугольника для его размещения. Затем он использует доступ Python CIM для изменения минимального размера шрифта.
#Helper function to make an envelope from a upper left X, Y, width and height
def MakeRec_UL(ulx, uly, w, h):
xyRecList = [[ulx, uly], [ulx+w, uly], [ulx+w,uly-h], [ulx,uly-h], [ulx,uly]]
array = arcpy.Array([arcpy.Point(*coords) for coords in xyRecList])
rec = arcpy.Polygon(array)
return rec
p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts('Layout')[0]
mf = lyt.listElements('MapFrame_Element', 'Map Frame')[0]
#Page units Centimeters
legStyle = p.listStyleItems('ArcGIS 2D', 'Legend', 'Legend 3')[0]
legEnv = MakeRec_UL(1.5, 14, 18.5, 10)
sb = lyt.createMapSurroundElement(legEnv, 'Legend', mf, legStyle, 'New Legend')
#CIM modifications - change the minimum font size
lyt_cim = lyt.getDefinition('V3')
for elm in lyt_cim.elements:
if elm.name == 'New Legend':
if elm.fittingStrategy == 'AdjustColumnsAndSize':
elm.minFontSize = 8
lyt.setDefinition(lyt_cim)