PictureElement

Summary

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 PictureElements, 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 X,Y element positions are based on the element's anchor position.

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, make sure the Preserve Aspect Ratio option is checked.

Note:

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

Properties

PropertyExplanationData Type
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
name
(Read and Write)

The name of the element.

String
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

Code sample

PictureElement example

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

import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
lyt = aprx.listLayouts("Main Attractions")[0]
pic = lyt.listElements("PICTURE_ELEMENT", "logo")[0]
pic.sourceImage = r"C:\Projects\YosemiteNP\yoslogo.png"
aprx.save()
del aprx