Synthèse
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.
Remarque :
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.
Propriétés
| Propriété | Explication | Type de données |
| anchor (Lecture seule) | Returns one of the following string values that represent the current anchor position. To change the value, use the setAnchor method.
| String |
| elementHeight (Lecture et écriture) | The height of the element in page units. The units assigned or reported are in page units. | Double |
| elementPositionX (Lecture et écriture) | The x-location of the picture element's anchor position. The units assigned or reported are in page units. | Double |
| elementPositionY (Lecture et écriture) | The y-location of the picture element's anchor position. The units assigned or reported are in page units. | Double |
| elementRotation (Lecture et écriture) | The element's rotation angle in degrees. Positive values rotate clockwise and negative values rotate counterclockwise. | Double |
| elementWidth (Lecture et écriture) | The width of the element in page units. The units assigned or reported are in page units. | Double |
| locked (Lecture et écriture) | When set to True, the element cannot be graphically selected in the layout view. | Boolean |
| longName (Lecture seule) | 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 (Lecture et écriture) | The name of the element. | String |
| parentGroupElement (Lecture seule) | If the element is in a group, the value returned will be a GroupElement, otherwise a NoneType will be returned. | GroupElement |
| sourceImage (Lecture et écriture) | A text string that represents the path to the picture data source. | String |
| type (Lecture seule) | Returns PICTURE_ELEMENT. | String |
| visible (Lecture et écriture) | 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 |
Vue d’ensemble des méthodes
| Méthode | Explication |
| 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. |
Méthodes
getDefinition (cim_version)
| Paramètre | Explication | Type de données |
cim_version | A string that represents the major version of the CIM that will be used.
| String |
| Type de données | Explication |
| Object | Returns the CIM definition for a PictureElement. |
For more information about working with the CIM and samples, see Python CIM access.
setAnchor (anchor)
| Paramètre | Explication | Type de données |
anchor | A string that specifies the location of the anchor 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)
| Paramètre | Explication | Type de données |
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.
Exemple de code
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 replacingThe 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')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 metersThe 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)Vous avez un commentaire à formuler concernant cette rubrique ?