Mapping Toolbox

distdim

Convert distances between different units

Syntax

• distout = distdim(distin,from,to)
  distout = distdim(distin,from,to,radius)
  

Description

distout = distdim(distin,from,to) returns the value of the input distance distin, which is in units specified by the valid distance units string from, in the desired units given by the valid distance units string to. Valid distance units strings are:

• 'kilometers' or 'km' for kilometers
  'meters' or 'm' for meters
  'nauticalmiles' or 'nm' for nautical miles
  'statutemiles' or 'sm' for statute miles
  'feet' or 'ft' for feet
  'degrees' or 'deg' for degrees (arc length)
  'radians' or 'rad' for radians (arc length)
  

distout = distdim(distin,from,to,radius) specifies the radius of a sphere to use when one of from or to is an unit string associated with arc length (radians or degrees). A degree of arc length covers more kilometers, for example, on Jupiter than it would on the Earth. You can enter the radius as a number (the radius of the sphere in the non arc length units), as a call to the almanac function (e.g., almanac('jupiter','radius','units')), again in the appropriate units, or as a string planet name (e.g., 'mars'), and the function will make the appropriate call to the almanac function. The radius of the Earth is the default.

Remarks

Distance is expressed in one of two general forms: as a linear measure in some unit (kilometers, miles, etc.) or as angular arc length (degrees or radians). While the use of linear units is generally understood, angular arc length is not necessarily as clear. The conversion from angular units to linear units for the arc along any circle is the angle in radians multiplied by the radius of the circle. On the sphere, this means that radians of latitude are directly translatable to kilometers, say, by multiplying by the radius of the Earth in kilometers (about 6371 km). However, the linear distance associated with radians of longitude changes with latitude; the radius in question is then not the radius of the Earth, but the (chord) radius of the small circle defining that parallel. In the Mapping Toolbox, the angle in radians or degrees associated with any distance is the arc length of a great circle passing through the points of interest. Therefore, the radius in question always refers to the radius of the relevant sphere, consistent with the distance command.

Examples

Convert 100 kilometers to nautical miles:

• distkm = 100
  distkm =
     100
  distnm = distdim(distkm,'kilometers','nauticalmiles')
  distnm =
     53.9957
  

A degree of arc length is about 60 nautical miles:

• distnm = distdim(1,'deg','nm')
  distnm =
     60.0405
  

This is not accidental. It is the original definition of the nautical mile. Naturally, this assumption does not hold on other planets:

• distnm = distdim(1,'deg','nm','mars')  
  distnm =
     31.9474   
  

See Also

almanac	Planetary data
angledim	Convert angle units
deg2km sm2nm nm2rad	Direct distance conversion functions
dist2str	Convert distances to display strings
distance	Distance between points
timedim	Convert time units

distortcalc

dms2deg, dms2rad