com.esri.arcgis.geoprocessing.tools.spatialanalysttools
Class CostDistance

java.lang.Object
  com.esri.arcgis.geoprocessing.AbstractGPTool
      com.esri.arcgis.geoprocessing.tools.spatialanalysttools.CostDistance

All Implemented Interfaces:

GPTool

public class CostDistance
extends AbstractGPTool

Calculates the least accumulative cost distance for each cell to the nearest source over a cost surface. The Cost Distance tool is contained in the Spatial Analyst Tools tool box.
Learn more about how Cost functions work

Software restrictions: none

Illustration:

Usage tips:

• 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.
• Cell locations with NoData in the input cost raster act as barriers in the cost surface functions. Any cell location that is assigned NoData on the input cost surface will receive NoData on all outputs (cost distance raster and, optionally, cost backlink raster).
• If the input source data and input cost raster are different extents, the default output extent is the intersection of the two. To get a cost distance surface for the entire extent, choose Union of Inputs on the raster settings of the environment settings.
• If a mask has been set in the environment, all masked cells will be treated as NoData values.
• When a mask has been defined in the Analysis window and the cells to be masked will mask a source, the cost surface 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 all outputs (cost distance raster and the optional cost backlink raster).
• The maximum distance is specified in the same cost units as those on the cost raster.
• The least-cost distance or minimum accumulative cost distance of a cell to a set of source cells is the lower bound of the least-cost distance from the cell to all source cells.
• The output type for the optional output distance raster is floating point.
• The output type for the optional output backlink raster is integer.
• The cost raster cannot contain values of zero since the algorithm is a multiplicative process. If your cost raster does contain values of zero, and these values represent areas of lowest cost, change values of zero to a small positive value (such as 0.01) before running Cost Distance, by first running the CON geoprocessing tool. If areas with a value of zero represent areas that should be excluded from the analysis, these values should be turned to NoData before running Cost Distance, by first running the SetNull geoprocessing tool.

Field Summary

Fields inherited from class com.esri.arcgis.geoprocessing.AbstractGPTool

vals

Constructor Summary

CostDistance()
Creates the Cost Distance tool with defaults.

CostDistance(Object inSourceData, Object inCostRaster, Object outDistanceRaster)
Creates the Cost Distance tool with the required parameters.

Method Summary

Object	getInCostRaster() Returns the Input cost raster parameter of this tool .
Object	getInSourceData() Returns the Input raster or feature source data parameter of this tool .
double	getMaximumDistance() Returns the Maximum distance parameter of this tool .
Object	getOutBacklinkRaster() Returns the Output backlink raster parameter of this tool .
Object	getOutDistanceRaster() Returns the Output distance raster parameter of this tool .
String	getToolboxAlias() Returns the alias of the tool box containing this tool.
String	getToolboxName() Returns the name of the tool box containing this tool.
String	getToolName() Returns the name of this tool.
void	setInCostRaster(Object inCostRaster) Sets the Input cost raster parameter of this tool .
void	setInSourceData(Object inSourceData) Sets the Input raster or feature source data parameter of this tool .
void	setMaximumDistance(double maximumDistance) Sets the Maximum distance parameter of this tool .
void	setOutBacklinkRaster(Object outBacklinkRaster) Sets the Output backlink raster parameter of this tool .
void	setOutDistanceRaster(Object outDistanceRaster) Sets the Output distance raster parameter of this tool .

Methods inherited from class com.esri.arcgis.geoprocessing.AbstractGPTool

getParameterValues, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CostDistance

public CostDistance()

Creates the Cost Distance tool with defaults.

Initializes the array of tool parameters with the default values specified when the tool was created.

CostDistance

public CostDistance(Object inSourceData,
                    Object inCostRaster,
                    Object outDistanceRaster)

Creates the Cost Distance tool with the required parameters.

Initializes the array of tool parameters with the values as specified for the required parameters and with the default values for the other parameters.

Parameters:

inSourceData - Composite Geodataset, for rasters, the input value can be integer, string, or floating-point type if in_value_raster is used.

inCostRaster - Composite Geodataset, 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 compensating for diagonal movement, to obtain the total cost of passing through the cell. The values on the in_cost_raster can be integer or floating point, but they cannot be negative or zero (you cannot have a negative or zero cost).

outDistanceRaster - Raster Dataset, the cost distance raster identifies, for each cell, the least accumulative cost distance over a cost surface to the identified source locations. A source can be a cell, a set of cells, or one or more feature locations.

Method Detail

getInSourceData

public Object getInSourceData()

Returns the Input raster or feature source data parameter of this tool . This parameter is Composite Geodataset, for rasters, the input value can be integer, string, or floating-point type if in_value_raster is used. This is a required parameter.

Returns:

the Input raster or feature source data

setInSourceData

public void setInSourceData(Object inSourceData)

Sets the Input raster or feature source data parameter of this tool . This parameter is Composite Geodataset, for rasters, the input value can be integer, string, or floating-point type if in_value_raster is used. This is a required parameter.

Parameters:

inSourceData - Composite Geodataset, for rasters, the input value can be integer, string, or floating-point type if in_value_raster is used.

getInCostRaster

public Object getInCostRaster()

Returns the Input cost raster parameter of this tool . This parameter is Composite Geodataset, 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 compensating for diagonal movement, to obtain the total cost of passing through the cell. The values on the in_cost_raster can be integer or floating point, but they cannot be negative or zero (you cannot have a negative or zero cost). This is a required parameter.

Returns:

the Input cost raster

setInCostRaster

public void setInCostRaster(Object inCostRaster)

Sets the Input cost raster parameter of this tool . This parameter is Composite Geodataset, 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 compensating for diagonal movement, to obtain the total cost of passing through the cell. The values on the in_cost_raster can be integer or floating point, but they cannot be negative or zero (you cannot have a negative or zero cost). This is a required parameter.

Parameters:

inCostRaster - Composite Geodataset, 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 compensating for diagonal movement, to obtain the total cost of passing through the cell. The values on the in_cost_raster can be integer or floating point, but they cannot be negative or zero (you cannot have a negative or zero cost).

getOutDistanceRaster

public Object getOutDistanceRaster()

Returns the Output distance raster parameter of this tool . This parameter is Raster Dataset, the cost distance raster identifies, for each cell, the least accumulative cost distance over a cost surface to the identified source locations. A source can be a cell, a set of cells, or one or more feature locations. This is a required parameter.

Returns:

the Output distance raster

setOutDistanceRaster

public void setOutDistanceRaster(Object outDistanceRaster)

Sets the Output distance raster parameter of this tool . This parameter is Raster Dataset, the cost distance raster identifies, for each cell, the least accumulative cost distance over a cost surface to the identified source locations. A source can be a cell, a set of cells, or one or more feature locations. This is a required parameter.

Parameters:

outDistanceRaster - Raster Dataset, the cost distance raster identifies, for each cell, the least accumulative cost distance over a cost surface to the identified source locations. A source can be a cell, a set of cells, or one or more feature locations.

getMaximumDistance

public double getMaximumDistance()

Returns the Maximum distance parameter of this tool . This parameter is Double, if an accumulative cost distance value exceeds the {max_distance}, the output value for the cell location will be NoData. The {max_distance} defines the extent for which the accumulative cost distances are calculated. The default distance is to the edge of the output raster. This is an optional parameter.

Returns:

the Maximum distance

setMaximumDistance

public void setMaximumDistance(double maximumDistance)

Sets the Maximum distance parameter of this tool . This parameter is Double, if an accumulative cost distance value exceeds the {max_distance}, the output value for the cell location will be NoData. The {max_distance} defines the extent for which the accumulative cost distances are calculated. The default distance is to the edge of the output raster. This is an optional parameter.

Parameters:

maximumDistance - Double, if an accumulative cost distance value exceeds the {max_distance}, the output value for the cell location will be NoData. The {max_distance} defines the extent for which the accumulative cost distances are calculated. The default distance is to the edge of the output raster.

getOutBacklinkRaster

public Object getOutBacklinkRaster()

Returns the Output backlink raster parameter of this tool . This parameter is Raster Dataset, if the path is to pass into the right neighbor, the cell will be assigned the value 1, 2 for the lower right diagonal cell, and continuing clockwise. The value 0 is reserved for source cells. This is an optional parameter.

Returns:

the Output backlink raster

setOutBacklinkRaster

public void setOutBacklinkRaster(Object outBacklinkRaster)

Sets the Output backlink raster parameter of this tool . This parameter is Raster Dataset, if the path is to pass into the right neighbor, the cell will be assigned the value 1, 2 for the lower right diagonal cell, and continuing clockwise. The value 0 is reserved for source cells. This is an optional parameter.

Parameters:

outBacklinkRaster - Raster Dataset, if the path is to pass into the right neighbor, the cell will be assigned the value 1, 2 for the lower right diagonal cell, and continuing clockwise. The value 0 is reserved for source cells.

getToolName

public String getToolName()

Returns the name of this tool.

Returns:

the tool name

getToolboxName

public String getToolboxName()

Returns the name of the tool box containing this tool.

Returns:

the tool box name

getToolboxAlias

public String getToolboxAlias()

Returns the alias of the tool box containing this tool.

Returns:

the tool box alias