PictureElement (arcpy.mapping)


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 ListLayoutElements function 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 PictureElements, use the PICTURE_ELEMENT constant for the element_type parameter. A wild card can also be used to further refine the search based on the element name.

It is recommended that each page layout element be given a unique name so that it can be easily isolated in Python. X,Y element positions are based on the element's anchor position, which is set using the Size and Position tab on the Elements Properties dialog box in ArcMap.

The PictureElement object has a sourceImage property that allows you to read or modify the picture source location. If you plan on replacing a picture with pictures of different sizes and aspect ratios, author the map document with a picture that has a height and width set 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, make sure the Preserve Aspect Ratio option is checked.


(Lesen und schreiben)

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

(Lesen und schreiben)

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

(Lesen und schreiben)

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

(Lesen und schreiben)

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

(Lesen und schreiben)

The name of the element.

(Lesen und schreiben)

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


Returns the element type for any given page layout element.

  • DATAFRAME_ELEMENTData frame element
  • GRAPHIC_ELEMENTGraphic element
  • LEGEND_ELEMENTLegend element
  • MAPSURROUND_ELEMENTMap surround element
  • PICTURE_ELEMENTPicture element
  • TEXT_ELEMENTText element


PictureElement example 1

The following script will find an image by name and set its data source to a new location.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
for elm in arcpy.mapping.ListLayoutElements(mxd, "PICTURE_ELEMENT"):
    if elm.name == "Photo":
        elm.sourceImage = r"C:\Project\Data\NewPhoto.bmp"
del mxd
PictureElement example 2

The following script demonstrates how different pictures can be switched out for each page in a Data Driven Pages enabled map document. There is a different picture for each page. The pictures are named Photo1.png, Photo2.png, Photo3.png, etc to match the corresponding page numbers.

import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
pict = arcpy.mapping.ListLayoutElements(mxd, "PICTURE_ELEMENT", "photo")[0]
for pageNum in range(1, mxd.dataDrivenPages.pageCount + 1):
    mxd.dataDrivenPages.currentPageID = pageNum
    pict.sourceImage = r"C:\Project\Data\Photo{0}.png".format(pageNum)
    print("Exporting page {0} of {1}"
    arcpy.mapping.ExportToPDF(mxd, r"C:\Project\Page{0}.pdf".format(pageNum))
del mxd