Least Cost Corridor (Spatial Analyst)

Summary

Calculates the sum of two accumulative cost distance rasters with the option to apply a threshold based on percentage or accumulative cost.

Learn more about how to connect locations with corridors

Usage

  • The input rasters should be distance accumulation and back direction rasters output from the Distance Accumulation or Distance Allocation tools.

  • Use the cost version of the distance accumulation rasters. The units of the rasters can be, but are not limited to, dollars per meter, preference per foot, or minutes per meter depending on the application. These cost units are captured in the cost surface. For additional information, see Adjust the encountered distance using a cost surface.

  • Corridors are nondirectional, meaning that traveling from the first source to the second source costs the same as traveling from the second source to the first source. When creating the accumulative cost distance and back direction rasters, do not specify values for any parameters that depend on directionality, those being the horizontal factor, vertical factor, and travel direction.

  • Use the same parameter settings for the Distance Accumulation or Distance Allocation tool when creating the first source's accumulative cost distance and back direction rasters, as well as the second source's accumulative cost distance and back direction rasters.

  • All input rasters must be floating-point type and must have the same cell size, extent, and spatial reference.

  • The values on the output corridor represent the sum of the accumulative cost to reach a given location with the same units as the input accumulative cost distance rasters.

  • If a specified threshold value is greater than the maximum accumulative cost when the two distance accumulation rasters are summed, the output corridor raster will cover the same area as the input accumulative rasters.

  • If a specified threshold value is less than the minimum value in the corridor raster, a warning message is returned, and the output raster will be empty.

  • The output corridor raster may contain cells with slightly greater accumulative costs than the threshold value. This is from the back direction rasters using cells assigned slightly higher costs than the threshold to connect disconnected cells to the corridor. For additional information, see Connect locations with corridors.

  • To generate a corridor, the Cell Size environment setting is ignored, and the cell size of the input accumulative cost rasters will be used to calculate the output raster. The pattern of the input rasters would be altered if the output were resampled to a different resolution.

  • 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

LabelExplanationData Type
Input accumulative cost distance raster 1

The input raster representing the accumulative cost distance from the first source.

Use the distance accumulation output from the Distance Accumulation or Distance Allocation tool.

Raster Layer
Input back direction raster 1

The input back direction raster from the first source. The units are degrees identifying the next cell along the least-cost path back to the first source.

Use the back direction output from the Distance Accumulation or Distance Allocation tool. The range of values is from 0 degrees to 360 degrees, with 0 reserved for the source cells. Due east (right) is 90, and the values increase clockwise (180 is south, 270 is west, and 360 is north).

Raster Layer
Input accumulative cost distance raster 2

The input raster representing the accumulative cost distance from the second source.

Use the distance accumulation output from the Distance Accumulation or Distance Allocation tool.

Raster Layer
Input back direction raster 2

The input back direction raster from the second source. The units are degrees identifying the next cell along the least-cost path back to the second source.

Use the back direction output from the Distance Accumulation or Distance Allocation tool. The range of values is from 0 degrees to 360 degrees, with 0 reserved for the source cells. Due east (right) is 90, and the values increase clockwise (180 is south, 270 is west, and 360 is north).

Raster Layer
Threshold method

Specifies how the threshold will be defined.

  • No thresholdNo threshold will be applied, and the resulting corridor will cover the full extent of the input rasters. This is the default.
  • Percent of least costThe threshold will be defined as a percent of the minimum value of the summed accumulative cost distance rasters.
  • Accumulative costThe threshold will be defined in accumulative cost distance units.
String
Threshold

A percent or accumulative cost threshold that determines whether a given cell will be included in the output corridor raster.

When the Threshold method parameter is set to Percent of least cost, the specified value indicates the percent increase to apply from the minimum value of the summed accumulative cost distance rasters. When the Threshold method parameter is set to Accumulative cost, the value indicates cells that have a summed accumulative cost equal to or below the value will be included in the corridor.

This parameter is only active if the Threshold method parameter is set to Percent of least cost or Accumulative cost.

Double

Return Value

LabelExplanationData Type
Output raster

The output corridor raster containing cells with values below the threshold in accumulative cost distance units.

The output raster is floating-point type.

Raster

LeastCostCorridor(in_accumulative_cost_distance_raster1, in_back_direction_raster1, in_accumulative_cost_distance_raster2, in_back_direction_raster2, threshold_method, threshold)
NameExplanationData Type
in_accumulative_cost_distance_raster1

The input raster representing the accumulative cost distance from the first source.

Use the distance accumulation output from the Distance Accumulation or Distance Allocation tool.

Raster Layer
in_back_direction_raster1

The input back direction raster from the first source. The units are degrees identifying the next cell along the least-cost path back to the first source.

Use the back direction output from the Distance Accumulation or Distance Allocation tool. The range of values is from 0 degrees to 360 degrees, with 0 reserved for the source cells. Due east (right) is 90, and the values increase clockwise (180 is south, 270 is west, and 360 is north).

Raster Layer
in_accumulative_cost_distance_raster2

The input raster representing the accumulative cost distance from the second source.

Use the distance accumulation output from the Distance Accumulation or Distance Allocation tool.

Raster Layer
in_back_direction_raster2

The input back direction raster from the second source. The units are degrees identifying the next cell along the least-cost path back to the second source.

Use the back direction output from the Distance Accumulation or Distance Allocation tool. The range of values is from 0 degrees to 360 degrees, with 0 reserved for the source cells. Due east (right) is 90, and the values increase clockwise (180 is south, 270 is west, and 360 is north).

Raster Layer
threshold_method

Specifies how the threshold will be defined.

  • NO_THRESHOLDNo threshold will be applied, and the resulting corridor will cover the full extent of the input rasters. This is the default.
  • PERCENT_OF_LEAST_COSTThe threshold will be defined as a percent of the minimum value of the summed accumulative cost distance rasters.
  • ACCUMULATIVE_COSTThe threshold will be defined in accumulative cost distance units.
String
threshold

A percent or accumulative cost threshold that determines whether a given cell will be included in the output corridor raster.

When the threshold_method parameter is set to PERCENT_OF_LEAST_COST, the specified value indicates the percent increase to apply from the minimum value of the summed accumulative cost distance rasters. When the threshold_method parameter is set to ACCUMULATIVE_COST, the value indicates cells that have a summed accumulative cost equal to or below the value will be included in the corridor.

This parameter is only enabled if the threshold_method parameter is set to PERCENT_OF_LEAST_COST or ACCUMULATIVE_COST.

Double

Return Value

NameExplanationData Type
out_raster

The output corridor raster containing cells with values below the threshold in accumulative cost distance units.

The output raster is floating-point type.

Raster

Code sample

Least Cost Corridor example 1 (Python window)

The following Python window script demonstrates how to use the LeastCostCorridor function.

import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/arcpyexamples/data"
out_LCC_raster = LeastCostCorridor("DistAccumRaster1.tif", "BackDirRaster1.tif",
                                   "DistAccumRaster2.tif", "BackDirRaster2.tif") 
out_LCC_raster.save("c:/arcpyexamples/output/corridor.tif")
Least Cost Corridor example 2 (stand-alone script)

Calculate a corridor between two areas.

# Name: LeastCostCorridor_Ex_02.py
# Description: Calculates a potential wildlife corridor between two known 
#               protected areas.
# Requirements: Spatial Analyst Extension

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

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

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

# Set local variables
in_accumulative_cost_distance_raster1 = "distaccum_s1.tif"
in_back_direction_raster1 = "backdir_s1.tif"
in_accumulative_cost_distance_raster2 = "distaccum_s2.tif"
in_back_direction_raster2 = "backdir_s2.tif"
threshold_method = "ACCUMULATIVE_COST" 
threshold = 500

# Run Least Cost Corridor
out_LCC_raster = LeastCostCorridor(
    in_accumulative_cost_distance_raster1, in_back_direction_raster1, 
    in_accumulative_cost_distance_raster2, in_back_direction_raster2, 
    "ACCUMULATIVE_COST", "500")

# Save the output 
out_LCC_raster.save("c:/arcpyexamples/output/corridor.tif")