Cost Back Link (Spatial Analyst)

License Level:BasicStandardAdvanced

Summary

Defines the neighbor that is the next cell on the least accumulative cost path to the nearest source.

Learn more about how Cost distance tools work

Illustration

Cost Back Link illustration
Cost_BackLink = CostBacklink(Source_Ras, Cost_Ras)

Usage

Syntax

CostBackLink (in_source_data, in_cost_raster, {maximum_distance}, {out_distance_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_distance_raster
(Optional)

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 Dataset

Return Value

NameExplanationData Type
out_backlink_raster

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

Code Sample

CostBackLink example 1 (Python window)

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

import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
outBacklink = CostBackLink("observers","costraster", 100000, 
                           "c:/sapyexamples/output/distRast")
outBacklink.save("c:/sapyexamples/output/backlink")
CostBackLink example 2 (stand-alone script)

Create a back link raster defining the direction of the next cell in least accumulated cost path analysis.

# Name: CostBackLink_Ex_02.py
# Description: Defines the neighbor that is the next cell on 
#              the least accumulative cost path to the nearest 
#              source.
# 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
inSource = "observers.shp"
inCostRaster = "costraster"
inMaxDist = 100000
outDistRast = "c:/sapyexamples/output/distRast"

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

# Execute CostBackLink
outBacklink = CostBackLink(inSource,inCostRaster, inMaxDist,
                           outDistRast)

# Save the output 
outBacklink.save("c:/sapyexamples/output/backlink.tif")

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
11/8/2012