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.


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.


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.


PropertyExplanationData Type
(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_CORNERBottom left corner position
  • BOTTOM_MID_POINTBottom center position
  • BOTTOM_RIGHT_CORNERBottom right corner position
  • CENTER_POINTCenter position
  • LEFT_MID_POINTLeft center position
  • RIGHT_MID_POINTRight center position
  • TOP_LEFT_CORNERTop left corner position
  • TOP_MID_POINTTop center position
  • TOP_RIGHT_CORNERTop right corner position
(Read and Write)

The height of the element in page units. The units assigned or reported are in page units.

(Read and Write)

The x-location of the picture element's anchor position. The units assigned or reported are in page units.

(Read and Write)

The y-location of the picture element's anchor position. The units assigned or reported are in page units.

(Read and Write)

The element's rotation angle in degrees. Positive values rotate clockwise and negative values rotate counterclockwise.

(Read and Write)

The width of the element in page units. The units assigned or reported are in page units.

(Read and Write)

When set to True, the element cannot be graphically selected in the layout view.

(Read and Write)

The name of the element.

(Read and Write)

A text string that represents the path to the picture data source.

(Read Only)


(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.


Method Overview

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.


getDefinition (cim_version)
ParameterExplanationData Type

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.
Return Value
Data TypeExplanation

Returns the CIM definition for a PictureElement.

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

setAnchor (anchor)
ParameterExplanationData Type

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.

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)
ParameterExplanationData Type

A modified CIM definition object originally retrieved using getDefinition.


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))
      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."