Calculate Metrics (Topographic Production Tools)

Summary

Populates metrics for features in a geodatabase. Metrics include length, width, area, and elevation attributes.

Usage

Caution:

This tool modifies the input data. See Tools that modify or update the input data for more information and strategies to avoid undesired data changes.

The following are supported feature attribute metrics:
- Length—The default attributes are LEG, LEN, LEN_, LGN, and LZN.
- Width—The default attributes are WID, WID_, and WGP.
- Area—The default attributes are ARA, ARE, and ARE_.
- Angle of orientation—The default attributes are AOO, DOF, and FEO.
- Elevation—The default attributes are ZV2 and ZVH (must be z-enabled data).
  
  Note:
  
  Elevation metrics that the tool derives from a raster file specified for the Elevation Raster parameter value will overwrite existing elevation data.
- Military Grid Reference System—The default attributes are MGRSValue and MGRS.
Input metric types are processed based on the geometry of the feature class as follows:
- Points—Elevation
- Lines—Length and Elevation
- Polygons—Length, Width, Area, Angle of Orientation, and Elevation
The Input Length Attributes, Input Width Attributes, Input Area Attributes, Input Angle of Orientation Attributes, and Input Elevation Attributes parameter values reference a comma-delimited list of field names in the data model. If one or more fields exist in the Input Features parameter value, the field will be calculated according to the metrics specified for the Input Metric Types parameter value.
You can add custom field names to the list of options in the Input Length Attributes, Input Width Attributes, Input Area Attributes, Input Angle of Orientation Attributes, and Input Elevation Attributes parameter values. This tool will attempt to compute metrics in a custom field.
This tool can calculate the Military Grid Reference System (MGRS) coordinates for features using the standard precision formats as well as the format used for Image City Map (ICM) annotation features. For ICM format, the value is a combination of the column and row number in which the feature is located.

License:

The ArcGIS Spatial Analyst extension allows this tool to rotate features such as springs and natural pools to face downhill. The ArcGIS Topographic Mapping product data files include certain point feature layers with a CBO_Rotation attribute field that is set up to be updated by this tool using the Elevation Raster parameter value and specifying Angle of orientation for the Input Metric Types parameter value.

Label	Explanation	Data type
Input Features	The features for which metrics will be calculated.	Feature Layer
Input Metric Types	Specifies the types of metrics that will be calculated. License: The Spatial Analyst extension is required when using an elevation raster and the Angle of orientation option to rotate point features so that they face downhill. Length—Length metrics will be calculated. Width—Width metrics will be calculated. Area—Area metrics will be calculated. Angle of orientation—Angle of orientation metrics will be calculated. Elevation—Elevation metrics will be calculated. Military Grid Reference System—Military Grid Reference System coordinates will be calculated.	String
Input Length Attributes (Optional)	A comma-delimited string of field names from which the length metrics will be calculated. The default is `LEG,LEN,LEN_,LGN,LZN`. You can add the names of other length metric fields; if the fields exist in the Input Features value, they will be computed.	String
Input Width Attributes (Optional)	A comma-delimited string of field names from which the width metrics will be calculated. The default is `WID,WID_,WGP`. You can add the names of other width metric fields; if the fields exist in the Input Features value, they will be computed.	String
Input Area Attributes (Optional)	A comma-delimited string of field names from which the area metrics will be calculated. The default is `ARA,ARE,ARE_`. You can add the names of other area metric fields; if the fields exist in the Input Features value, they will be computed.	String
Input Angle of Orientation Attributes (Optional)	A comma-delimited string of field names from which the angle of orientation metrics will be calculated. The default is `AOO,DOF,FEO`. You can add the names of other angle of orientation metric fields; if the fields exist in the Input Features value, they will be computed.	String
Input Elevation Attributes (Optional)	A comma-delimited string of field names from which the elevation metrics will be calculated. The default is `ZV2,ZVH`. You can add the names of other elevation metric fields; if the fields exist in the Input Features value, they will be computed.	String
Input Floating Point Precision (Optional)	The precision of the metrics written to the target attributes.	Long
Input MGRS Attributes (Optional)	A comma-delimited string of field names from which the MGRS coordinates will be calculated. The default is `MGRSValue,MGRS`. You can add the names of other MGRS fields; if the fields exist in the Input Features value, they will be computed. The fields must have a String field type and a field length greater than the largest possible MGRS coordinate value.	String
MGRS Precision (Optional)	Specifies the precision of the coordinates that will be calculated for the target attributes. 6×8 (4Q)—The precision will be calculated at grid-level precision, typically the polygon formed by a 6-degree wide UTM zone and 8-degree high latitude bands. 100km (4QFJ)—The precision will be calculated at 100,000 meters squared. 10km (4QFJ16)—The precision will be calculated at 10,000 meters squared. 1km (4QFJ1267)—The precision will be calculated at 1,000 meters squared. 100m (4QFJ123678)—The precision will be calculated at 100 meters squared. 10m (4QFJ12346789)—The precision will be calculated at 10 meters squared. 1m (4QFJ1234567890)—The precision will be calculated at 1 meter squared. Image City Map (1234)—The precision will be calculated at the level of an Image City Map (ICM). This is the default.	String
Elevation Raster (Optional)	The raster file from which the elevation metrics will be derived. Elevation metrics derived from a raster file specified here will overwrite existing elevation data. License: The Spatial Analyst extension is required when using an elevation raster and the angle of orientation to rotate point features so that they face downhill.	Raster Layer; Mosaic Layer
Only populate NULL values (Optional)	Specifies whether only null metric values will be calculated. Checked—Only null values will be calculated. Unchecked—All values will be calculated. This option will overwrite the existing values for the specified input attribute fields of the Input Features parameter value. This is the default.	Boolean

Derived output

Label	Explanation	Data type
Output Features	The features on which metrics were calculated.	Feature Layer

arcpy.topographic.CalculateMetrics(in_features, in_metric_types, {in_length_attributes}, {in_width_attributes}, {in_area_attributes}, {in_angle_attributes}, {in_elevation_attributes}, {in_precision}, {mgrs_attributes}, {mgrs_precision}, {elevation_raster}, {only_populate_null_values})

Name	Explanation	Data type
in_features [in_features,...]	The features for which metrics will be calculated.	Feature Layer
in_metric_types [in_metric_types,...]	Specifies the types of metrics that will be calculated. License: The Spatial Analyst extension is required when using an elevation raster and the `ANGLE_OF_ORIENTATION` option to rotate point features so that they face downhill. `LENGTH`—Length metrics will be calculated. `WIDTH`—Width metrics will be calculated. `AREA`—Area metrics will be calculated. `ANGLE_OF_ORIENTATION`—Angle of orientation metrics will be calculated. `ELEVATION`—Elevation metrics will be calculated. `MGRS`—Military Grid Reference System coordinates will be calculated.	String
in_length_attributes (Optional)	A comma-delimited string of field names from which the length metrics will be calculated. The default is `LEG,LEN,LEN_,LGN,LZN`. You can add the names of other length metric fields; if the fields exist in the `in_features` value, they will be computed.	String
in_width_attributes (Optional)	A comma-delimited string of field names from which the width metrics will be calculated. The default is `WID,WID_,WGP`. You can add the names of other width metric fields; if the fields exist in the `in_features` value, they will be computed.	String
in_area_attributes (Optional)	A comma-delimited string of field names from which the area metrics will be calculated. The default is `ARA,ARE,ARE_`. You can add the names of other area metric fields; if the fields exist in the `in_features` value, they will be computed.	String
in_angle_attributes (Optional)	A comma-delimited string of field names from which the angle of orientation metrics will be calculated. The default is `AOO,DOF,FEO`. You can add the names of other angle of orientation metric fields; if the fields exist in the `in_features` value, they will be computed.	String
in_elevation_attributes (Optional)	A comma-delimited string of field names from which the elevation metrics will be calculated. The default is `ZV2,ZVH`. You can add the names of other elevation metric fields; if the fields exist in the `in_features` value, they will be computed.	String
in_precision (Optional)	The precision of the metrics written to the target attributes.	Long
mgrs_attributes (Optional)	A comma-delimited string of field names from which the MGRS coordinates will be calculated. The default is `MGRSValue,MGRS`. You can add the names of other MGRS fields; if the fields exist in the `in_features` value, they will be computed. The fields must have a String field type and a field length greater than the largest possible MGRS coordinate value.	String
mgrs_precision (Optional)	Specifies the precision of the coordinates that will be calculated for the target attributes. `6x8 (4Q)`—The precision will be calculated at grid-level precision, typically the polygon formed by a 6-degree wide UTM zone and 8-degree high latitude bands. `100km (4QFJ)`—The precision will be calculated at 100,000 meters squared. `10km (4QFJ16)`—The precision will be calculated at 10,000 meters squared. `1km (4QFJ1267)`—The precision will be calculated at 1,000 meters squared. `100m (4QFJ123678)`—The precision will be calculated at 100 meters squared. `10m (4QFJ12346789)`—The precision will be calculated at 10 meters squared. `1m (4QFJ1234567890)`—The precision will be calculated at 1 meter squared. `Image City Map (1234)`—The precision will be calculated at the level of an Image City Map (ICM). This is the default.	String
elevation_raster (Optional)	The raster file from which the elevation metrics will be derived. Elevation metrics derived from a raster file specified here will overwrite existing elevation data. License: The Spatial Analyst extension is required when using an elevation raster and the angle of orientation to rotate point features so that they face downhill.	Raster Layer; Mosaic Layer
only_populate_null_values (Optional)	Specifies whether only null metric values will be calculated. `ONLYPOPNULLVALS`—Only null values will be calculated. `NO_ONLYPOPNULLVALS`—All values will be calculated. This option will overwrite the existing values for the specified input attribute fields of the `in_features` parameter value. This is the default.	Boolean

Derived output

Name	Explanation	Data type
out_features	The features on which metrics were calculated.	Feature Layer

Code sample

CalculateMetrics example 1 (stand-alone script)

The following code sample calculates the width fields for polyline features in the attribute table.

# Name: CalculateMetrics_sample1.py
# Description: Calculating the width field for features in a polyline feature class

# Import System Modules
import arcpy

# Setting Local Variables
input_features = r'C:\Temp\Test.gdb\RiverLines'
field_name = 'WID'

# Creating feature layer
river_lines = arcpy.management.MakeFeatureLayer(input_features, 'RiverLines').getOutput(0)

# Calculating WIDTH of input features on the WID field
arcpy.topographic.CalculateMetrics(river_lines, 'WIDTH', '#', field_name, '#', '#', '#', '#', '#', '#', '#', 'NO_ONLYPOPNULLVALS')

CalculateMetrics example 2 (stand-alone script)

The following code sample iterates through the features in a database and calculates metric attributes.

# Name: CalculateMetrics_sample2.py
# Description: Iterates through the features in a database and calculates metric attributes

# Import System Modules
import arcpy
import string
import os

# Setting Local Variables
input_database = r'C:\Data\Sample.gdb'
raster = r'C:\Data\Monterey.dt2'
metric_type = 'LENGTH;WIDTH;AREA;ANGLE_OF_ORIENTATION;ELEVATION;MGRS'

# Getting feature classes from database
arcpy.env.workspace = input_database
feature_classes = []
feature_datasets = arcpy.ListDatasets('*', 'Feature')
for dataset in feature_datasets:
    fclass = arcpy.ListFeatureClasses('*', '', dataset)
    for fc in fclass:
        feature_classes.append(os.path.join(input_database, dataset, fc))

# Converting feature classes into layers
layer_list = []
for feat_class in feature_classes:
    class_name = os.path.split(feat_class)[1]
    arcpy.management.MakeFeatureLayer(feat_class, class_name)
    layer_list.append(class_name)

# Creating string for input to Calculate Metrics Fields tool
feature_string = ''
for layer in layer_list:
    feature_string += '{};'.format(layer)

# Calculating Metric fields on all features classes in the input database
arcpy.topographic.CalculateMetrics(feature_string, metric_type, '#', '#', '#', '#', '#', '#', '#', '#', raster, 'NO_ONLYPOPNULLVALS')

Environments

Current Workspace

Licensing information

Basic: No
Some parameters require the Spatial Analyst extension—see the tool reference page for more detail.
Standard: No
Some parameters require the Spatial Analyst extension—see the tool reference page for more detail.
Advanced: Requires Topographic Mapping
Some parameters require the Spatial Analyst extension—see the tool reference page for more detail.

Calculate Metrics (Topographic Production Tools)

Summary

Usage

Caution:

Note:

License:

Parameters

License:

License:

Derived output

Environments

Licensing information

Related topics