ArcGIS Help 10.2 - PictureElement (arcpy.mapping)

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

Properties

Property	Explanation	Data 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 data frame element's anchor position. The units assigned or reported are in page units.	Double
elementPositionY (Read and Write)	The y location of the data frame element's anchor position. The units assigned or reported are in page units.	Double
elementWidth (Read and Write)	The width of the element in page units. The units assigned or reported are in page units.	Double
name (Read and Write)	The name of the element.	String
sourceImage (Read and Write)	A text string that represents the path to the image data source.	String
type (Read Only)	Returns the element type for any given page layout element. DATAFRAME_ELEMENT —Data frame element GRAPHIC_ELEMENT —Graphic element LEGEND_ELEMENT —Legend element MAPSURROUND_ELEMENT —Map surround element PICTURE_ELEMENT —Picture element TEXT_ELEMENT —Text element	String

Code Sample

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"
mxd.save()
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}"
          .format(mxd.dataDrivenPages.currentPageID,
                  mxd.dataDrivenPages.pageCount))
    arcpy.mapping.ExportToPDF(mxd, r"C:\Project\Page{0}.pdf".format(pageNum))
del mxd

3/3/2014