Cost Distance

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

Learn more about how Cost functions work


Illustration

Cost Distance illustration

Usage tips

Command line and Scripting

Map Algebra

ArcObjects

Syntax

CostDistance_sa (in_source_data, in_cost_raster, out_distance_raster, maximum_distance, out_backlink_raster)
Parameter Explanation Datatype
Input raster or feature source data (Required)

The input source locations.

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

For rasters, the input value can be integer, string, or floating-point type if in_value_raster is used.

Composite Geodataset
Input cost raster (Required)

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 compensating for diagonal movement, to obtain the total cost of passing through the cell. The values on the in_cost_raster can be integer or floating point, but they cannot be negative or zero (you cannot have a negative or zero cost).

Composite Geodataset
Output distance raster (Optional)

The name of 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.

Raster Dataset
Maximum distance (Optional)

Defines the threshold that the accumulative cost values cannot exceed.

If an accumulative cost distance value exceeds the {max_distance}, the output value for the cell location will be NoData. The {max_distance} defines 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 name of the output cost backlink raster.

The backlink 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.

Raster Dataset
Data types for geoprocessing tool parameters

Script Example

# CostDistance_sample.py
# Description:
#   Calculates for each cell the least accumulative cost distance
#   to the nearest source over a cost  surface. 
# Requirements: None
# Author: ESRI
# Date: Sept 6, 2005

# Import system modules
import arcgisscripting

# Create the Geoprocessor object
gp = arcgisscripting.create()

try:
    # Set local variables
    InSourceRaster = "C:/data/source_ras"
    InCostRaster = "C:/data/cost_ras"
    OutDistanceRaster = "C:/data/out_Dist"    
    InMaxDistance = ""    
    OutBkLinkRaster = "C:/data/out_BkLink"

    # Check out Spatial Analyst extension license
    gp.CheckOutExtension("Spatial")

    # Process: CostDistance
    gp.CostDistance_sa(InSourceRaster, InCostRaster, OutDistanceRaster, InMaxDistance,  OutBkLinkRaster)

except:
    # If an error occurred while running a tool, then print the messages.
    print gp.GetMessages()

Map Algebra syntax

CostDistance(<source_grid>, <cost_grid>, {o_backlink_grid}, {o_allocate_grid}, {max_distance}, {value_grid})

Parameter Explanation
<source_grid> A raster that identifies those cells to which a least accumulated cost distance for every cell is calculated. The input value types can be either integer or floating point.
<cost_grid> 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 compensating for diagonal movement, to obtain the total cost of passing through the cell. The values on the <cost_grid> can be integer or floating point, but they cannot be negative or zero (you cannot have a negative or zero cost).
{o_backlink_grid} The name of the output cost backlink raster. The backlink raster contains a value of 0 through 8, which defines the direction or identifies the next neighboring cell (the succeeding cell) along the least accumulative cost path from a cell to reach a 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.
{o_allocate_grid} The name of the output cost allocation raster. The cost allocation raster identifies, for each cell, which source would require the least accumulative cost to reach.
{max_distance} Defines the threshold that the accumulative cost values cannot exceed. If an accumulative cost distance value exceeds the {max_distance}, the output value for the cell location will be NoData. The {max_distance} defines the extent at which the accumulative cost distances are computed. The default distance is to the edge of the output raster.
{value_grid} An optional input raster that identifies the zone values that should be used for each cell on the <source_grid>. The value defined by the {value_grid} for each source cell will be assigned to all cells that will be allocated to the source cell in the cost allocation computations. The default zone value for a source cell is the value on <source_grid>. This parameter can be used if other values or zones are to be used instead of those existing in the input source raster. This parameter can also be used if the source raster was created by the Test function, a Boolean operator that will only output the binary values 0 and 1.

Map Algebra example

costdistance(source, cost)
costdistance(source, cost, out_back, out_alloc)
costdistance(source, cost, out_back, out_alloc, 500)
costdistance(source, cost, #, #, #, value_grid.ph)
costdistance(test(ingrid1 > 5), cost, out_back, #, #, value_grid)
costdistance(source, ingrid1 + ingrid2, #, out_all, 1000)

ArcObjects syntax

IDistanceOp::CostDistance (sourceData As IGeoDataset, costRaster As IGeoDataset, [maxDistance As Variant], [valueRaster As Variant]) As IGeoDataset

See also CostDistanceFull

Parameter Explanation
sourceData An input Raster, RasterDataset, RasterBand, RasterDescriptor, FeatureClass, or FeatureClassDescriptor that identifies those cells to which the least accumulated cost distance for every cell is calculated. The input value types can be either integer or floating point.
costRaster An input Raster, RasterDataset, RasterBand, or RasterDescriptor 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 compensating for diagonal movement, to obtain the total cost of passing through the cell. The values on the costRaster can be integer or floating point, but they cannot be negative or zero (you cannot have a negative or zero cost).
[maxDistance] Defines the threshold that the accumulative cost values cannot exceed. If an accumulative cost distance value exceeds the maxDistance, the output value for the cell location will be NoData. The maxDistance defines the extent at which the accumulative cost distances are calculated. If no maxDistance is specified, the distance will be measured to the edge of the output raster. The data type for maxDistance can be either integer or floating point.
[valueRaster] An optional input raster that identifies the zone values that should be used for each cell on the sourceData. The value defined by the valueRaster for each source cell will be assigned to all cells that will be allocated to the source cell in the cost allocation computations. If no valueRaster is specified, the zone value for a source cell is the value on the sourceData. This parameter can be used if other values or zones are to be used instead of those existing in the input source. This parameter can also be used if the source raster was created by the ILogicalOp::Test or ILogicalOp::Boolean methods, which only output the binary values 0 and 1. The data type for the valueRaster can be Raster, RasterDataset, RasterBand, or RasterDescriptor.
distance A Boolean expression that, if True, will create an output Raster that for each cell the least accumulative cost distance is calculated over a cost surface, the costRaster, to a source cell or a set of source cells specified in the sourceData.
backlink A Boolean expression that, if True, will create an output cost back link raster. The backlink raster contains a value of 0 through 8, which defines the direction or identifies the next neighboring cell (the succeeding cell) along the least accumulative cost path from a cell to reach a 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.
allocation A Boolean expression that, if True, will create an output cost allocation raster. The cost allocation raster identifies, for each cell, which source would require the least accumulative cost to reach.

ArcObjects example

' Create the RasterDistanceOp object
Dim pDistanceOp As IDistanceOp
Set pDistanceOp = New RasterDistanceOp

' Declare the input source raster object
Dim pSourceDataset As IGeoDataset

' Calls function to open the source raster dataset from disk
Set pSourceDataset = OpenRasterDataset ("D:\SpatialData", "sourceraster")

' Declare the input cost raster object
Dim pCostDataset As IGeoDataset

' Calls function to open the cost raster dataset from disk
Set pCostDataset = OpenRasterDataset ("D:\SpatialData", "cost raster")

' Declare the output raster object
Dim pOutputRaster As IGeoDataset

' Calls the method
Set pOutputRaster = pDistanceOp.CostDistance (pSourceDataset, pCostDataset)

' To call the CostDistanceFull method, use the above code except replace 
'  the method call with:
Set pOutputRaster = pDistanceOp.CostDistanceFull(pSourceDataset, pCostDataset, True, True, False)

' To access the backlink raster from the output generated from the above code:
pRasterBandCollection As IRasterBandCollection		
Set pRasterBandCollection = pOutputRaster		
Dim pRasBand As IRasterband	
Set pRasBand = pRasterBandCollection.Item(1)		
Set pRasterBandCollection = New Raster		
Dim pBackLink as IRaster				
Set pBackLink = pRasterBandCollection.AppendBand(pRasBand)

See Also

  • Cost Allocation
  • Cost Back Link
  • Cost Path
  • CostDistanceFull
  • Using the ArcGIS Spatial Analyst toolbar to calculate cost distance
  • An overview of the Distance tools