Calculate Travel Cost (Raster Analysis)

Summary

Calculates the least accumulative cost distance from or to the least-cost source, while accounting for surface distance along with horizontal and vertical cost factors.

Legacy:

This tool is deprecated and will be removed in a future release.

The Distance Accumulation or Distance Allocation tools provide enhanced functionality or performance.

Illustration

Usage

• This raster analysis portal tool is available when you are signed in to an ArcGIS Enterprise portal that has ArcGIS Image Server configured for Raster Analysis. When the tool is run, ArcGIS Pro serves as a client and the processing occurs in the servers federated with ArcGIS Enterprise. The portal tool accepts layers from your portal as input and creates output in your portal.

  The input raster layer supports a layer from the portal, a URI or URL to an image service, or the output from the Make Image Server Layer tool. The input feature layer can be a layer from the portal or a URI or URL to a feature service. This tool does not support local raster data or layers. While you can use local feature data and layers as input to this portal tool, best practice is to use layers from your portal as input.

• One example application of this tool is to identify the cheapest route to construct a new road to a proposed school.

• When the input source data is an image service, the set of source cells consists of all cells in the source raster that have valid values. Cells that have NoData values are not included in the source set. The value 0 is considered a legitimate source.

• When the input source data is a feature service, the source locations are converted internally to a raster before performing the analysis. The resolution of the raster can be controlled with the Output cell size parameter or the Cell Size environment. By default, the resolution will be determined by the shorter of the width or height of the extent of input feature, in the input spatial reference, divided by 250.

• Cell locations with NoData in the Input cost raster act as barriers. Any cell location that is assigned NoData on the input cost surface will receive NoData on all output rasters

• For the Output distance image service, the least-cost distance (or minimum accumulative cost distance) of a cell from or to a set of source locations is the lower bound of the least-cost distances from the cell to all source locations.

• The cost raster cannot contain values of zero since the algorithm is a multiplicative process. If your cost raster does contain values of zero, and these values represent areas of lowest cost, change values of zero to a small positive value (such as 0.01) before running Calculate Travel Cost. If areas with a value of zero represent areas that should be excluded from the analysis, these values should be turned to NoData before running Calculate Travel Cost.

• The default values for the Horizontal factor modifiers are the following:

  Keywords       Zero factor   Cut angle     Slope   Side value
  --------------   -----------   -----------   -----   ---------
  Binary           1.0            45           ~       ~
  Forward          0.5            45 (fixed)   ~       1.0
  Linear           0.5           181            1/90   ~
  Inverse linear   2.0           180           -1/90   ~

• The default values for the Vertical factor modifiers are the following:

  Keyword                   Zero    Low    High   Slope  Power  Cos    Sec
                            factor  cut    cut                  power  power
                                    angle  angle                             
  ------------------------  ------  -----  -----  -----  -----  -----  -----
  Binary                    1.0     -30    30     ~      ~      ~      ~
  Linear                    1.0     -90    90      1/90  ~      ~      ~
  Symmetric linear          1.0     -90    90      1/90  ~      ~      ~
  Inverse linear            1.0     -45    45     -1/45  ~      ~      ~
  Symmetric inverse linear  1.0     -45    45     -1/45  ~      ~      ~
  Cos                       ~       -90    90     ~      1.0    ~      ~
  Sec                       ~       -90    90     ~      1.0    ~      ~
  Cos_sec                   ~       -90    90     ~      ~      1.0    1.0
  Sec_cos                   ~       -90    90     ~      ~      1.0    1.0

• The characteristics of the source, or the movers from or to a source, can be controlled by specific parameters. The Source cost multiplier parameter determines the mode of travel or magnitude at the source, Source start cost sets the starting cost before the movement begins, Source resistance rate is a dynamic adjustment accounting for the impact of accumulated cost, for example, simulating how much a hiker is getting fatigued, and Source capacity sets how much cost a source can assimilate before reaching its limit. The Travel direction identifies if the mover is starting at a source and moving to non-source locations, or is starting at non-source locations and moving back to a source.

• If Source start cost is specified and the Travel direction is Travel from source, the source locations on the output cost distance surface will be set to the value of Source start cost; otherwise, the source locations on the output cost distance surface will be set to zero.

• If any of the source characteristics parameters are specified using a field, the source characteristic will be applied on a source-by-source basis, according to the information in the given field for the source data. When a keyword or a constant value is given, it will be applied to all sources.

Parameters

Dialog

Label	Explanation	Data Type
Input Source Raster or Features	The layer that defines the sources to calculate the distance to. The layer can be raster or feature.	Raster Layer; Image Service; Feature Layer; String
Output Distance Name	The name of the output distance raster service. The cost distance image service identifies, for each cell, the least accumulative cost distance over a cost surface to the identified source locations.	String
Input Cost Raster (Optional)	A raster defining the impedance or cost to move planimetrically through each cell. The value at each cell location represents the cost-per-unit distance for moving through the cell. Each cell location value is multiplied by the cell resolution while also compensating for diagonal movement to obtain the total cost of passing through the cell. The values of the cost raster can be integer or floating point, but they cannot be negative or zero (you cannot have a negative or zero cost).	Raster Layer; Image Service; String
Input Surface Raster (Optional)	A raster defining the elevation values at each cell location. The values are used to calculate the actual surface distance covered when passing between cells.	Raster Layer; Image Service; String
Maximum Distance (Optional)	Defines the threshold that the accumulative cost values cannot exceed.	Double
Input Horizontal Raster (Optional)	A raster defining the horizontal direction at each cell. The values on the raster must be integers ranging from 0 to 360, with 0 degrees being north, or toward the top of the screen, and increasing clockwise. Flat areas should be given a value of -1. The values at each location will be used in conjunction with the Horizontal Factor to determine the horizontal cost incurred when moving from a cell to its neighbors.	Raster Layer; Image Service; String
Horizontal Factor (Optional)	The Horizontal Factor defines the relationship between the horizontal cost factor and the horizontal relative moving angle. There are several factors with modifiers from which to select that identify a defined horizontal factor graph. The graphs are used to identify the horizontal factor used in calculating the total cost of moving into a neighboring cell. In the explanations below, two acronyms are used: HF stands for horizontal factor, which defines the horizontal difficulty encountered when moving from one cell to the next; and HRMA stands for horizontal relative moving angle, which identifies the angle between the horizontal direction from a cell and the moving direction. There are several types of horizontal factor available: Binary—Indicates that if the HRMA is less than the cut angle, the HF is set to the value associated with the zero factor; otherwise, it is infinity. Forward—Establishes that only forward movement is allowed. The HRMA must be greater or equal to 0 and less than 90 degrees (0 <= HRMA < 90). If the HRMA is greater than 0 and less than 45 degrees, the HF for the cell is set to the value associated with the zero factor. If the HRMA is greater than or equal to 45 degrees, the side value modifier value is used. The HF for any HRMA equal to or greater than 90 degrees is set to infinity. Linear—Specifies that the HF is a linear function of the HRMA. Inverse Linear—Specifies that the HF is an inverse linear function of the HRMA. The default is Binary. Characteristics for the horizontal keywords: Zero factor—Establishes the horizontal factor to be used when the HRMA is zero. This factor positions the y-intercept for any of the horizontal factor functions. Cut angle—Defines the HRMA angle beyond which the HF will be set to infinity. Slope—Establishes the slope of the straight line used with the Linear and Inverse Linear horizontal factor keywords. The slope is specified as a fraction of rise over run (for example, 45 percent slope is 1/45, which is input as 0.02222). Side value—Establishes the HF when the HRMA is greater than or equal to 45 degrees and less than 90 degrees when the Forward horizontal factor keyword is specified.	Horizontal Factor
Input Vertical Raster (Optional)	A raster defining the vertical (z) value for each cell.	Raster Layer; Image Service; String
Vertical Factor (Optional)	The Vertical Factor defines the relationship between the vertical cost factor and the vertical relative moving angle (VRMA). There are several factors with modifiers from which to select that identify a defined vertical factor graph. The graphs are used to identify the vertical factor used in calculating the total cost for moving into a neighboring cell. In the explanations below, two acronyms are used: VF stands for vertical factor, which defines the vertical difficulty encountered in moving from one cell to the next; and VRMA stands for vertical relative moving angle, which identifies the slope angle between the FROM or processing cell and the TO cell. There are several types of vertical factor available: Binary—Specifies that if the VRMA is greater than the low-cut angle and less than the high-cut angle, the VF is set to the value associated with the zero factor; otherwise, it is infinity. Linear—Indicates that the VF is a linear function of the VRMA. Symmetric Linear—Specifies that the VF is a linear function of the VRMA in either the negative or positive side of the VRMA, respectively, and the two linear functions are symmetrical with respect to the VF (y) axis. Inverse Linear—Indicates that the VF is an inverse linear function of the VRMA. Symmetric Inverse Linear—Specifies that the VF is an inverse linear function of the VRMA in either the negative or positive side of the VRMA, respectively, and the two linear functions are symmetrical with respect to the VF (y) axis. Cos—Identifies the VF as the cosine-based function of the VRMA. Sec—Identifies the VF as the secant-based function of the VRMA. Cos-Sec—Specifies that the VF is the cosine-based function of the VRMA when the VRMA is negative and the secant-based function of the VRMA when the VRMA is nonnegative. Sec-Cos—Specifies that the VF is the secant-based function of the VRMA when the VRMA is negative and the cosine-based function of the VRMA when the VRMA is nonnegative. The default is Binary. Characteristics for the vertical keywords: Zero factor—Establishes the vertical factor used when the VRMA is zero. This factor positions the y-intercept of the specified function. By definition, the zero factor is not applicable to any of the trigonometric vertical functions (COS, SEC, COS-SEC, or SEC-COS). The y-intercept is defined by these functions. Low Cut angle—Defines the VRMA angle below which the VF will be set to infinity. High Cut angle—Defines the VRMA angle above which the VF will be set to infinity. Slope—Establishes the slope of the straight line used with the Linear and Inverse Linear vertical-factor keywords. The slope is specified as a fraction of rise over run (for example, 45 percent slope is 1/45, which is input as 0.02222).	Vertical Factor
Cost Multiplier (Optional)	Multiplier to apply to the cost values. Allows for control of the mode of travel or the magnitude at a source. The greater the multiplier, the greater the cost to move through each cell. The values must be greater than zero. The default is 1.	Double; Field
Start Cost (Optional)	The starting cost from which to begin the cost calculations. Allows for the specification of the fixed cost associated with a source. Instead of starting at a cost of zero, the cost algorithm will begin with the value set by Start Cost. The values must be zero or greater. The default is 0.	Double; Field
Resistance Rate (Optional)	This parameter simulates the increase in the effort to overcome costs as the accumulative cost increases. It is used to model fatigue of the traveler. The growing accumulative cost to reach a cell is multiplied by the resistance rate and added to the cost to move into the subsequent cell. It is a modified version of a compound interest rate formula that is used to calculate the apparent cost of moving through a cell. As the value of the resistance rate increases, it increases the cost of the cells that are visited later. The greater the resistance rate, the more additional cost is added to reach the next cell, which is compounded for each subsequent movement. Since the resistance rate is similar to a compound rate and generally the accumulative cost values are very large, small resistance rates are suggested, such as 0.02, 0.005, or even smaller, depending on the accumulative cost values. The values must be zero or greater. The default is 0.	Double; Field
Capacity (Optional)	Defines the cost capacity for the traveler for a source. The cost calculations continue for each source until the specified capacity is reached. The values must be greater than zero. The default capacity is to the edge of the output raster.	Double; Field
Travel Direction (Optional)	Defines the direction of the traveler when applying horizontal and vertical factors, the source resistance rate, and the source starting cost. Either specify the From source or To source keyword, which will be applied to all sources, or specify a field in the source data that contains the keywords to identify the direction of travel for each source. That field must contain the strings FROM_SOURCE or TO_SOURCE. From source—The horizontal factor, vertical factor, source resistance rate, and source starting cost will be applied beginning at the input source, and moving out to the non-source cells. This is the default. To source—The horizontal factor, vertical factor, source resistance rate, and source starting cost will be applied beginning at each non-source cell and moving back to the input source.	String
Output Backlink Name (Optional)	The name of the output backlink raster service. The backlink raster contains values of 0 through 360, which define the direction along the least accumulative cost path from a cell to reach its least-cost source, while accounting for surface distance as well as horizontal and vertical surface factors.	String
Output Allocation Name (Optional)	The name of the output allocation raster service. This raster identifies the zone of each source location (cell or feature) that could be reached with the least accumulative cost. The output raster is of integer type.	String
Allocation Field (Optional)	A field on the source input that holds the values that define each source.	String

Derived Output

Label	Explanation	Data Type
Output Distance Raster	The output distance raster.	Raster Layer
Output Backlink Raster	The output backlink raster.	Raster Layer
Output Allocation Raster	The output allocation raster.	Raster Layer

Python

arcpy.ra.CalculateTravelCost(inputSourceRasterOrFeatures, outputDistanceName, {inputCostRaster}, {inputSurfaceRaster}, {maximumDistance}, {inputHorizontalRaster}, {horizontalFactor}, {inputVerticalRaster}, {verticalFactor}, {sourceCostMultiplier}, {sourceStartCost}, {sourceResistanceRate}, {sourceCapacity}, {sourceTravelDirection}, {outputBacklinkName}, {outputAllocationName}, {allocationField})

Name	Explanation	Data Type
inputSourceRasterOrFeatures	The layer that defines the sources to calculate the distance to. The layer can be raster or feature.	Raster Layer; Image Service; Feature Layer; String
outputDistanceName	The name of the output distance raster service. The cost distance image service identifies, for each cell, the least accumulative cost distance over a cost surface to the identified source locations.	String
inputCostRaster (Optional)	A raster defining the impedance or cost to move planimetrically through each cell. The value at each cell location represents the cost-per-unit distance for moving through the cell. Each cell location value is multiplied by the cell resolution while also compensating for diagonal movement to obtain the total cost of passing through the cell. The values of the cost raster can be integer or floating point, but they cannot be negative or zero (you cannot have a negative or zero cost).	Raster Layer; Image Service; String
inputSurfaceRaster (Optional)	A raster defining the elevation values at each cell location. The values are used to calculate the actual surface distance covered when passing between cells.	Raster Layer; Image Service; String
maximumDistance (Optional)	Defines the threshold that the accumulative cost values cannot exceed.	Double
inputHorizontalRaster (Optional)	A raster defining the horizontal direction at each cell. The values on the raster must be integers ranging from 0 to 360, with 0 degrees being north, or toward the top of the screen, and increasing clockwise. Flat areas should be given a value of -1. The values at each location will be used in conjunction with the {horizontal_factor} to determine the horizontal cost incurred when moving from a cell to its neighbors.	Raster Layer; Image Service; String
horizontalFactor (Optional)	The Horizontal Factor defines the relationship between the horizontal cost factor and the horizontal relative moving angle. There are several factors with modifiers from which to select that identify a defined horizontal factor graph. The graphs are used to identify the horizontal factor used in calculating the total cost of moving into a neighboring cell. In the explanations below, two acronyms are used: HF stands for horizontal factor, which defines the horizontal difficulty encountered when moving from one cell to the next; and HRMA stands for horizontal relative moving angle, which identifies the angle between the horizontal direction from a cell and the moving direction. There are several types of horizontal factor available: Binary—Indicates that if the HRMA is less than the cut angle, the HF is set to the value associated with the zero factor; otherwise, it is infinity. Forward—Establishes that only forward movement is allowed. The HRMA must be greater or equal to 0 and less than 90 degrees (0 <= HRMA < 90). If the HRMA is greater than 0 and less than 45 degrees, the HF for the cell is set to the value associated with the zero factor. If the HRMA is greater than or equal to 45 degrees, the side value modifier value is used. The HF for any HRMA equal to or greater than 90 degrees is set to infinity. Linear—Specifies that the HF is a linear function of the HRMA. Inverse Linear—Specifies that the HF is an inverse linear function of the HRMA. The default is Binary. Characteristics for the horizontal keywords: Zero factor—Establishes the horizontal factor to be used when the HRMA is zero. This factor positions the y-intercept for any of the horizontal factor functions. Cut angle—Defines the HRMA angle beyond which the HF will be set to infinity. Slope—Establishes the slope of the straight line used with the Linear and Inverse Linear horizontal factor keywords. The slope is specified as a fraction of rise over run (for example, 45 percent slope is 1/45, which is input as 0.02222). Side value—Establishes the HF when the HRMA is greater than or equal to 45 degrees and less than 90 degrees when the Forward horizontal factor keyword is specified.	Horizontal Factor
inputVerticalRaster (Optional)	A raster defining the vertical (z) value for each cell.	Raster Layer; Image Service; String
verticalFactor (Optional)	The Vertical Factor defines the relationship between the vertical cost factor and the vertical relative moving angle (VRMA). There are several factors with modifiers from which to select that identify a defined vertical factor graph. The graphs are used to identify the vertical factor used in calculating the total cost for moving into a neighboring cell. In the explanations below, two acronyms are used: VF stands for vertical factor, which defines the vertical difficulty encountered in moving from one cell to the next; and VRMA stands for vertical relative moving angle, which identifies the slope angle between the FROM or processing cell and the TO cell. There are several types of vertical factor available: Binary—Specifies that if the VRMA is greater than the low-cut angle and less than the high-cut angle, the VF is set to the value associated with the zero factor; otherwise, it is infinity. Linear—Indicates that the VF is a linear function of the VRMA. Symmetric Linear—Specifies that the VF is a linear function of the VRMA in either the negative or positive side of the VRMA, respectively, and the two linear functions are symmetrical with respect to the VF (y) axis. Inverse Linear—Indicates that the VF is an inverse linear function of the VRMA. Symmetric Inverse Linear—Specifies that the VF is an inverse linear function of the VRMA in either the negative or positive side of the VRMA, respectively, and the two linear functions are symmetrical with respect to the VF (y) axis. Cos—Identifies the VF as the cosine-based function of the VRMA. Sec—Identifies the VF as the secant-based function of the VRMA. Cos-Sec—Specifies that the VF is the cosine-based function of the VRMA when the VRMA is negative and the secant-based function of the VRMA when the VRMA is nonnegative. Sec-Cos—Specifies that the VF is the secant-based function of the VRMA when the VRMA is negative and the cosine-based function of the VRMA when the VRMA is nonnegative. The default is Binary. Characteristics for the vertical keywords: Zero factor—Establishes the vertical factor used when the VRMA is zero. This factor positions the y-intercept of the specified function. By definition, the zero factor is not applicable to any of the trigonometric vertical functions (COS, SEC, COS-SEC, or SEC-COS). The y-intercept is defined by these functions. Low Cut angle—Defines the VRMA angle below which the VF will be set to infinity. High Cut angle—Defines the VRMA angle above which the VF will be set to infinity. Slope—Establishes the slope of the straight line used with the Linear and Inverse Linear vertical-factor keywords. The slope is specified as a fraction of rise over run (for example, 45 percent slope is 1/45, which is input as 0.02222).	Vertical Factor
sourceCostMultiplier (Optional)	Multiplier to apply to the cost values. Allows for control of the mode of travel or the magnitude at a source. The greater the multiplier, the greater the cost to move through each cell. The values must be greater than zero. The default is 1.	Double; Field
sourceStartCost (Optional)	The starting cost from which to begin the cost calculations. Allows for the specification of the fixed cost associated with a source. Instead of starting at a cost of zero, the cost algorithm will begin with the value set by sourceStartCost. The values must be zero or greater. The default is 0.	Double; Field
sourceResistanceRate (Optional)	This parameter simulates the increase in the effort to overcome costs as the accumulative cost increases. It is used to model fatigue of the traveler. The growing accumulative cost to reach a cell is multiplied by the resistance rate and added to the cost to move into the subsequent cell. It is a modified version of a compound interest rate formula that is used to calculate the apparent cost of moving through a cell. As the value of the resistance rate increases, it increases the cost of the cells that are visited later. The greater the resistance rate, the more additional cost is added to reach the next cell, which is compounded for each subsequent movement. Since the resistance rate is similar to a compound rate and generally the accumulative cost values are very large, small resistance rates are suggested, such as 0.02, 0.005, or even smaller, depending on the accumulative cost values. The values must be zero or greater. The default is 0.	Double; Field
sourceCapacity (Optional)	Defines the cost capacity for the traveler for a source. The cost calculations continue for each source until the specified capacity is reached. The values must be greater than zero. The default capacity is to the edge of the output raster.	Double; Field
sourceTravelDirection (Optional)	Defines the direction of the traveler when applying horizontal and vertical factors, the source resistance rate, and the source starting cost. FROM_SOURCE—The horizontal factor, vertical factor, source resistance rate, and source starting cost will be applied beginning at the input source, and moving out to the non-source cells. This is the default. TO_SOURCE—The horizontal factor, vertical factor, source resistance rate, and source starting cost will be applied beginning at each non-source cell and moving back to the input source. Either specify the FROM_SOURCE or TO_SOURCE keyword, which will be applied to all sources, or specify a field in the source data that contains the keywords to identify the direction of travel for each source. That field must contain the strings FROM_SOURCE or TO_SOURCE.	String
outputBacklinkName (Optional)	The name of the output backlink raster service. The backlink raster contains values of 0 through 360, which define the direction along the least accumulative cost path from a cell to reach its least-cost source, while accounting for surface distance as well as horizontal and vertical surface factors.	String
outputAllocationName (Optional)	The name of the output allocation raster service. This raster identifies the zone of each source location (cell or feature) that could be reached with the least accumulative cost. The output raster is of integer type.	String
allocationField (Optional)	A field on the source input that holds the values that define each source.	String

Derived Output

Name	Explanation	Data Type
outputDistanceRaster	The output distance raster.	Raster Layer
outputBacklinkRaster	The output backlink raster.	Raster Layer
outputAllocationRaster	The output allocation raster.	Raster Layer

Code sample

CalculateTravelCost example 1 (Python window)

This example calculates the travel cost from a single source.

import arcpy
arcpy.ra.CalculateTravelCost('https://MyPortal.esri.com/server/rest/services/Hosted/reccenter/ImageServer',
                             "outDist", "inCostRas", "inSurfaceRas", "200000")

CalculateTravelCost example 2 (stand-alone script)

This example calculates the travel cost from a set of sources.

# Name: CalculateTravelCost_Ex_02.py
# Description: Calculates for each cell the least accumulative cost distance
#    to the nearest source over a cost  surface. 
# Requirements: ArcGIS Image Server

# Import system modules
import arcpy

# Set local variables
inSource = 'https://MyPortal.esri.com/server/rest/services/Hosted/landuse/ImageServer'
outDistName = 
inCostRast = "costraster"
inElev = "elevation"
maxDist = "50000"

inHoriz = "backlink2"
horizFactor = "FORWARD 0.5 1.0"
inVertical = "focalcost.tif"
verticalFactor = "Binary 1.0 -30 30"

sourceCostMultiplier =
sourceStartCost =
sourceResistanceRate =
sourceCapacity = 
sourceTravelDirection =

optBacklinkName = "c:/sapyexamples/output/pathbacklink"
optAlloName =
allocField = 

# Execute CalculateTravelCost
arcpy.ra.CalculateTravelCost(inSource, outDistName, inCostRast, inElev, maxDist, inHoriz, horizFactor,
                           inVertical, verticalFactor, sourceCostMultiplier, sourceStartCost,
                           sourceResistanceRate, sourceCapacity, sourceTravelDirection, optBacklinkName,
                           optAlloName, allocField)

# Execute CostDistance
outTravelCost = CalculateTravelCost(inSourceData, inCostRaster, maxDistance, outBkLinkRaster)

Environments

Cell Size, Extent, Mask, Output Coordinate System, Pyramid, Snap Raster

Licensing information

• Basic: Requires ArcGIS Image Server
• Standard: Requires ArcGIS Image Server
• Advanced: Requires ArcGIS Image Server