Available with Spatial Analyst license.
Summary
Calculates, for each cell, the nearest source based on Euclidean distance.
Illustration
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 easily 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 Output cell size parameter or the Cell Size environment. By default, the resolution will be determined by the shorter of the width or height of the extent of input feature, in the input spatial reference, divided by 250.
When using polygon 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 employs the same default Cell assignment type method as the Polygon to Raster tool, which is CELL_CENTER. This means that data not located at the center of the cell will not be included in the intermediate rasterized source output, and so will not be represented in the distance calculations. For example, if your 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 of them 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 could rasterize the input features directly with the Polygon to Raster tool and set a Priority field, and use the resulting output as input to the Distance tool. Alternatively, you could select a small enough cell size to capture the appropriate amount of detail from the input features.
The Maximum distance is specified in the same map units as the input source data.
The input value raster is useful if the input raster or feature source data is a raster derived from a function that results in either one or zero. These functions lose their original zone values associated with the source cell locations. The input value raster can either restore these values or allow analysis on additional combinations of zone values within the source cells.
If an input value raster is used, it may change the configuration and results of the Euclidean allocation output. It will not affect the optional Euclidean distance or direction results.
If a Mask has been set in the environment and the cells to be masked will mask a source, the Euclidean 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 on the output rasters.
The NoData values created by the masked cells are ignored in the calculations on non-source cell locations. The Euclidean distance for cells behind NoData values is calculated as if the NoData value is not present. Any cell location that is assigned NoData because of the mask on the input surface will receive NoData on all the output rasters.
See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.
Syntax
EucAllocation (in_source_data, {maximum_distance}, {in_value_raster}, {cell_size}, {source_field}, {out_distance_raster}, {out_direction_raster})| Parameter | Explanation | Data Type |
in_source_data | The input source locations. This is a raster or feature dataset that identifies the cells or locations to which the Euclidean distance for every output cell location is calculated. For rasters, the input type can be integer or floating point. If the input source raster is floating point, the {in_value_raster} must be set, and it must be of integer type. The value raster will take precedence over any setting of the {source_field}. | Raster Layer | Feature Layer |
maximum_distance (Optional) | Defines the threshold that the accumulative distance values cannot exceed. If an accumulative Euclidean distance value exceeds this value, the output value for the cell location will be NoData. The default distance is to the edge of the output raster. | Double |
in_value_raster (Optional) |
The input integer raster that identifies the zone values that should be used for each input source location. For each source location (cell or feature), the value defined by the {in_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}. | Raster Layer |
cell_size (Optional) | The cell size at which the output raster will be created. This will be the value in the environment if it is explicitly set. If it is not set in the environment, the default cell size will depend on if the input source data is a raster or a feature, as follows:
| Analysis Cell Size |
source_field (Optional) | The field used to assign values to the source locations. It must be integer type. If the {in_value_raster} has been set, the values in that input will have precedence over any setting for the {source_field}. | Field |
out_distance_raster (Optional) | The output Euclidean distance raster. The distance raster identifies, for each cell, the Euclidean distance to the closest source cell, set of source cells, or source location. The output raster is of floating-point type. | Raster Dataset |
out_direction_raster (Optional) | The output Euclidean direction raster. The direction raster contains the calculated direction, in degrees, each cell center is from the closest source cell center. 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 integer type. | Raster Dataset |
Return Value
| Name | Explanation | Data Type |
| out_allocation_raster | The output Euclidean allocation raster. The cell values (zones) identify the nearest source location. The output raster is of integer type. | Raster |
Code sample
EucAllocation example 1 (Python window)
The following Python Window script demonstrates how to use the EuclideanAllocation tool.
import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
eucAllocate = EucAllocation("observers", 50000, "elevation", 25, "FID",
"c:/sapyexamples/output/outeucdist",
"c:/sapyexamples/output/outeucdir")
eucAllocate.save("c:/sapyexamples/output/eucalloc")
EucAllocation example 2 (stand-alone script)
Calculates, for each cell, the zone of the closest source location in Euclidean distance.
# Name: EucAllocation_Ex_02.py
# Description: Calculates, for each cell, the zone of the closest
# source location in Euclidean distance.
# 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
inSource = "observers.shp"
maxDist = 50000
valRaster = "elevation"
cellSize = 25
sourceField = "FID"
optOutDist = "c:/sapyexamples/output/outeucdist02"
optOutDir = "c:/sapyexamples/output/outeucdir02"
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Execute EucAllocation
eucAllocate = EucAllocation(inSource, maxDist, valRaster, cellSize,
sourceField, optOutDist, optOutDir)
# Save the output
eucAllocate.save("c:/sapyexamples/output/eucalloc02")
Environments
Licensing information
- ArcGIS Desktop Basic: Requires Spatial Analyst
- ArcGIS Desktop Standard: Requires Spatial Analyst
- ArcGIS Desktop Advanced: Requires Spatial Analyst