Calculate Grid Convergence Angle (Cartography)

Summary

Calculates the rotation angle for true north based on the center point of each feature in a feature class and populates this value in a specified field. This field can be used in conjunction with a spatial map series to rotate each map to true north.

Usage

  • Calculating a geodesic angle requires a valid projected coordinate system to be specified.

    • If you specify a coordinate system field, the tool will use the projected coordinate system value (projection engine string) for each feature. If there is an invalid projection engine string, the tool will use the coordinate system specified as the Cartographic Coordinate System environment variable.
    • If you do not use a field to specify the projected coordinate system, the tool will use the one specified as the Cartographic Coordinate System in the Cartography environment settings.

Parameters

LabelExplanationData Type
Input Features

The input feature class (points, multipoints, lines, and polygons).

Feature Layer
Angle Field

The existing field that will be populated with the true north calculation value in decimal degrees.

Field
Rotation Method
(Optional)

Specifies the method used to calculate the rotation value.

  • GeographicThe angle is calculated clockwise with 0 at the top. This is the default.
  • ArithmeticThe angle is calculated counterclockwise with 0 at the right.
  • GraphicThe angle is calculated counterclockwise with 0 at the top.
String
Coordinate System Field
(Optional)

The field containing a projection engine string for a projected coordinate system to be used for angle calculation. The angle calculation for each feature will be based on the projected coordinate system projection engine string for the specific feature. In cases of an invalid value, the tool will use the cartographic coordinate system specified in the Cartography environment settings. The default is none, or no field specified. When no field is specified, the projected coordinate system used for calculation will be taken from the Cartography environment settings.

Field

Derived Output

LabelExplanationData Type
Output Features

The updated feature class with calculated rotation values.

Feature Layer

arcpy.cartography.CalculateGridConvergenceAngle(in_features, angle_field, {rotation_method}, {coordinate_sys_field})
NameExplanationData Type
in_features

The input feature class (points, multipoints, lines, and polygons).

Feature Layer
angle_field

The existing field that will be populated with the true north calculation value in decimal degrees.

Field
rotation_method
(Optional)

Specifies the method used to calculate the rotation value.

  • GEOGRAPHICThe angle is calculated clockwise with 0 at the top. This is the default.
  • ARITHMETICThe angle is calculated counterclockwise with 0 at the right.
  • GRAPHICThe angle is calculated counterclockwise with 0 at the top.
String
coordinate_sys_field
(Optional)

The field containing a projection engine string for a projected coordinate system to be used for angle calculation. The angle calculation for each feature will be based on the projected coordinate system projection engine string for the specific feature. In cases of an invalid value, the tool will use the cartographic coordinate system specified in the Cartography environment settings. The default is none, or no field specified. When no field is specified, the projected coordinate system used for calculation will be taken from the Cartography environment settings.

Field

Derived Output

NameExplanationData Type
out_features

The updated feature class with calculated rotation values.

Feature Layer

Code sample

CalculateGridConvergenceAngle example 1 (Python window)

The following example calculates a true north rotation angle for a feature.

import arcpy
arcpy.env.workspace = "C:\data\ProjectData.gdb"
arcpy.CalculateGridConvergenceAngle_cartography("US_states", "angle", 
                                                "GEOGRAPHIC", "UTM")
CalculateGridConvergenceAngle example 2 (stand-alone script)

The following example calculates a true north rotation angle for point features.

# Name: calculategridconvergenceangle_example.py
# Description: Calculates the true north rotation angle for features

# Import system modules
import arcpy

# Set environment settings
arcpy.env.workspace = "C:\Data\ProjectData.gdb"

# Set local variables
inFeatures = "US_states"
angleField = "angle"
rotationMethod = "GEOGRAPHIC"
coordSystemField = "UTM"

# Execute CalculateGridConvergenceAngle
arcpy.CalculateGridConvergenceAngle_cartography(inFeatures, angleField,
                                                rotationMethod,
                                                coordSystemField)

Environments

Cartographic Coordinate System

This setting is used when no coordinate system field is chosen, or if a coordinate system field is chosen and the coordinate system string value is invalid, in which case the coordinate system specified here will be used in the angle calculation.

Licensing information

  • Basic: Yes
  • Standard: Yes
  • Advanced: Yes

Related topics