Convert length units
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.
distOut = distdim(distIn,from,to) converts distIn from the units specified by the string from to the units specified by the string 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), where one of the unit strings, either from or to, indicates angular units and the other unit string indicates length units, 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 strings: '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.
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')
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.)
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, '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
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');
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')
unitsratio('meters','km') * deg2km(dist, 'mars')