distance

Distance between points on sphere or ellipsoid

Syntax

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

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

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

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

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

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

Description

[arclen,az] = distance(lat1,lon1,lat2,lon2) calculates the arc length arclen and azimuth az of the great circle arc from the starting point with coordinates lat1 and lon1 to the ending point with coordinates lat2 and lon2. The function uses the shorter (minor) great circle arc. This syntax references the coordinates to a sphere and returns arclen and az as spherical distances in degrees.

[arclen,az] = distance(pt1,pt2) calculates the arc length and azimuth from the starting point with coordinates pt1 and ending point with coordinates pt2.

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

[arclen,az] = distance(lat1,lon1,lat2,lon2,ellipsoid) specifies a reference ellipsoid for the coordinates. This syntax returns arclen in the units of the semimajor axis of the reference ellipsoid.

[arclen,az] = distance(pt1,pt2,ellipsoid) specifies a reference ellipsoid for the coordinates. This syntax returns arclen in the units of the semimajor axis of the reference ellipsoid.

[arclen,az] = distance(___,units) specifies the angle units for the coordinates and azimuth, in addition to any combination of input arguments from the previous syntaxes.

[arclen,az] = distance(method,___), where method is "rh", calculates the arc length and azimuth using a rhumb line. The default for method is "gc", which calculates the arc length and azimuth using a great circle arc (for a sphere) or a geodesic arc (for an ellipsoid).

Examples

Calculate Spherical Distance Between Two Points

Find the spherical distance between New York City and Paris. By default, the distance function calculates the great circle distance and returns the result as a spherical distance in degrees.

arclen1 = distance(40.71,-74.01,48.86,2.35)

arclen1 = 
52.4971

Find the rhumb line distance between the same two points.

arclen2 = distance("rh",40.71,-74.01,48.86,2.35)

arclen2 = 
54.6718

Calculate Linear Distance Between Two Points

You can return the arc length as a linear distance by specifying a reference ellipsoid as input to the distance function.

Create a World Geodetic System of 1984 (WGS84) reference ellipsoid with a length unit of meters.

wgs84 = wgs84Ellipsoid("m");

Find the linear distance between New York City and Paris. When you specify a reference ellipsoid as input to the distance function, the function returns linear distances in the units of the semimajor axis of the ellipsoid.

d = distance(40.71,-74.01,48.86,2.35,wgs84)

d = 
5.8531e+06

Input Arguments

lat1 — Latitude of start point

scalar | array

Latitude of the start point, specified as a scalar or array.

You can specify lat1, lon1, lat2, and lon2 using a combination of scalars and arrays, as long as the arrays are of the same size. The function expands the scalar inputs to match the size of the array inputs.

Data Types: single | double

lon1 — Longitude of start point

scalar | array

Longitude of the start point, specified as a scalar or array.

You can specify lat1, lon1, lat2, and lon2 using a combination of scalars and arrays, as long as the arrays are of the same size. The function expands the scalar inputs to match the size of the array inputs.

Data Types: single | double

lat2 — Latitude of end point

scalar | array

Latitude of the end point, specified as a scalar or array.

You can specify lat1, lon1, lat2, and lon2 using a combination of scalars and arrays, as long as the arrays are of the same size. The function expands the scalar inputs to match the size of the array inputs.

Data Types: single | double

lon2 — Longitude of end point

scalar | array

Longitude of the end point, specified as a scalar or array.

You can specify lat1, lon1, lat2, and lon2 using a combination of scalars and arrays, as long as the arrays are of the same size. The function expands the scalar inputs to match the size of the array inputs.

Data Types: single | double

pt1 — Latitude and longitude of start point

N-by-2 matrix

Latitude and longitude of the start point, specified as an N-by-2 numeric matrix of the form [lat1 lon1], where lat1 and lon1 are column vectors.

Data Types: single | double

pt2 — Latitude and longitude of the end point

N-by-2 matrix

Latitude and longitude of the end point, specified as an N-by-2 numeric matrix of the form [lat2 lon2], where lat2 and lon2 are column vectors.

Data Types: single | double

ellipsoid — Reference ellipsoid

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

Reference ellipsoid, specified as a referenceSphere object, a referenceEllipsoid object, an oblateSpheroid object, or a two-element vector of the form [semimajor_axis eccentricity], where semimajor_axis is the length of the semimajor axis and eccentricity is the eccentricity. The values semimajor_axis and eccentricity must be of data type double.

units — Angle unit

"degrees" (default) | "radians"

Angle unit, specified as one of these options:

• "degrees" — Degrees

• "radians" — Radians

Data Types: char | string

method — Type of curve connecting start point and end point

"gc" (default) | "rh"

Type of curve connecting the start point and end point, specified as one of these options:

• "gc" — For spheres, calculate the arc length and azimuth using the great circle arc that connects the points. For ellipsoids, calculate the arc length and azimuth using the geodesic that connects the points.

• "rh" — Calculate the arc length and azimuth using the rhumb line that connects the points.

For more information about rhumb lines and great circles, see Comparison of Rhumb Lines and Great Circles.

Data Types: char | string

Output Arguments

arclen — Arc length

scalar | array

Arc length, returned as a scalar or array.

• When you specify the coordinates using lat1, lon1, lat2, and lon2, the size of this argument matches the size of the largest latitude or longitude input.

• When you specify the coordinates using pt1 and pt2, this argument is a vector with length N.

The units of arclen depend on whether you specify a reference ellipsoid as input.

• When you do not specify a reference ellipsoid as input, arclen is a spherical distance in degrees. You can return a spherical distance in radians by using the units input argument.

• When you specify a reference ellipsoid as input, arclen is a linear distance in the units of the semimajor axis of the ellipsoid.

Data Types: double

az — Azimuth

scalar | array

Azimuth of the second point in each pair with respect to the first, returned as a scalar or array. The azimuth is the angle at which the arc crosses the meridian containing the first point. Azimuths are measured clockwise from north.

• When you specify the coordinates using lat1, lon1, lat2, and lon2, the size of this argument matches the size of the largest latitude or longitude input.

• When you specify the coordinates using pt1 and pt2, this argument is a vector with length N.

This table shows the azimuths associated with cardinal and intercardinal compass directions.

Compass Direction	Azimuth
North	0° or 360°
Northeast	45°
East	90°
Southeast	135°
South	180°
Southwest	225°
West	270°
Northwest	315°

Data Types: single | double

Tips

You can convert spherical distances to linear distances by using conversion functions such as deg2km and deg2nm.

Algorithms

The accuracy of geodesic azimuth calculations decreases as the distance between the points increases. Additionally, the calculations can break down when the points are nearly antipodal or close to the equator.

When you specify a reference ellipsoid and two points that are both close to the equator and nearly antipodal, the distance function issues a warning and returns both arclen and az as values of NaN.

Version History

Introduced before R2006a