Main Content

Angular measurements have many distinct roles in geospatial data handling. For example, they are used to specify

Absolute positions — latitudes and longitudes

Relative positions — azimuths, bearings, and elevation angles

Spherical distances between point locations

Absolute positions are expressed in *geodetic coordinates*, which are
actually angles between lines or planes on a reference sphere or ellipsoid. Relative positions
use units of angle to express the direction between one place on the reference body from
another one. Spherical distances quantify how far two places are from one another in terms of
the angle subtended along a great-circle arc. On nonspherical reference bodies, distances are
usually given in linear units such as kilometers (because on them, arc lengths are no longer
proportional to subtended angle).

The basic unit for angles in MATLAB^{®} is the radian. For example, if the variable theta represents an angle and you
want to take its sine, you can use `sin(theta)`

if and only if the value of
theta is expressed in radians. If a variable represents the value of an angle in degrees,
then you must convert the value to radians before taking the sine. For example,

thetaInDegrees = 30; thetaInRadians = thetaInDegrees * (pi/180) sinTheta = sin(thetaInRadians)

`pi/180`

. However, you should consider using `deg2rad`

for this
purpose:thetaInRadians = deg2rad(thetaInDegrees)

thetaInDegrees = thetaInRadians * (180/pi)

`rad2deg`

,thetaInDegrees = rad2deg(thetaInRadians)

It reduces the likelihood of human error (e.g., you might type "pi/108" by mistake)

It signals clearly your intent—important to do should others ever read, modify, or debug your code

The functions `rad2deg`

and `deg2rad`

are very simple and efficient, and operate on vector and higher-dimensioned input as well as
scalars.

Unlike MATLAB trigonometric functions, Mapping Toolbox™ functions do not always assume that angular arguments are in units of radians.

The low-level utility functions intended as building blocks of more complex features or
applications work only in units of radians. Examples include the functions
`unwrapMultipart`

and `meridianarc`

.

Many high-level functions, including `distance`

, can work in either
degrees or radians. Their interpretation of angles is controlled by the
`'angleunits'`

input argument. (`angleunits`

can be
either `'degrees'`

or `'radians'`

, and can generally be
abbreviated.) This flexibility balances convenience and efficiency, although it means that
you must take care to check what assumptions each function is making about its inputs.

In all Mapping Toolbox computations that involve angles in degrees, floating-point numbers (generally MATLAB class double) are used, which allows for integer and fractional values and rational approximations to irrational numbers. However, several traditional notations, which are still in wide use, represent angles as pairs or triplets of numbers, using minutes of arc (1/60 of degree) and seconds of arc (1/60 of a minute):

Degrees-minutes notation (DM), e.g., 35° 15’, equal to 35.25°

Degrees-minutes-seconds notation (DMS) , e.g., 35° 15’ 45’’, equal to 35.2625°

In degrees-minutes representation, an angle is split into three separate parts:

A sign

A nonnegative, integer-valued degrees component

A nonnegative minutes component, real-valued and in the half-open interval [0 60)

For example, -1 radians is represented by a minus sign (-) and the numbers [57, 17.7468...]. (The fraction in the minutes part approximates an irrational number and is rounded here for display purposes. This subtle point is revisited in the following section.)

The toolbox includes the function `degrees2dm`

to perform conversions
of this sort. You can use this function to export data in DM form, either for display
purposes or for use by another application. For example,

degrees2dm(rad2deg(-1))

ans = -57.0000 17.7468

`degrees2dm`

converts a single-columned input to a pair of
columns. Rather than storing the sign in a separate element, `degrees2dm`

applies to the first nonzero element in each row. Function `dm2degrees`

converts in the opposite direction, producing a real-valued column vector of degrees from a
two-column array having an integer degrees and real-valued minutes column. Thus,
dm2degrees(degrees2dm(pi)) == pi

ans = 1

A sign

A nonnegative integer-valued degrees component

A minutes component which can be any integer from 0 through 59

A nonnegative minutes component, real-valued and in the half-open interval [0 60)

For example, -1 radians is represented by a minus sign (-) and the numbers
[57, 17, 44.8062...], which can be seen using Mapping Toolbox function
`degrees2dms`

,

degrees2dms(rad2deg(-1))

ans = -57.0000 17.0000 44.8062

`degrees2dms`

works like `degrees2dm`

; it converts single-columned input to
three-column form, applying the sign to the first nonzero element in each row.A fourth function, `dms2degrees`

, is similar to
`dm2degrees`

and supports data import by producing a real-valued column
vector of degrees from an array with an integer-valued degrees column, an integer-value
minutes column, and a real-valued seconds column. As noted, the four functions,
`degrees2dm`

, `degrees2dms`

,
`dm2degrees`

, and `dms2degrees`

, are particular
about the shape of their inputs; in this regard they are distinct from the other
angle-conversion functions in the toolbox.

The toolbox makes no internal use of DM or DMS representation. The conversion functions
`dm2degrees`

and `dms2degrees`

are provided only as
tools for data import. Likewise, `degrees2dm`

and
`degrees2dms`

are only useful for displaying geographic coordinates on
maps, publishing coordinate values, and for formatting data to be exported to other
applications. Methods for accomplishing this are discussed below, in Formatting Latitudes and Longitudes.

Functions `deg2rad`

and `rad2deg`

are simple to use and efficient, but how do you write code to convert
angles if you do not know ahead of time what units the data will use? The toolbox provides a
set of utility functions that help you deal with such situations at run time.

In almost all cases—even at the time you are coding—you know either the input or destination angle units. When you do, you can use one of these functions:

For example, you might wish to implement a very simple sinusoidal projection on the unit sphere, but allow the input latitudes and longitudes to be in either degrees or radians. You can accomplish this as follows:

function [x, y] = sinusoidal(lat, lon, angleunits) [lat, lon] = toRadians(angleunits, lat, lon); x = lon .* cos(lat); y = lat;

`angleunits`

turns out to be
`'radians'`

at run time, the `toRadians`

function has
no real work to do; all the functions in this group handle such "no-op" situations
efficiently. In the very rare instances when you must code an application or MATLAB function in which the units of both input angles and output angles remain
unknown until run time, you can still accomplish the conversion by using the
`unitsratio`

function. For example,

fromUnits = 'radians'; toUnits = 'degrees'; piInDegrees = unitsratio(toUnits, fromUnits) * pi

piInDegrees = 180