MapSurroundElement

Краткая информация

Класс 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.

  • BOTTOM_LEFT_CORNERВ левом нижнем углу
  • BOTTOM_MID_POINTСнизу по центру
  • BOTTOM_RIGHT_CORNERВ правом нижнем углу
  • CENTER_POINTВ центре
  • LEFT_MID_POINTСлева по центру
  • RIGHT_MID_POINTСправа по центру
  • TOP_LEFT_CORNERВ левом верхнем углу
  • TOP_MID_POINTСверху по центру
  • TOP_RIGHT_CORNERВ правом верхнем углу
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)
ПараметрОписаниеТип данных
style_item

A reference to a StyleItem in a project.

StyleItem

При привязывании 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.

  • V2The 2.x version of the CIM will be used.
  • V3The 3.x version of the CIM will be used.
String
Возвращаемое значение
Тип данныхОписание
Object

Возвращает определение CIM для значения MapsurroundElement.

Более подробно о работе с CIM и примеры см. Доступ к CIM в Python.

setAnchor (anchor)
ПараметрОписаниеТип данных
anchor

A string that specifies the location of the anchor position.

  • BOTTOM_LEFT_CORNERThe anchor will be set at the bottom left corner position.
  • BOTTOM_MID_POINTThe anchor will be set at the bottom center position.
  • BOTTOM_RIGHT_CORNERThe anchor will be set at the bottom right corner position.
  • CENTER_POINTThe anchor will be set at the center position.
  • LEFT_MID_POINTThe anchor will be set at the left center position.
  • RIGHT_MID_POINTThe anchor will be set at the right center position.
  • TOP_LEFT_CORNERThe anchor will be set at the top left corner position.
  • TOP_MID_POINTThe anchor will be set at the top center position.
  • TOP_RIGHT_CORNERThe anchor will be set at the top right corner 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, пример 1

Скрипт ниже выполняет поиск элемента 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
MapsurroundElement, пример 2

Следующий скрипт создает стрелку севера в точке расположения в компоновке, используя системный стиль 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)
MapsurroundElement, пример 3

Следующий скрипт создает масштабную линейку в компоновке, используя вспомогательную функцию для создания прямоугольника для ее размещения, а также использует системный стиль 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)
MapsurroundElement, пример 4

Следующий скрипт создает в компоновке легенду, используя системный стиль 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)