Available with Spatial Analyst license.
Summary
Calculates distance allocation for each cell to the provided sources based on straight-line distance, cost distance, true surface distance, as well as vertical and horizontal cost factors.
Usage
The input source data can be a feature class or raster.
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. 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 shorter of the width or height of the extent of the input feature, in the input spatial reference, divided by 250.
If there is NoData on any of these inputs: Input cost raster, Input surface raster, Input vertical raster, or Input horizontal raster, the cells at those locations across all inputs are ignored in the calculation. NoData on any of these rasters is persisted throughout the calculation and therefore is NoData on all outputs.
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.
When no Extent environment setting is specified, the processing extent is determined in the following way:
If only the Input raster or feature source data and Input barrier raster or feature data are specified, 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 are used in Optimal Path As Line and Optimal Path As Raster and the generated paths can move around the barriers. To use the extent as an implicit barrier, you must explicitly set the Extent in the environment settings.
If any of the following raster datasets are specified, Input surface raster, Input cost raster, Input vertical raster, or Input horizontal raster, the processing extent is the intersection of these rasters.
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 are set based on an order of precedence: Input cost raster, Input surface raster, Input vertical raster, Input horizontal raster, Input raster or feature source data, and Input barrier raster or feature data.
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 tool can be used as input for the Input horizontal raster.
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.
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. The Parallel processing with Spatial Analyst help topic has 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 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.
See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.
Syntax
DistanceAllocation(in_source_data, {in_barrier_data}, {in_surface_raster}, {in_cost_raster}, {in_vertical_raster}, {vertical_factor}, {in_horizontal_raster}, {horizontal_factor}, {out_distance_accumulation_raster}, {out_back_direction_raster}, {out_source_direction_raster}, {out_source_location_raster}, {source_field}, {source_initial_accumulation}, {source_maximum_accumulation}, {source_cost_multiplier}, {source_direction}, {distance_method})| Parameter | Explanation | Data Type |
in_source_data | The input source locations. This is a raster or feature dataset that identifies the cells or locations from or to which the least accumulated cost distance for every output cell location is calculated. For rasters, the input type can be integer or floating point. | Raster Layer; Feature Layer |
in_barrier_data (Optional) | The dataset that defines the barriers. The barriers can be defined by an integer or a floating-point raster, or by a feature layer. 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 |
in_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 |
in_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). | Raster Layer |
in_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) | The Vertical factor object defines the relationship between the vertical cost factor and the vertical relative moving angle (VRMA). There are several factors with modifiers from which to select 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 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; and VRMA stands for vertical relative moving angle, which identifies the slope angle between the FROM or processing cell and the TO cell. The object comes in the following forms:
The definitions and parameters of these are the following:
The modifiers to the vertical parameters are the following:
| Vertical Factor |
in_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 to determine the horizontal cost incurred when moving from a cell to its neighbors. | Raster Layer |
horizontal_factor (Optional) | The Horizontal Factor object defines the relationship between the horizontal cost factor and the horizontal relative moving angle. There are several factors with modifiers from which to select 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 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; and HRMA stands for horizontal relative moving angle, which identifies the angle between the horizontal direction from a cell and the moving direction. The object comes in the following forms:
The definitions and parameters of these are the following:
The modifiers to the horizontal keywords are the following:
| Horizontal Factor |
out_distance_accumulation_raster (Optional) | The output distance raster. The distance accumulation raster contains the accumulative distance for each cell from, or to, the least-cost source. | Raster Dataset |
out_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 (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. | Raster Dataset |
out_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 (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. | Raster Dataset |
out_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 |
source_field (Optional) | The field used to assign values to the source locations. It must be of integer type. | Field |
source_initial_accumulation (Optional) | The initial accumulative cost 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 the value set by source_initial_accumulation. The values must be zero or greater. The default is 0. | Double; Field |
source_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 |
source_cost_multiplier (Optional) | The 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. | Double; Field |
source_direction (Optional) | Specifies the direction of the traveler when applying horizontal and vertical factors.
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 string FROM_SOURCE or TO_SOURCE. | String; Field |
distance_method (Optional) | Specifies whether to calculate the distance using a planar (flat earth) or a geodesic (ellipsoid) method.
| String |
Return Value
| Name | Explanation | Data Type |
| out_distance_allocation_raster | The output distance allocation raster. | Raster |
Code sample
The following Python window script demonstrates how to use the DistanceAllocation tool.
import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
outDistAlloc = DistanceAllocation("insources.shp", "barriers.tif")
outDistAlloc.save("c:/sapyexamples/output/distalloc.tif")Calculate, for each cell, the least accumulative cost distance to the nearest source, while accounting for surface distance and horizontal and vertical cost factors.
# Name: DistanceAllocation_Ex_02.py
# Description: Calculates the distance allocation.
# Requirements: Spatial Analyst Extension
# Import system modules
import arcpy
from arcpy import env
from arcpy.sa import *
# Set environment settings
env.workspace = "C:/sapyexamples/data"
# Set local variables
inSources = "insources.shp"
inBarrier = "barriers.tif"
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Execute EucDirections
outDistAlloc = DistanceAllocation(inSources, inBarrier)
# Save the output
outDistAlloc.save("c:/sapyexamples/output/distAllo2.tif")Environments
Licensing information
- Basic: Requires Spatial Analyst
- Standard: Requires Spatial Analyst
- Advanced: Requires Spatial Analyst