PictureElement

摘要

可通过 PictureElement 类访问图片属性，以在页面布局上重新定位图片以及获取和设置其数据源。

说明

PictureElement 对象表示已插入页面布局的栅格或图像。 Layout 对象上的 listElements 方法将返回页面布局元素对象的 Python 列表。 然后需要迭代列表中的每个项目或指定一个索引编号以引用特定的页面元素对象。 要仅返回 PictureElement 对象的列表，应对 element_type 参数使用 PICTURE_ELEMENT 常量。 还可以使用 wildcard 对基于元素 name 的搜索进行进一步优化。

PictureElement 对象具有 sourceImage 属性，可用于读取原始源或指定新图片源位置。 如果您打算将图片替换为大小和横纵比不同的图片，则使用表示您希望所有其他图片在页面布局上占据的整个区域的高度和宽度创作原始图片。 如果图片已使用 sourceImage 属性替换并且具有不同的横纵比，则它将使用最长尺寸占据原数图片区域。 已替换图片不能大于原数创作的尺寸。 您还想要设置锚点位置，以便所有新图片相对于该位置进行适应。 如果您不想倾斜图片，确保将保留横纵比选项设置为 True。

图片始终存储在工程中。 sourceImage 属性会在插入图片时显示原始源位置，但是可以从磁盘中移除文件，图片仍会在布局中显示。

可通过 ArcGISProject 对象上的 createPictureElement 方法使用页面单位将图片添加到 Layout 对象，或使用地图单位将图形图层添加到 Map 对象。 可使用点或矩形面几何创建图片。 新建图片的默认锚点位置为左上方，该坐标表示 X 和 Y 元素位置。

注：

可使用 Python CIM 访问修改布局中的其他图片属性，但是这不适用于图形图层中的图片元素。 这是因为所有图片数据保留在二进制引用中，以优化性能。 图形图层还具有硬限制 4000 个元素或大小限制 10MB。 这意味着无法插入大于 10MB 的单张图片或超过 10 MB 的任意数量图片。

属性

属性	说明	数据类型
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
name (可读写)	元素的名称。	String
sourceImage (可读写)	用于表示到图片数据源的路径的文本字符串。	String
type (只读)	返回 PICTURE_ELEMENT	String
visible (可读写)	如果元素在布局上可见，则返回 True。 打印或导出之前，您可以打开和关闭元素的可见性，而无需从页面移除不需要的对象。	Boolean

方法概述

方法	说明
getDefinition (cim_version)	返回图片元素的 CIM 定义。
setAnchor (anchor)	setAnchor 方法可控制 PictureElement 的锚点位置。
setDefinition (definition_object)	设置图片元素的 CIM 定义。

方法

getDefinition (cim_version)

参数	说明	数据类型
cim_version	A string that represents the major version of the CIM that will be used. V2—The 2.x version of the CIM will be used. V3—The 3.x version of the CIM will be used.	String

返回值

数据类型	说明
Object	返回 PictureElement 的 CIM 定义。

有关使用 CIM 和示例的详细信息，请参阅 Python CIM 访问。

setAnchor (anchor)

参数	说明	数据类型
anchor	A string that specifies the location of the anchor position. BOTTOM_LEFT_CORNER—The anchor will be set at the bottom left corner position. BOTTOM_MID_POINT—The anchor will be set at the bottom center position. BOTTOM_RIGHT_CORNER—The anchor will be set at the bottom right corner position. CENTER_POINT—The anchor will be set at the center position. LEFT_MID_POINT—The anchor will be set at the left center position. RIGHT_MID_POINT—The anchor will be set at the right center position. TOP_LEFT_CORNER—The anchor will be set at the top left corner position. TOP_MID_POINT—The anchor will be set at the top center position. TOP_RIGHT_CORNER—The anchor will be set at the top right corner position.	String

设置锚点位置非常有用，因为您可以控制元素在调整大小时的展开方式。 例如，当您希望图片保持在特定位置居中时，可以将锚点位置设置为 CENTER_POINT。 当根据点要素的位置将图片放置为地图图形时，这将非常有用。

setDefinition (definition_object)

参数	说明	数据类型
definition_object	A modified CIM definition object originally retrieved using getDefinition.	Object

有关使用 CIM 和示例的详细信息，请参阅 Python CIM 访问。

代码示例

PictureElement 示例 1

以下脚本将在目录结构中搜索工程文件。 对于找到的每个工程，该脚本将循环遍历所有布局以查找图片元素。 如果找到了 oldSourcePath，则会将其替换为 newSourcePath 并打印进行了更改的工程和布局。

import arcpy, os

rootFolder = r'C:\Projects'
oldSourcePath = r'C:\Projects\OldLogo.png'
newSourcePath = r'C:\Projects\NewLogo.png'

for (rootFolder, dirs, files) in os.walk(rootFolder):
  for file in files:
    if file.endswith('.aprx'):
      p = arcpy.mp.ArcGISProject(os.path.join(rootFolder,file))
      print(os.path.join(rootFolder,file))
      for lyt in p.listLayouts():      
        for pic in lyt.listElements('picture_element'):
          if pic.sourceImage == oldSourcePath:
            pic.sourceImage = newSourcePath
            print(f'Found OldLogo: /n  Project: {file} /n  :Layout: {lyt.name}') 
      #p.save()  #Test before permenantly replacing

PictureElement 示例 2

以下脚本会使用包络矩形将两个新图片添加至布局。 当前使用一个函数帮助创建几何，需指定 X,Y 锚点位置以及采用页面单位的宽度和高度。 在插入图片后，即会将这些图片添加到新的 GroupElement 中。

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]

picPath1 = r'C:\Projects\Fenway.jpg'
picPath2 = r'C:\Projects\Chowdah.png'

pic1 = p.createPictureElement(lyt, MakeRec_UL(1,7.5,8.67,6.5), picPath1, 'Fenway')
pic2 = p.createPictureElement(lyt, MakeRec_UL(5.8,7.34,4.2,6.43), picPath2, 'Chowdah')

newGroup = p.createGroupElement(lyt, [pic1, pic2], 'Favorite Pets')

PictureElement 示例 3

以下脚本将使用点几何在要素类中每个点要素位置处添加图片。 该脚本在放置图片时还会根据图片的指定宽度和高度将其居中在点要素上。

p = arcpy.mp.ArcGISProject('current')
m = p.listMaps('Map')[0]  #USA Contiguous Albers Equal Area Conic USGS_1
ptLyr = m.listLayers('*Point')[0]
graLyr = m.createGraphicsLayer()
m.moveLayer(ptLyr, graLyr, 'AFTER')

picPath = r'C:\Projects\Chowdah.png'

for row in arcpy.da.SearchCursor(ptLyr, ['SHAPE@XY']):
    x, y = row[0]
    centeredPt = arcpy.Point(x-50000, y+75000) #1/2 width and height
    pic = p.createPictureElement(graLyr, centeredPt, picPath, 'Chowdah')
    pic.elementWidth = 100000   #map units meters
    pic.elementHieght = 150000  #map units meters

PictureElement 示例 4

以下脚本使用 Python CIM 访问设置图片的 AltText 字符串。

p = arcpy.mp.ArcGISProject('current')
lyt = p.listLayouts('Layout')[0]

picPath = r'C:\Projects\Fenway.jpg'

picElm = p.createPictureElement(lyt, arcpy.Point(1,5), picPath, 'Fenway')
picElm.elementWidth = 4
picElm.elementHeight = 3

#Create AltText using Python CIM Access
lyt_cim = lyt.getDefinition('V3')
for elm in lyt_cim.elements:
    if elm.name == 'Fenway Pic':
        altTxt = arcpy.cim.CreateCIMObjectFromClassName("CIMStringMap", "V3")
        altTxt.key = "AltText"
        altTxt.value = "Picture of Fenway, a Golden Retriever, staring at sushi."
        elm.customProperties.append(altTxt)
lyt.setDefinition(lyt_cim)