Summary
The DataFrame object provides access to many of the data frame properties found within a map document (.mxd). A reference to the DataFrame object is often used as an argument for many functions to filter layers or tables within a specific data frame.
Discussion
The DataFrame object provides access to important data frame properties. The ListDataFrames function returns a Python list of DataFrame objects. It is necessary to then iterate through each item in the list or to specify an index number to reference a specific DataFrame object. The object works with both map units and page units depending upon the property being used. For example, it can be used to set map extent, scale, and rotation, as well as items like spatial reference. The DataFrame object can also be positioned and/or sized on the layout using page units. The DataFrame object also provides access to informational items like credits and description.
A reference to a data frame can also be very useful when trying to reference other objects as well. For example, the ListLayers function provides an optional parameter called data_frame so that layers can be searched within a single data frame rather than the entire map document. The DataFrame object is also used as an optional parameter to distinguish printing or export a data frame versus a page layout. For this reason it is important to uniquely name each data frame so a specific data frame can be easily referenced.
The data frame extent coordinates are based on the extent of the data frame in Layout View, not in Data View. This is because the shape of the data frame in Data View may have a different aspect ratio than the data frame in Layout View.
The elementPositionX and elementPositionY parameters are based on the element's anchor position which is set via the Size and Position Tab on the elements properties dialog box in ArcMap.
Page units can only be changed in the ArcMap via Customize > ArcMap Options > Layout View Tab.
Properties
| Property | Explanation | Data Type |
| credits (Read and Write) | Provides the ability to either get or set the data frame credits information. | String |
| description (Read and Write) | Provides the ability to either get or set the data frame description information. | String |
| displayUnits (Read and Write) | Provides the ability to either get or set the data frame distance units. | String |
| 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 |
| extent (Read and Write) | Provides the ability to get or set the data frame's map extent using map coordinates (i.e., map units). A copy of the Extent object must be made before modifying its properties. The modified copy is then used to set the new extent properties. Note: If you try to set the extent by simply referencing the Extent object, changes won't be saved. For example, df.extent.xMin = some value won't work. If the aspect ratio of the extent does not match the shape of the data frame, the final extent will be adjusted to fit the new extent within the shape of the data frame. In other words, if you set explicit X, Y coordinates, you may not get the same values returned if you attempt to read them later. Note: The properties of the Extent object are by default read-only in the help system. A special exception was made for the arcpy.mapping scripting environment to enable changing extents during a map automation process. | Extent |
| geographicTransformations (Read and Write) | Provides the ability to either get or set the data frame's geographic transformation(s). The property will return the name(s) of the transformation(s) in a list. Only existing, predefined transformation names (or their corresponding code value) can be used to set a geographic transformation. A complete list of transformations and code values can be found on the ArcGIS Resource Center. The geographicTransformations property cannot be used to create custom transformations. Only predefined methods can be referenced. There is always one geographic transformation loaded into a map document by default: NAD_1927_To_NAD_1983_NADCON. This will be overwritten when setting a new list. Geographic transformations can also be cleared by setting an empty list. The following examples will set two transformation methods using name strings. The first from NAD27 to NAD 83 and the second from NAD83 to HARN. The second example does the same thing but uses transformation codes instead. | String |
| mapUnits (Read Only) | Returns a string value that reports the current data frame map units. These are based on the data frame's current coordinate system. | String |
| name (Read and Write) | Provides the ability to either get or set the data frame's name as it appears in the table of contents in a map document and also the actual name of the element within the layout. | String |
| referenceScale (Read and Write) | Provides the ability to either get or set the data frame's reference scale. This is the scale in which all symbol and text sizes used in the data frame will be made relative. | Double |
| rotation (Read and Write) | Provides the ability to either get or set the data frame's rotation value. It represents the number of degrees by which the data frame will be rotated, measured counterclockwise from the north. To rotate clockwise, use a negative value. | Double |
| scale (Read and Write) | Provides the ability to either get or set the current scale of the active data frame. A numerical (double) value must be used. | Double |
| spatialReference (Read and Write) | Provides access to the SpatialReference of the data frame. The spatial reference contains information about the coordinate system and units. | SpatialReference |
| time (Read Only) | Returns the DataFrameTime object that provides access to controlling the display for time-enabled layers. | DataFrameTime |
| type (Read Only) | Returns the element type for any given page layout element.
| String |
Method Overview
| Method | Explanation |
| panToExtent (extent) | Pans and centers the data frame extent using a new Extent object without changing the data frame's scale |
| zoomToSelectedFeatures () | Changes the data frame extent to match the extent of the currently selected features for all layers in a data frame |
Methods
panToExtent (extent)
This method is perfect for situations where data frame scale does not change. Rather than setting the extent and then having to reset the scale each time, panToExtent maintains the scale and simply centers the current data frame on the new extent.
The following example will pan the extent of a data frame by passing in the extent of selected features for a specific layer. The Layer class getSelectedExtent method is used for this purpose.
df.panToExtent(lyr.getSelectedExtent())
zoomToSelectedFeatures ()
This performs the same ArcMap operation as Selection > Zoom To Selected Features. One difference is that if no features are selected, it will zoom to the full extent of all layers. If you want to zoom to the extent of selected features for a specific layer, try using the Layer.getSelectedExtent method.
The following example will zoom to the extent of all selected features:
df.zoomToSelectedFeatures()
The following example will zoom to the extent of selected features for a specific layer. This example uses a method on the Layer object.
df.extent = lyr.getSelectedExtent()
Code Sample
DataFrame example 1
The following script will set each data frame's rotation property to 0 and scale property to 1:24000 before exporting each data frame to an individual output TIFF file using the data frame name property as the name of the output file.
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
for df in arcpy.mapping.ListDataFrames(mxd):
df.rotation = 0
df.scale = 24000
outFile = r"C:\Project\Output\\" + df.name + ".tif"
arcpy.mapping.ExportToTIFF(mxd, outFile, df)
del mxd
DataFrame example 2
The following script will set the data frame's extent to the extent of the selected features in a layer. A 10% buffer is added to the extent by multiplying the scale. This example uses the getSelectedExtent method on the Layer object. This script is run from the interactive window within ArcMap using the CURRENT keyword rather than providing a path to a map document.
import arcpy
mxd = arcpy.mapping.MapDocument("CURRENT")
df = arcpy.mapping.ListDataFrames(mxd, "Transportation")[0]
accidentLayer = arcpy.mapping.ListLayers(mxd, "accidents", df)[0]
arcpy.SelectLayerByAttribute_management(accidentLayer, "NEW_SELECTION", "\"Accidents\" > 5")
df.extent = accidentLayer.getSelectedExtent(False)
df.scale = df.scale * 1.1
arcpy.mapping.ExportToPDF(mxd, r"C:\Project\Output\FrequentAccidents.pdf", df)
arcpy.RefreshActiveView()
del mxd
DataFrame example 3
The following script will modify the position and size of a specific data frame on the layout.
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Transportation")[0]
df.elementPositionX, df.elementPositionY = 1, 1
df.elementHeight, df.elementWidth = 5, 6.5
mxd.save()
del mxd
DataFrame example 4
The following script converts a data frame's extent object into a polygon feature so that it can be used with the SelectLayerByLocation_management function.
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Transportation")[0]
lyr = arcpy.mapping.ListLayers(mxd, "Accidents", df)[0]
#The DataFrame extent object is converted into a polygon feature so it can be used with the SelectLayerByLocation function.
dfAsFeature = arcpy.Polygon(arcpy.Array([df.extent.lowerLeft, df.extent.lowerRight, df.extent.upperRight, df.extent.upperLeft]),
df.spatialReference)
arcpy.SelectLayerByLocation_management(lyr, "INTERSECT", dfAsFeature, "", "NEW_SELECTION")
mxd.save()
del mxd