Euclidean Allocation (Spatial Analyst)

Available with Spatial Analyst license.

Summary

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

The Distance Allocation tool provides enhanced functionality or performance.

Learn more about Euclidean distance analysis

Illustration

Euc_Alloc = EucAllocation(Source_Ras)

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 to a raster internally before performing the analysis.

• When using 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 uses the same default Cell assignment type as the Feature to Raster tool, which is the cell center method. This means that data not located at the center of the cell will not be included in the intermediate rasterized source output, so it 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 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 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.

• 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 cell size can be defined by a numeric value or obtained from an existing raster dataset. If the cell size hasn’t been explicitly specified as the parameter value, it is derived from the Cell Size environment if it has been specified. If the parameter cell size or the environment cell size have not been specified, the default output cell size is determined based on the type of input dataset as follows:

  • If the input dataset is a raster, the cell size of the dataset is used.
  • If the input dataset is a feature and the Snap Raster environment has been set, the cell size of the snap raster is used. If no snap raster is set, the cell size is calculated from the shorter of the width or height of the extent divided by 250, in which the extent is in the Output Coordinate System specified in the environment.

• If the cell size is specified using a numeric value, the tool will use it directly for the output raster.

  If the cell size is specified using a raster dataset, the parameter will show the path of the raster dataset instead of the cell size value. The cell size of that raster dataset will be used directly in the analysis, provided the spatial reference of the dataset is the same as the output spatial reference. If the spatial reference of the dataset is different than the output spatial reference, it will be projected based on the selected Cell Size Projection Method.

• The default processing extent for this tool is the Union of Inputs. The combined extent of both input datasets will be processed.

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

Parameters

Dialog

Label	Explanation	Data Type
Input raster or feature 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 Input value raster parameter must be set, and it must be integer. The value raster will take precedence over the Source field parameter setting.	Raster Layer; Feature Layer
Maximum distance (Optional)	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
Input value raster (Optional)	The input integer raster that identifies the zone values that will be used for each input source location. For each source location (cell or feature), the Input value raster value will be assigned to all cells allocated to the source location for the computation. The value raster will take precedence over the Source field parameter setting.	Raster Layer
Output cell size (Optional)	The cell size of the output raster that will be created. This parameter can be defined by a numeric value or obtained from an existing raster dataset. If the cell size hasn't been explicitly specified as the parameter value, the environment cell size value will be used if specified; otherwise, additional rules will be used to calculate it from the other inputs. See the usage section for more detail.	Analysis Cell Size
Source field (Optional)	The field used to assign values to the source locations. It must be of integer type. If the Input value raster parameter has been set, the values in that input will have precedence over the Source field parameter setting.	Field
Output 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
Output direction raster (Optional)	The output Euclidean direction raster. The direction raster contains the calculated direction, in degrees, that 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
Distance Method (Optional)	Specifies whether to calculate the distance 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. Therefore, regardless of input or output projection, the results do not change.	String
Input raster or feature 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.	Raster Layer; Feature Layer
Out back direction raster (Optional)	The output Euclidean back direction raster. 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

Return Value

Label	Explanation	Data Type
Output allocation raster	The output Euclidean allocation raster. The cell values (zones) identify the nearest source location. The output raster is of integer type.	Raster

Python

EucAllocation(in_source_data, {maximum_distance}, {in_value_raster}, {cell_size}, {source_field}, {out_distance_raster}, {out_direction_raster}, {distance_method}, {in_barrier_data}, {out_back_direction_raster})

Name	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 parameter must be set, and it must integer. The value raster will take precedence over the source_field parameter setting.	Raster Layer; Feature Layer
maximum_distance (Optional)	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 will be used for each input source location. For each source location (cell or feature), the in_value_raster value will be assigned to all cells allocated to the source location for the computation. The value raster will take precedence over the source_field parameter setting.	Raster Layer
cell_size (Optional)	The cell size of the output raster that will be created. This parameter can be defined by a numeric value or obtained from an existing raster dataset. If the cell size hasn't been explicitly specified as the parameter value, the environment cell size value will be used if specified; otherwise, additional rules will be used to calculate it from the other inputs. See the usage section for more detail.	Analysis Cell Size
source_field (Optional)	The field used to assign values to the source locations. It must be of integer type. If the in_value_raster parameter has been set, the values in that input will have precedence over the source_field parameter setting.	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, that 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
distance_method (Optional)	Specifies whether to calculate the distance 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. Therefore, regardless of input or output projection, the results do not change.	String
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.	Raster Layer; Feature Layer
out_back_direction_raster (Optional)	The output Euclidean back direction raster. 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

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"

# Execute EucAllocation
eucAllocate = EucAllocation(inSource, maxDist, valRaster, cellSize,
                             sourceField, optOutDist, optOutDir)

# Save the output 
eucAllocate.save("c:/sapyexamples/output/eucalloc02")

Environments

Auto Commit, Cell Size, Cell Size Projection Method, Compression, Current Workspace, Extent, Geographic Transformations, Mask, Output CONFIG Keyword, Output Coordinate System, Parallel Processing Factor, Scratch Workspace, Snap Raster, Tile Size

Licensing information

• Basic: Requires Spatial Analyst
• Standard: Requires Spatial Analyst
• Advanced: Requires Spatial Analyst