The Distance Allocation tool calculates allocation for each cell to input sources based on straight-line distance, cost distance, and true surface distance, as well as vertical and horizontal cost factors.
The outputs are hosted imagery layers.
Learn how Distance Allocation works
Examples
Example scenarios for this tool include the following:
- Identify the allocated areas that field workers are responsible for covering.
- Identify areas that are allocated to habitat patches for bobcats.
Usage notes
To properly handle the edge of the projection at a global extent when performing distance analysis at a global scale, ensure that either a cylindrical projection or a geographic output coordinate system is used in conjunction with the Geodesic option for the Distance Method parameter.
Distance Allocation includes configurations for input layers, distance settings, and result layers.
Input layers
The Input layers group includes the following parameters:
Input source raster or features specifies the raster or feature layer that identifies the sources to which the allocation is calculated. You can choose a layer using the Layer button, or use the Draw input features button to create a sketch layer to use as the input. For feature inputs, a count of features is displayed below the layer name. The count includes all features in the layer, except features that have been removed using a filter. Environment settings, such as Processing extent, are not reflected in the feature count.
If the input is a raster, it must consist of cells that have valid values (zero is a valid value) for the sources, and the remaining cells must be assigned NoData.
If the input is a feature layer, it can be point, line, or polygon.
When the input source data is a feature, 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.
To avoid this situation, as an intermediate step, you can rasterize the input features directly using the Convert Feature to Raster tool and set the Value field parameter. Then use the resulting output as input to the distance tool you want to use.
If a source falls on NoData in any of the corresponding input rasters, it is ignored in the analysis, and therefore no allocation will be calculated from that source.
When using feature data for the input source data, be aware of whether the output cell size is coarse relative to the detail present in the input. The internal rasterization process uses a cell center method for the cell assignment type. This means that data that is not located at the center of the cell will not be included in the intermediate rasterized source output, and it will not be represented in the distance calculations. For example, if the 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 using the Convert Feature to Raster tool and set the Value field parameter. Then use the resulting output as input to the 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.
Input source field is used to assign values to the source locations. The field must be of integer type.
The Optional layers group includes the following parameters:
Input barrier raster or features is a dataset that defines the barriers. Barriers are obstacles that must be routed around. They can be defined either as raster or feature.
You can choose a layer using the Layer button, or use the Draw input features button to create a sketch layer to use as the input. For feature inputs, a count of features is displayed below the layer name. The count includes all features in the layer, except features that have been removed using a filter. Environment settings, such as Processing extent, are not reflected in the feature count.
For a raster layer, the input type can be integer or float. Any cells that have a value (including zero) will be treated as a barrier. Any cells that are NoData will not be treated as a barrier.
For a feature, the input can be point, line, or polygon. Feature inputs will be converted internally to a raster before being processed.
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 Input cost raster, Input surface raster, Input vertical raster, and Input horizontal raster parameters. Where NoData cells are connected only by diagonal cells, they will be thickened with additional NoData cells to make an impermeable barrier.
Input surface raster is 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.
If the Input surface raster parameter has a vertical coordinate system (VCS), the values of the surface raster are considered to be in the units of the VCS. If the surface raster 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 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.
Input cost raster is 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. Cost raster values that are negative or zero are invalid but will be treated as small positive cost values. The accumulative cost algorithm is a multiplicative process, and it cannot calculate accumulative cost correctly if cost values are negative or zero. If the cost raster contains those values, and those locations represent areas that are to be excluded from the analysis, turn those cells into NoData before running the tool. You can do this using the Set Null tool. The NoData value is treated as a barrier in this analysis, so any locations that are NoData in the input will be NoData in the result.
Distance settings
The Distance settings group includes the following parameter groups:
Distance method specifies whether the distance will be calculated using a planar (flat earth) method or a geodesic (ellipsoid) method.
- Planar—The distance calculation will be performed on a projected flat plane using a 2D Cartesian coordinate system. This is the default method.
- Geodesic—The distance calculation will be performed on the ellipsoid. Regardless of the input or output projection, the results will not change.
The Vertical movement group includes the following parameters:
Input vertical raster is 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.
Vertical factor defines the relationship between the vertical cost factor and the vertical relative moving angle.
There are several factors with modifiers available that identify a defined vertical factor graph. The graphs are used to identify the vertical factor used in calculating the total cost of moving into a neighboring cell.
In the descriptions below, The VF defines the vertical difficulty encountered in moving from one cell to the next, and the VRMA modifier identifies the slope angle between the From source cell and the To source cell.
The vertical factor parameter types 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.
- Inverse linear—The VF is an inverse 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, and the two linear functions are symmetrical with respect to the VF (y) axis.
- Symmetric inverse linear—The VF is an inverse linear function of the VRMA in either the negative or positive side of the VRMA, 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.
- Hiking time—The VF defines the relationship between the vertical cost factor and the VRMA through the reciprocal of Tobler's function, which results in hiking time in hours.
- Bidirectional hiking time—The VF defines the relationship between the vertical cost factor and the VRMA through a bidirectional hiking function.
The modifiers to the vertical factor parameters are as follows:
- 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 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).
The default values for the vertical factor modifiers are the following:
Function Zero factor Low cut angle High cut angle Slope Power Cos power Sec power Binary
1
-30
30
N/A
N/A
N/A
N/A
Linear
1
-90
90
1.111E-02
N/A
N/A
N/A
Inverse linear
1
-45
45
-2.222E-02
N/A
N/A
N/A
Symmetric linear
1
-90
90
1.111E-02
N/A
N/A
N/A
Symmetric inverse linear
1
-45
45
-2.222E-02
N/A
N/A
N/A
Cos
N/A
-90
90
N/A
1
N/A
N/A
Sec
N/A
-90
90
N/A
1
N/A
N/A
Cos - Sec
N/A
-90
90
N/A
N/A
1
1
Sec - Cos
N/A
-90
90
N/A
N/A
1
1
Hiking time
N/A
-70
70
N/A
N/A
N/A
N/A
Bidirectional hiking time
N/A
-70
70
N/A
N/A
N/A
N/A
The Horizontal movement group includes the following parameters:
Input horizontal raster is 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 value 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.
There are several factors with modifiers available that identify a defined horizontal factor 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, horizontal factor (HF) defines the horizontal difficulty encountered when moving from one cell to the next, and horizontal relative moving angle (HRMA) identifies the angle between the horizontal direction from a cell and the moving direction.
The horizontal factor parameter types 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 (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.
The modifiers to the horizontal factor parameters are as follows:
- Zero factor—The horizontal factor used when the HRMA is 0. 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.
The default values for the horizontal factor modifiers are the following:
Function Zero factor Cut angle Slope Side value Binary
1
45
N/A
N/A
Forward
0.5
N/A
N/A
1
Linear
0.5
181
1.111E-02
N/A
Inverse linear
2
180
-1.111E-02
N/A
The Source characteristics group includes the following list of parameters.
If any of the Source characteristics values 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 provided, it will be applied to all sources.
Initial accumulation is the initial accumulative cost to begin the cost calculation.
If the Initial accumulation value 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 distance accumulation raster will be set to zero.
The values must be zero or greater. The default is 0.
Maximum accumulation is the maximum accumulation for the traveler for a source.
The cost calculations continue for each source until the specified accumulation is reached.
The values must be greater than zero. The default accumulation is to the edge of the output raster.
Cost multiplier is a multiplier to apply 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.
Travel direction specifies the direction of the traveler when applying horizontal and vertical factors.
From source—The horizontal factor and vertical factor will be applied beginning at the input source and travel out to the nonsource cells. This is the default.
To source—The horizontal factor and vertical factor 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 FROM_SOURCE or TO_SOURCE string.
Results layers
The Result layers group includes the following parameters:
Output distance allocation raster name is the name of the raster that indicates the closest, or least-cost, source for each cell to reach.
The name must be unique. If a layer with the same name already exists in your organization, the tool will fail and you will be prompted to use a different name.
The Optional layers group includes the following parameters:
Output distance accumulation raster name is the name of the output raster that contains the accumulative distance for each cell from, or to, the least-cost source.
- Output back direction raster name is the name of the optional output raster that contains the calculated direction in degrees.
- Output source direction raster name is the name of the optional output raster that identifies the direction of the least accumulated cost source cell as an azimuth in degrees.
- Output source location raster name is the name of the optional output raster that identifies the source locations as a multiband output.
The name of each optional output must be unique. If any layer with the same name already exists in your organization, the tool will fail and you will be prompted to use a different name.
- Save in folder specifies the name of a folder in My content where the result will be saved.
Environments
Analysis environment settings are additional parameters that affect a tool's results. You can access the tool's analysis environment settings from the Environment settings parameter group.
This tool honors the following analysis environments:
- Cell size
- Processing extent
Note:
The default processing extent is Full extent. This default is different from Map Viewer Classic in which Use current map extent is enabled by default.
- Mask
- Output coordinate system
- Snap raster
- Parallel processing factor
Outputs
This tool includes the following outputs:
The Output distance allocation raster name layer indicates the closest or least-cost source for each cell to reach.
The Output distance accumulation raster name layer records the accumulative distance for each cell from, or to, the least-cost source.
This raster is of type float.
The Output back direction raster name layer records the calculated back direction in degrees. The direction identifies the next cell along the shortest path back to the closest source while avoiding barriers.
The range of values is from 0 degrees to 360 degrees, with 0 reserved for the source cells. Due east (right) is 90, and the values increase clockwise (180 is south, 270 is west, and 360 is north).
This raster is of type float.
-
The Output source direction raster name layer records the direction of the least accumulated cost source cell as an azimuth in degrees.
The range of values is from 0 degrees to 360 degrees, with 0 reserved for the source cells. Due east (right) is 90, and the values increase clockwise (180 is south, 270 is west, and 360 is north).
This raster is of type float.
The Output source location raster name layer identifies the source locations as a multiband output. The first band contains a row index, and the second band contains a column index.
These indexes identify the location of the source cell that is the least accumulated cost distance away.
Usage requirements
This tool requires the following user type and configurations:
References
- Douglas, D. "Least-cost Path in GIS Using an Accumulated Cost Surface and Slopelines", Cartographica: The International Journal for Geographic Information and Geovisualization, 1994, Vol. 31, No. 3, DOI: 10.3138/D327-0323-2JUT-016M
- Goodchild, M.F. "An evaluation of lattice solutions to the problem of corridor location", Environment and Planning A: Economy and Space, 1977, Vol. 9, pages 727-738
- Sethian, J.A.. "Level Set Methods and Fast Marching Methods", Evolving Interfaces in Computational Geometry, Fluid Mechanics, Computer Vision, and Materials Science, Cambridge University Press, 2nd Edition, 1999
- Warntz, W. "Transportation, Social Physics, and the Law Of Refraction", The Professional Geographer, 1957, Vol. 9, No. 4, pages 2-7
- Zhao, H. "A fast sweeping method for Eikonal equations", Mathematics off Computation, 2004, Vol. 74, No, 250, pages 603-627
Resources
Use the following resources to learn more:
- How Distance Allocation works
- Distance Allocation in ArcGIS REST API
- distance_allocation in ArcGIS API for Python
- Distance Allocation in ArcGIS Pro with the Raster Analysis extension
- Distance Allocation in ArcGIS Pro with the Spatial Analyst extension