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.
Illustration
Usage
This raster analysis portal tool is available when you are signed in to an ArcGIS Enterprise
portal that has an ArcGIS Image Server configured for Raster Analysis . When the tool is invoked, 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.0The 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.
Syntax
arcpy.ra.CalculateTravelCost(inputSourceRasterOrFeatures, outputDistanceName, {inputCostRaster}, {inputSurfaceRaster}, {maximumDistance}, {inputHorizontalRaster}, {horizontalFactor}, {inputVerticalRaster}, {verticalFactor}, {sourceCostMultiplier}, {sourceStartCost}, {sourceResistanceRate}, {sourceCapacity}, {sourceTravelDirection}, {outputBacklinkName}, {outputAllocationName}, {allocationField})| Parameter | 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:
The default is Binary. Characteristics for the horizontal keywords:
| 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:
The default is Binary. Characteristics for the vertical keywords:
| 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.
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
This example calculates the travel cost from a single source.
import arcpy
arcpy.CalculateTravelCost_ra('https://MyPortal.esri.com/server/rest/services/Hosted/reccenter/ImageServer',
"outDist", "inCostRas", "inSurfaceRas", "200000")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.CalculateTravelCost_ra(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
Licensing information
- Basic: Requires ArcGIS Image Server
- Standard: Requires ArcGIS Image Server
- Advanced: Requires ArcGIS Image Server