Distance Allocation function—ArcGIS Pro

Available with Spatial Analyst license.

Overview

Calculates distance allocation for each cell to the provided sources based on straight-line distance, cost distance, and true surface distance, as well as vertical and horizontal cost factors.

This is a global raster function.

Notes

If you have source features, you can first convert them to a raster dataset using the Rasterize Features function. Use a consistent input for the Raster input to that function. This will ensure that the features are properly converted to a raster dataset using the same cell size, extent, and spatial reference.

The NoData values that exist in the Source Raster are not included as valid values in the function. The value 0 is considered a legitimate value in the source raster. A Source Raster can be created using the extraction tools or the Clip function.

Barriers are obstacles that must be routed around. They can be defined in two ways.

For the Input barrier raster parameter, barriers can be represented either by cells that have a valid value or by feature data that is converted to a raster. Where barriers are connected only by diagonal cells, the barriers will be thickened to make them impermeable.

Barriers are also defined by locations where NoData cells exist in the following inputs: Input cost raster, Input surface raster, Input vertical raster, and Input horizontal raster. Where NoData is connected only by diagonal cells, it will be thickened with additional NoData cells to make it an impermeable barrier.

If the input Surface Raster value has a vertical coordinate system (VCS), the values of the surface raster are considered to be in the units of the VCS. If the input Surface Raster value does not have a VCS and the data is projected, the surface values are considered to be in the linear units of the spatial reference. If the input Surface Raster does not have a VCS and the data is not projected, the surface values are considered to be in meters. The final distance accumulation result is in cost per linear unit, or in linear units if no cost is introduced.

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 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 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   ~

Checking the Boolean option Generate source row and column as additional bands in output will result in a multiband raster consisting of three bands. The first band is the distance allocation band, the second band contains a row index, and the third band contains a column index. These indices identify the location of the source cell that is the least accumulated cost distance away. The source row index and source column index can be used together to perform intensity mapping. If you query any location in your study area across band two and three, you will know the row and column of the least cost source for that location.

The characteristics of the source, or the movers from or to a source, can be controlled by specific parameters.

Initial accumulation sets the starting cost before the movement begins.
Maximum accumulations specifies how much cost a source can accumulate before reaching its limit.
Multiplier to apply to costs specifies the mode of travel.
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 value, that value is applied to all of the sources. If the parameters are specified through fields associated with the Source Raster, the values in the table will be uniquely applied to the corresponding sources.

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

When no Extent environment setting is specified then the processing extent is determined in the following way.

If only the Source Raster and Raster Barriers are specified then the union of the inputs, expanded by two cell widths on each side, is used as the processing extent. The reason the output raster is expanded by two rows and columns is so that the outputs can be used in Optimal Path As Raster function or Optimal Path As Line geoprocessing tool the generated paths can move around the barriers. To use the extent as an implicit barrier you must explicitly set the Extent value in the environment settings.
The processing extent will be the intersection of Surface Raster, Cost Raster, Vertical Raster, or Horizontal Raster, if specified.

The analysis Mask environment can be set to a feature class or a raster dataset. If the mask is a feature, it will be converted to a raster. The cells that have a value define the locations that are within the mask area. NoData cells define the locations that are outside the mask area and will be treated as a barrier.

When Cell Size or Snap Raster environment settings are not specified, and there are multiple rasters specified as inputs, then the Cell Size and Snap Raster environments are set based on an order of precedence: Cost Raster, Surface Raster, Vertical Raster, Horizontal Raster, Source Raster and Raster Barriers.

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 name	Description
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.
Source Field	The field used to assign values to the source locations. It must be an integer type.
Raster Barriers	The raster that defines the barriers. The dataset must contain NoData where there are no barriers. Barriers are represented by valid values including zero. The barriers can be defined by an integer or a floating-point raster.
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.
Cost Raster	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.
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.
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.
Source Row and Column Bands	Determines whether only the allocation raster is created or if a multiband result is created. Unchecked—The result is the distance allocation raster. This is a single-band result. This is the default. Checked—A multiband raster is created. The first band is the distance allocation raster, the second band contains a row index and the third band contains a column index. These indices identify the location of the source cell that is the least accumulated cost distance away.
Initial Accumulation	The initial accumulative cost to begin the cost calculation. 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. A numeric (double) value or a field from the Source Raster can be used for this parameter. The value must be zero or greater. The default is 0.
Maximum Accumulation	Defines the maximum accumulative cost for the traveler for a source. The cost calculations continue for each source until the specified capacity is reached. A numeric (double) value or a field from the Source Raster can be used for this parameter. The value must be greater than zero. The default capacity is to the edge of the output raster.
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.
Travel Direction	Defines the direction of the traveler when applying vertical factor, horizontal factor and the source resistance rate. From Source—The vertical factor, horizontal factor and 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 vertical factor, horizontal factor and 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.
Distance Method	Determines whether the distance will be calculated using a planar (flat earth) or a geodesic (ellipsoid) method. Planar—Planar measurements use 2D Cartesian mathematics to calculate length and area. The option is only available when measuring in a projected coordinate system and the 2D plane of that coordinate system will be used as the basis for the measurements. Geodesic—The shortest line between two points on the earth's surface on a spheroid (ellipsoid). Regardless of input or output projection, the results will not change. Note: One use for a geodesic line is when you want to determine the shortest distance between two cities for an airplane's flight path. This is also known as a great circle line if based on a sphere rather than an ellipsoid.

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:

Overview

Notes

Parameters

Note:

Environment settings

Related topics

In this topic