Convert length units
distOut = distdim(distIn,
from
,to
)
distOut = distdim(distIn,from
,to
,radius)
distOut = distdim(distIn,from
,to
,sphere
)
Note:

distOut = distdim(distIn,
converts from
,to
)distIn
from
the units specified by from
to the units
specified by to
. from
and to
are
caseinsensitive, and may equal any of the following:
'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
indicates
angular units ('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
,radius)from
or to
,
indicates angular units. 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
indicates length) or output
distance (when to
indicates length). If
neither from
nor to
indicates
angular units, or if both do, then the value of radius
is
ignored.
distOut = distdim(distIn,
,
where either from
,to
,sphere
)from
or to
indicates
angular units, uses a great circle arc on a sphere approximating a
body in the Solar System. sphere
may be
one of the following: 'sun'
, 'moon'
, 'mercury'
, 'venus'
, 'earth'
, 'mars'
, 'jupiter'
, 'saturn'
, 'uranus'
, 'neptune'
,
or 'pluto'
, and is caseinsensitive. If neither to
nor from
is
angular, sphere
is ignored.
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 nowobsolete 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
are
known at the time of coding, then you may be able to replace 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
until
run time, you can generally replace
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 greatcircle 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 greatcircle 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