distdim

(Not recommended) Convert length units

The distdim function is not recommended. Use a different conversion function or the unitsratio function instead. For more information, see Version History.

Syntax

distOut = distdim(distIn,originalUnit,targetUnit)

distOut = distdim(distIn,originalUnit,targetUnit,r)

distOut = distdim(distIn,originalUnit,targetUnit,refSphere)

Description

distOut = distdim(distIn,originalUnit,targetUnit) converts the distance distIn from the units specified by originalUnit to the units specified by targetUnit. This function assumes that distIn is along a great circle path on a reference sphere. If originalUnit or targetUnit is an angular unit, then this syntax uses a reference sphere with a radius of 6371 kilometers.

distOut = distdim(distIn,originalUnit,targetUnit,r) when either originalUnit or targetUnit is a length unit, and the other is an angular unit, converts the distance using a reference sphere with radius r. The function ignores r when originalUnit and targetUnit are both angular units or both length units.

distOut = distdim(distIn,originalUnit,targetUnit,refSphere) when either originalUnit or targetUnit is a length unit, and the other is an angular unit, converts the distance using the reference sphere refSphere. The function ignores refSphere when originalUnit and targetUnit are both angular units or both length units.

Examples

Convert Kilometers to Nautical Miles

Convert 100 kilometers to nautical miles.

distIn = 100;
distdim(distIn,"km","nm")

ans =

   53.9957

Calculate the same conversion using the unitsratio function.

distIn * unitsratio("nm","km")

ans =

   53.9957

Calculate the same conversion using the km2nm function.

km2nm(distIn)

ans =

   53.9957

Input Arguments

distIn — Distance in original units

numeric array

Distance in original units, specified as a numeric array.

originalUnit — Original unit of measure

"kilometers" | "km" | "degrees" | "deg" | ...

Original unit of measure, specified as one of these options:

• These angular units.

  Value	Unit Name
  "degrees", "deg"	Degrees
  "radians", "rad"	Radians

• These length units.

  Value	Unit Name
  "km", "kilometers"	Kilometers
  "m", "meters"	Meters
  "nm", "nauticalmiles"	Nautical miles
  "ft", "feet"	U.S. survey feet
  "mi", "sm", "miles", "statutemiles"	Statute miles

This argument is case insensitive.

Data Types: char | string

targetUnit — Target unit of measure

"kilometers" | "km" | "degrees" | "deg" | ...

Target unit of measure, specified as one of these options:

• These angular units.

  Value	Unit Name
  "degrees", "deg"	Degrees
  "radians", "rad"	Radians

• These length units.

  Value	Unit Name
  "km", "kilometers"	Kilometers
  "m", "meters"	Meters
  "nm", "nauticalmiles"	Nautical miles
  "ft", "feet"	U.S. survey feet
  "mi", "sm", "miles", "statutemiles"	Statute miles

This argument is case insensitive.

Data Types: char | string

r — Radius of reference sphere

numeric scalar

Radius of the reference sphere, specified as a numeric scalar. Specify r using the length unit indicated by originalUnit or targetUnit.

refSphere — Reference sphere

"earth" (default) | "sun" | "moon" | "mercury" | "venus" | ...

Reference sphere, specified as "earth", "sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn", "uranus", "neptune", or "pluto".

This argument is case insensitive.

Data Types: char | string

Output Arguments

distOut — Distance in target units

numeric array

Distance in target units, returned as a numeric array of the same size as distIn.

Version History

Introduced before R2006a

R2007b: distdim is not recommended

The distdim function is not recommended. The replacement functionality depends on whether you know the original and target units before run time.

If you know the units before run time, then you can replace the distdim function with a conversion function. This table shows the supported conversion functions.

Original Unit	Conversion Functions
Degrees	deg2km — Convert degrees to kilometers deg2nm — Convert degrees to nautical miles deg2sm — Convert degrees to statute miles deg2rad — Convert degrees to radians
Radians	rad2km — Convert radians to kilometers rad2nm — Convert radians to nautical miles rad2sm — Convert radians to statute miles rad2deg — Convert radians to degrees
Kilometers	km2nm — Convert kilometers to nautical miles km2sm — Convert kilometers to statute miles km2deg — Convert kilometers to degrees km2rad — Convert kilometers to radians
Meters	None
Nautical miles	nm2km — Convert nautical miles to kilometers nm2sm — Convert nautical miles to statute miles nm2deg — Convert nautical miles to degrees nm2rad — Convert nautical miles to radians
U.S. survey feet	None
Statute miles	sm2km — Convert statute miles to kilometers sm2nm — Convert statute miles to nautical miles sm2deg — Convert statute miles to degrees sm2rad — Convert statute miles to radians

This table shows typical replacement patterns to use when updating your code to use a conversion function.

Not Recommended	Recommended
distdim(distIn,"deg","rad")	deg2rad(distIn)
distdim(distIn,"km","deg",r)	km2deg(distIn,r)
distdim(distIn,"deg","nm",refSphere)	deg2nm(distIn,refSphere)

If you do not know the units before run time, or if a conversion function does not exist, then you can replace the distdim function with the unitsratio function. To convert between a length unit and an angle unit, use both the unitsratio function and a conversion function. This table shows typical replacement patterns to use when updating your code.

Not Recommended	Recommended
distdim(distIn,originalUnit,targetUnit)	distIn * unitsratio(targetUnit,originalUnit)
distdim(distIn,"deg","m")	unitsratio("m","km") * deg2km(distIn)
distdim(distIn,"deg","m","mars")	unitsratio("m","km") * deg2km(distIn,"mars")

To indicate U.S. survey feet using the unitsratio function, specify "surveyfeet" or "sf" instead of "feet" or "ft". To indicate statute miles using the unitsratio function, specify "statute miles" or "sm" instead of "miles" or "mi".