Available with Spatial Analyst license.
Overview
Calculates, for each cell, its least-cost source based on the least accumulative cost over a cost surface.
Legacy:
This function is deprecated and will be removed in a future release.
The Distance Allocation function provides enhanced functionality or performance.
Learn more about how cost distance tools work
This is a global raster function.
Notes
The input source data must be a raster layer.
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.
If you have source features, you can convert them to a raster dataset using the Rasterize Features function. Use your existing Cost Raster as the Raster input to the rasterization function. This will ensure that the features are properly converted to a raster dataset using the same cell size, extent, and spatial reference.
To calculate allocation, source locations can have an associated value that can be specified by the Source Field parameter. If the input source is an integer raster, the default field is VALUE. If the input Source Raster is a floating-point raster, an integer Value Raster parameter must be specified.
Cell values of NoData in the Cost Raster act as barriers in the cost surface. Any cells that are assigned a value of NoData in the Cost Raster will also have a value of NoData in the output raster. The Cost Raster cannot contain a value of 0 since the algorithm is a multiplicative process. If values of 0 represent areas of low cost, change the value of 0 to a small positive value such as 0.01 using the Con function. If the value of 0 represents areas that should be excluded from the analysis, these values should be turned into NoData using the Set Null function.
If the Source Raster and the Cost Raster have different extents, the default output extent is the intersection of the two rasters. If you want a cost distance surface output of the entire extent, choose the Union of Inputs option on the Output Extent geoprocessing environment.
The Maximum Distance is specified in the same cost unit as the Cost Raster.
The Value Raster is useful if the Source Raster was derived from an operation that resulted in Boolean cell values. These operations cause the Source Raster to lose the original zone values that were associated with the source cell locations. The Value Raster can either restore these cell values or allow analysis on additional combinations of zone values within the source cells. If the Value Raster is used, it may change the configuration and results of the output.
The characteristics of the source, or the movers from a source, can be controlled by the following parameters:
- Multiplier to Apply to Costs—The mode of travel or magnitude at the source.
- Start Cost—The starting cost before the movement begins.
- Accumulative Cost Resistance Rate—A dynamic adjustment accounting for the impact of accumulated cost; for example, simulating how much a hiker is becoming fatigued.
- Capacity—The cost a source can assimilate before reaching its limit.
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 the Mask has been set in the geoprocessing environments, all masked cells will be treated as NoData values. When a mask is defined in the Raster Analysis window and the cells to be masked will mask a source, the calculations will occur on the remaining source cells. The source cells that are masked will not be considered in the computations. These cell locations will be assigned NoData in the output raster. See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this function.
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. If the input Source Raster is floating point, the Value Raster must be set, and it must be an integer. The Value Raster will take precedence over any setting of the Source Field. |
Source Field | The field used to assign values to the source locations. It must be an integer type. If the Value Raster has been set, the values in that input will take precedence over any setting for the Source Field. |
Cost Raster (Required) | 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. |
Maximum Distance | The threshold that the accumulative cost values cannot exceed. If an accumulative cost distance exceeds this value, the output value for the cell location will be NoData. The maximum distance defines the extent for which the accumulative cost distances are calculated. The default distance is to the extent of the output raster. |
Value Raster | The input integer raster that identifies the zone values to be used for each input source location. For each source location cell, the value defined by the Value Raster will be assigned to all cells allocated to the source location for the computation. The Value Raster will take precedence over any setting for the Source Field. |
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. The values must be greater than zero. The default is 1. A numeric (double) value or a field from the Source Raster can be used for this parameter. |
Start Cost | The starting cost that will be used to begin the cost calculations. 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. The value must be zero or greater. The default is 0. |
Accumulative Cost Resistance Rate | This parameter simulates the increase in the effort to overcome costs as the accumulative cost increases. It is used to model fatigue of the traveler. The growing accumulative cost to reach a cell is multiplied by the resistance rate and added to the cost to move into the subsequent cell. It's a modified version of a compound interest rate formula that's used to calculate the apparent cost of moving through a cell. As the value of the resistance rate increases, it increases the cost of the cells that are visited later. The greater the resistance rate, the higher the cost to reach the next cell, which is compounded for each subsequent movement. Since the resistance rate is similar to a compound rate and generally the accumulative cost values are very large, small resistance rates are suggested, such as 0.005 or even smaller, depending on the accumulative cost values. The value must be greater than zero. The default capacity is to the edge of the output raster. A numeric (double) value or a field from the Source Raster can be used for this parameter. |
Capacity | Defines the cost capacity for the traveler for a source. The cost calculations continue for each source until the specified capacity is reached. The value must be greater than zero. The default capacity is to the edge of the output raster. A numeric (double) value or a field from the Source Raster can be used for this parameter. |
Travel Direction | Defines the direction of the traveler when applying 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: