Overview
Calculates accumulated distance for each cell to sources, allowing for 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 value 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.0The 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 back direction band as additional band in output will result in a multiband layer being created. The first band is the distance accumulation raster and the second band is the back direction raster. Both of these rasters are needed to generate an optimal path from the sources to a given destination. To generate a path, first use Extract Band function to extract the distance accumulation raster and the back direction raster, these layers are used as input to the Cost Path function. The distance accumulation raster will be used as the Cost Distance Raster and the back direction raster will be used as the Cost Backlink Raster.
The characteristics of the source, or the movers from or to a source, can be controlled by the following parameters:
- Initial accumulation—Set the starting cost before the movement begins.
- Maximum accumulations—Specify how much cost a source can accumulate before reaching its limit.
- Multiplier to apply to costs—Specify the mode of travel.
- Travel direction—Specify 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, the processing extent is determined by the following:
If only the Source Raster and Raster Barriers values are specified, the union of the inputs—expanded by two cell widths on each side—is used as the processing extent. The output raster is expanded by two rows and columns so the outputs can be used in the Optimal Path As Raster function or Optimal Path As Line tool and 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 the Surface Raster, Cost Raster, Vertical Raster, or Horizontal Raster values, 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 the Cell Size or Snap Raster environment settings are not specified, and there are multiple rasters specified as inputs, the Cell Size and Snap Raster environments are set based on the following 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. It can be an integer or a floating-point 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:
Modifiers to the vertical keywords include the following:
|
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:
Modifiers to the horizontal factors include the following:
|
Generate back direction band as additional band in output |
Determines whether only the distance accumulation raster is created or a multiband raster consisting of both the distance accumulation raster and the back direction raster is created.
The back direction raster calculates, for each cell, the direction, in degrees, to the neighboring cell along the shortest path back to the closest source while avoiding barriers. |
Distance Method | Determines whether the distance will be calculated using a planar (flat earth) or a geodesic (ellipsoid) method.
|
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. A numeric (double) value or a field from the Source Raster can be used for this parameter. The values must be greater than zero. The default is 1. |
Travel Direction | Defines the direction of the traveler when applying vertical factor, horizontal factor and the source resistance rate.
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: