Show Navigation | Hide Navigation

You are here:
Extensions > Spatial Analyst > Spatial Analyst functional reference > Distance (Spatial Analyst)

Euclidean Allocation
Release 9.3 Last modified September 7, 2011	Print all topics in : "Distance (Spatial Analyst)"

Related Topics

Calculates, for each cell, the nearest source based on Euclidean distance.

Learn more about how Euclidean functions work

Illustration

Euclidean Allocation illustration

Command Line:
EucAllocation_sa Source_Ras Euc_Alloc

Usage tips

Command line and Scripting

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 zero is considered a legitimate source. A source raster can be easily created using the Extract By tools.
When the input source data is a feature class, the source locations are converted internally to a raster before performing the Euclidean analysis. The resolution of the raster can be controlled with the Output cell size parameter.
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.
The output allocation raster is of integer type.
The output direction raster is of integer type.
The output distance raster is of floating point type.
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 Euclidean function 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 assigned NoData because of the mask on the input surface will receive NoData on all the output rasters: Euclidean allocation, Euclidean distance, and Euclidean direction.
The following environment settings affect this tool:
- General: Current Workspace, Scratch Workspace, Output Coordinate system, Output Extent, Snap Raster.
- Raster Analysis: Cell size, Mask.
- Raster Storage: See the Raster Storage settings for the particular output raster format selected.

Command line syntax
An overview of the Command Line window
EucAllocation_sa <in_source_data> <out_allocation_raster> {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. A raster or feature dataset in which the zone of closest cells is determined for each defined location. The value of each location in the input source dataset is assigned to its respective zone in the output raster. For rasters, the input can be integer or floating point. If the input is floating point, a value raster must be set. The value raster must be integer. The value raster will take precedence over the source field if it is set.	Composite Geodataset
<out_allocation_raster>	A raster that identifies the zone that could be reached with the least accumulative cost from each source location.	Raster Dataset
{maximum_distance}	Defines the threshold that the accumulative distance values cannot exceed. The {maximum_distance} defines the extent for which the accumulative Euclidean distances are calculated. If an accumulative Euclidean distance value exceeds the {maximum_distance}, 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}	An optional integer input raster that identifies the zone values that should be used for each source location on the in_source_data. 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 in the cost allocation computations. The value raster will take precedence over any setting for the {source_field}. This parameter can be used if other values or zones are used instead of those existing in the input source. This parameter must be used if the source field is floating point. This parameter can also be used if the source raster was created by the Test function, a Boolean operator that will only output the binary values zero and one.	Composite Geodataset
{cell_size}	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's not set in the environment, and if the in_source_data is a raster, the cell size will default to that of the in_source_data. If the in_source_data is a feature dataset, the cell size will default to the shorter of the width or height of the extent of input features in the input spatial reference, divided by 250.	Analysis cell size
{source_field}	The field used to assign values to the source locations when the {in_value_raster} is not set. The value raster will take precedence over any setting for the {source_field}. If the {source_field} is floating point, an {in_value_raster} must be used. By setting the {in_value_raster}, the field set for the {source_field} parameter will be overridden by the value field of the {in_value_raster}.	Field
{out_distance_raster}	The name of 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.	Raster Dataset
{out_direction_raster}	The name of 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 0 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).	Raster Dataset

Data types for geoprocessing tool parameters

Command line example

EucAllocation_sa C:/data/source.shp C:/data/alloc_ras 2 "" 30 SOURCEID C:/data/dist_ras C:/data/dir_ras

Scripting syntax
About getting started with writing geoprocessing scripts
EucAllocation_sa (in_source_data, out_allocation_raster, maximum_distance, in_value_raster, cell_size, source_field, out_distance_raster, out_direction_raster)

Parameter	Explanation	Data Type
in_source_data (Required)	The input source locations. A raster or feature dataset in which the zone of closest cells is determined for each defined location. The value of each location in the input source dataset is assigned to its respective zone in the output raster. For rasters, the input can be integer or floating point. If the input is floating point, a value raster must be set. The value raster must be integer. The value raster will take precedence over the source field if it is set.	Composite Geodataset
out_allocation_raster (Required)	A raster that identifies the zone that could be reached with the least accumulative cost from each source location.	Raster Dataset
maximum_distance (Optional)	Defines the threshold that the accumulative distance values cannot exceed. The {maximum_distance} defines the extent for which the accumulative Euclidean distances are calculated. If an accumulative Euclidean distance value exceeds the {maximum_distance}, 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)	An optional integer input raster that identifies the zone values that should be used for each source location on the in_source_data. 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 in the cost allocation computations. The value raster will take precedence over any setting for the {source_field}. This parameter can be used if other values or zones are used instead of those existing in the input source. This parameter must be used if the source field is floating point. This parameter can also be used if the source raster was created by the Test function, a Boolean operator that will only output the binary values zero and one.	Composite Geodataset
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's not set in the environment, and if the in_source_data is a raster, the cell size will default to that of the in_source_data. If the in_source_data is a feature dataset, the cell size will default to the shorter of the width or height of the extent of input features in the input spatial reference, divided by 250.	Analysis cell size
source_field (Optional)	The field used to assign values to the source locations when the {in_value_raster} is not set. The value raster will take precedence over any setting for the {source_field}. If the {source_field} is floating point, an {in_value_raster} must be used. By setting the {in_value_raster}, the field set for the {source_field} parameter will be overridden by the value field of the {in_value_raster}.	Field
out_distance_raster (Optional)	The name of 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.	Raster Dataset
out_direction_raster (Optional)	The name of 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 0 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).	Raster Dataset

Data types for geoprocessing tool parameters

Script example

# EucAllocation_sample.py
# Description: 
#   Calculates for each cell its nearest source based on 
#   Euclidean distance.
# Requirements: None
# Author: ESRI
# Date: Sept 6, 2005
# Import system modules
import arcgisscripting

# Create the Geoprocessor object
gp = arcgisscripting.create()

try:    
    # Set local variables
    InSourceData = "C:/data/source.shp"
    OutAllocRaster = "C:/data/alloc_ras"
    InMaxDistance = "2"
    InValueRaster = ""
    InCellSize = "30"
    InSourceField = "SOURCEID"
    OutDistanceRaster = "C:/data/dist_ras"
    OutDirectionRaster = "C:/data/dir_ras"

    # Check out Spatial Analyst extension license
    gp.CheckOutExtension("Spatial")

    # Process: EucAllocation
    gp.EucAllocation_sa(InSourceData, OutAllocRaster, InMaxDistance, InValueRaster, InCellSize, InSourceField, OutDistanceRaster, OutDirectionRaster)

except:
    # If an error occurred while running a tool, then print the messages.
    print gp.GetMessages()

Map Algebra syntax
See EucAllocation

ArcObjects syntax
See EucAllocation