Path Distance (Spatial Analyst)

License Level:BasicStandardAdvanced

Summary

Calculates, for each cell, the least accumulative cost distance to the nearest source, while accounting for surface distance and horizontal and vertical cost factors.

Learn more about how the path distance tools work

Usage

Syntax

PathDistance (in_source_data, {in_cost_raster}, {in_surface_raster}, {in_horizontal_raster}, {horizontal_factor}, {in_vertical_raster}, {vertical_factor}, {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
(Optional)

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
in_surface_raster
(Optional)

A raster defining the elevation values at each cell location.

The values are used to calculate the actual surface distance covered when passing between cells.

Raster Layer
in_horizontal_raster
(Optional)

A raster defining the horizontal direction at each cell.

The values on the raster must be integers ranging from 0 to 360 with 0 degrees being north, or toward the top of the screen, and increasing clockwise. Flat areas should be given a value of -1. The values at each location will be used in conjunction with the {horizontal_factor} to determine the horizontal cost incurred when moving from a cell to its neighbors.

Raster Layer
horizontal_factor
(Optional)

The Horizontal Factor object defines the relationship between the horizontal cost factor and the horizontal relative moving angle.

There are several factors with modifiers from which to select that identify a defined horizontal factor graph. Additionally, a table can be used to create a custom graph. The graphs are used to identify the horizontal factor used in calculating the total cost of moving into a neighboring cell.

In the explanations below, two acronyms are used: 'HF' stands for horizontal factor, which defines the horizontal difficulty encountered when moving from one cell to the next; and 'HRMA' stands for horizontal relative moving angle, which identifies the angle between the horizontal direction from a cell and the moving direction.

The object comes in the following forms:

The definitions and parameters of these are:

  • HfBinary({zero_factor},{cut_angle})

    Indicates that if the HRMA is less than the cut angle, the HF is set to the value associated with the zero factor; otherwise, it is infinity.

  • HfForward({zero_factor},{side_value})

    Establishes that only forward movement is allowed. The HRMA must be greater or equal to 0 and less than 90 (0 <= HRMA < 90). If the HRMA is greater than 0 and less than 45 degrees, the HF for the cell is set to the value associated with the zero factor. If the HRMA is greater than or equal to 45 degrees, then the side value modifier value is used. The HF for any HRMA equal to or greater than 90 degrees is set to infinity.

  • HfLinear({zero_factor},{cut_angle},{slope})

    Specifies that the HF is a linear function of the HRMA.

  • HfInverseLinear({zero_factor},{cut_angle},{slope})

    Specifies that the HF is an inverse linear function of the HRMA.

  • HfTable(in_table)

    Identifies that a table file will be used to define the horizontal factor graph used to determine the HFs.

The Modifiers to the horizontal keywords are:

  • {zero_factor}—Establishes the horizontal factor used when the HRMA is 0. This factor positions the y intercept for any of the horizontal factor functions.
  • {cut_angle}—Defines the HRMA angle beyond which the HF will be set to infinity.
  • {slope}—Establishes the slope of the straight line used with the LINEAR and INVERSE_LINEAR horizontal-factor keywords. The slope is specified as a fraction of rise over run (for example, 45 percent slope is 1/45, which is input as 0.02222).
  • {side_value}—Establishes the HF when the HRMA is greater than or equal to 45 degrees and less than 90 degrees when the FORWARD horizontal-factor keyword is specified.
  • in_table—Identifies the name of the table defining the HF.

Horizontal factor
in_vertical_raster
(Optional)

A raster defining the z-values for each cell location.

The values are used for calculating the slope used to identify the vertical factor incurred when moving from one cell to another.

Raster Layer
vertical_factor
(Optional)

The Vertical factor object defines the relationship between the vertical cost factor and the vertical relative moving angle (VRMA).

There are several factors with modifiers from which to select that identify a defined vertical factor graph. Additionally, a table can be used to create a custom graph. The graphs are used to identify the vertical factor used in calculating the total cost for moving into a neighboring cell.

In the explanations below, two acronyms are used: 'VF' stands for vertical factor, which defines the vertical difficulty encountered in moving from one cell to the next; and 'VRMA' stands for vertical relative moving angle, which identifies the slope angle between the FROM or processing cell and the TO cell.

The object comes in the following forms:

The definitions and parameters of these are:

  • VfBinary({zero_factor},{low_cut_angle},{high_cut_angle})

    Specifies that if the VRMA is greater than the low-cut angle and less than the high-cut angle, the VF is set to the value associated with the zero factor; otherwise, it is infinity.

  • VfLinear({zero_factor},{low_cut_angle},{high_cut_angle},{slope})

    Indicates that the VF is a linear function of the VRMA.

  • VfInverseLinear({zero_factor},{low_cut_angle},{high_cut_angle},{slope})

    Indicates that the VF is an inverse linear function of the VRMA.

  • VfSymLinear({zero_factor},{low_cut_angle},{high_cut_angle},{slope})

    Specifies that the VF is a linear function of the VRMA in either the negative or positive side of the VRMA, respectively, and the two linear functions are symmetrical with respect to the VF (y) axis.

  • VfSymInverseLinear({zero_factor},{low_cut_angle},{high_cut_angle},{slope})

    Specifies that the VF is an inverse linear function of the VRMA in either the negative or positive side of the VRMA, respectively, and the two linear functions are symmetrical with respect to the VF (y) axis.

  • VfCos({low_cut_angle},{high_cut_angle},{cos_power})

    Identifies the VF as the cosine-based function of the VRMA.

  • VfSec({low_cut_angle},{high_cut_angle},{sec_power})

    Identifies the VF as the secant-based function of the VRMA.

  • VfCosSec({low_cut_angle},{high_cut_angle},{cos_power},{sec_power})

    Indicates that the VF is the cosine-based function of the VRMA when the VRMA is negative and the secant-based function of the VRMA when the VRMA is nonnegative.

  • VfSecCos({low_cut_angle},{high_cut_angle},{sec_power},{cos_power})

    Specifies that the VF is the secant-based function of the VRMA when the VRMA is negative and the cosine-based function of the VRMA when the VRMA is nonnegative.

  • VfTable(in_table)

    Identifies that a table file will be used to define the vertical-factor graph used to determine the VFs.

The Modifiers to the vertical parameters are:

  • {zero_factor}—Establishes the vertical factor used when the VRMA is zero. This factor positions the y-intercept of the specified function. By definition, the zero factor is not applicable to any of the trigonometric vertical functions (Cos, Sec, Cos_Sec, or Sec_Cos). The y-intercept is defined by these functions.
  • {low_cut_angle}—Defines the VRMA angle below which the VF will be set to infinity.
  • {high_cut_angle}—Defines the VRMA angle above which the VF will be set to infinity.
  • {slope}—Establishes the slope of the straight line used with the VfLinear and VfInverseLinear parameters. The slope is specified as a fraction of rise over run (for example, 45 percent slope is 1/45, which is input as 0.02222).
  • in_table—Identifies the name of the table defining the VF.
Vertical factor
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, while accounting for surface distance as well as horizontal and vertical surface factors.

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 path distance raster.

The output path distance raster identifies, for each cell, the least accumulative cost distance, over a cost surface to the identified source locations, while accounting for surface distance as well as horizontal and vertical surface factors.

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

PathDistance example 1 (Python window)

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

import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
outPathDist = PathDistance("observers.shp", "costraster", "elevation", "backlink2",
                            HfForward(0.5, 1.0), "focalcost.tif", VfBinary(1.0, -30, 30),  
                            50000, "c:/sapyexamples/output/backlinkpath")
outPathDist.save("c:/sapyexamples/output/pathdistout")
PathDistance example 2 (stand-alone script)

Calculates, for each cell, the least accumulative cost distance to the nearest source, while accounting for surface distance and horizontal and vertical cost factors.

# Name: PathDistance_Ex_02.py
# Description: Calculates, for each cell, the least accumulative 
#              cost distance to the nearest source, while accounting 
#              for surface distance and horizontal and vertical 
#              cost factors.  
# 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"
inCostRast = "costraster"
inElev = "elevation"

# The horizontal factor
inHoriz = "backlink2"
# Create the HfForward Object
zeroFactor = 0.5
sideValue = 1.0
myHorizFactor = HfForward(zeroFactor, sideValue)

#The vertical factor
inVertical = "focalcost.tif"
# Create the VfBinary Object
zeroFactor = 1.0
lowCutAngle = -30
highCutAngle = 30
myVerticalFactor = VfBinary(zeroFactor, lowCutAngle, highCutAngle)

maxDist = 50000
optBacklinkOut = "c:/sapyexamples/output/pathbacklink"

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

# Execute PathDistance
outPathDist = PathDistance(inSource, inCostRast, inElev, inHoriz, 
                           myHorizFactor, inVertical, myVerticalFactor, 
                           maxDist, optBacklinkOut)

# Save the output 
outPathDist.save("c:/sapyexamples/output/pathdistout02")

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