distance

Distance between points on sphere or ellipsoid

Syntax

[arclen,az] = distance(lat1,lon1,lat2,lon2)

[arclen,az] = distance(lat1,lon1,lat2,lon2,ellipsoid)

[arclen,az] = distance(pt1,pt2)

[arclen,az] = distance(pt1,pt2,ellipsoid)

[arclen,az] = distance(___,units)

[arclen,az] = distance(method,___)

Description

[arclen,az] = distance(lat1,lon1,lat2,lon2) computes the lengths, arclen, of the great circle arcs connecting pairs of points on the surface of a sphere. In each case, the shorter (minor) arc is assumed. The function can also compute the azimuths, az, of the second point in each pair with respect to the first (that is, the angle at which the arc crosses the meridian containing the first point).

[arclen,az] = distance(lat1,lon1,lat2,lon2,ellipsoid) computes geodesic arc length and azimuth assuming that the points lie on the reference ellipsoid defined by the input ellipsoid.

[arclen,az] = distance(pt1,pt2) accepts N-by-2 coordinate arrays of pairs of points, pt1 and pt2, that store latitude coordinates in the first column and longitude coordinates in the second column.

This syntax is equivalent to arclen = distance(pt1(:,1),pt1(:,2),pt2(:,1),pt2(:,2)).

[arclen,az] = distance(pt1,pt2,ellipsoid) computes geodesic arc length and azimuth assuming that the points lie on the reference ellipsoid defined by the input ellipsoid.

[arclen,az] = distance(___,units) also specifies the angle units of the latitude and longitude coordinates for any of the preceding syntaxes.

[arclen,az] = distance(method,___) also specifies whether the track is a great circle/geodesic or a rhumb line arc, for any of the preceding syntaxes.

Examples

Find Difference in Distance Along Two Tracks

Using pt1,pt2 notation, find the distance from Norfolk, Virginia (37°N, 76°W), to Cape St. Vincent, Portugal (37°N, 9°W), just outside the Straits of Gibraltar. The distance between these two points depends upon the track method.

arclen = distance('gc',[37,-76],[37,-9])

arclen =

   52.3094

arclen = distance('rh',[37,-76],[37,-9])

arclen =

    53.5086

The difference between these two tracks is 1.1992 degrees, or about 72 nautical miles. This represents about 2% of the total trip distance. The tradeoff is that at the cost of those 72 miles, the entire trip can be made on a rhumb line with a fixed course of 90º, due east, while in order to follow the shorter great circle path, the course must be changed continuously.

On a meridian and on the Equator, great circles and rhumb lines coincide, so the distances are the same. For example,

% Great circle distance
arclen = distance(37,-76,67,-76) 

arclen =

     30.0000

% Rhumb line distance
arclen = distance('rh',37,-76,67,-76) 

arclen =

     30.0000

Input Arguments

lat1, lon1 — First set of latitude or longitude coordinates

numeric scalar | numeric array

First set of latitude or longitude coordinates, specified as a numeric scalar or numeric array. The coordinates are expressed in degrees unless units is specified as 'radians'.

Data Types: single | double

lat2, lon2 — Second set of latitude or longitude coordinates

numeric scalar | numeric array

Second set of latitude or longitude coordinates, specified as a numeric scalar or numeric array. The coordinates are expressed in degrees unless units is specified as 'radians'.

Data Types: single | double

pt1 — First set of point coordinates

N-by-2 numeric matrix

First set of point coordinates, specified as an N-by-2 numeric matrix. pt1 is equivalent to [lat1 lon1] when lat1 and lon1 are column vectors.

Data Types: single | double

pt2 — Second set of point coordinates

N-by-2 numeric matrix

Second set of point coordinates, specified as an N-by-2 numeric matrix. pt2 is equivalent to [lat2 lon2] when lat2 and lon2 are column vectors.

Data Types: single | double

ellipsoid — Reference ellipsoid

referenceSphere object | referenceEllipsoid object | oblateSpheroid object | two-element vector

Reference ellipsoid, specified as an referenceSphere, referenceEllipsoid, or oblateSpheroid object, or a two-element vector of the form [semimajor_axis eccentricity].

Example: referenceEllipsoid('GRS80')

Example: [6378.137 0.0818191910428158]

units — Angle units

'degrees' (default) | 'radians'

Angle units of the latitude and longitude coordinates, specified as 'degrees' or 'radians'.

Data Types: char

method — Track method

'gc' (default) | 'rh'

Track method, specified as one of the following character vectors.

• 'gc' — Great circle distances are computed on a sphere and geodesic distances are computed on an ellipsoid.

• 'rh' — Rhumb line distances are computed on either a sphere or ellipsoid.

Data Types: char

Output Arguments

arclen — Arc length

numeric scalar | numeric vector | numeric array

Arc length, returned as a numeric scalar or array of the same size as the input latitude and longitude arrays, lat1, lon1, lat2 and lon2. When coordinates are specified using coordinate arrays pt1 and pt2, then arclen is a numeric vector of length N.

• When ellipsoid is not specified, arclen is expressed in degrees or radians of arc, consistent with the value of units.

• When ellipsoid is specified, arclen, is expressed in the same length units as the semimajor axis of the ellipsoid.

Data Types: double

az — Azimuth

numeric scalar | numeric vector | numeric array

Azimuth of the second point in each pair with respect to the first, returned as a numeric scalar or array of the same size as the input latitude and longitude arrays, lat1, lon1, lat2 and lon2. When coordinates are specified using coordinate arrays pt1 and pt2, then arclen is a numeric vector of length N. az is measured clockwise from north.

Data Types: single | double

Tips

• The size of nonscalar latitude and longitude coordinates, lat1, lon1, lat2, and lon2, must be consistent. When given a combination of scalar and array inputs, the distance function automatically expands scalar inputs to match the size of the arrays.

• To express the output arclen as an arc length in either degrees or radians, omit the ellipsoid argument. This is possible only on a sphere. If ellipsoid is supplied, arclen is a distance expressed in the same units as the semimajor axis of the ellipsoid. Specify ellipsoid as [R 0] to compute arclen as a distance on a sphere of radius R, with arclen having the same units as R.

Algorithms

Distance calculations for geodesics degrade slowly with increasing distance and may break down for points that are nearly antipodal, as well as when both points are very close to the Equator. In addition, for calculations on an ellipsoid, there is a small but finite input space, consisting of pairs of locations in which both the points are nearly antipodal and both points fall close to (but not precisely on) the Equator. In this case, a warning is issued and both arclen and az are set to NaN for the “problem pairs.”

Alternatives

Distance between two points can be calculated in two ways. For great circles (on the sphere) and geodesics (on the ellipsoid), the distance is the shortest surface distance between two points. For rhumb lines, the distance is measured along the rhumb line passing through the two points, which is not, in general, the shortest surface distance between them.

When you need to compute both distance and azimuth for the same point pair(s), it is more efficient to do so with a single call to distance. That is, use

[arclen az] = distance(...);

rather than the slower

arclen = distance(...)
az = azimuth(...)

Version History

Introduced before R2006a