Distance Accumulation (Spatial Analyst Tools)
Summary
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.
Usage
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. Zero is a valid value. 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 longer of the width or height of the extent of the input feature, in the input spatial reference, divided by 1,000.
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 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 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.
Barriers are obstacles that must be routed around. They can be defined in two ways.
For the Input Raster or Feature Barrier 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.
Cost raster values that are negative or zero are invalid but will be treated as small positive 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.
If a source falls on NoData in any of the corresponding input rasters, it will be ignored in the analysis and no distance from that source will be calculated.
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 Hiking time ~ -70 70 ~ ~ ~ ~ Bidirectional hiking time ~ -70 70 ~ ~ ~ ~The output of the Aspect tool can be used as input for the Input 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 ~The characteristics of the source, or the movers from or to a source, can be controlled by the following parameters:
Initial Accumulation sets the initial cost before the movement begins.
Maximum Accumulation specifies how much cost a source can accumulate before reaching its limit.
Cost Multiplier specifies the mode of travel or magnitude at the source.
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 characteristic parameters are specified using a field, the source characteristic will be applied on a source-by-source basis, according to the information in the specified field for the source data. When a keyword or a constant value is provided, it will be applied to all sources.
If the Initial Accumulation parameter value is specified, the source locations on the output cost distance surface will be set to that value; otherwise, the source locations on the output cost distance surface will be set to zero.
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.
When no Extent environment setting is specified, the processing extent is determined in the following way:
If only the Input Raster or Feature Sources and Input Raster or Feature Barriers values are specified, the union of the inputs, expanded by two cell widths on each side, will be used as the processing extent. The reason the output raster is expanded by two rows and columns is so the outputs can be used in the Optimal Path As Line and Optimal Path As Raster tools, and 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 the Input Surface Raster, Input Cost Raster, Input Vertical Raster, or Input Horizontal Raster parameter value if specified.
The analysis Mask environment can be set to a feature 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 this order of precedence: Input Cost Raster, Input Surface Raster, Input Vertical Raster, Input Horizontal Raster, Input Raster or Feature Sources, and Input Raster or Feature Barriers.
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 administrative 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.
When the output raster format is
.crf, this tool supports the Pyramid raster storage environment. Pyramids will be created in the output by default. For any other output format, this environment is not supported, and pyramids will not be created.See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.
Parameters
| Label | Explanation | Data type |
|---|---|---|
|
Input Raster or Feature Sources |
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. |
Raster Layer; Feature Layer |
|
Input Raster or Feature Barriers (Optional) |
The dataset that defines the barriers. The barriers can be defined by an integer or a floating-point raster, or by a point, line, or polygon feature. For a raster barrier, the barrier must have a valid value, including zero, and the areas that are not barriers must be NoData. |
Raster Layer; Feature 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 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. Cost raster values that are negative or zero are invalid but will be treated as small positive cost values. |
Raster Layer |
|
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 option 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; VRMA stands for vertical relative moving angle, which identifies the slope angle between the FROM or processing cell and the TO cell. The options are as follows:
The modifiers to the vertical keywords are the following:
|
Vertical Factor |
|
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 option 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; HRMA stands for horizontal relative moving angle, which identifies the angle between the horizontal direction from a cell and the moving direction. The options are as follows:
The modifiers to the horizontal factors are the following:
|
Horizontal Factor |
|
Output Back Direction Raster (Optional) |
The back direction raster contains the calculated 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 is 90, and the values increase clockwise (180 is south, 270 is west, and 360 is north). The output raster is of type float. |
Raster Dataset |
|
Output Source Direction Raster (Optional) |
The source direction raster identifies 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 is 90, and the values increase clockwise (180 is south, 270 is west, and 360 is north). The output raster is of type float. |
Raster Dataset |
|
Output Source Location Raster (Optional) |
The source location raster is 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. |
Raster Dataset |
|
Initial Accumulation (Optional) |
The initial accumulative cost that will be used to begin the cost calculation. 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 this value. The values must be zero or greater. The default is 0. |
Double; Field |
|
Maximum Accumulation (Optional) |
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. |
Double; Field |
|
Costs 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 |
|
Travel Direction (Optional) |
Specifies the direction of the traveler when applying horizontal and vertical factors. 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
|
String; Field |
|
Distance Method (Optional) |
Specifies whether the distance will be calculated using a planar (flat earth) or a geodesic (ellipsoid) method.
|
String |
Return value
| Label | Explanation | Data type |
|---|---|---|
|
Output Distance Accumulation Raster |
The output distance raster. The output raster is of floating-point type. |
Raster |
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, Pyramid, Scratch Workspace, Snap Raster, Tile Size
Licensing information
- Basic: Requires Spatial Analyst
- Standard: Requires Spatial Analyst
- Advanced: Requires Spatial Analyst