Mapping Toolbox™

distance - Distance between points on sphere or ellipsoid

Syntax

[dist,az] = distance(lat1,lon1,lat2,lon2) [dist,az] = distance(lat1,lon1,lat2,lon2,ellipsoid) [dist,az] = distance(lat1,lon1,lat2,lon2,units) [dist,az] = distance(lat1,lon1,lat2,lon2,ellipsoid,units) [dist,az] = distance(pt1,pt2) [dist,az] = distance(pt1,pt2,ellipsoid) [dist,az] = distance(pt1,pt2,units) [dist,az] = distance(pt1,pt2,ellipsoid,units) [dist,az] = distance(track,...) dist = distance(...)

Description

[dist,az] = distance(lat1,lon1,lat2,lon2) computes the great circle distance(s) between pairs of points on the surface of a sphere. The input latitudes and longitudes, lat1, lon1, lat2, and lon2 are in degrees and can be scalars or arrays of equal size. The distance dist is expressed in degrees of arc length and will have the same size as the input arrays. az is the azimuth clockwise from north and in the specified angular units, from the first point to the second point. The value in az is identical to that obtained by calling azimuth(...). When given a combination of scalar and array inputs, the scalar inputs are automatically expanded to match the size of the arrays.

[dist,az] = distance(lat1,lon1,lat2,lon2,ellipsoid) specifies the ellipsoidal shape of the Earth to be used with the two-element ellipsoid vector and computes the geodesic distance. The ellipsoid vector is of the form [semimajor_axis, eccentricity]. The resulting distance and azimuth are expressed in the same units as the semimajor axis of the ellipsoid vector. The default ellipsoid is a unit sphere, which is sufficient for most applications. Use the almanac function to obtain an ellipsoid vector for ellipsoids by name.

[dist,az] = distance(lat1,lon1,lat2,lon2,units) uses the string units to define the angle units of the input latitudes and longitudes and the outputs dist and az. units may equal 'degrees' (the default value) or 'radians'.

[dist,az] = distance(lat1,lon1,lat2,lon2,ellipsoid,units) uses the units string to specify the units of the latitude-longitude coordinates, but the output range has the same units as the semimajor axis of the ellipsoid vector.

[dist,az] = distance(pt1,pt2) calculates the great circle distance and azimuth from pt1 to pt2. These two-column matrices should be of the form [latitude longitude] in degrees. The resulting distance is returned in terms of degrees of arc length.

[dist,az] = distance(pt1,pt2,ellipsoid) calculates the great circle distance and azimuth from pt1 to pt2 on an ellipsoid specified with an ellipsoid vector.

[dist,az] = distance(pt1,pt2,units) specifies the angle units of pt1 and pt2. The default value is 'degrees'. These units are also the distance units of the result (e.g., degrees of arc length) unless a ellipsoid vector is specified.

[dist,az] = distance(pt1,pt2,ellipsoid,units) is also a valid syntax.

[dist,az] = distance(track,...) specifies whether great circle distances or rhumb line distances are desired. Great circle distances, the default, are indicated with the standard track string 'gc'. Rhumb line distances are indicated with the standard track string 'rh'.

dist = distance(...) returns only the distance dist.

Remarks

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. For more information on this distinction, see Great Circles, Rhumb Lines, and Small Circles in the Mapping Toolbox User's Guide.

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

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

rather than the slower

dist = distance(...)
az = azimuth(...)

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

Distance along Long Geodesics

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 dist and az are set to NaN for the "problem pairs."

Examples

Imagine a trip 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 string selected. Using the pt1,pt2 notation, the two cases result in

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

dist =
   52.3094

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

dist =
    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 trade-off 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,

dist = distance(37,-76,67,-76) % great circle distance

dist =
     30.0000

dist = distance('rh',37,-76,67,-76) % rhumb line distance

dist =
     30.0000