ArcGIS for Desktop

  • ArcGIS Pro
  • ArcMap

  • ArcGIS Pro
  • ArcMap
ArcGIS for Desktop

ArcGIS Online

The mapping platform for your organization

ArcGIS for Desktop

A complete professional GIS

ArcGIS for Server

GIS in your enterprise

ArcGIS for Developers

Tools to build location-aware apps

ArcGIS Solutions

Free template maps and apps for your industry

ArcGIS Marketplace

Get apps and data for your organization

  • ArcGIS Pro
  • ArcMap
Esri
English
  • English
  • Deutsch
  • Español
  • Français
  • 日本語
  • Русский
  • 简体中文
  • Sign In
user
  • My Profile
  • Sign Out

ArcMap

  • Home
  • Get Started
  • Map
  • Analyze
  • Manage Data
  • Tools
  • More...
  • Analyze
  • ArcPy
  • Mapping module
  • Classes
  • Back to Top
  • Introduction to arcpy.mapping
  • Getting started with arcpy.mapping tutorial
  • Guidelines for arcpy.mapping
  • Alphabetical list of arcpy.mapping classes
  • Alphabetical list of arcpy.mapping functions
  • Alphabetical list of arcpy.mapping constants
  • Updating and fixing data sources with arcpy.mapping
  • Classes

    • DataDrivenPages
    • DataFrameTime
    • DataFrame
    • GraduatedColorsSymbology
    • GraduatedSymbolsSymbology
    • GraphicElement
    • LabelClass
    • Layer
    • LayerTime
    • LegendElement
    • MapDocument
    • MapsurroundElement
    • PDFDocument
    • PictureElement
    • RasterClassifiedSymbology
    • StyleItem
    • TableView
    • TextElement
    • UniqueValuesSymbology

    Functions

    • Exporting and Printing Maps
    • Managing Documents and Layers

    DataFrame

    This ArcGIS 10.3 documentation has been archived and is no longer updated. Content and links may be outdated. See the latest documentation.
    • Summary
    • Discussion
    • Properties
    • Method Overview
    • Methods
    • Code Sample

    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

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

    df = arcpy.mapping.ListDataFrames(mxd)[0]
    newExtent = df.extent
    newExtent.XMin, newExtent.YMin = -180.0, -90.0
    newExtent.XMax, newExtent.YMax = 180.0, 90.0
    df.extent = newExtent
    
    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.

    df.geographicTransformations = [u'NAD_1927_To_NAD_1983_NADCON', u'NAD_1983_To_HARN_New_Jersey']
    df.geographicTransformations = [1241,1554]
    
    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.

    • DATAFRAME_ELEMENT —Dataframe element
    • GRAPHIC_ELEMENT —Graphic element
    • LEGEND_ELEMENT —Legend element
    • MAPSURROUND_ELEMENT —Mapsurround element
    • PICTURE_ELEMENT —Picture element
    • TEXT_ELEMENT —Text element
    String

    Method Overview

    MethodExplanation
    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)
    ParameterExplanationData Type
    extent

    A geoprocessing Extent object

    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
    

    ArcGIS for Desktop

    • Home
    • ArcGIS Pro
    • ArcMap
    • Documentation
    • Pricing
    • Support

    ArcGIS

    • ArcGIS Online
    • ArcGIS for Desktop
    • ArcGIS for Server
    • ArcGIS Platform
    • ArcGIS Developer
    • ArcGIS Solutions
    • ArcGIS Marketplace

    About Esri

    • About Us
    • Careers
    • Insiders Blog
    • User Conference
    • Developer Summit
    Esri
    © Copyright 2016 Environmental Systems Research Institute, Inc. | Privacy | Legal