### Arc Lengths of Angles Not Constant

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'

*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')

to see that the difference between a statute mile
and an international mile is just over three millimeters. This may
seem like a very small amount over the length of a single mile, but
mixing up these units could result in a significant error over a sufficiently
long baseline. Originally, the behavior of `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
strings for each of these units; see the `unitsratio` help
for further information.)

### Replacing distdim

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)

with

unitsratio(TO, FROM) * dist

If
you are using units of feet or miles, see the cautionary note above
about how they are interpreted. For example, with `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, replace

dist1_meters = distdim(dist1_nm, 'nm', 'meters');
dist2_meters = distdim(dist2_nm, 'nm', 'meters');

with

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 replace

distdim(dist, 'degrees', 'meters', 'mars')

with

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