Cost Distance (Spatial Analyst)

License Level:BasicStandardAdvanced

Summary

Calculates the least accumulative cost distance for each cell to the nearest source over a cost surface.

Learn more about how Cost distance tools work

Illustration

Cost Distance illustration
Cost_Dist = CostDistance(Source_Ras, Cost_Ras)

Usage

Syntax

CostDistance (in_source_data, in_cost_raster, {maximum_distance}, {out_backlink_raster})
ParameterExplanationData Type
in_source_data

The input source locations.

This is a raster or feature dataset that identifies the cells or locations to which the least accumulated cost distance for every output cell location is calculated.

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)

Defines 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 defines 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 back-link raster.

The back-link raster contains values of 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 continuing clockwise. The value 0 is reserved for source cells.

Back-link positions
Raster Dataset

Return Value

NameExplanationData 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", 200000, "backlink")
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"

# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")

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

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

Environments

Related Topics

Licensing Information

ArcGIS for Desktop Basic: Requires Spatial Analyst
ArcGIS for Desktop Standard: Requires Spatial Analyst
ArcGIS for Desktop Advanced: Requires Spatial Analyst
4/10/2014