| Label | Explanation | Data Type |
Grid Template (XML file) | The XML grid definition template that stores the specification's graphic properties for each grid layer. In addition to the graphic properties, which cannot be altered before execution, the definition has specific default values, exposed as parameters, that can be modified before execution. | File |
Input Area of Interest [feature or extent] | The polygon feature layer or geographic extent used to determine the area over which the grid features are created. | Feature Layer; Extent |
Target Feature Dataset | The feature dataset that will store the grid features. Grid-specific feature classes will be created if they do not already exist. If they already exist, and a grid with the same name and type as the one being created also exists, it will be overwritten. | Feature Dataset |
Output Layer Name | The name of the group layer that will be created to contain the symbolized grid and graticule feature classes. The group layer can be composed of the following layers for grid elements:
Note:This is a temporary layer that you must save in the project or as a layer file. | Group Layer |
Grid Name [value or field] (Optional) | The name used to uniquely identify the grid. You can use a unique name for the grid or choose a field from the input area of interest feature layer. | String; Field |
Configure map frame and layout using grid settings (Optional) | Adjusts the map, map frame, and layout settings to ensure they match the grid layer. The map’s coordinate system as well as the map frame's scale, rotation, size, and extent can be altered to enforce consistency. This setting requires that a map frame is chosen from the Map Frame parameter.
| Boolean |
Layout (Optional) | The layout that contains the map frame to which the grid will be added when the Configure map frame and layout using grid settings check box is checked. The layout can be in the current project or from an existing layout file. | Layout |
Map Frame (Optional) | The map frame that will be updated. The map associated with the map frame can also be updated. | String |
Reference Scale (Optional) | The scale at which the grid is created and should be viewed. When the reference scale from the XML grid definition file is defined as Use Environment, the reference scale is derived in the following order:
| Double |
Rotation (Optional) | The rotation angle for the grid components. Rotation is used to create annotation features that are aligned with the page. Unless otherwise specified, rotation is calculated using the area of interest feature. When the rotation type from the XML grid definition file is defined as Use Environment, the rotation is derived in the following order:
| Double |
Mask Size (Optional) | The mask is a polygon feature that forms an outer ring around the extent of the neatline and is used to mask data that falls in the area reserved for coordinate labels. Mask size defines the width of the polygon mask feature in map or page units. The data frame may need to be resized to fit around the edge of the mask while including the coordinate labels. | Linear Unit |
XY Tolerance (Optional) | The minimum distance between geodatabase features, expressed in linear units. This value defaults to the value set in the grid XML. You can set higher values for data with less coordinate accuracy and lower values for data with extremely high accuracy. Features that fall within the set x,y tolerance will be considered coincident. | Linear Unit |
Primary Coordinate System (Optional) | The primary coordinate system used to create grid features. The final product or data frame should use the same coordinate system. This coordinate system must be a projected coordinate system. When the primary coordinate system in the XML grid definition file is defined as Use Environment, the default primary coordinate system is derived in the following order:
| Spatial Reference |
Ancillary Coordinate System 1 (Optional) | The first of up to four ancillary coordinate systems used to create grid features. The grid template XML file specifies the number of ancillary grids. | Spatial Reference |
Ancillary Coordinate System 2 (Optional) | The second of up to four ancillary coordinate systems used to create grid features. The grid template XML file specifies the number of ancillary grids. | Spatial Reference |
Ancillary Coordinate System 3 (Optional) | The third of up to four ancillary coordinate systems used to create grid features. The grid template XML file specifies the number of ancillary grids. | Spatial Reference |
Ancillary Coordinate System 4 (Optional) | The fourth of up to four ancillary coordinate systems used to create grid features. The grid template XML file specifies the number of ancillary grids. | Spatial Reference |
Summary
Creates a grouped layer of feature classes depicting grid, graticule, and border features using predefined cartographic specifications. Grid layers are ideal for advanced grid definitions that are scale and extent specific.
Each grid layer can be composed of a mask (polygon), clip (polygon), segments (line), gridlines (line), ticks (line), endpoints (point), points (point), and annotation feature classes. These components are stored as features in corresponding feature classes. These feature classes are saved in a specified feature dataset in a geodatabase. There are seven feature classes that store the basic components of a grid. Each feature class is named with a three-letter prefix that helps identify the grid component the feature class holds. These feature classes/components are as follows:
- ANO_ is the annotation feature class.
- CLP_ is the clip feature class.
- EPT_ is the endpoints feature class.
- GLN_ is the gridlines feature class.
- MSK_ is the masks feature class.
- PNT_ is the points feature class.
- SEG_ is the segments feature class.
- TKS_ is the ticks feature class.
These feature classes can hold information for multiple grids. An eighth feature class (GRD_) contains organizational information, such as map name and grid types that are used to organize your grids.
The grid definition template is stored in a predefined XML file. This file stores specification properties for each grid, such as the number, color, and line weight of gridlines. When the definition template is applied, features are created according to the specification based on the active extent or extent of a selected feature (area of interest), scale, and coordinate systems.
Note:
A product file installer is available for ArcGIS Production Mapping and ArcGIS Defense Mapping. The product files contain predefined layout PAGX templates that can be used for cartographic production.
Learn more about Defense Mapping product files and Production Mapping product files.
Usage
This tool is designed for projected maps that will be printed or exported. It is not meant for creating grids or graticules that dynamically update as the user navigates the map.
You must define an area of interest to determine the extent of the grid layer to be created. If you are using a feature layer to define the area of interest, it must be a polygon feature class or polygon layer. Only one selected feature will be used from this layer. If the layer has more than one feature, the tool will only create a grid layer based on the feature with the lowest ObjectID.
The grid template XML file defines grid components depicting measurements or locations for primary and ancillary coordinate systems. All coordinate systems specified must share a common geographic coordinate system. If the primary coordinate system uses a different datum than the default, for example, if you change the coordinate system from one that uses WGS 1984 to one that uses NAD 1983, you must change each ancillary coordinate system from WGS 1984 to NAD 1983.
The grid template, area of interest, input feature dataset, and the primary and ancillary coordinate system must use the same datum. For example, WGS 1984 or NAD 1983.
The grid template XML file specifies the number of ancillary grids and creates grid components for up to four ancillary coordinate systems. Ancillary coordinate systems can't be added or deleted, but you can override the default values.
The primary coordinate system must be a projected coordinate system.
Ancillary coordinate systems can be either a projected coordinate system or a geographic coordinate system.
Checking the Configure map frame and layout using grid settings parameter check box ensures that the map frame in the layout is adjusted to best fit the created grid, while honoring the map frame's anchor point. The map frame's coordinate system, scale, rotation, size, and extent can be altered to match the XML grid specification. When this setting is enabled, a value must be specified for the map frame. The default for this check box is unchecked, which will not change your map frame properties.
The default values for the following parameters are automatically derived from the grid template XML and can be modified before execution:
- Output Layer Name
- Grid Name with the String Value
- Reference Scale
- Rotation
- Mask Size
- XY Tolerance
- Primary Coordinate System
- Ancillary Coordinate System
Parameters
arcpy.topographic.MakeGridsAndGraticulesLayer(in_grid_xml, area_of_interest, target_feature_dataset, out_layer_name, {grid_name}, {configure_layout}, {layout}, {map_frame}, {reference_scale}, {rotation}, {mask_size}, {xy_tolerance}, {primary_coordinate_system}, {ancillary_coordinate_system_1}, {ancillary_coordinate_system_2}, {ancillary_coordinate_system_3}, {ancillary_coordinate_system_4})| Name | Explanation | Data Type |
in_grid_xml | The XML grid definition template that stores the specification's graphic properties for each grid layer. In addition to the graphic properties, which cannot be altered before execution, the definition has specific default values, exposed as parameters, that can be modified before execution. | File |
area_of_interest | The polygon feature layer or geographic extent used to determine the area over which the grid features are created. | Feature Layer; Extent |
target_feature_dataset | The feature dataset that will store the grid features. Grid-specific feature classes will be created if they do not already exist. If they already exist, and a grid with the same name and type as the one being created also exists, it will be overwritten. | Feature Dataset |
out_layer_name | The name of the group layer that will be created to contain the symbolized grid and graticule feature classes. The group layer can be composed of the following layers for grid elements:
Note:This is a temporary layer that you must save in the project or as a layer file. | Group Layer |
grid_name (Optional) | The name used to uniquely identify the grid. You can use a unique name for the grid or choose a field from the input area of interest feature layer. | String; Field |
configure_layout (Optional) | Adjusts the map, map frame, and layout settings to ensure they match the grid layer. The map’s coordinate system as well as the map frame's scale, rotation, size, and extent can be altered to enforce consistency. This setting requires that a map frame is chosen from the map_frame parameter.
| Boolean |
layout (Optional) | The layout that contains the map frame to which the grid will be added when the configure_layout parameter is enabled. The layout can be in the active project or from an existing layout file. | Layout |
map_frame (Optional) | The map frame that will be updated. The map associated with the map frame can also be updated. | String |
reference_scale (Optional) | The scale at which the grid is created and should be viewed. When the reference scale from the XML grid definition file is defined as Use Environment, the reference scale is derived in the following order:
| Double |
rotation (Optional) | The rotation angle for the grid components. Rotation is used to create annotation features that are aligned with the page. Unless otherwise specified, rotation is calculated using the area of interest feature. When the rotation type from the XML grid definition file is defined as Use Environment, the rotation is derived in the following order:
| Double |
mask_size (Optional) | The mask is a polygon feature that forms an outer ring around the extent of the neatline and is used to mask data that falls in the area reserved for coordinate labels. Mask size defines the width of the polygon mask feature in map or page units. The data frame may need to be resized to fit around the edge of the mask while including the coordinate labels. | Linear Unit |
xy_tolerance (Optional) | The minimum distance between geodatabase features, expressed in linear units. This value defaults to the value set in the grid XML. You can set higher values for data with less coordinate accuracy and lower values for data with extremely high accuracy. Features that fall within the set x,y tolerance will be considered coincident. | Linear Unit |
primary_coordinate_system (Optional) | The primary coordinate system used to create grid features. The final product or data frame should use the same coordinate system. This coordinate system must be a projected coordinate system. When the primary coordinate system in the XML grid definition file is defined as Use Environment, the default primary coordinate system is derived in the following order:
| Spatial Reference |
ancillary_coordinate_system_1 (Optional) | The first of up to four ancillary coordinate systems used to create grid features. The grid template XML file specifies the number of ancillary grids. | Spatial Reference |
ancillary_coordinate_system_2 (Optional) | The second of up to four ancillary coordinate systems used to create grid features. The grid template XML file specifies the number of ancillary grids. | Spatial Reference |
ancillary_coordinate_system_3 (Optional) | The third of up to four ancillary coordinate systems used to create grid features. The grid template XML file specifies the number of ancillary grids. | Spatial Reference |
ancillary_coordinate_system_4 (Optional) | The fourth of up to four ancillary coordinate systems used to create grid features. The grid template XML file specifies the number of ancillary grids. | Spatial Reference |
Code sample
This Python stand-alone sample creates a dataset in a file geodatabase and creates grid features in that dataset over the selected AOI.
# Name: MakeGridsAndGraticulesLayer_sample1.py
# Description: Creates a dataset in a file geodatabase and creates grid features
# in that dataset over the selected AOI.
# Import System Modules
import arcpy
# Check Out Extensions
arcpy.CheckOutExtension('Foundation')
# Setting Local Variables
# Grid template
grid_xml = r'C:\Data\Topo_50K_WGS84.xml'
# Location for grids database
output_path = r'C:\Data'
# Grid area of interest (aoi) feature class
aoi = r'C:\Data\MapIndex.gdb\Index_50K'
# field name to query to identify a single map sheet
grid_name_field = 'MAP_SHEET_NAME'
# name of the map sheet over which the grids will be created
map_sheet_name = 'Acme'
# The primary and ancillary coordinate system in the grid template,
# the area of interest and the grid feature dataset must use the same datum.
# Determine the GCS of AOI feature class's spatial reference
desc = arcpy.Describe(aoi)
sr = desc.spatialReference.GCS
# Create a database and feature dataset for output grid features using the GCS
grid_dataset_name = "{0}_Grids".format(sr.name)
grid_database = arcpy.management.CreateFileGDB(output_path, 'Grids')
grid_dataset = arcpy.management.CreateFeatureDataset(grid_database, grid_dataset_name, sr)
# Make a feature layer from the Area of Interest features,
aoi_lyr = arcpy.management.MakeFeatureLayer(aoi, 'AOI_Index')
#Select a single feature in the layer - the map sheet with name Acme
aoi_query = "{0} = '{1}'".format(grid_name_field, map_sheet_name)
arcpy.management.SelectLayerByAttribute(aoi_lyr, 'NEW_SELECTION', aoi_query)
# Create grid feature over the selected AOI
# Add the grid to the Base Map Frame in the specified layout file
grid_layer_name = "{0}_Grids".format(map_sheet_name)
arcpy.topographic.MakeGridsAndGraticulesLayer(grid_xml, aoi_lyr, grid_dataset,
grid_layer_name, grid_name_field)
# Check In Extensions
arcpy.CheckInExtension('Foundation')This Python stand-alone sample creates a dataset in a file geodatabase and creates grid features in that dataset over the selected AOI. The created grids are added to the Base Map Frame in the specified .pagx file.
# Name: MakeGridsAndGraticulesLayer_sample2.py
# Description: Creates a dataset in a file geodatabase and creates grid features
# in that dataset over the selected AOI. The created grids are added to the
# 'Base Map Frame' in the specified .pagx file.
# Import System Modules
import arcpy
# Check Out Extensions
arcpy.CheckOutExtension('Foundation')
# --- Setting Local Variables ---
# Grid template
grid_xml = r'C:\Data\Topo_50K_WGS84.xml'
# Location for grids database
output_path = r'C:\Data'
# Grid area of interest (aoi) feature class
aoi = r'C:\Data\MapIndex.gdb\Index_50K'
# Field name to query to identify a single map sheet
grid_name_field = 'MAP_SHEET_NAME'
# Name of the map sheet over which the grids will be created
map_sheet_name = 'Redlands'
# Layout to be updated
layout = r'C:\Data\LayoutTemplate50K.pagx'
# Map frame to be updated
map_frame_name = 'Base Map Frame'
# --- Create output Feature Dataset ---
# The primary and ancillary coordinate system in the grid template,
# the area of interest and the grid feature dataset must use the same datum.
# Determine the GCS of AOI feature class's spatial reference
desc = arcpy.Describe(aoi)
sr = desc.spatialReference.GCS
# Create a database and feature dataset for output grid features using the GCS
grid_database_name = "{0}_Grids".format(map_sheet_name)
grid_dataset_name = "{0}_Grids".format(sr.name)
grid_database = arcpy.management.CreateFileGDB(output_path, grid_database_name)
grid_dataset = arcpy.management.CreateFeatureDataset(grid_database, grid_dataset_name, sr)
# --- Define the AOI ---
# Make a feature layer from the Area of Interest features,
aoi_lyr = arcpy.management.MakeFeatureLayer(aoi, 'AOI_Index')
#Select a single feature in the layer - the map sheet with name Acme
aoi_query = "{0} = '{1}'".format(grid_name_field, map_sheet_name)
arcpy.management.SelectLayerByAttribute(aoi_lyr, 'NEW_SELECTION', aoi_query)
# --- Create the Grid ---
# Create grid feature over the selected AOI
# Add the grid to the Base Map Frame in the specified layout file
grid_layer_name = "{0}_Grids".format(map_sheet_name)
arcpy.topographic.MakeGridsAndGraticulesLayer(grid_xml, aoi_lyr, grid_dataset,
grid_layer_name, grid_name_field,
"CONFIGURE_LAYOUT", layout, map_frame_name)
# Check In Extensions
arcpy.CheckInExtension('Foundation')Environments
Licensing information
- Basic: No
- Standard: Requires Production Mapping
- Advanced: Requires Production Mapping