Summary
The Camera object provides access to 2D and 3D viewer properties that control the display in a MapFrame or MapView.
Discussion
The ArcGIS AllSource application integrates 2D and 3D display and, therefore, the Camera object is used to control both the scale and extent for 2D maps and the camera position for 3D maps in a MapFrame or MapView.
The camera property on the MapFrame or MapView object returns a Camera object.
Because both 2D and 3D properties are available on the object, it is important to check the mode property on the Camera object. If the Camera mode is MAP then you can set 2D properties. If the Camera mode is either GLOBAL or LOCAL, then you can set 3D properties. You can also check the MapType property on the Map object; a value of MAP represents 2D and a value of SCENE represents 3D.
Extent is not a direct property of the Camera object because it is not an explicit property but rather a derived property. Camera positions do not store extent properties, but from an X, Y location and a scale, extent is derived. The getExtent method will return a derived extent. When an extent is returned from a 3D map view, it is based on the camera position looking straight down (pitch=-90). When the setExtent method is used on a 3D map, again, the result will appear as if the camera is looking straight down.
Properties
| Property | Explanation | Data Type |
| heading (Read and Write) | Provides the ability to either get or set the map view rotation value. This is also known as yaw or azimuth. It represents the number of degrees by which the map's data will be rotated, measured counterclockwise from the north. To rotate clockwise, use a negative value. It applies to both 2D and 3D map types. | Double |
| mode (Read Only) | Returns the viewer mode for the camera. Each viewer mode supports a different collection of camera properties.
| String |
| pitch (Read and Write) | Provides the ability to either get or set a map view's pitch. Pitch is the equivalent of moving a plane's nose up or down (rotating along the axis that passes through the plane's wings). Positive values, looking forward, are above the horizon (pointing upward) and negative values are below the horizon (pointing downward). A 2D map type will have a value of -90.0 (looking straight down). | Double |
| roll (Read and Write) | Provides the ability to either get or set a map view's roll. Roll is the equivalent of tilting a plane's wings up or down (rotating along the axis that passes through the center of the plane from front to back). A zero value is perfectly horizontal. Positive values will tilt the left side upward (or right side downward). Negative values do the opposite. A 2D map type will have a value of 0.0. | Double |
| scale (Read and Write) | Provides the ability to either get or set the scale of the data in a map frame. A numerical (double) value must be used. Scales really only apply only to 2D map types because of their planimetric view of the data. Scales can be returned from 3D maps types but are only an estimation. | Double |
| X (Read and Write) | Provides the ability to either get or set the X value. For 2D maps this is based on the center of the map frame. For 3D maps it represents the X position of the camera relative to the view. | Double |
| Y (Read and Write) | Provides the ability to either get or set the Y value. For 2D maps this is based on the center of the map frame. For 3D maps it represents the Y position of the camera relative to the view. | Double |
| Z (Read and Write) | Provides the ability to either get or set the Z value. For 3D maps it represents the Z position of the camera relative to the view. 2D maps don't support this value and a nan will be returned. | Double |
Method Overview
| Method | Explanation |
| getExtent () | Returns an Extent object for a 2D map frame. |
| setExtent (extent) |
Sets the Extent for a map frame in a layout. |
Methods
getExtent ()
| Data Type | Explanation |
| Extent | A geoprocessing Extent object. |
If the map type is 2D and unrotated, the extent returned will match the X, Y bounding box for the map view or map frame. If the map is rotated, the extent returned will be larger because a rotated envelope will have a larger extent than an un-rotated envelope. If the map type is 3D, the extent returned is based on the map view's heading, pitch, and roll values equal to 0.
Code sample
The following script will set the extent of a map frame named Yosemite National Park on a layout named Main Attractions at Yosemite National Park to match the extent of a layer named Ranger Stations.
import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\YosemiteNP\Yosemite.aprx")
m = aprx.listMaps("Yose*")[0]
lyr = m.listLayers("Ranger Stations")[0]
lyt = aprx.listLayouts("Main Attr*")[0]
mf = lyt.listElements("mapframe_element", "Yosemite National Park")[0]
mf.camera.setExtent(mf.getLayerExtent(lyr, False, True))
aprx.saveACopy(r"C:\Projects\YosemiteNP\Yosemite_Updated.aprx")
del aprxThe following script will change two map frame's map from a 2D to a 3D map. The script first imports two documents into a blank project. Next, it references the appropriate maps and map frames. Finally, and most importantly, it changes the Camera type property to GLOBAL before changing the map property from a 2D map to a 3D map.
import arcpy
aprx = arcpy.mp.ArcGISProject(r"C:\Projects\Blank.aprx")
#Import documents into project
aprx.importDocument(r"C:\Projects\YosemiteNP\Documents\Yosemite.mxd")
aprx.importDocument(r"C:\Projects\YosemiteNP\Documents\Yosemite_3DViews.3dd")
#Reference maps
m_scenic = aprx.listMaps("Globe layers")[0]
#Reference Layout and map frames
lyt = aprx.listLayouts()[0]
mf_inset1 = lyt.listElements("MapFrame_Element", "Inset1")[0]
mf_inset2 = lyt.listElements("MapFrame_Element", "Inset2")[0]
#Convert inset maps into Globe Views
mf_inset1.camera.type = "GLOBAL"
mf_inset1.map = m_scenic
mf_inset2.camera.type = "GLOBAL"
mf_inset2.map = m_scenic
aprx.saveACopy(r"C:\Projects\YosemiteNP\Yosemite.aprx")