LinearUnitConversionFactor

Summary

Returns the factor for converting a distance measurement to a different linear unit.

Discussion

The linear units supported by the function are the same units returned from the geoprocessing Linear Units parameter data type, with the following exceptions:

• Unknown—Only known units can be converted.

• Decimal Degrees—Decimal degrees are measured on a sphere and do not have a consistent conversion factor to the other units.

Learn more about geoprocessing units of measurement

Syntax

LinearUnitConversionFactor(from_unit, to_unit)

Parameter	Explanation	Data Type
from_unit	Specifies the original or source linear unit. Kilometers—Kilometers Meters—Meters Decimeters—Decimeters Millimeters—Millimeters Centimeters—Centimeters NauticalMilesInt—International nautical miles MilesInt—Statute miles YardsInt—International yards FeetInt—International feet InchesInt—International inches NauticalMilesUS—US survey nautical miles MilesUS—US survey miles YardsUS—US survey yards FeetUS—US survey feet InchesUS—US survey inches Points—Points	String
to_unit	Specifies the target or destination linear unit. Kilometers—Kilometers Meters—Meters Decimeters—Decimeters Millimeters—Millimeters Centimeters—Centimeters NauticalMilesInt—International nautical miles MilesInt—Statute miles YardsInt—International yards FeetInt—International feet InchesInt—International inches NauticalMilesUS—US survey nautical miles MilesUS—US survey miles YardsUS—US survey yards FeetUS—US survey feet InchesUS—US survey inches Points—Points	String

Return value

Data Type	Explanation
Double	The conversion factor that will be used to convert values between the two linear units.

Code sample

LinearUnitConversionFactor example 1

A simple use case for converting from international miles to kilometers.

import arcpy

# Convert 620.5 MilesInt to Kilometers
area = 620.5 * arcpy.LinearUnitConversionFactor(from_unit="MilesInt", to_unit="Kilometers")

print(area)  # This will print a value of 998.597952

LinearUnitConversionFactor example 2

Within a script tool, convert a specified value to meters for processing.

import arcpy
import locale
import sys

dist = arcpy.GetParameter(n)  # Update n to the parameter index
dist_value, dist_unit = dist.split(" ")  # For example, "10 Kilometers"

# Convert the distance into "Meters" as needed later in this script
try:
    conv_factor = arcpy.LinearUnitConversionFactor(dist_unit, "Meters")
except ValueError as e:
    # If it fails, the likely distance unit is "Unknown" or "Decimal Degrees".
    # Add code to either deal with it or produce an appropriate error as shown below.
    arcpy.AddError('Invalid linear unit type.')
    sys.exit()

# Apply the conv_factor to the supplied value
# locale.atof is required for locales that don't use a period as the separator
dist_m = locale.atof(dist_value) * conv_factor

Related topics

• ArealUnitConversionFactor