When using spherical coordinates, distances are expressed as angles, not lengths. As there is an infinity of arcs that can connect two points on a sphere or spheroid, by convention the shortest one (the great circle distance) is used to measure how close two points are. As is explained in Working with Distances on the Sphere, you can convert angular distance on a sphere to linear distance. This is different from working on an ellipsoid, where one can only speak of linear distances between points, and to compute them one must specify which reference ellipsoid to use.
In spherical or geodetic coordinates, a position is
a latitude taken together with a longitude, e.g., (lat,lon)
,
which defines the horizontal coordinates of a point on the surface
of a planet. When we consider two points, e.g.,(lat1,lon1)
and (lat2,lon2)
,
there are several ways in which their 2–D spatial relationships
are typically quantified:
The azimuth (also called heading) to take to get from (lat1,lon1)
to (lat2,lon2)
The back azimuth (also called heading) from (lat2,lon2)
to (lat1,lon1)
The spherical distance separating (lat1,lon1)
from (lat2,lon2)
The linear distance (range) separating (lat1,lon1)
from (lat2,lon2)
The first three are angular quantities, while the last is a length. Mapping Toolbox™ functions exist for computing these quantities. For more information, see Directions and Areas on the Sphere and Spheroid and also Navigation for additional examples.
There is no single default unit of distance measurement in the
toolbox. Navigation functions use nautical miles as a default and
the distance
function uses degrees of arc length.
For many functions, the default unit for distances and positions is
degrees, but you need to verify the default assumptions before using
any of these functions.
Note When distances are given in terms of angular units (degrees or radians), be careful to remember that these are specified in terms of arc length. While a degree of latitude always subtends one degree of arc length, this is only true for degrees of longitude along the equator. |
Linear measurements of lengths and distances on spheres and spheroids can use the same units they do on the plane, such as feet, meters, miles, and kilometers. They can be used for
Absolute positions, such as map coordinates or terrain elevations
Dimensions, such as a planet's radius or its semimajor and semiminor axes
Distances between points or along routes, in 2-D or 3-D space or across terrain
Length units are needed to describe
The dimensions of a reference sphere or ellipsoid
The line-of-sight distance between points
Distances along great circle or rhumb line curves on an ellipsoid or sphere
X-Y locations in a projected coordinate system or map grid
Offsets from a map origin (false eastings and northings)
X-Y-Z locations in Earth-centered Earth-fixed (ECEF) or local vertical systems
Heights of various types (terrain elevations above a geoid, an ellipsoid, or other reference surface)
Using the toolbox effectively depends on being consistent about units of length. Depending on the specific function and the way you are calling it, when you specify lengths, you could be
Explicitly specifying a radius, reference spheroid object, or ellipsoid vector
Relying on the function itself to specify a default radius or ellipsoid
Relying on the reference ellipsoid associated with a map projection structure (mstruct)
Whenever you are doing a computation that involves a reference sphere or ellipsoid, make sure that the units of length you are using are the same units used to define the radius of the sphere or semimajor axis of the ellipsoid. These considerations are discussed below.
The following Mapping Toolbox functions convert between different units of length:
unitsratio
computes multiplicative
factors for converting between 12 different units of length as well
as between degrees and radians. You can use unistratio
to
perform conversions when neither the input units of length nor the
output units of length are known until run time. See Converting Angle Units that Vary at Run Time for
more information.
km2nm
, km2sm
, nm2km
, nm2sm
, sm2km
,
and sm2nm
perform simple and convenient conversions
between kilometers, nautical miles, and statute miles.
These utility functions accept scalars, vectors, and matrices, or any shape. For an overview of these functions and angle conversion functions, see Summary: Available Distance and Angle Conversion Functions.
The unitsratio
function
can compute the ratio between any of the following units of length:
Microns
Millimeters
Centimeters
Meters
Kilometers
Inches
International feet
U.S. survey feet
Yards
International miles
U.S. survey (statute) miles
The syntax for unitsratio
is
ratio = unitsratio(to-unit,from-unit)
You can use the output from unitsratio
as
a multiplicative conversion factor.
For example, the following shows that 4 inches span just over 10 centimeters:
cmPerInch = unitsratio('cm','inch') cm = cmPerInch * 4 cmPerInch = 2.5400 cm = 10.1600
To convert this number of centimeters back to inches, type
inch = unitsratio('in','centimeter') * cmPerInch inch = 1
Note that unitsratio
supports various abbreviations
for units of length.
The unitsratio
function also lets you convert
angles between degrees and radians.
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 the Mapping Toolbox function 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 a string-valued '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 as Strings.
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
Many geospatial domains (seismology, for example) describe distances between points on the surface of the earth as angles. This is simply the result of dividing the length of the shortest great-circle arc connecting a pair points by the radius of the Earth (or whatever planet one is measuring). This gives the angle (in radians) subtended by rays from each point that join at the center of the Earth (or other planet). This is sometimes called a "spherical distance." You can thus call the resulting number a "distance in radians." You could also call the same number a "distance in earth radii." When you work with transformations of geodata, keep this in mind.
You can easily convert that angle from radians to degrees. For
example, you can call distance
to compute the
distance in meters from London to Kuala Lumpur:
latL = 51.5188; lonL = -0.1300; latK = 2.9519; lonK = 101.8200; earthRadiusInMeters = 6371000; distInMeters = distance(latL, lonL,... latK, lonK, earthRadiusInMeters) distInMeters = 1.0571e+007
distInRadians = distInMeters / earthRadiusInMeters distInRadians = 1.6593
distInDegrees = rad2deg(distInRadians) distInDegrees = 95.0692
Mapping Toolbox software includes a set of six functions to conveniently convert distances along the surface of the Earth (or another planet) from units of kilometers (km), nautical miles (nm), or statue miles (sm) to spherical distances in degrees (deg) or radians (rad):
km2deg
, nm2deg
,
and sm2deg
go from length to angle in degrees
km2rad
, nm2rad
,
and sm2rad
go from length to angle in radians
You could replace the final two steps in the preceding example with
distInKilometers = distInMeters/1000; earthRadiusInKm = 6371; km2deg(distInKilometers, earthRadiusInKm) ans = 95.0692
deg2km
, deg2nm
,
and deg2sm
go from angle in degrees to length
rad2km
, rad2nm
,
and rad2sm
go from angle in radians to length
When given a single input argument, all 12 functions assume a radius of 6,371,000 meters (6371 km, 3440.065 nm, or 3958.748 sm), which is widely-used as an estimate of the average radius of the Earth. An optional second parameter can be used to specify a planetary radius (in output length units) or the name of an object in the Solar System.
On the Earth, a degree of arc length at the equator is about 60 nautical miles:
nauticalmiles = deg2nm(1) nauticalmiles = 60.0405
The Earth is the default assumption for these conversion functions. You can use other radii, however:
moon = referenceSphere('moon','km'); nauticalmiles = deg2nm(1,moon.Radius) nauticalmiles = 30.3338
The function deg2sm
returns distances in
statute, rather than nautical, miles:
deg2sm(1) ans = 69.0932
Certain syntaxes of the distance
and reckon
functions
use angles to denote distances in the way described above. In the
following statements, the range argument, arclen
,
is in degrees (along with all the other inputs and outputs):
[arclen, az] = distance(lat1, lon1, lat2, lon2) [latout, lonout] = reckon(lat, lon, arclen, az)
units
argument, you can
use radians instead:[arclen, az] = distance(lat1, lon1, lat2, lon2, 'radians') [latout, lonout] = reckon(lat, lon, arclen, az, 'radians')
ellipsoid
argument is provided, however, then arclen
has
units of length, and they match the units of the semimajor axis length
of the reference ellipsoid. If you specify ellipsoid = [1
0]
(the unit sphere), arclen
can be considered
to be either an angle in radians or a length defined in units of earth
radii. It has the same value either way. Thus, in the following computation, lat1
, lon1
, lat2
, lon2
,
and az
are in degrees, but arclen
will
appear to be in radians: [arclen, az] = distance(lat1, lon1, lat2, lon2, [1 0])
The following table shows the Mapping Toolbox unit-to-unit distance and arc conversion functions. They all accept scalar, vector, and higher-dimension inputs. The first two columns and rows involve angle units, the last three involve distance units:
Functions that Directly Convert Angles, Lengths, and Spherical Distances
Convert | To Degrees | To Radians | To Kilometers | To Nautical Miles | To Statute Miles |
---|---|---|---|---|---|
Degrees | toDegrees fromDegrees | deg2rad toRadians fromDegrees | deg2km | deg2nm | deg2sm |
Radians | rad2deg toDegrees fromRadians | toRadians fromRadians | rad2km | rad2nm | rad2sm |
Kilometers | km2deg | km2rad | km2nm | km2sm | |
Nautical Miles | nm2deg | nm2rad | nm2km | nm2sm | |
Statute Miles | sm2deg | sm2rad | sm2km | sm2nm |
The angle conversion functions along the major diagonal, toDegrees
, toRadians
, fromDegrees
,
and fromRadians
, can have no-op results. They
are intended for use in applications that have no prior knowledge
of what angle units might be input or desired as output.
The terms decimal degrees and decimal minutes are often used in geospatial data handling and navigation. The preceding section avoided using them because its focus was on the representation of angles within MATLAB, where they can be arbitrary binary floating-point numbers.
However, once an angle in degrees is converted to a string, it is often helpful to describe that string as representing the angle in decimal degrees. Thus,
num2str(rad2deg(1)) ans = 57.2958
rad2deg(1)
as
being in decimal degrees, but strictly speaking, that is not true
until it is somehow converted to a string in base 10. That is, a binary
floating-point number is not a decimal number, whether it represents
an angle in degrees or not. If it does represent an angle and that
number is then formatted and displayed as having a fractional part,
only then is it appropriate to speak of "decimal degrees."
Likewise, the term "decimal minutes" applies when you
convert a degrees-minutes representation to a string, as innum2str(degrees2dm(rad2deg(1))) ans = 57 17.7468
When a DM or DMS representation of an angle is expressed as
a string, it is traditional to tag the different components with
the special characters d
, m
,
and s
, or °, ', and ".
When the angle is a latitude or longitude, a letter often designates the sign of the angle:
N
for positive latitudes
S
for negative latitudes
E
for positive longitudes
W
for negative longitudes
For example, 123 degrees, 30 minutes, 12.7 seconds west of Greenwich can be written as 123d30m12.7sW, 123° 30° 12.7" W, or -123° 30° 12.7".
Use the function str2angle
to
import latitude and longitude data formatted as such strings. Conversely,
you can format numeric degree data for display or export with angl2str
, or combine degrees2dms
or degrees2dm
with sprintf
to
customize formatting.
See Degrees, Minutes, and Seconds for more details about DM and DMS representation.