The Distance Accumulation tool calculates accumulated distance from each cell to input sources.
Note:
This tool is now available in Map Viewer, the modern map-making tool in ArcGIS Enterprise. To learn more, see Distance Accumulation (Map Viewer).
To run this tool, the portal must be configured for raster analysis.
If you do not see this tool in Map Viewer Classic, contact your organization administrator. Your portal may not be configured for raster analysis, or you may not have the privileges required to run the tool.
Workflow diagram
Examples
Example applications include answering questions such as the following:
- What is the distance to the closest town?
- What is the cost distance to the closest road?
- What is the distance around barriers to the closest water source?
Usage notes
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.
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 could rasterize the input features directly with the Convert 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.
If a source falls on NoData in any of the corresponding input rasters, it is ignored in the analysis, and therefore no distance from that source will be calculated.
If the input surface raster 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 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.
Barriers are obstacles that must be routed around. They can be defined in two ways.
For the Choose barrier raster or feature 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:Choose cost raster, Choose surface raster, Choose vertical raster, and Choose horizontal raster. Where NoData is connected only by diagonal cells, it will be thickened with additional NoData cells to make it an impermeable barrier.
The cost raster cannot contain values of zero since the algorithm is a multiplicative process. If your cost raster does contain values of zero, and these values represent areas of lowest cost, change those cells to a small positive value (such as 0.01) before running this tool.
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 Derive Aspect tool can be used as input for the Choose 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 specific 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.
- Multiplier to apply to costs 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 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 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 in the following way:
If only the source and the barrier data are specified, the union of the inputs, expanded by two cell widths on each side, will used as the processing extent. The reason the output raster is expanded by two rows and columns is so that when the outputs can be used in Optimal Path As Raster and Optimal Path As Line 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 Barriers.
When the Cell Size or Snap Raster environment settings are not specified, and there are multiple rasters specified as inputs, Cell Size and Snap Raster environments are set based on an order of precedence: cost raster, surface raster, vertical raster, horizontal raster, source data, and barrier data.
The parameters for this tool are listed in the following table:
Parameter | Explanation |
---|---|
Choose source raster or features | A raster or feature layer that identifies the sources to which the distance will be calculated. 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. |
Choose barrier raster or feature (optional) | The dataset that defines the barriers. For a raster, 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 service, the input can be point, line, or polygon. |
Choose surface raster (optional) | Specifies whether the distance will be calculated using a planar (flat earth) or a geodesic (ellipsoid) method. The values are used to calculate the actual surface distance covered when passing between cells. |
Choose 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). |
Choose 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. |
Vertical factor (optional) | The Vertical factor defines the relationship between the vertical cost factor (VF) and the vertical relative moving angle (VRMA). This option is only available if Choose vertical raster (optional) is specified. There are several factors with modifiers 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 modifiers to the vertical parameters are as follows:
|
Choose 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. |
Horizontal factor (optional) | The Horizontal factor defines the relationship between the horizontal cost factor and the horizontal relative moving angle. This option is only available if Choose horizontal raster (optional) is specified. There are several factors with modifiers 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 definitions and parameters of these HF are as follows:
The modifiers to the horizontal keywords are as follows:
|
Initial accumulation (optional) | The initial accumulative cost that will be used to begin the cost calculation. This 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 Initial accumulation. The values must be zero or greater. The default is 0. |
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. |
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. |
Travel direction (optional) | 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. |
Distance method (optional) | Specifies whether the distance will be calculated using a planar (flat earth) or a geodesic (ellipsoid) method.
|
Result distance accumulation raster name | The distance accumulation raster contains the accumulative distance for each cell from, or to, the least-cost source. The output raster is of type float. The name of the layer that will be created in My Content and added to the map. The default name is based on the tool name and the input layer name. If the layer already exists, you will be prompted to provide another name. You can specify the name of a folder in My Content where the result will be saved using the Save result in drop-down box. |
Result back direction raster name (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 (right) is 90, and the values increase clockwise (180 is south, 270 is west, and 360 is north). The output raster is of type float. The name of the layer that will be created in My Content and added to the map. The default name is based on the tool name and the input layer name. If the layer already exists, you will be prompted to provide another name. You can specify the name of a folder in My Content where the result will be saved using the Save result in drop-down box. |
Result source direction raster name (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 (right) is 90, and the values increase clockwise (180 is south, 270 is west, and 360 is north). The output raster is of type float. The name of the layer that will be created in My Content and added to the map. The default name is based on the tool name and the input layer name. If the layer already exists, you will be prompted to provide another name. You can specify the name of a folder in My Content where the result will be saved using the Save result in drop-down box. |
Result source location raster name (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. The name of the layer that will be created in My Content and added to the map. The default name is based on the tool name and the input layer name. If the layer already exists, you will be prompted to provide another name. You can specify the name of a folder in My Content where the result will be saved using the Save result in drop-down box. |
Environments
Analysis environment settings are additional parameters that affect a tool's results. You can access the tool's analysis environment settings by clicking the gear icon at the top of the tool pane.
This tool honors the following Analysis Environments:
- Output coordinate system—Specifies the coordinate system of the output layer.
- Extent—Specifies the area to be used for analysis.
- Snap Raster—Adjusts the extent of the output so it matches the cell alignment of the specified snap raster layer.
- Cell size—The cell size to use in the output layer.
- Mask—Specifies a mask layer, where only the cells that fall within the mask area will be used for analysis.
- Parallel processing factor—Controls the raster processing CPU or GPU instances.
Similar tools and raster functions
The Distance Accumulation tool calculates accumulated distance from each cell to input sources. Other tools may be useful in solving similar problems.
Map Viewer Classic analysis tools and raster functions
Use the Distance Allocation tool or the Distance Allocation raster function if a distance allocation image service output is required.
Distance Accumulation is also available as a raster function.
ArcGIS Pro analysis tools and raster functions
The Distance Accumulation and Distance Allocation geoprocessing tools are available in the Spatial Analyst toolbox.
The Distance Accumulation and Distance Allocation geoprocessing tools are available in the Raster Analysis toolbox.
Distance Accumulation and Distance Allocation are available as raster functions.
ArcGIS Enterprise developers resources
If you are working in the ArcGIS REST API, use the Distance Accumulation and the Distance Allocation tasks.
If you are working in ArcGIS API for Python, use distance_accumulation and distance_allocation from the arcgis.raster.functions.gbl module.