ArcGIS Help 10.2 - Grid (arcpyproduction.mapping)

This topic applies to ArcGIS for Desktop Standard and ArcGIS for Desktop Advanced only.

Summary

The Grid object provides access to grid properties for a grids and graticules layer. A reference to the Grid object is often used as an argument for functions to access grid properties.

Discussion

The Grid object provides access to important properties of a grid, which is created using the Make Grids And Graticules Layer geoprocessing tool or the Grids and Graticules Designer. The ListGrids function can be used to return a list of the Grid objects in a feature dataset. An in-memory grid object can be created from a Grid Template(XML File) by using Grid(<grid_xml_path>).

Note:

Grid objects created using grid_xml_path will only have properties that are contained in the XML. They do not hold database storage-related information as they are grid objects in memory only. For example, there is no layer property set for grids created using this parameter.

Properties

Property	Explanation	Data Type
baseSpatialReference (Read Only)	Returns the base spatial reference of the grid's primary coordinate system.	SpatialReference
layer (Read Only)	Returns the group layer created from the Grid object. The group layer contains all grid subcomponents as sublayers. This is the same as the output group layer from the Make Grids And Graticules Layer geoprocessing tool.	Layer
name (Read and Write)	Provides the ability to get or set the name of the Grid object. The name for the cartographic grid may not be the name of the layer. The name allows for distinction between grids stored in the same feature dataset and set of feature classes.	String
scale (Read and Write)	Provides the ability to get or set the reference scale of the Grid object.	Double
type (Read and Write)	Provides the ability to get or set the type associated with the Grid object. All grids of the same type will have the same appearance. Type defines a style of grid, map product, or series.	String

Method Overview

Method	Explanation
updateDataFrameProperties (data_frame, {area_of_interest})	Updates the coordinate system, rotation, scale, data frame size, and shape based on the properties and values stored in the Grid object.
calculateExtent (data_frame_width, data_frame_height, input_point_geometry, scale)	Calculates the extent/AOI of a map based on the map data frame size, scale, and properties from the current Grid object.

Methods

updateDataFrameProperties (data_frame, {area_of_interest})

Parameter	Explanation	Data Type
data_frame	A reference to a DataFrame object within a map document.	DataFrame
area_of_interest	A geometry that represents the area of the map.	Geometry

This method provides functionality that is equivalent to the Grid Layout tool. It is used to ensure that the key cartographic data frame properties match the grid, thus enforcing the map display to show shapes, sizes, and measurements as intended based on the grid design. It projects the data frame to the grid's primary coordinate system, changes data frame scale to match the grid's scale, changes data frame size to grid's extent at specified scale, and rotates data frame to grid's specified rotation angle. If the grid is created from an XML file, the optional area_of_interest parameter needs to be defined.

Note:

To run this function, the .mxd must be in layout view and the data frame must be projected.

Caution:

This method changes the data frame properties. To preserve the changes, the .mxd must be saved or copied.

The following example updates the .mxd file's data frame properties based on those in the Rotation Scale GCS grid object.

import arcpy
import arcpyproduction

# Check out Production Mapping extension
arcpy.CheckOutExtension("Foundation")

# Set the grid workspace and name
gridWorkspace = r'C:\Project\Grids\GridsUpdateDF.gdb\WGS84'
gridName = "RotationScaleGCS"

# Define the map document, data frame, and layout view
mxd = arcpy.mapping.MapDocument(r"C:\Project\Grids\GridsUpdateDFTest.mxd")
active_df = mxd.activeDataFrame
mxd.activeView = "PAGE_LAYOUT"

# Update data frame using the properties of the RotationScaleGCS grid
# and save results in a new .mxd
Rotationgrids = arcpyproduction.mapping.ListGrids(gridWorkspace, gridName)
if Rotationgrids[0].name == gridName:
    Rotationgrids[0].updateDataFrameProperties(active_df)
    mxd.saveACopy(r"C:\Project\Grids\UpdateResults.mxd")
else:
    print "Error Obtaining Grid "+ gridName

# Check in extension
arcpy.CheckInExtension("Foundation")

The following example updates the .mxd file's data frame properties based on an XML grid and the defined AOI.

import arcpy
import arcpyproduction

# Check out Production Mapping extension
arcpy.CheckOutExtension("Foundation")

#Get the grid object using its XML path
ArcDir = arcpy.GetInstallInfo()['InstallDir']
grid = arcpyproduction.mapping.Grid(ArcDir + r"\GridTemplates\GridTemplates\Topo_50K_WGS84.xml")

#Define the map document, dataframe to update, and set it to Layout View
mxd_path = r"C:\Project\TopoMap.mxd"
mxd = arcpy.mapping.MapDocument(mxd_path)
df = mxd.activeDataFrame
mxd.activeView = "PAGE_LAYOUT"

# Get an Area of Interest feature for which that grid can be applied
feature_class = r'C:\Project\AOI.gdb\TLM50'
query_exp = "MSNAME = 'R712X44584'"
with arcpy.da.SearchCursor(feature_class,["MSNAME","SHAPE@"],query_exp) as cur:
    for row in cur:
        name = row[0]
        geom = row[1]

# Update the dataframe properties using the grid and save as a new mxd
grid.updateDataFrameProperties(df,geom)
mxd.saveACopy(r"C:\Project\Update_"+name+"_Results.mxd")

# Check in extension
arcpy.CheckInExtension("Foundation")

calculateExtent (data_frame_width, data_frame_height, input_point_geometry, scale)

Parameter	Explanation	Data Type
data_frame_width	The width of the data frame in page units.	Double
data_frame_height	The height of the data frame in page units.	Double
input_point_geometry	A Geometry object referencing a centroid of a map.	Geometry
scale	The map scale to be used for calculating the extent.	Double

Return Value

Data Type	Explanation
Geometry	A polygon geometry (AOI) that represents the map extent.

All maps display on a flat surface (page or screen), showing some geographic extent at a defined scale. However, only a specific amount of ground area can be seen on a flat surface at a specific scale.

There are a number of factors used in calculating the size of maps:

Geographic extent: the area on the ground that will be displayed in a map.
Flat viewing surface’s extent: the size of the window (or data frame) through which the area on the ground is displayed.
Map scale: The ratio of a distance on the map to the corresponding distance on the ground.

Complicating this calculation is the curvature of the earth's surface; the coordinate system of the flat surface as well as the geographic extent’s specific latitude and longitude must also be factored into the calculation.

The calculateExtent method is used to calculate the geographic extent of a map by providing a data frame’s size and scale. This method also uses the latitude and longitude of the provided input point geometry with the coordinate system and data frame rotation information assigned to the grid object being used.

The following example creates an extent based on the specification in the Calibrated grid template in GridTemplates and the defined input parameters.

import arcpy 
import arcpyproduction

#Create a point with known spatial reference e.g. WGS_1984_Web_Mercator_Auxillary_Sphere
sr = arcpy.SpatialReference(3857)
newPoint = arcpy.Point(-13046304, 4036487)
pointGeom = arcpy.PointGeometry(newPoint,sr)

#Create a reference to a grid that will be used to calculate the extent
#This sample uses the Calibrated grid template in GridTemplates
grid_template = arcpy.GetInstallInfo()['InstallDir']+r"\GridTemplates\Calibrated_1500K_to_2250K_WGS84.xml"
grid = arcpyproduction.mapping.Grid(grid_template)

#Define the input dataframe size and scale for which the new extent will be calculated
dataframe_width = 8
dataframe_height = 11
scale = 50000

#Create a new extent  based on the defined input parameters
newExtent = grid.calculateExtent(dataframe_width,dataframe_height,pointGeom,scale)

#Create a copy of the new extent by using the CopyFeatures tool
arcpy.CopyFeatures_management(newExtent, "C:/geometry/NewExtent.shp")

Code Sample

Grid example 1

The following script will read the name and type properties of grids in an existing workspace and delete the grids from the workspace using the properties as parameters in the Delete Grids and Graticules geoprocessing tool.

import arcpy
import arcpyproduction

# Check out Production Mapping extension
arcpy.CheckOutExtension('foundation')

# Set the grid workspace
grid_dataset = r"C:\Project\Grids.gdb\WGS84"

# Get the list of grids in the workspace
lstGrids = arcpyproduction.mapping.ListGrids(grid_dataset)

# Loop through the list of grids and delete each grid
# Delete Grids And Graticules accepts grid name and type as a second parameter
# The second parameter format is <grid name> (<grid type>)
for grid in lstGrids:
    grid_name = grid.name
    grid_type = grid.type
    arcpy.DeleteGridsAndGraticules_cartography(grid_dataset, grid_name + ' (' + grid.type + ')')

# Check in extension
arcpy.CheckInExtension('foundation')

Grid example 2

This sample creates the grid object from a grid XML file and checks the type and scale.

import arcpy
import arcpyproduction

# Check out Production Mapping extension
arcpy.CheckOutExtension("foundation")

# Create grid object from a XML file and check type and scale
ArcDir = arcpy.GetInstallInfo()['InstallDir']
gridobj = arcpyproduction.mapping.Grid(ArcDir + r"\GridTemplates\Calibrated_1500K_to_2250K_WGS84.xml")
print "Grid Type = " + str(gridobj.type) + "   Grid Scale = " + str(gridobj.scale)

# Check in extension
arcpy.CheckInExtension("foundation")

Grid example 3

This sample script uses the base spatial reference property of a grid object from an existing .xml file to create a feature dataset and creates a grid using the Make Grids And Graticules Layer geoprocessing tool.

import arcpy
import arcpyproduction

# Check out Production Mapping extension
arcpy.CheckOutExtension('foundation')

# Set the values of the tool's parameters using one of the grid
# definition XML files located under the GridTemplates directory
ArcDir = arcpy.GetInstallInfo()['InstallDir']
grid_xml = ArcDir + "/GridTemplates/Quad_24K_NAD83.xml"

# Get the grid's Geographic Coordinate System
grid = arcpyproduction.mapping.Grid(grid_xml)
spatial_ref = grid.baseSpatialReference
grid_gcs = spatial_ref.GCS
grid_dataset_name = grid_gcs.name


# Make a new feature dataset based on the Geographic Coordinate System
fds_result = arcpy.CreateFeatureDataset_management("C:/Project/GridDatabase.gdb",grid_dataset_name,grid_gcs)

# Use the Make Grids and Graticules Layer geoprocessing service to make a grid
lyr_result = arcpy.MakeFeatureLayer_management("C:/Project/AOIs.gdb/QUAD_24K_AOI","QUAD_24K")
arcpy.SelectLayerByAttribute_management("QUAD_24K", "NEW_SELECTION","\"MSNAME\" = 'Raymond California'")
arcpy.MakeGridsAndGraticulesLayer_cartography(grid_xml,"QUAD_24K",fds_result,"QUAD_24K_Grids","MSNAME")

# Check in extension
arcpy.CheckInExtension('foundation')