Cost Distance (Spatial Analyst)

Available with Spatial Analyst license.

Summary

Calculates the least accumulative cost distance for each cell from or to the least-cost source over a cost surface.

Legacy:

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

The Distance Accumulation tool provides enhanced functionality or performance.

Learn more about how Cost distance tools work

Illustration

Cost_Dist = CostDistance(Source_Ras, Cost_Ras)

Usage

• The input source data can be a feature class or a raster. The feature class can be point, line or polygon.

• When the input source data is a raster, 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. Zero is a valid value. A source raster can be created using the extraction tools.

• When the input source data is a feature class, the source locations are converted internally to a raster before performing the analysis. The resolution of the raster can be controlled with the Cell Size environment. By default, the resolution will be set to the resolution of the input cost raster.

• When using feature data for the input source data, care must be taken with how the output cell size is handled when it is coarse, relative to the detail present in the input. The internal rasterization process uses the same default Cell assignment type value as the Feature to Raster tool, which is the cell center method. This means that data that is not located at the center of the cell will not be included in the intermediate rasterized source output, so it will not be represented in the distance calculations. For example, if the sources are a series of small polygons (such as building footprints) that are small relative to the output cell size, it is possible that only a few will fall under the centers of the output raster cells, seemingly causing most of the others to be lost in the analysis.

  To avoid this situation, as an intermediate step, you can rasterize the input features directly with the Feature to Raster tool and set the Field parameter. Then use the resulting output as input to the particular distance tool you want to use. Alternatively, you can select a small cell size to capture the appropriate amount of detail from the input features.

• When the source input is a feature, the first valid available field will be used by default. If no valid fields exist, the ObjectID field (for example, OID or FID, depending on the type of feature input) will be used.

• Cell locations with NoData in the Input Cost Raster parameter value act as barriers in the cost surface tools. Any cell location that is assigned NoData on the input cost surface will receive NoData on all output rasters (cost distance, allocation, and backlink).

• The Maximum Distance parameter value is specified in the same cost units as those on the cost raster.

• For the output distance raster, 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 Cost Distance, by first running the Con tool. 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 Cost Distance, by first running the Set Null tool.

• The characteristics of the source, or the movers from or to a source, can be controlled by specific parameters. The Source cost multiplier parameter specifies 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. Travel direction identifies whether the mover is starting at a source and moving to nonsource locations or starting at nonsource locations and moving back to a source.

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

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

• The default processing extent for this tool is the extent of the Input Cost Raster parameter value.

• This tool supports parallel processing. If your computer has multiple processors or processors with multiple cores, better performance may be achieved, particularly on larger datasets. See the Parallel processing with Spatial Analyst help topic for details on this capability and how to configure it.

  When using parallel processing, temporary data will be written to manage the data chunks being processed. The default temp folder location will be on your local C: drive. You can control the location of this folder by setting up a system environment variable named TempFolders and specifying the path to a folder to use (for example, E:\RasterCache). If you have administrative privileges on your machine, you can also use a registry key (for example, [HKEY_CURRENT_USER\SOFTWARE\ESRI\ArcGISPro\Raster]).

  By default, this tool will use 50 percent of the available cores. If the input data is smaller than 5,000 by 5,000 cells in size, fewer cores may be used. You can control the number of cores the tool uses with the Parallel processing factor environment.

• When the output raster format is .crf, this tool supports the Pyramid raster storage environment. Pyramids will be created in the output by default. For any other output format, this environment is not supported, and pyramids will not be created.

• See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.

Parameters

Dialog

Label	Explanation	Data Type
Input raster or feature source data	The input source locations. This is a raster or feature (point, line, or polygon) identifying the cells or locations that will be used to calculate the least accumulated cost distance for each output cell location. For rasters, the input type can be integer or floating point.	Raster Layer; Feature Layer
Input cost raster	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
Maximum distance (Optional)	The threshold that the accumulative cost values cannot exceed. If an accumulative cost distance value exceeds this value, the output value for the cell location will be NoData. The maximum distance is the extent for which the accumulative cost distances are calculated. The default distance is to the edge of the output raster.	Double
Output backlink raster (Optional)	The output cost backlink raster. The backlink raster contains values 0 through 8, which define the direction or identify the next neighboring cell (the succeeding cell) along the least accumulative cost path from a cell to reach its least-cost source. If the path is to pass into the right neighbor, the cell will be assigned the value 1, 2 for the lower right diagonal cell, and continue clockwise. The value 0 is reserved for source cells.	Raster Dataset
Multiplier to apply to costs (Optional)	The multiplier that will be applied to the cost values. This 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 that will be used 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 this value. The values must be zero or greater. The default is 0.	Double; Field
Accumulative cost 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)	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)	Specifies the direction of the traveler when applying the source resistance rate and the source starting cost. If you select the String option, you can choose between from and to options, which will be applied to all sources. If you select the Field option, you can select the field from the source data that determines the direction to use for each source. The field must contain the text string FROM_SOURCE or TO_SOURCE. Travel from source—The source resistance rate and source starting cost will be applied beginning at the input source and travel out to the nonsource cells. This is the default. Travel to source—The source resistance rate and source starting cost will be applied beginning at each nonsource cell and travel back to the input source.	String; Field

Return Value

Label	Explanation	Data Type
Output distance raster	The output cost distance raster. The cost distance raster identifies, for each cell, the least accumulative cost distance over a cost surface to the identified source locations. A source can be a cell, a set of cells, or one or more feature locations. The output raster is of floating-point type.	Raster

Python

CostDistance(in_source_data, in_cost_raster, {maximum_distance}, {out_backlink_raster}, {source_cost_multiplier}, {source_start_cost}, {source_resistance_rate}, {source_capacity}, {source_direction})

Name	Explanation	Data Type
in_source_data	The input source locations. This is a raster or feature (point, line, or polygon) identifying the cells or locations that will be used to calculate the least accumulated cost distance for each output cell location. For rasters, the input type can be integer or floating point.	Raster Layer; Feature Layer
in_cost_raster	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
maximum_distance (Optional)	The threshold that the accumulative cost values cannot exceed. If an accumulative cost distance value exceeds this value, the output value for the cell location will be NoData. The maximum distance is the extent for which the accumulative cost distances are calculated. The default distance is to the edge of the output raster.	Double
out_backlink_raster (Optional)	The output cost backlink raster. The backlink raster contains values 0 through 8, which define the direction or identify the next neighboring cell (the succeeding cell) along the least accumulative cost path from a cell to reach its least-cost source. If the path is to pass into the right neighbor, the cell will be assigned the value 1, 2 for the lower right diagonal cell, and continue clockwise. The value 0 is reserved for source cells.	Raster Dataset
source_cost_multiplier (Optional)	The multiplier that will be applied to the cost values. This 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
source_start_cost (Optional)	The starting cost that will be used 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 this value. The values must be zero or greater. The default is 0.	Double; Field
source_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
source_capacity (Optional)	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
source_direction (Optional)	Specifies the direction of the traveler when applying the source resistance rate and the source starting cost. FROM_SOURCE—The source resistance rate and source starting cost will be applied beginning at the input source and travel out to the nonsource cells. This is the default. TO_SOURCE—The source resistance rate and source starting cost will be applied beginning at each nonsource cell and travel back to the input source. 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 string FROM_SOURCE or TO_SOURCE.	String; Field

Return Value

Name	Explanation	Data Type
out_distance_raster	The output cost distance raster. The cost distance raster identifies, for each cell, the least accumulative cost distance over a cost surface to the identified source locations. A source can be a cell, a set of cells, or one or more feature locations. The output raster is of floating-point type.	Raster

Code sample

CostDistance example 1 (Python window)

The following Python Window script demonstrates how to use the CostDistance tool.

import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
outCostDist = CostDistance("source.shp", "elevation", "", "backlink", "Multiplier", "StartCost", "Resistance", 500000)
outCostDist.save("C:/sapyexamples/output/costdist")

CostDistance example 2 (stand-alone script)

Calculate the least accumulated cost distance raster from point shape file source locations.

# Name: CostDistance_Ex_02.py
# Description: Calculates for each cell the least accumulative cost distance
#    to the nearest source over a cost  surface. 
# Requirements: Spatial Analyst Extension

# Import system modules
import arcpy
from arcpy import env
from arcpy.sa import *

# Set environment settings
env.workspace = "C:/sapyexamples/data"

# Set local variables
inSourceData = "source.shp"
inCostRaster = "elevation"
maxDistance = 20000000   
outBkLinkRaster = "C:/sapyexamples/output/outbklink"

# Execute CostDistance
outCostDistance = CostDistance(inSourceData, inCostRaster, maxDistance, outBkLinkRaster)

# Save the output 
outCostDistance.save("C:/sapyexamples/output/outcostdist")

Environments

Auto Commit, Cell Size, Cell Size Projection Method, Compression, Current Workspace, Extent, Geographic Transformations, Mask, Output CONFIG Keyword, Output Coordinate System, Parallel Processing Factor, Pyramid, Scratch Workspace, Snap Raster, Tile Size