PictureElement

Summary

The PictureElement class provides access to picture properties that enable the repositioning of a picture on the page layout as well as getting and setting its data source.

Discussion

The PictureElement object represents a raster or image that has been inserted into the page layout. The listElements method on the Layout object returns a Python list of page layout element objects. It is necessary to then iterate through each item in the list or specify an index number to reference a specific page element object. To return a list of only PictureElement objects, use the PICTURE_ELEMENT constant for the element_type parameter. A wildcard can also be used to further refine the search based on the element name.

The PictureElement object has a sourceImage property that allows you to read the original source or specify a new picture source location. If you plan on replacing a picture with pictures of different sizes and aspect ratios, author the original picture with a height and width that represents the complete area you want all other pictures to occupy on the page layout. When a picture is replaced using the sourceImage property and has a different aspect ratio, it will be fit to the area of the original picture using the longest dimension. Replaced pictures will never be larger than the original authored size. You will also want to set the anchor position so that all new pictures are fit relative to that location. If you don't want pictures to be skewed, ensure the Preserve Aspect Ratio option is set to True.

Pictures are always stored in the project. The sourceImage property displays the original source location during the time the picture was inserted but the file can be removed from disk and the picture will continue to display in the layout.

The createPictureElement method on the ArcGISProject object allows you to add pictures to either a Layout object using page units or a graphics layer in a Map object using map units. Pictures can be created using either a Point or a rectangular Polygon geometry. The default anchor position for a newly created picture is upper left and that coordinate represents the X and Y element positions.

Note:

Additional picture properties in a layout can be modified using Python CIM Access, but the same is not true for picture elements in a graphics layer. This is due to all picture data being persisted in binary reference to optimize performance. A graphics layer also has a hard limit of either 4000 elements or a size limit of 10MBs. This means you can not insert a single picture that is greater than 10MBs or any number of pictures that exceeds 10 MBs.

Properties

Property	Explanation	Data Type
anchor (Read Only)	Returns one of the following string values that represent the current anchor position. To change the value, use the setAnchor method. BOTTOM_LEFT_CORNER—Bottom left corner position BOTTOM_MID_POINT—Bottom center position BOTTOM_RIGHT_CORNER—Bottom right corner position CENTER_POINT—Center position LEFT_MID_POINT—Left center position RIGHT_MID_POINT—Right center position TOP_LEFT_CORNER—Top left corner position TOP_MID_POINT—Top center position TOP_RIGHT_CORNER—Top right corner position	String
elementHeight (Read and Write)	The height of the element in page units. The units assigned or reported are in page units.	Double
elementPositionX (Read and Write)	The x-location of the picture element's anchor position. The units assigned or reported are in page units.	Double
elementPositionY (Read and Write)	The y-location of the picture element's anchor position. The units assigned or reported are in page units.	Double
elementRotation (Read and Write)	The element's rotation angle in degrees. Positive values rotate clockwise and negative values rotate counterclockwise.	Double
elementWidth (Read and Write)	The width of the element in page units. The units assigned or reported are in page units.	Double
locked (Read and Write)	When set to True, the element cannot be graphically selected in the layout view.	Boolean
longName (Read Only)	An element's full name including group information if it exists. For example, an element named 'Picture' in a group element named 'Group Element' will return a longName value of 'Group Element\\Picture'. If the element is not in a group, the longName will be the same as the name value.	String
name (Read and Write)	The name of the element.	String
parentGroupElement (Read Only)	If the element is in a group, the value returned will be a GroupElement, otherwise a NoneType will be returned.	GroupElement
sourceImage (Read and Write)	A text string that represents the path to the picture data source.	String
type (Read Only)	Returns PICTURE_ELEMENT.	String
visible (Read and Write)	Returns True if the element is visible on the layout. Instead of moving unwanted objects off the page before printing or exporting, you can turn the element's visibility on and off.	Boolean

Method Overview

Method	Explanation
getDefinition (cim_version)	Returns a picture element's CIM definition.
setAnchor (anchor)	The setAnchor method controls the anchor position for a PictureElement.
setDefinition (definition_object)	Sets a picture element's CIM definition.

Methods

getDefinition (cim_version)

Parameter	Explanation	Data Type
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

Return Value

Data Type	Explanation
Object	Returns the CIM definition for a PictureElement.

For more information about working with the CIM and samples, see Python CIM access.

setAnchor (anchor)

Parameter	Explanation	Data Type
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

Setting the anchor position is helpful because you can control how the element might expand when resized. For example, you can set the anchor position to CENTER_POINT when you want the picture to stay centered at a specific location. This is useful when placing pictures as map graphics based on a point feature's location.

setDefinition (definition_object)

Parameter	Explanation	Data Type
definition_object	A modified CIM definition object originally retrieved using getDefinition.	Object

For more information about working with the CIM and samples, see Python CIM access.

Code sample

PictureElement example 1

The following script will walk a directory structure searching for project files. For each project found, the script loops through all layouts looking for picture elements. If it finds an oldSourcePath, it replaces it with a newSourcePath and prints the projects and layouts changes were made.

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 example 2

The following script will add two new pictures to a layout using an envelope. A function is being used to help create the geometry by specifying the X,Y anchor position and the width and height in page units. After the pictures are inserted, the are added into a new 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 example 3

The following script will add a picture at the location of each point feature in a feature class using a point geometry. The script also places the picture so that it is centered on the point feature based on its specified width and height.

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 example 4

The following script uses Python CIM Access to set a picture's AltText string.

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)