Back to Top

Distance Allocation (Raster Analysis)

In this topic

  1. Summary
  2. Illustration
  3. Usage
  4. Parameters
  5. Environments
  6. Licensing information

Summary

Calculates distance allocation for each cell to the provided sources based on straight-line distance, cost distance, and true surface distance, as well as vertical and horizontal cost factors.

Illustration

Distance Allocation workflow

Usage

  • This raster analysis portal tool is available when you are signed in to an ArcGIS Enterprise portal that has ArcGIS Image Server configured for Raster Analysis. When the tool is run, ArcGIS Pro serves as a client and the processing occurs in the servers federated with ArcGIS Enterprise. The portal tool accepts layers from your portal as input and creates output in your portal.

    The input raster layer supports a layer from the portal, a URI or URL to an image service, or the output from the Make Image Server Layer tool. The input feature layer can be a layer from the portal or a URI or URL to a feature service. This tool does not support local raster data or layers. While you can use local feature data and layers as input to this portal tool, best practice is to use layers from your portal as input.

  • The input source data can be a feature service or an image service. The feature service can be point, line, or polygon.

  • 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 the input source data is an image service, 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 service, 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 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 could 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 Barriers 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 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 ArcGIS Spatial Analyst extension 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.

  • 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 Spatial Analyst 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 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.
    • 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 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 value 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.

  • 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 that 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 Input Surface Raster, Input Cost Raster, Input Vertical Raster, or Input Horizontal Raster, if specified.

  • The analysis Mask environment can be set to a feature service or an image service. 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 an 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.

  • See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.

Parameters

DialogPython

LabelExplanationData Type
Input Raster or Feature Sources

The input source locations.

This is an image service or feature service identifying the cells or locations from or to which the allocation for every output cell location is calculated.

For an image service, the input type can be integer or floating point. For a feature service, the input type can be point, line or polygon.

Raster Layer; Feature Layer
Output Distance Allocation Raster Name

The name of the output distance allocation raster service.

String
Input Raster or Feature Barriers
(Optional)

The dataset that defines the barriers.

The barriers can be defined by an integer or a floating-point image service, or by a feature service. For a feature service, the input type can be point, line or polygon.

For an image service 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)

An image service 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)

An image service 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)

An image service 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. 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, vertical factor (VF) defines the vertical difficulty encountered in moving from one cell to the next, and vertical relative moving angle (VRMA) identifies the slope angle between the FROM or processing cell and the TO cell.

The Vertical Factor options are as follows:

  • Binary—If the VRMA is greater than the low-cut angle and less than the high-cut angle, the VF is set to the value associated with the zero factor; otherwise, it is infinity.
  • Linear—The VF is a linear function of the VRMA.
  • Symmetric Linear—The VF is a linear function of the VRMA in either the negative or positive side of the VRMA, and the two linear functions are symmetrical with respect to the VF (y) axis.
  • Inverse Linear—The VF is an inverse linear function of the VRMA.
  • Symmetric Inverse Linear—The VF is an inverse linear function of the VRMA in either the negative or positive side of the VRMA, and the two linear functions are symmetrical with respect to the VF (y) axis.
  • Cos—The VF is the cosine-based function of the VRMA.
  • Sec—The VF is the secant-based function of the VRMA.
  • Cos-Sec—The VF is the cosine-based function of the VRMA when the VRMA is negative and is the secant-based function of the VRMA when the VRMA is not negative.
  • Sec-Cos—The VF is the secant-based function of the VRMA when the VRMA is negative and is the cosine-based function of the VRMA when the VRMA is not negative.
  • Hiking Time— Defines the relationship between the vertical cost factor and the vertical relative moving angle through the reciprocal of Tobler's function, which results in hiking time in hours.
  • Bidirectional Hiking Time—Defines the relationship between the vertical cost factor and the vertical relative moving angle through a bidirectional hiking function.

Modifiers to the vertical keywords are as follows:

  • Zero factor—The vertical factor used when the VRMA is zero. This factor positions the y-intercept of the specified function. By definition, the zero factor is not applicable to any of the trigonometric vertical functions (COS, SEC, COS-SEC, or SEC-COS). The y-intercept is defined by these functions.
  • Low Cut angle—The VRMA angle below which the VF will be set to infinity.
  • High Cut angle—The VRMA angle above which the VF will be set to infinity.
  • Slope—The slope of the straight line used with the Linear and Inverse Linear vertical factor keywords. The slope is specified as a fraction of rise over run (for example, 45 percent slope is 1/45, which is input as 0.02222).
Vertical Factor
Input Horizontal Raster
(Optional)

An image service 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. 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 Horizontal Factor options are as follows:

  • Binary—If the HRMA is less than the cut angle, the HF is set to the value associated with the zero factor; otherwise, it is infinity.
  • Forward—Only forward movement is allowed. The HRMA must be greater than or equal to 0 and less than 90 degrees (0 <= HRMA < 90). If the HRMA is greater than 0 and less than 45 degrees, the HF for the cell is set to the value associated with the zero factor. If the HRMA is greater than or equal to 45 degrees, the side value modifier value is used. The HF for any HRMA equal to or greater than 90 degrees is set to infinity.
  • Linear—The HF is a linear function of the HRMA.
  • Inverse Linear—The HF is an inverse linear function of the HRMA.

Modifiers to the horizontal factors are as follows:

  • Zero factor—The horizontal factor to be used when the HRMA is zero. This factor positions the y-intercept for any of the horizontal factor functions.
  • Cut angle—The HRMA angle beyond which the HF will be set to infinity.
  • Slope—The slope of the straight line used with the Linear and Inverse Linear horizontal factor keywords. The slope is specified as a fraction of rise over run (for example, 45 percent slope is 1/45, which is input as 0.02222).
  • Side value—The HF when the HRMA is greater than or equal to 45 degrees and less than 90 degrees when the Forward horizontal factor keyword is specified.
Horizontal Factor
Output Distance Accumulation Raster Name
(Optional)

The output distance accumulation raster name.

The distance accumulation raster contains the accumulative distance for each cell from, or to, the least-cost source.

String
Output Back Direction Raster Name
(Optional)

The output back direction raster name.

The back direction raster contains calculated directions in degrees. The direction identifies the next cell along the optimal path back to the least accumulative cost source while avoiding barriers.

The range of values is from 0 degrees to 360 degrees. The value 0 is reserved for the source cells. Due east (right) is 90 degrees, and the values increase clockwise (180 is south, 270 is west, and 360 is north).

The output raster is of type float.

String
Output Source Direction Raster Name
(Optional)

The output source direction raster name.

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. The value 0 is reserved for the source cells. Due east (right) is 90 degrees, and the values increase clockwise (180 is south, 270 is west, and 360 is north).

The output raster is of type float.

String
Output Source Location Raster Name
(Optional)

The output source location raster name.

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.

String
Source Field
(Optional)

The field used to assign values to the source locations. It must be of type integer.

Field
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 the value set by Initial accumulation.

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
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.

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 FROM_SOURCE or TO_SOURCE.

  • Travel 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.
  • Travel to source—The horizontal factor and vertical factor will be applied beginning at each nonsource cell and travel back to the input source.
String; Field
Distance Method
(Optional)

Specifies whether the distance will be calculated using a planar (flat earth) or a geodesic (ellipsoid) method.

  • Planar—The distance calculation will be performed on a projected flat plane using a 2D Cartesian coordinate system. This is the default.
  • Geodesic—The distance calculation will be performed on the ellipsoid. Regardless of input or output projection, the results will not change.
String

Derived Output

LabelExplanationData Type
Output Distance Allocation Raster

The output distance allocation raster.

Raster
Output Distance Accumulation Raster

The output distance accumulation raster.

Raster
Output Back Direction Raster

The output back direction raster.

Raster
Output Source Direction Raster

The output source direction raster.

Raster
Output Source Location Raster

The output source location raster.

Raster

arcpy.ra.DistanceAllocation(inputSourceRasterOrFeatures, outputDistanceAllocationRasterName, {inputBarrierRasterOrFeatures}, {inputSurfaceRaster}, {inputCostRaster}, {inputVerticalRaster}, {verticalFactor}, {inputHorizontalRaster}, {horizontalFactor}, {outputDistanceAccumulationRasterName}, {outputBackDirectionRasterName}, {outputSourceDirectionRasterName}, {outputSourceLocationRasterName}, {sourceField}, {sourceInitialAccumulation}, {sourceMaximumAccumulation}, {sourceCostMultiplier}, {sourceDirection}, {distanceMethod})
NameExplanationData Type
inputSourceRasterOrFeatures

The input source locations.

This is an image service or feature service identifying the cells or locations from or to which the allocation for every output cell location is calculated.

For an image service, the input type can be integer or floating point. For a feature service, the input type can be point, line or polygon.

Raster Layer; Feature Layer
outputDistanceAllocationRasterName

The name of the output distance allocation raster service.

String
inputBarrierRasterOrFeatures
(Optional)

The dataset that defines the barriers.

The barriers can be defined by an integer or a floating-point image service, or by a feature service. For a feature service, the input type can be point, line or polygon.

For an image service barrier, the barrier must have a valid value, including zero, and the areas that are not barriers must be NoData.

Raster Layer; Feature Layer
inputSurfaceRaster
(Optional)

An image service 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
inputCostRaster
(Optional)

An image service 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
inputVerticalRaster
(Optional)

An image service 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
verticalFactor
(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 that identify a defined vertical factor 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, vertical factor (VF) defines the vertical difficulty encountered in moving from one cell to the next, and VRMA identifies the slope angle between the FROM or processing cell and the TO cell.

The object comes in the following forms: VfBinary, VfLinear, VfInverseLinear, VfSymLinear, VfSymInverseLinear, VfCos, VfSec, VfSec, VfCosSec, VfSecCos, VfHikingTime, VfBidirHikingTime, VfTable

The definitions and parameters of these forms are as follows:

  • VfBinary({zeroFactor}, {lowCutAngle}, {highCutAngle})

    If the VRMA is greater than the low-cut angle and less than the high-cut angle, the VF is set to the value associated with the zero factor; otherwise, it is infinity.

  • VfLinear({zeroFactor}, {lowCutAngle}, {highCutAngle}, {slope})

    The VF is a linear function of the VRMA.

  • VfInverseLinear({zeroFactor}, {lowCutAngle}, {highCutAngle}, {slope})

    The VF is an inverse linear function of the VRMA.

  • VfSymLinear({zeroFactor}, {lowCutAngle}, {highCutAngle}, {slope})

    The VF is a linear function of the VRMA in either the negative or positive side of the VRMA, and the two linear functions are symmetrical with respect to the VF (y) axis.

  • VfSymInverseLinear({zeroFactor}, {lowCutAngle}, {highCutAngle}, {slope})

    The VF is an inverse linear function of the VRMA in either the negative or positive side of the VRMA, and the two linear functions are symmetrical with respect to the VF (y) axis.

  • VfCos({lowCutAngle}, {highCutAngle}, {cosPower})

    The VF is the cosine-based function of the VRMA.

  • VfSec({lowCutAngle}, {highCutAngle}, {secPower})

    The VF is the secant-based function of the VRMA.

  • VfCosSec({lowCutAngle}, {highCutAngle}, {cosPower}, {secPower})

    The VF is the cosine-based function of the VRMA when the VRMA is negative and is the secant-based function of the VRMA when the VRMA is not negative.

  • VfSecCos({lowCutAngle}, {highCutAngle}, {secPower}, {cos_power})

    The VF is the secant-based function of the VRMA when the VRMA is negative and is the cosine-based function of the VRMA when the VRMA is not negative.

  • VfHikingTime({lowCutAngle}, {highCutAngle})

    The VF is the hiking time function of the VRMA.

  • VfBidirHikingTime({lowCutAngle}, {highCutAngle})

    The VF is a bidirectional modified hiking time function of the VRMA.

The modifiers to the vertical parameters are as follows:

  • zeroFactor—The vertical factor used when the VRMA is zero. This factor positions the y-intercept of the specified function. By definition, the zero factor is not applicable to any of the trigonometric vertical functions (Cos, Sec, Cos-Sec, or Sec-Cos). The y-intercept is defined by these functions.
  • lowCutAngle—The VRMA angle below which the VF will be set to infinity.
  • highCutAngle—The VRMA angle above which the VF will be set to infinity.
  • slope—The slope of the straight line used with the VfLinear and VfInverseLinear parameters. The slope is specified as a fraction of rise over run (for example, 45 percent slope is 1/45, which is input as 0.02222).
Vertical Factor
inputHorizontalRaster
(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
horizontalFactor
(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 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 object comes in the following forms: HfBinary, HfForward, HfLinear, and HfInverseLinear

The definitions and parameters of these are as follows:

  • HfBinary({zeroFactor}, {cutAngle})

    If the HRMA is less than the cut angle, the HF is set to the value associated with the zero factor; otherwise, it is infinity.

  • HfForward({zeroFactor}, {sideValue})

    Only forward movement is allowed. The HRMA must be greater than or equal to 0 and less than 90 (0 <= HRMA < 90). If the HRMA is greater than 0 and less than 45 degrees, the HF for the cell is set to the value associated with the zero factor. If the HRMA is greater than or equal to 45 degrees, the side value modifier value is used. The HF for any HRMA equal to or greater than 90 degrees is set to infinity.

  • HfLinear({zeroFactor}, {cutAngle}, {slope})

    The HF is a linear function of the HRMA.

  • HfInverseLinear({zeroFactor}, {cutAngle}, {slope})

    The HF is an inverse linear function of the HRMA.

The modifiers to the horizontal keywords are as follows:

  • zeroFactor—The horizontal factor to be used when the HRMA is 0. This factor positions the y-intercept for any of the horizontal factor functions.
  • cutAngle—The HRMA angle beyond which the HF will be set to infinity.
  • slope—The slope of the straight line used with the HfLinear and HfInverseLinear horizontal factor keywords. The slope is specified as a fraction of rise over run (for example, 45 percent slope is 1/45, which is input as 0.02222).
  • sideValue—The HF when the HRMA is greater than or equal to 45 degrees and less than 90 degrees when the HfForward horizontal factor keyword is specified.

Horizontal Factor
outputDistanceAccumulationRasterName
(Optional)

The output distance accumulation raster name.

The distance accumulation raster contains the accumulative distance for each cell from, or to, the least-cost source.

String
outputBackDirectionRasterName
(Optional)

The output back direction raster name.

The back direction raster contains calculated directions in degrees. The direction identifies the next cell along the optimal path back to the least accumulative cost source while avoiding barriers.

The range of values is from 0 degrees to 360 degrees. The value 0 is reserved for the source cells. Due east (right) is 90 degrees, and the values increase clockwise (180 is south, 270 is west, and 360 is north).

The output raster is of type float.

String
outputSourceDirectionRasterName
(Optional)

The output source direction raster name.

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. The value 0 is reserved for the source cells. Due east (right) is 90 degrees, and the values increase clockwise (180 is south, 270 is west, and 360 is north).

The output raster is of type float.

String
outputSourceLocationRasterName
(Optional)

The output source location raster name.

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.

String
sourceField
(Optional)

The field used to assign values to the source locations. It must be of type integer.

Field
sourceInitialAccumulation
(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 the value set by source_initial_accumulation.

The values must be zero or greater. The default is 0.

Double; Field
sourceMaximumAccumulation
(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
sourceCostMultiplier
(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
sourceDirection
(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 string FROM_SOURCE or TO_SOURCE.

String; Field
distanceMethod
(Optional)

Specifies whether the distance will be calculated using a planar (flat earth) or a geodesic (ellipsoid) method.

  • PLANAR—The distance calculation will be performed on a projected flat plane using a 2D Cartesian coordinate system. This is the default.
  • GEODESIC—The distance calculation will be performed on the ellipsoid. Regardless of input or output projection, the results will not change.
String

Derived Output

NameExplanationData Type
outputDistanceAllocationRaster

The output distance allocation raster.

Raster
outputDistanceAccumulationRaster

The output distance accumulation raster.

Raster
outputBackDirectionRaster

The output back direction raster.

Raster
outputSourceDirectionRaster

The output source direction raster.

Raster
outputSourceLocationRaster

The output source location raster.

Raster

Code sample

DistanceAllocation example 1 (Python window)

The following Python window script demonstrates how to use the DistanceAllocation tool.

import arcpy

arcpy.ra.DistanceAllocation('https://MyPortal.esri.com/server/rest/services/Hosted/sources/ImageServer',
                            'outDistanceAllocation',
                            'https://MyPortal.esri.com/server/rest/services/Hosted/barrier/ImageServer',
                            'https://MyPortal.esri.com/server/rest/services/Hosted/surface/ImageServer',
                            'https://MyPortal.esri.com/server/rest/services/Hosted/cost/ImageServer')
DistanceAllocation example 2 (stand-alone script)

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: ArcGIS Image Server

# Import system modules
import arcpy

# Set local variables
inputSourceRasterOrFeatures = 'https://MyPortal.esri.com/server/rest/services/Hosted/sources/ImageServer'
outputDistanceAllocationRasterName = "outDistAllo"
inputBarrierRasterOrFeatures  = 'https://MyPortal.esri.com/server/rest/services/Hosted/barrier/ImageServer'
inputSurfaceRaster = 'https://MyPortal.esri.com/server/rest/services/Hosted/surface/ImageServer'
inputCostRaster = 'https://MyPortal.esri.com/server/rest/services/Hosted/cost/ImageServer'
inputVerticalRaster = 'https://MyPortal.esri.com/server/rest/services/vertical/sources/ImageServer'
verticalFactor = ""
inputHorizontalRaster = 'https://MyPortal.esri.com/server/rest/services/Hosted/horizontal/ImageServer'
horizontalFactor = ""
outputDistanceAccumulationRasterName = "outAccum"
outputBackDirectionRasterName = "outBackDir"
outputSourceDirectionRasterName = "outSourceDir"
outputSourceLocationRasterName = "outSourceLocation"
sourceField = "SourceID"
sourceInitialAccumulation = "IntitalAccum"
sourceMaximumAccumulation = "500000"
sourceCostMultiplier = "CostMultiplier"
sourceDirection = "FROM_SOURCE"
distanceMethod = "PLANAR"

# Execute 
arcpy.ra.DistanceAllocation(inputSourceRasterOrFeatures, outputDistanceAllocationRasterName,
                            inputBarrierRasterOrFeatures, inputSurfaceRaster,
                            inputCostRaster, inputVerticalRaster, verticalFactor,
                            inputHorizontalRaster, horizontalFactor,
                            outputDistanceAccumulationRasterName, outputBackDirectionRasterName,
                            outputSourceDirectionRasterName, outputSourceLocationRasterName,
                            sourceField, sourceInitialAccumulation, sourceMaximumAccumulation,
                            sourceCostMultiplier, sourceDirection, distanceMethod)

Environments

Extent, Cell Size, Mask, Output Coordinate System, Pyramid, Snap Raster

Licensing information

  • Basic: Requires ArcGIS Image Server
  • Standard: Requires ArcGIS Image Server
  • Advanced: Requires ArcGIS Image Server

Related topics

  • An overview of the Use Proximity toolset
  • An overview of the Distance toolset
  • Find a geoprocessing tool
  • Distance Allocation
  • Distance Allocation function

Feedback on this topic?

In this topic
  1. Summary
  2. Illustration
  3. Usage
  4. Parameters
  5. Environments
  6. Licensing information