Note: This page has been translated by MathWorks. Please click here

To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

Convert length units

`distOut = distdim(distIn,`

* from*,

`to`

distOut = distdim(distIn,

`from`

`to`

distOut = distdim(distIn,

`from`

`to`

`sphere`

`distdim`

has been replaced by `unitsratio`

,
but will be maintained for backward compatibility. See Replacing distdim for details.

`distOut = distdim(distIn,`

converts * from*,

`to`

`distIn`

from
the units specified by `from`

`to`

`from`

`to`

`'meters'` or `'m'` | |

`'feet'` or `'ft'` | U.S. survey feet |

`'kilometers'` or `'km'` | |

`'nauticalmiles'` or `'nm'` | |

`'miles'` , `'statutemiles'` , `'mi'` ,
or `'sm'` | Statute miles |

`'degrees'` or `'deg'` | |

`'radians'` or `'rad'` |

If either * from* or

`to`

`'degrees'`

or `'radians'`

),
the conversion to or from linear distance is made along a great circle
arc on a sphere with a radius of 6371 km, the mean radius of the Earth.`distOut = distdim(distIn,`

specifies
the radius when one of the units, either * from*,

`to`

`from`

`to`

`distdim`

uses a great circle
arc on a sphere of the given radius. The specified length units must
apply to `radius`

as well as to the input distance
(when `from`

`to`

`from`

`to`

`radius`

is
ignored.`distOut = distdim(distIn,`

,
where either * from*,

`to`

`sphere`

`from`

`to`

`sphere`

`'sun'`

, `'moon'`

, `'mercury'`

, `'venus'`

, `'earth'`

, `'mars'`

, `'jupiter'`

, `'saturn'`

, `'uranus'`

, `'neptune'`

,
or `'pluto'`

, and is case-insensitive. If neither `to`

`from`

`sphere`

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

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 always 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
6,371 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. 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`

function.

*Exercise caution with 'feet' and 'miles'.* `distdim`

interprets `'feet'`

and `'ft'`

as
U.S. survey feet, and does not support international feet at all.
In contrast, `unitsratio`

follows the opposite,
and more standard approach, interpreting both `'feet'`

and `'ft'`

as
international feet. `unitsratio`

provides separate
options, including `'surveyfeet'`

and `'sf'`

,
to indicate survey feet. By definition, one international foot is
exactly 0.3048 meters and one U.S. survey foot is exactly 1200/3937
meters. For many applications, the difference is significant. Most
projected coordinate systems use either the meter or the survey foot
as a standard unit. International feet are less likely to be used,
but do occur sometimes. Likewise, `distdim`

interprets `'miles'`

and `'mi'`

as
statute miles (also known as U.S. survey miles), and does not support
international miles at all. By definition, one international mile
is 5,280 international feet and one statute mile is 5,280 survey feet.
You can evaluate:

unitsratio('millimeter','statute mile') - ... unitsratio('millimeter','mile')

`distdim`

with
respect to `'miles'`

and `'mi'`

was
documented only indirectly, via the now-obsolete `unitstr`

function.
As with feet, `unitsratio`

takes a more standard
approach. `unitsratio`

interprets `'miles'`

and `'mi'`

as
international miles, and `'statute miles'`

and `'sm'`

as
statute miles. (`unitsratio`

accepts several other
character vectors for each of these units; see the `unitsratio`

help
for further information.) If both * from* and

`to`

`distdim`

with
a direct conversion utility, as in the following examples:` distdim(dist,'nm',km')` | ⇒ `nm2km(dist)` |

` distdim(dist,'sm','deg') ` | ⇒ ` sm2deg(dist)` |

`distdim(dist, 'rad', 'km', 'moon')` | ⇒
`rad2km(dist,'moon') ` |

If there is no appropriate direct conversion utility, or you
won't know the values of * from* and/or

`to`

distdim(dist, FROM, TO)

unitsratio(TO, FROM) * dist

`distIn`

in
meters and `distOut`

in survey feet, ```
distOut
= distdim(distIn, 'meters', 'feet')
```

should be replaced with ```
distOut
= unitsratio('survey feet','meters') * distIn
```

. Saving a
multiplicative factor computed with `unitsratio`

and
using it to convert in a separate step can make code cleaner and more
efficient than using `distdim`

. For example, replacedist1_meters = distdim(dist1_nm, 'nm', 'meters'); dist2_meters = distdim(dist2_nm, 'nm', 'meters');

metersPerNM = unitsratio('meters','nm'); dist1_meters = metersPerNM * dist1_nm; dist2_meters = metersPerNM * dist2_nm;

`unitsratio`

does
not perform great-circle conversion between units of length and angle,
but it can be easily combined with other functions to do so. For example,
to convert degrees to meters along a great-circle arc on a sphere
approximating the planet Mars, you could replacedistdim(dist, 'degrees', 'meters', 'mars')

unitsratio('meters','km') * deg2km(dist, 'mars')

`deg2km`

| `deg2nm`

| `deg2sm`

| `km2deg`

| `km2nm`

| `km2rad`

| `km2sm`

| `nm2deg`

| `nm2km`

| `nm2rad`

| `nm2sm`

| `rad2km`

| `rad2nm`

| `rad2sm`

| `sm2deg`

| `sm2km`

| `sm2nm`

| `sm2rad`

| `unitsratio`

Was this topic helpful?