Path Distance Allocation (Spatial Analyst)

Available with Spatial Analyst license.

Summary

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 tool provides enhanced functionality or performance.

Learn more about how the path distance tools work

Usage

• The Path Distance tools are comparable to the Cost Distance tools 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 tools add more complexity to the analysis by accounting for the actual surface distance as well as other horizontal and vertical factors.

• The input source data can be a feature class or a raster. The feature class can be point, line or polygon.

• When the input source data is a raster, the set of source cells consists of all cells in the source raster that have valid values. Cells that have NoData values are not included in the source set. The value 0 is considered a legitimate source. A source raster can be created using the extraction tools.

• When the input source data is a feature class, the source locations are converted internally to a raster before performing the analysis. The resolution of the raster can be controlled with the Cell Size environment. By default, if no other rasters are specified in the tool, the resolution will be determined by the shorter of the width or height of the extent of the input feature, in the input spatial reference, divided by 250.

• When using feature data for the input source data, care must be taken with how the output cell size is handled when it is coarse, relative to the detail present in the input. The internal rasterization process uses the same default Cell assignment type value as the Feature to Raster tool, which is the cell center method. This means that data that is not located at the center of the cell will not be included in the intermediate rasterized source output, so it will not be represented in the distance calculations. For example, if your sources are a series of small polygons (such as building footprints) that are small relative to the output cell size, it is possible that only a few will fall under the centers of the output raster cells, seemingly causing most of the others to be lost in the analysis.

  To avoid this situation, as an intermediate step, you can rasterize the input features directly with the Feature to Raster tool and set the Field parameter. Then use the resulting output as input to the particular distance tool you want to use. Alternatively, you can select a small cell size to capture the appropriate amount of detail from the input features.

• To calculate allocation, source locations can have an associated value, which can be specified by the Source field parameter. If the input source is an integer raster, the default field is VALUE. If it is a feature, it will be the first integer field in the attribute table. If the input source data is a floating-point raster, an integer value raster parameter must be specified.

• Cells with NoData act as barriers in the Path Distance tools. 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.

• If the input source data and the cost raster are different extents, the default output extent is the intersection of the two. To get a cost distance surface for the entire extent, choose the Union of Inputs option on the output Extent environment settings.

• The output of the Aspect tool can be used as input for the Input horizontal raster parameter.

• The Maximum distance parameter value is specified in the same cost units as those on the cost raster.

• For the output distance raster, the least-cost distance (or minimum accumulative cost distance) of a cell from or 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 characteristics of the source, or the movers from or to a source, can be controlled by specific parameters. The Source cost multiplier parameter specifies 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. Travel direction identifies whether the mover is starting at a source and moving to nonsource locations or starting at nonsource 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 and Travel direction is Travel from source, the source locations on the output cost distance surface will be set to the Source start cost value; otherwise, the source locations on the output cost distance surface will be set to zero.

• This tool supports parallel processing. If your computer has multiple processors or processors with multiple cores, better performance may be achieved, particularly on larger datasets. See the Parallel processing with Spatial Analyst help topic for 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 tool will use 50 percent of the available cores. If the input data is smaller than 5,000 by 5,000 cells in size, fewer cores may be used. You can control the number of cores the tool uses with the Parallel processing factor environment.

• See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.

Parameters

Dialog

Label	Explanation	Data Type
Input raster or feature source data	The input source locations. This is a raster or feature (point, line, or polygon) identifying the cells or locations that will be used to calculate the least accumulated cost distance for each output cell location. For rasters, the input type can be integer or floating point. If the input source raster is floating point, the Input value raster parameter must be set, and it must be integer. The value raster will take precedence over the Source field parameter setting.	Raster Layer; Feature Layer
Input 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
Input 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
Input 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 parameter to determine the horizontal cost incurred when moving from a cell to its neighbors.	Raster Layer
Horizontal factor (Optional)	Specifies the relationship between the horizontal cost factor and the horizontal relative moving angle (HRMA). There are several factors with modifiers 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 descriptions 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 Horizontal factor options are as follows: Binary—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—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 equal to or greater than 90 degrees is set to infinity. Linear—The HF is a linear function of the HRMA. Inverse Linear—The HF is an inverse linear function of the HRMA. Table—A table file will be used to define the horizontal factor graph used to determine the HFs. Modifiers to the horizontal factors are 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—The HRMA angle beyond which the HF will be set to infinity. Slope—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—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—The name of the table defining the HF.	Horizontal Factor
Input 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)	Specifies 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 for moving into a neighboring cell. In the descriptions 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 Vertical factor options are as follows: Binary—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—The VF is a linear function of the VRMA. Symmetric Linear—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—The VF is an inverse linear function of the VRMA. Symmetric Inverse Linear—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—The VF is the cosine-based function of the VRMA. Sec—The VF is the secant-based function of the VRMA. Cos-Sec—The VF is the cosine-based function of the VRMA when the VRMA is negative and is the secant-based function of the VRMA when the VRMA is not negative. Sec-Cos—The VF is the secant-based function of the VRMA when the VRMA is negative and is the cosine-based function of the VRMA when the VRMA is not negative. Table—A table file will be used to define the vertical-factor graph that is used to determine the VFs. Modifiers to the vertical keywords are the following: Zero factor—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—The VRMA angle below which the VF will be set to infinity. High Cut angle—The VRMA angle above which the VF will be set to infinity. Slope—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—The name of the table defining the VF.	Vertical Factor
Maximum distance (Optional)	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 is the extent for which the accumulative cost distances are calculated. The default distance is to the edge of the output raster.	Double
Input value raster (Optional)	The input integer raster that identifies the zone values that will be used for each input source location. For each source location (cell or feature), the Input value raster value will be assigned to all cells allocated to the source location for the computation. The value raster will take precedence over the Source field parameter setting.	Raster Layer
Source field (Optional)	The field used to assign values to the source locations. It must be of integer type. If the Input value raster parameter has been set, the values in that input will have precedence over the Source field parameter setting.	Field
Output distance raster (Optional)	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 Dataset
Output backlink raster (Optional)	The output cost backlink raster. The backlink raster contains values 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 continue clockwise. The value 0 is reserved for source cells.	Raster Dataset
Multiplier to apply to costs (Optional)	The multiplier that will be applied to the cost values. This 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.	Double; Field
Start cost (Optional)	The starting cost that will be used to begin the cost calculations. Allows for the specification of the fixed cost associated with a source. Instead of starting at a cost of zero, the cost algorithm will begin with the value set by Start cost. The values must be zero or greater. The default is 0.	Double; Field
Accumulative cost resistance rate (Optional)	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 is a modified version of a compound interest rate formula that is 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 more additional cost is added 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.02, 0.005, or even smaller, depending on the accumulative cost values. The values must be zero or greater. The default is 0.	Double; Field
Capacity (Optional)	The cost capacity for the traveler for a source. The cost calculations continue for each source until the specified capacity is reached. The values must be greater than zero. The default capacity is to the edge of the output raster.	Double; Field
Travel direction (Optional)	Specifies the direction of the traveler when applying horizontal and vertical factors and the source resistance rate. If you select the String option, you can choose between from and to options, which will be applied to all sources. If you select the Field option, you can select the field from the source data that determines the direction to use for each source. The field must contain the text string FROM_SOURCE or TO_SOURCE. Travel from source—The horizontal factor, vertical factor, and source resistance rate will be applied beginning at the input source and travel out to the nonsource cells. This is the default. Travel to source—The horizontal factor, vertical factor, and source resistance rate will be applied beginning at each nonsource cell and travel back to the input source.	String; Field

Return Value

Label	Explanation	Data Type
Output allocation raster	The output path distance allocation raster. This raster identifies the zone of each source location (cell or feature) that could be reached with the least accumulative cost, while accounting for surface distance and horizontal and vertical cost factors. The output raster is of integer type.	Raster

Python

PathAllocation(in_source_data, {in_cost_raster}, {in_surface_raster}, {in_horizontal_raster}, {horizontal_factor}, {in_vertical_raster}, {vertical_factor}, {maximum_distance}, {in_value_raster}, {source_field}, {out_distance_raster}, {out_backlink_raster}, {source_cost_multiplier}, {source_start_cost}, {source_resistance_rate}, {source_capacity}, {source_direction})

Name	Explanation	Data Type
in_source_data	The input source locations. This is a raster or feature (point, line, or polygon) identifying the cells or locations that will be used to calculate the least accumulated cost distance for each output cell location. For rasters, the input type can be integer or floating point. If the input source raster is floating point, the in_value_raster parameter must be set, and it must integer. The value raster will take precedence over the source_field parameter setting.	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 parameter 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 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 descriptions 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: HfBinary, HfForward, HfLinear, HfInverseLinear, and HfTable. The definitions and parameters of these are the following: HfBinary({zeroFactor}, {cutAngle}) 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({zeroFactor}, {sideValue}) Only forward movement is allowed. The HRMA must be greater than 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, the side value modifier value is used. The HF for any HRMA equal to or greater than 90 degrees is set to infinity. HfLinear({zeroFactor}, {cutAngle}, {slope}) The HF is a linear function of the HRMA. HfInverseLinear({zeroFactor}, {cutAngle}, {slope}) The HF is an inverse linear function of the HRMA. HfTable(inTable) A table file will be used to define the horizontal factor graph used to determine the HFs. The modifiers to the horizontal keywords are the following: zeroFactor—The horizontal factor to be used when the HRMA is 0. This factor positions the y-intercept for any of the horizontal factor functions. cutAngle—The HRMA angle beyond which the HF will be set to infinity. slope—The slope of the straight line used with the HfLinear and HfInverseLinear 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—The HF when the HRMA is greater than or equal to 45 degrees and less than 90 degrees when the HfForward horizontal-factor keyword is specified. inTable—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 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 descriptions 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: VfBinary, VfLinear, VfInverseLinear, VfSymLinear, VfSymInverseLinear, VfCos, VfSec, VfSec, VfCosSec, VfSecCos, VfTable. The definitions and parameters of these are the following: VfBinary({zeroFactor}, {lowCutAngle}, {highCutAngle}) 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({zeroFactor}, {lowCutAngle}, {highCutAngle}, {slope}) The VF is a linear function of the VRMA. VfInverseLinear({zeroFactor}, {lowCutAngle}, {highCutAngle}, {slope}) The VF is an inverse linear function of the VRMA. VfSymLinear({zeroFactor}, {lowCutAngle}, {highCutAngle}, {slope}) 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({zeroFactor}, {lowCutAngle}, {highCutAngle}, {slope}) 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({lowCutAngle}, {highCutAngle}, {cosPower}) The VF is the cosine-based function of the VRMA. VfSec({lowCutAngle}, {highCutAngle}, {secPower}) The VF is the secant-based function of the VRMA. VfCosSec({lowCutAngle}, {highCutAngle}, {cosPower}, {secPower}) The VF is the cosine-based function of the VRMA when the VRMA is negative and is the secant-based function of the VRMA when the VRMA is not negative. VfSecCos({lowCutAngle}, {highCutAngle}, {secPower}, {cos_power}) The VF is the secant-based function of the VRMA when the VRMA is negative and is the cosine-based function of the VRMA when the VRMA is not negative. VfTable(inTable) A table file will be used to define the vertical-factor graph used to determine the VFs. The modifiers to the vertical parameters are the following: zeroFactor—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. lowCutAngle—The VRMA angle below which the VF will be set to infinity. highCutAngle—The VRMA angle above which the VF will be set to infinity. slope—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). inTable—The name of the table defining the VF.	Vertical Factor
maximum_distance (Optional)	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 is the extent for which the accumulative cost distances are calculated. The default distance is to the edge of the output raster.	Double
in_value_raster (Optional)	The input integer raster that identifies the zone values that will be used for each input source location. For each source location (cell or feature), the in_value_raster value will be assigned to all cells allocated to the source location for the computation. The value raster will take precedence over the source_field parameter setting.	Raster Layer
source_field (Optional)	The field used to assign values to the source locations. It must be of integer type. If the in_value_raster parameter has been set, the values in that input will have precedence over the source_field parameter setting.	Field
out_distance_raster (Optional)	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 Dataset
out_backlink_raster (Optional)	The output cost backlink raster. The backlink raster contains values 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 continue clockwise. The value 0 is reserved for source cells.	Raster Dataset
source_cost_multiplier (Optional)	The multiplier that will be applied to the cost values. This 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.	Double; Field
source_start_cost (Optional)	The starting cost that will be used to begin the cost calculations. Allows for the specification of the fixed cost associated with a source. Instead of starting at a cost of zero, the cost algorithm will begin with the value set by source_start_cost. The values must be zero or greater. The default is 0.	Double; Field
source_resistance_rate (Optional)	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 is a modified version of a compound interest rate formula that is 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 more additional cost is added 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.02, 0.005, or even smaller, depending on the accumulative cost values. The values must be zero or greater. The default is 0.	Double; Field
source_capacity (Optional)	The cost capacity for the traveler for a source. The cost calculations continue for each source until the specified capacity is reached. The values must be greater than zero. The default capacity is to the edge of the output raster.	Double; Field
source_direction (Optional)	Specifies the direction of the traveler when applying horizontal and vertical factors and the source resistance rate. FROM_SOURCE—The horizontal factor, vertical factor, and source resistance rate will be applied beginning at the input source and travel out to the nonsource cells. This is the default. TO_SOURCE—The horizontal factor, vertical factor, and source resistance rate will be applied beginning at each nonsource cell and travel back to the input source. Specify the FROM_SOURCE or TO_SOURCE keyword, which will be applied to all sources, or specify a field in the source data that contains the keywords to identify the direction of travel for each source. That field must contain the string FROM_SOURCE or TO_SOURCE.	String; Field

Return Value

Name	Explanation	Data Type
out_allocation_raster	The output path distance allocation raster. This raster identifies the zone of each source location (cell or feature) that could be reached with the least accumulative cost, while accounting for surface distance and horizontal and vertical cost factors. The output raster is of integer type.	Raster

Code sample

PathAllocation example 1 (Python window)

The following Python window script demonstrates how to use the PathDistanceAllocation tool.

import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
pathAlloc = PathAllocation("observers.shp", "costraster", "elevation", "hfraster",
                            HfForward(0.5, 1.0), "elevation", VfBinary(1.0, -30, 30),  
                            "", "valueraster", "FID", "c:/sapyexamples/output/optpathdist", 
                            "c:/sapyexamples/output/optpathbl", "Multiplier", "StartCost", "Resistance", 500000)
pathAlloc.save("c:/sapyexamples/output/allocpath")

PathAllocation example 2 (stand-alone script)

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

# Name: PathAllocation_Ex_02.py
# Description: Calculates, for each cell, its nearest source based 
#              on the least accumulative cost over a cost surface, 
#              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"
costRast = "costraster"
surfaceRast = "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 = 25000
valRaster = "eucdirout"
sourceField = "FID"
optPathDistOut = "c:/sapyexamples/output/optdistpath"
optPathBLOut = "c:/sapyexamples/output/pathblinkout"

# Execute PathAllocation
pathAlloc = PathAllocation(inSource, costRast, surfaceRast, 
                           inHoriz, myHorizFactor, inVertical, myVerticalFactor, 
                           maxDist, valRaster, sourceField, 
                           optPathDistOut, optPathBLOut)

# Save the output 
pathAlloc.save("c:/sapyexamples/output/allocpath02")

Environments

Auto Commit, Cell Size, Cell Size Projection Method, Compression, Current Workspace, Extent, Geographic Transformations, Mask, Output CONFIG Keyword, Output Coordinate System, Parallel Processing Factor, Scratch Workspace, Snap Raster, Tile Size

Licensing information

• Basic: Requires Spatial Analyst
• Standard: Requires Spatial Analyst
• Advanced: Requires Spatial Analyst