# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

# distdim

Convert length units

## Syntax

```distOut = distdim(distIn,from,to) distOut = distdim(distIn,from,to,radius) distOut = distdim(distIn,from,to,sphere) ```

### Note

`distdim` has been replaced by `unitsratio`, but will be maintained for backward compatibility. See Replacing distdim for details.

## Description

`distOut = distdim(distIn,from,to)` converts `distIn` from the units specified by `from` to the units specified by `to`. `from` and `to` are case-insensitive, 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,from,to,radius)` specifies the radius when one of the units, either `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,from,to,sphere)`, where either `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 case-insensitive. If neither `to` nor `from` is angular, `sphere` is ignored.

## 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 ```

## Tips

### 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 character vectors 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') ```