Main Content

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 Compatibility Considerations.

    Description

    example

    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

    collapse all

    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

    collapse all

    Distance in original units, specified as a numeric array.

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

    • These angular units.

      ValueUnit Name
      "degrees", "deg"Degrees
      "radians", "rad"Radians
    • These length units.

      ValueUnit 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

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

    • These angular units.

      ValueUnit Name
      "degrees", "deg"Degrees
      "radians", "rad"Radians
    • These length units.

      ValueUnit 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

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

    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

    collapse all

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

    Version History

    Introduced before R2006a

    collapse all

    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 UnitConversion 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

    MetersNone
    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 feetNone
    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 RecommendedRecommended
    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 RecommendedRecommended
    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".