Show Navigation | Hide Navigation
You are here:
Extensions > Spatial Analyst > Spatial Analyst functional reference > Distance (Spatial Analyst)

Path Distance
Release 9.2
Last modified January 3, 2008		 E-mail This Topic Printable Version Give Us Feedback

Print all topics in : "Distance (Spatial Analyst)"


Related Topics

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 Path Distance works


Usage tips

Command line syntax
An overview of the Command Line window
PathDistance_sa <in_source_data> <out_distance_raster> {in_cost_raster} {in_surface_raster} {in_horizontal_raster} {horizontal_factor} {in_vertical_raster} {vertical_factor} {maximum_distance} {out_backlink_raster}

Parameter Explanation Data Type
<in_source_data>

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, it must be of integer type. For features, only integer fields can be used.

 Composite Geodataset
<out_distance_raster>

The name of the output path distance raster.

The path distance raster identifies, for each cell, the least accumulative cost path distance to the identified source locations. A source can be a cell, a set of cells, or one or more feature locations.

 Raster Dataset
{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 of surface 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
{in_surface_raster}

A raster defining the elevation values at each cell location.

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

 Composite Geodataset
{in_horizontal_raster}

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.

 Composite Geodataset
{horizontal_factor}

Defines the relationship between the horizontal cost factor and the horizontal relative moving angle (HRMA).

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 for moving into a neighboring cell.

In the explanations below, two acronyms are used:

'HF' stands for horizontal factor, which defines the horizontal difficulty encountered in moving from one cell to the next.

'HRMA' stands for horizontal relative moving angle, which identifies the angle between the horizontal direction from a cell and the moving direction.

Horizontal factor types:

  • BINARY  — 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.

  • FORWARD  — 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 zerofactor. 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.

  • LINEAR  — Specifies that the HF is a linear function of the HRMA.

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

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

Modifiers to the horizontal keywords:

  • ZEROFACTOR  — Establishes the horizontal factor used when the HRMA is 0. This factor positions the y intercept for any of the horizontal factor functions.

  • CUTANGLE  — 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).

  • SIDEVALUE  — 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.

  • TABLENAME  — Identifies the name of the table defining the HF.

To summarize, the horizontal factor types are:

Binary          Zero factor  Cut angle
Forward         Zero factor  Side value
Linear          Zero factor  Cut angle   Slope
Inverse_Linear  Zero factor  Cut angle   Slope
Table           Table name

 Horizontal factor
{in_vertical_raster}

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.

 Composite Geodataset
{vertical_factor}

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.

'VRMA' stands for vertical relative moving angle, which identifies the slope angle between the FROM or processing cell and the TO cell.

Vertical factor types:

  • BINARY  — 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 zerofactor; otherwise it is infinity.

  • LINEAR  — Indicates that the VF is a linear function of the VRMA.

  • SYMMETRIC LINEAR  — 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.

  • INVERSE LINEAR  — Indicates that the VF is an inverse linear function of the VRMA.

  • SYMMETRIC INVERSE LINEAR  — 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.

  • COS  — Identifies the VF as the cosine-based function of the VRMA

  • SEC  — Identifies the VF as the secant-based function of the VRMA.

  • COS-SEC  — 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.

  • SEC-COS  — 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.

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

Modifiers to the vertical keywords:

  • ZEROFACTOR  — Establishes the vertical factor used when the VRMA is zero. This factor positions the y-intercept of the specified function. By definition, the zerofactor 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.

  • LCUTANGLE  — Defines the VRMA angle below which the VF will be set to infinity.

  • HCUTANGLE  — Defines the VRMA angle above which the VF will be set to infinity.

  • SLOPE  — Establishes the slope of the straight line used with the LINEAR and INVERSE_LINEAR vertical-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).

  • TABLENAME  — Identifies the name of the table defining the VF.

To summarize, the vertical factor types are: 

Binary                    Zero factor    Low cut angle   High cut angle
Linear                    Zero factor    Low cut angle   High cut angle  Slope
Inverse Linear            Zero factor    Low cut angle   High cut angle  Slope
Symmetric Linear          Zero factor    Low cut angle   High cut angle  Slope
Symmetric Inverse Linear  Zero factor    Low cut angle   High cut angle  Slope
Cos                       Low cut angle  High cut angle  Power
Sec                       Low cut angle  High cut angle  Power
Cos-Sec                   Low cut angle  High cut angle  Cos power       Sec power
Sec-Cos                   Low cut angle  High cut angle  Cos power       Sec power
Table                     Table name

 Vertical factor
{maximum_distance}

Defines the threshold that the accumulative cost distance values cannot exceed.

If an accumulative cost distance value exceeds the {max_distance}, the output value for the cell will be NoData. The {maximum_distance} defines the extent to which the accumulative cost distances are computed.

 Double
{out_backlink_raster}

The name of the output 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
Data types for geoprocessing tool parameters


Command line example

PathDistance_sa C:/data/source_ras C:/data/out_dist C:/data/cost_ras C:/data/surface C:/data/hor_ras "BINARY 1 30" C:/data/ver_ras "LINEAR 1 -60 60 0.02" "" C:/data/out_blink

Scripting syntax
About getting started with writing geoprocessing scripts
PathDistance_sa (in_source_data, out_distance_raster, in_cost_raster, in_surface_raster, in_horizontal_raster, horizontal_factor, in_vertical_raster, vertical_factor, maximum_distance, out_backlink_raster)

Parameter Explanation Data Type
in_source_data (Required)

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, it must be of integer type. For features, only integer fields can be used.

 Composite Geodataset
out_distance_raster (Required)

The name of the output path distance raster.

The path distance raster identifies, for each cell, the least accumulative cost path distance to the identified source locations. A source can be a cell, a set of cells, or one or more feature locations.

 Raster Dataset
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 of surface 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
in_surface_raster (Optional)

A raster defining the elevation values at each cell location.

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

 Composite Geodataset
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.

 Composite Geodataset
horizontal_factor (Optional)

Defines the relationship between the horizontal cost factor and the horizontal relative moving angle (HRMA).

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 for moving into a neighboring cell.

In the explanations below, two acronyms are used:

'HF' stands for horizontal factor, which defines the horizontal difficulty encountered in moving from one cell to the next.

'HRMA' stands for horizontal relative moving angle, which identifies the angle between the horizontal direction from a cell and the moving direction.

Horizontal factor types:

  • BINARY  — 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.

  • FORWARD  — 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 zerofactor. 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.

  • LINEAR  — Specifies that the HF is a linear function of the HRMA.

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

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

Modifiers to the horizontal keywords:

  • ZEROFACTOR  — Establishes the horizontal factor used when the HRMA is 0. This factor positions the y intercept for any of the horizontal factor functions.

  • CUTANGLE  — 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).

  • SIDEVALUE  — 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.

  • TABLENAME  — Identifies the name of the table defining the HF.

To summarize, the horizontal factor types are:

Binary          Zero factor  Cut angle
Forward         Zero factor  Side value
Linear          Zero factor  Cut angle   Slope
Inverse_Linear  Zero factor  Cut angle   Slope
Table           Table name

 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.

 Composite Geodataset
vertical_factor (Optional)

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.

'VRMA' stands for vertical relative moving angle, which identifies the slope angle between the FROM or processing cell and the TO cell.

Vertical factor types:

  • BINARY  — 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 zerofactor; otherwise it is infinity.

  • LINEAR  — Indicates that the VF is a linear function of the VRMA.

  • SYMMETRIC LINEAR  — 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.

  • INVERSE LINEAR  — Indicates that the VF is an inverse linear function of the VRMA.

  • SYMMETRIC INVERSE LINEAR  — 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.

  • COS  — Identifies the VF as the cosine-based function of the VRMA

  • SEC  — Identifies the VF as the secant-based function of the VRMA.

  • COS-SEC  — 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.

  • SEC-COS  — 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.

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

Modifiers to the vertical keywords:

  • ZEROFACTOR  — Establishes the vertical factor used when the VRMA is zero. This factor positions the y-intercept of the specified function. By definition, the zerofactor 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.

  • LCUTANGLE  — Defines the VRMA angle below which the VF will be set to infinity.

  • HCUTANGLE  — Defines the VRMA angle above which the VF will be set to infinity.

  • SLOPE  — Establishes the slope of the straight line used with the LINEAR and INVERSE_LINEAR vertical-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).

  • TABLENAME  — Identifies the name of the table defining the VF.

To summarize, the vertical factor types are: 

Binary                    Zero factor    Low cut angle   High cut angle
Linear                    Zero factor    Low cut angle   High cut angle  Slope
Inverse Linear            Zero factor    Low cut angle   High cut angle  Slope
Symmetric Linear          Zero factor    Low cut angle   High cut angle  Slope
Symmetric Inverse Linear  Zero factor    Low cut angle   High cut angle  Slope
Cos                       Low cut angle  High cut angle  Power
Sec                       Low cut angle  High cut angle  Power
Cos-Sec                   Low cut angle  High cut angle  Cos power       Sec power
Sec-Cos                   Low cut angle  High cut angle  Cos power       Sec power
Table                     Table name

 Vertical factor
maximum_distance (Optional)

Defines the threshold that the accumulative cost distance values cannot exceed.

If an accumulative cost distance value exceeds the {max_distance}, the output value for the cell will be NoData. The {maximum_distance} defines the extent to which the accumulative cost distances are computed.

 Double
out_backlink_raster (Optional)

The name of the output 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

Data types for geoprocessing tool parameters


Script example

# PathDistance_sample.py
# Description: 
#   Calculates for each cell the least accumulative cost distance 
#   to the nearest source over a cost surface while accounting
#   for surface distance and horizontal and vertical cost factors. 
# Requirements: None
# Author: ESRI
# Date: Sept 6, 2005
# Import system modules
import arcgisscripting

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

try:
    # Set local variables
    InSourceRas = "C:/data/source_ras"
    OutDistanceRaster = "C:/data/out_dist"
    InCostRas = "C:/data/cost_ras"
    InSurfaceRas = "C:/data/surface"
    InHorRas = "C:/data/hor_ras"
    InHorFactor = "BINARY 1 30"
    InVerRas = "C:/data/ver_ras"
    InVerFact = "LINEAR 1 -60 60 0.02"
    InMaxDistance = ""
    OutBackLinkRaster = "C:/data/out_blink"

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

    # Process: PathDistance
    gp.PathDistance_sa(InSourceRas, OutDistanceRaster, InCostRas, InSurfaceRas, InHorRas, InHorFactor, InVerRas, InVerFact, InMaxDistance, OutBackLinkRaster)

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

Map Algebra syntax
PathDistance(<source_grid>, {cost_grid}, {surface_grid}, {horiz_factor_grid}, {horiz_factor_parm}, {vert_factor_grid}, {vert_factor_parm}, {o_backlink_grid}, {o_allocate_grid}, {max_distance}, {value_grid})

Parameter Explanation
<source_grid> A raster that identifies those cells from which a least accumulative cost distance is calculated to each cell.
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 of surface 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).
{surface_grid} A raster identifying the z-values at each cell location.
The values are used to calculate the actual surface distance covered when passing between cells.
{horiz_factor_grid} 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 towards the top of the screen, and increasing clockwise. Flat areas should be given the value of -1. The values at each location will be used in conjunction with the {horiz_factor_parm} to determine the horizontal cost incurred when moving from a cell to its neighbors.
{horiz_factor_parm} Defines the relationship between the horizontal cost factor and the horizontal relative moving angle (HRMA).
The input parameter may be one of several keywords (and modifiers) identifying a defined horizontal factor graph or an ASCII file that creates a custom graph. The graphs are used to identify the horizontal factor used in calculating the total cost for moving into a neighboring cell. If the parameter is used with any modifier, the string must be double quoted. The format for the horizontal parameter is: 
    "keyword {modifier_1 ... modifier_n}"

Spaces must be used to separate the keyword and modifiers.
The format for the horizontal parameter modifiers is: 
    modifier_name=value or table_name

There is an equal sign (=) between the modifier name and its value, but there are no spaces between any of the three.
If no keyword is specified, the default horizontal parameter is BINARY.
Two acronyms are used in the explanations of the horizontal factor keywords and modifiers:
HF stands for horizontal factor, which defines the horizontal difficulty encountered when moving from one cell to the next.
HRMA stands for horizontal relative moving angle, which identifies the angle between the horizontal direction from a cell and the moving direction.

Horizontal-factor keywords:
  • BINARY  — Indicates that if the HRMA is less than the cut angle, the HF is set to the value associated with the zerofactor; otherwise, it is infinity.
  • FORWARD  — Establishes that only forward movement is allowed. The HRMA must be greater or equal to 0 and less than 90 degrees (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 zerofactor. If the HRMA is greater than or equal to 45 degrees, the side value modifier value is used. The HF for any HRMA equal to or greater than 90 degrees is set to infinity.
  • LINEAR  — Defines that the HF is a linear function of the HRMA.
  • INVERSE_LINEAR  — Specifies that the HF is an inverse linear function of the HRMA.
  • TABLE  — Specifies that an ASCII file will be used to define the horizontal factor graph used to determine the HFs. The name of the table is entered as a modifier after a blank space following the keyword.

Modifiers to the horizontal keywords:
  • ZEROFACTOR  — Establishes the horizontal factor to be used when the HRMA is zero. This factor positions the y-intercept for any of the horizontal factor functions.
  • CUTANGLE  — 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).
  • SIDEVALUE  — Establishes the HF when the HRMA is greater than or equal to 45 degrees and less than 90 degrees for the FORWARD horizontal factor keyword that is specified.
  • table_name  — Identifies the name of the ASCII table defining the HF. It is used in conjunction with the TABLE horizontal factor keyword.

Default Values for Horizontal Factor Modifiers: 
Keywords         Zerofactor   Cutangle    Slope   Sidevalue

Binary           1.0          45          ~       ~

Forward          0.5          45(fixed)   ~       1.0

Linear           0.5          181          1/90   ~

Inverse_linear   2.0          180         -1/90   ~
{vert_factor_grid} 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.
{vert_factor_parm} Defines the relationship between the vertical cost factor and the vertical relative moving angle (VRMA).
The input parameter may be one of several keywords (and modifiers) identifying a defined vertical factor graph or an ASCII file creating a custom graph. The graphs are used to identify the vertical factor used in calculating the total cost for moving into a neighboring cell. If the parameter is used with any modifier, the string must be double quoted. The format for the vertical parameter is: 
    "keyword {modifier_1 ... modifier_n}"

Spaces must be used to separate the keyword and modifiers.
The format for the vertical parameter modifiers is: 
    modifier_name=value or table_name

There is an equal sign (=) between the modifier name and its value, but there are no spaces between any of the three.
If no keyword is specified, the default vertical parameter is SEC.
Two acronyms are used in the explanations of the vertical factor keywords and modifiers:
VF stands for vertical factor, which defines the vertical difficulty encountered when moving from one cell to the next.
VRMA stands for vertical relative moving angle, which identifies the slope angle between the FROM or processing cell and the TO cell.
Vertical-factor keywords:
  • BINARY  — Specifies that if the VRMA is greater than the low-cut angle and less than the high-cut angle, then the VF is set to the value associated with the zerofactor; otherwise, it is infinity.
  • LINEAR  — Indicates that the VF is a linear function of the VRMA.
  • SYM_LINEAR  — Defines 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.
  • INVERSE_LINEAR  — Indicates that the VF is an inverse linear function of the VRMA.
  • SYM_INVERSE_LINEAR  — Identifies 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.
  • COS  — Defines the VF as the cosine-based function of the VRMA.
  • SEC — Identifies the VF as the secant-based function of the VRMA.
  • COS-SEC  — 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.
  • SEC-COS  — 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.
  • TABLE  — Identifies that an ASCII file will be used to define the VFs. The name of the table is entered as a modifier after a blank space following the keyword.

Modifiers to the vertical factor keywords:
  • ZEROFACTOR  — Establishes the vertical factor used when the VRMA is zero. This factor positions the y-intercept of the specified function. By definition, the zerofactor 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.
  • LCUTANGLE  — Defines the VRMA angle below which the VF will be set to infinity.
  • HCUTANGLE  — Defines the VRMA angle above which the VF will be set to infinity.
  • SLOPE  — Establishes the slope of the straight line used with the LINEAR and INVERSE_LINEAR vertical factor keyword. 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).
  • table_name  — Identifies the name of the ASCII file defining the VF. It is used in conjunction with the TABLE vertical factor keyword.

Default Values for Vertical Factor Modifiers 
KEYWORDS              ZEROFACTOR   LCUTANGLE   HCUTANGLE   SLOPE   COSPOWER   SECPOWER

Binary                1.0          -30         30          ~       ~          ~

Linear                1.0          -90         90           1/90   ~          ~

Sym_linear            1.0          -90         90           1/90   ~          ~

Inverse_linear        1.0          -45         45          -1/45   ~          ~

Sym_inverse_linear    1.0          -45         45          -1/44   ~          ~	

Cos                   ~            -90         90          ~       1.0        ~ 

Sec                   ~            -90         90          ~       ~          1.0

Cos_sec               ~            -90         90          ~       1.0        1.0

Sec_cos               ~            -90         90          ~       1.0        1.0
{o_backlink_grid} The name of the output back link raster.
The back link raster contains values of 0 through 8, which is a code identifying the direction of the next neighboring cell (the succeeding cell) when retracing (from the destination to the source) the least accumulative cost path from a source cell to a destination.
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
{o_allocate_grid} The name of the output cost allocation raster.
The output raster defines, for each cell, the zone on the <source_grid> that achieves the minimum cost distance or the least accumulative cost to reach the cell.
{max_distance} Defines the threshold that the accumulative cost distance values cannot exceed.
If an accumulative cost distance value exceeds the {max_distance}, the output value for the cell will be NODATA. The {max_distance} defines the extent to which the accumulative cost distances are computed.
{value_grid} An optional input raster that identifies the zone value 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 are allocated to the source cell location in terms of the minimum cost distance. 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 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 zero and one.

Map Algebra example

pathdistance(source, cost)
pathdistance(source, cost, surface, #, #, #, #, out_back, out_alloc)
pathdistance(source, cost, surface, horiz, LINEAR, vert, COS,   out_back, out_alloc, 500)
pathdistance(source, cost, #, horiz, "BINARY CUTANGLE=120", vert, "LINEAR SLOPE=0.0111", #, value_grid.ph)
pathdistance(test(ingrid1 > 5), cost, horiz.cost2, vert, "TABLE vftable", out_back, #, #, value_grid)
pathdistance(source, ingrid1 + ingrid2, #, surface, horiz, #, vert, #, out_all, 1000)

ArcObjects syntax
IDistanceOp::PathDistance (sourceData As IGeoDataset, [costRaster], [surfaceRaster], [horizRaster], [horizFactor], [vertRaster], [vertFactor], [maxDistance], [valueRaster]) as IGeoDataset

See also PathDistanceFull

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).
[surfaceRaster] An input Raster, RasterDataset, RasterBand, or RasterDescriptor defining the elevation values at each cell location.
The values are used to calculate the actual surface distance covered when passing between cells.
[horizRaster] An input Raster, RasterDataset, RasterBand, or RasterDescriptor defining the horizontal direction at each cell.
The values 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 the value of -1.
The values at each location will be used in conjunction with the horizFactor to determine the horizontal cost incurred when moving from a cell to its neighbors.
[horizFactor] The esriPathDistanceHorizontalEnum defining the relationship between the horizontal cost factor and the horizontal relative moving angle (HRMA).
The available enums are:
esriPathDistanceHorizontalInvalid
esriPathDistanceHorizontalBinary
esriPathDistanceHorizontalForward esriPathDistanceHorizontalLinear
esriPathDistanceHorizontalInverseLinear esriPathDistanceHorizontalTable
[vertRaster] An input Raster, RasterDataset, RasterBand, or RasterDescriptor defining the z-value at each cell.
The values are used for calculating the slope used to identify the vertical factor incurred when moving from one cell to another.
[vertFactor] The esriPathDistanceVerticalEnum defining the relationship between the vertical cost factor and the vertical relative moving angle (VRMA).
The available enums are:
esriPathDistanceVerticalInvalid
esriPathDistanceVerticalBinary
esriPathDistanceVerticalLinear
esriPathDistanceVerticalInverseLinear
esriPathDistanceVerticalTable
esriPathDistanceVerticalSymLinear
esriPathDistanceVerticalSymInverseLinear
esriPathDistanceVerticalCos
esriPathDistanceVerticalSec
esriPathDistanceVerticalCosSec
esriPathDistanceVerticalSecCos
[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 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 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 zero and one.
The data type for the valueRaster can be Raster, RasterDataset, RasterBand, or RasterDescriptor.

ArcObjects example

Sub PathDistance_Example()

' Calculates for each cell the least-accumulative-path distance over a path 
'  surface to a source cell or a set of source cells.
'
' PathDistance(ByVal sourceData As esriGeoDatabase.IGeoDataset, _ 
'     [costRaster], [surfaceRaster], [horizRaster], [horizFactor], _
'     [vertRaster], [vertFactor], [maxDistance], [valueRaster]) _
'     As esriGeoDatabase.IGeoDataset

On Error GoTo ErrorHandler

Dim pDistanceOp As IDistanceOp2
Set pDistanceOp = New RasterDistanceOp

' Dataset names
Dim sRasNm01 As String
sRasNm01 = "C:\data\Source"
Dim sRasNm02 As String
sRasNm02 = "C:\data\HorRas"

' Open dataset as a raster using an utility function
Dim pRas01 As IRaster
Set pRas01 = Util_CreateDefaultIRaster(sRasNm01)
Dim pRas02 As IRaster
Set pRas02 = Util_CreateDefaultIRaster(sRasNm02)

' Create Raster Analysis Environment
Dim pEnv As IRasterAnalysisEnvironment
Set pEnv = pDistanceOp
Set pEnv.OutWorkspace = Util_OpenIRasterWorkspace("C:\data")

' Create Horizontal Factor
Dim pHF As IPathDistanceHorizontalFactor
Set pHF = New PathDistanceHorizontalFactor
pHF.SetForward 0.5, 1

' Execute the method
Dim pRasOut As IRaster
Set pRasOut = pDistanceOp.PathDistance(pRas01, , , pRas02, pHF)

Exit Sub
ErrorHandler:
MsgBox Err.Description & " " & Err.Source
End Sub

Please visit the Feedback page to comment or give suggestions on ArcGIS Desktop Help.
Copyright © Environmental Systems Research Institute, Inc.