getConvergenceAngle

Calculate the grid convergence for a spatial reference at a given point. The grid convergence is the angle between True North and Grid North at a point on a map. The grid convergence can be used to convert a horizontal direction expressed as an azimuth in a geographic coordinate system (relative to True North) to a direction expressed as a bearing in a projected coordinate system (relative to Grid North), and vice versa.

Sign convention

The grid convergence returned by this method is positive when Grid North lies east of True North. The following formula demonstrates how to obtain a bearing (b) from an azimuth (a) using the grid convergence (c) returned by this method:

b = a - c

This sign convention is sometimes named the Gauss-Bomford convention.

Other notes:

• Returns 0 if the spatial reference is a geographic coordinate system

• Returns NAN if the point is outside the projection's horizon or on error

• If the point has no spatial reference, it is assumed to be in the given spatial reference

• If the point's spatial reference differs from the spatial reference given, its location is transformed automatically to the given spatial reference