Path Distance Allocation function

Available with Spatial Analyst license.

Overview

Calculates the least-cost source for each cell based on the least accumulative cost over a cost surface, while accounting for surface distance along with horizontal and vertical cost factors.

Tip:

The Distance Allocation function provides enhanced functionality or performance.

Learn more about how the path distance tools work

This is a global raster function.

Notes

The Path Distance functions are comparable to the Cost Distance functions in that both determine the minimum accumulative travel cost from or to a source for each location on a raster surface. However, the Path Distance functions add more complexity to the analysis by accommodating the actual surface distance as well as other horizontal and vertical factors.

Cells with NoData act as barriers in the Path Distance functions. The cost distance for cells behind NoData values is calculated by the accumulative cost necessary to move around the NoData barrier. Any cell location that is assigned NoData on any one of the input rasters will receive NoData on all output rasters.

The Maximum Distance is specified in the same cost unit as the Cost Raster.

For the output raster, the least-cost distance (or minimum accumulative cost distance) of a cell to a set of source locations is the lower bound of the least-cost distances from the cell to all source locations.

The default values for the Horizontal factor modifiers are the following:

Keywords         Zero factor   Cut angle     Slope   Side value
--------------   -----------   -----------   -----   ---------
Binary           1.0            45           ~       ~
Forward          0.5            45 (fixed)   ~       1.0
Linear           0.5           181            1/90   ~
Inverse linear   2.0           180           -1/90   ~

The default values for the Vertical factor modifiers are the following:

Keyword                   Zero    Low    High   Slope  Power  Cos    Sec
                          factor  cut    cut                  power  power
                                  angle  angle                             
------------------------  ------  -----  -----  -----  -----  -----  -----
Binary                    1.0     -30    30     ~      ~      ~      ~
Linear                    1.0     -90    90      1/90  ~      ~      ~
Symmetric linear          1.0     -90    90      1/90  ~      ~      ~
Inverse linear            1.0     -45    45     -1/45  ~      ~      ~
Symmetric inverse linear  1.0     -45    45     -1/45  ~      ~      ~
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

The output of the Aspect function can be used as input for Horizontal Raster parameter.

The characteristics of the source, or the movers from or to a source, can be controlled by specific parameters. The Source cost multiplier parameter determines the mode of travel or magnitude at the source, Source start cost sets the starting cost before the movement begins, Source resistance rate is a dynamic adjustment accounting for the impact of accumulated cost, for example, simulating how much a hiker is getting fatigued, and Source capacity sets how much cost a source can assimilate before reaching its limit. The Travel direction identifies if the mover is starting at a source and moving to non-source locations, or is starting at non-source locations and moving back to a source.

If any of the source characteristics parameters are specified using a field, the source characteristic will be applied on a source-by-source basis, according to the information in the given field for the source data. When a keyword or a constant value is given, it will be applied to all sources.

If Source start cost is specified the source locations on the output cost distance surface will be set to the value of Source start cost; otherwise, the source locations on the output cost distance surface will be set to zero.

This function supports parallel processing. If your computer has multiple processors or processors with multiple cores, better performance may be achieved, particularly on larger datasets. See Parallel processing with Spatial Analyst for more details on this capability and how to configure it.

When using parallel processing, temporary data will be written to manage the data chunks being processed. The default temp folder location will be on your local C drive. You can control the location of this folder by setting up a system environment variable named TempFolders and specifying the path to a folder to use (for example, E:\RasterCache). If you have admin privileges on your machine, you can also use a registry key (for example, [HKEY_CURRENT_USER\SOFTWARE\ESRI\ArcGISPro\Raster]).

By default, this function will use 50 percent of the available cores. If the input data is smaller than 5,000 by 5,000 cells, fewer cores may be used. You can control the number of cores the tool uses with the Parallel processing factor environment.

Parameters

Parameter nameDescription

Source Raster

(Required)

The input source locations.

This is a raster dataset identifying the cells or locations from which the least accumulated cost distance for every output cell location is calculated.

It can be an integer or a floating-point type.

Cost Raster

(Required)

A raster defining the cost or impedance to move planimetrically through each cell. The value at each cell location represents the cost-per-unit distance for moving through it. Each cell location value is multiplied by the cell resolution, and also compensates 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.

Surface Raster

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.

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 parameter to determine the horizontal cost incurred when moving from a cell to its neighbors.

Horizontal Factor

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

There are several factors with modifiers 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 of moving into a neighboring cell.

In the explanations below, two acronyms are used: HF and HRMA. 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 types include the following:

  • 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 than 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 zero factor. If the HRMA is greater than or equal to 45 degrees, the side value modifier value is used. The HF for any HRMA value 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 factors include the following:

  • Zero factor—The horizontal factor to be used when the HRMA is zero. 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.
  • Table name—Identifies the name of the table defining the HF.

Vertical Raster

Defines the relationship between the vertical cost factor and the vertical relative moving angle (VRMA).

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

Vertical Factor

Defines the relationship between the vertical cost factor and the vertical relative moving angle (VRMA).

There are several factors with modifiers 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 of moving into a neighboring cell.

In the explanations below, two acronyms are used: VF and VRMA. 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 include the following:

  • 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 zero factor; 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—Specifies 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 not negative.
  • 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 not negative.
  • Table—Identifies that a table file will be used to define the vertical-factor graph that is used to determine the VFs.

Modifiers to the vertical keywords include the following:

  • 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 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).
  • Table name—Identifies the name of the table defining the VF.

Maximum Distance

The threshold that the accumulative cost values cannot exceed. If an accumulative cost distance 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 extent of the output raster.

Value Raster

The input integer raster that identifies the zone values to be used for each input source location. For each source location cell, the value defined by the Value Raster will be assigned to all cells allocated to the source location for the computation. The Value Raster will take precedence over any setting for the Source Field.

Source Field

The field used to assign values to the source locations. It must be an integer type. If the Value Raster has been set, the values in that input will take precedence over any setting for the Source Field.

Multiplier to Apply to Costs

A multiplier that will be applied to the cost values.

This parameter allows for control of the mode of travel or the magnitude at a source. The greater the multiplier, the greater the cost to move through each cell.

The values must be greater than zero. The default is 1.

A numeric (double) value or a field from the Source Raster can be used for this parameter.

Start Cost

The starting cost that will be used to begin the cost calculations. This parameter allows for the specification of the fixed cost associated with a source. Instead of starting at a cost of 0, the cost algorithm will begin with the value specified.

The value must be zero or greater. The default is 0.

Accumulative Cost Resistance Rate

This parameter simulates the increase in the effort to overcome costs as the accumulative cost increases. It is used to model fatigue of the traveler. The growing accumulative cost to reach a cell is multiplied by the resistance rate and added to the cost to move into the subsequent cell.

It's a modified version of a compound interest rate formula that's used to calculate the apparent cost of moving through a cell. As the value of the resistance rate increases, it increases the cost of the cells that are visited later. The greater the resistance rate, the higher the cost to reach the next cell, which is compounded for each subsequent movement. Since the resistance rate is similar to a compound rate and generally the accumulative cost values are very large, small resistance rates are suggested, such as 0.005 or even smaller, depending on the accumulative cost values.

The value must be greater than zero. The default capacity is to the edge of the output raster.

Capacity

Defines the cost capacity for the traveler for a source. The cost calculations continue for each source until the specified capacity is reached.

The value must be greater than zero. The default capacity is to the edge of the output raster.

Travel Direction

Defines the direction of the traveler when applying the source resistance rate.

  • From Source—The source resistance rate will be applied beginning at the input source and moving out to the non-source cells. This is the default.
  • To Source—The source resistance rate will be applied beginning at each non-source cell and moving back to the input source.

Either specify the From Source or To Source keyword, which will be applied to all sources, or specify a field in the Source Raster that contains the keywords to identify the direction of travel for each source. That field must contain the string FROM_SOURCE or TO_SOURCE.

Environment settings

Geoprocessing environment settings for global functions are controlled at the application level. Setting processing environments in ArcGIS Pro can be done by clicking the Environments button on the Analysis tab. See Analysis environments and Spatial Analyst for additional details on environment settings.

The following environments are supported by this global function:

Related topics