Cost Path As Polyline (Spatial Analyst)

Available with Spatial Analyst license.

Summary

Calculates the least-cost path from a source to a destination as a line feature.

Tip:

The Optimal Path As Line tool provides enhanced functionality or performance.

Learn more about creating the least-cost path

Usage

  • The Cost Path as Polyline tool produces an output polyline feature that records the least-cost path or paths from sources to the closest destination, defined within the accumulative cost surface, in terms of cost distance.

  • One or more of the weighted cost tools (Cost Distance, Cost Back Link, or Cost Allocation) are generally required to have been run prior to running Cost Path as Polyline to create the input cost distance and back link rasters. These are mandatory input rasters to Cost Path as Polyline.

  • When the input destination data is a raster, the set of destination cells consists of all cells in the Input raster or feature destination data that have valid values. Cells that have NoData values are not included in the source set. The value zero is considered a legitimate destination. A destination raster can be created using the extraction tools.

  • When the source input is a feature, the first valid available field will be used by default. If no valid fields exist, the ObjectID field (for example, OID or FID, depending on the type of feature input) will be used.

  • When using polygon feature data for the input feature destinations, care must be taken with how the output cell size is handled, particularly when it is coarse relative to the detail present in the input. An internal rasterization process using the Polygon to Raster tool is applied, with a default setting for the Cell assignment type of Cell center. This means that data that is not located at the center of the cell will not be included in the intermediate rasterized destination output, and will not be represented in the distance calculations. For example, if your destinations 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 many of the others to be lost in the analysis.

    To avoid this situation, as an intermediate step, you can 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 can select a small cell size to capture the appropriate amount of detail from the input features.

  • The output polyline feature has a field called DestID that identifies to which destination each line leads. If the output is written to a file geodatabase, there is a field called shape_length that contains the total length of the least-cost path.

  • Cost Path as Polyline will ignore the Cell size environment setting and use the cell size of the Input cost backlink raster for the output raster. The pattern of the back link raster would be seriously altered if it were resampled to a different resolution. To avoid any confusion, the cell size should not be set when using this tool.

  • Cost Path as Polyline can be used to determine the flow path based on D8 flow direction. To use Cost Path as Polyline in this way, use a D8 flow direction raster as input for the Input cost backlink raster. You also need to supply an Input cost distance raster; the Input cost distance raster is not used to determine the path. Whether you use a constant raster or a digital elevation model (DEM), your path will be the same; only an attribute value on your path will vary. See the Flow Direction tool for more information on D8 flow direction rasters.

  • Cost Path as Polyline can be used to determine a path around barriers based on the Output back direction raster generated from the Euclidean tools. To use Cost Path as Polyline in this way, first run any of the Euclidean tools with Input raster or feature barrier data defined to generate the Output distance raster and Output back direction raster. Use the outputs generated from the Euclidean tools as input to Cost Path as Polyline.

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

Parameters

LabelExplanationData Type
Input raster or feature destination data

A raster or feature dataset that identifies those cells from which the least-cost path is determined to the least costly source.

If the input is a raster, it must consist of cells that have valid values for the destinations, and the remaining cells must be assigned NoData. Zero is a valid value.

Raster Layer; Feature Layer
Input cost distance or euclidean distance raster

The cost distance raster to be used to determine the least-cost path from the sources to the destinations.

The cost distance raster is usually created with the Cost Distance, Cost Allocation, or Cost Back Link tools. The cost distance raster stores, for each cell, the minimum accumulative cost distance over a cost surface from each cell to a set of source cells.

Raster Layer
Input cost backlink, back direction or flow direction raster

The cost backlink raster to be used to determine the path to return to a source via the least-cost path, or the shortest path.

For each cell in a backlink, back direction, or flow direction raster, the value identifies the neighbor that is the next cell on the path from that cell to a source cell.

Raster Layer
Output polyline features

The output feature class that will hold the least cost path.

Feature Class
Path type
(Optional)

Specifies a keyword defining the manner in which the values and zones on the input destination data will be interpreted in the cost path calculations.

  • Best single For all cells on the input destination data, the least-cost path is derived from the cell with the minimum of the least-cost paths to source cells.
  • Each zone For each zone on the input destination data, a least-cost path is determined and saved on the output raster. With this option, the least-cost path for each zone begins at the cell with the lowest cost distance weighting in the zone.
  • Each cell For each cell with valid values on the input destination data, a least-cost path is determined and saved on the output raster. With this option, each cell of the input destination data is treated separately, and a least-cost path is determined for each cell.
String
Destination field
(Optional)

The field to be used to obtain values for the destination locations.

Input feature data must contain at least one valid field.

Field
Force flow direction convention for backlink raster
(Optional)

Specifies whether the input backlink raster will be treated as a flow direction raster. Flow direction rasters can have integer values that range from 0-255.

  • Unchecked—The Input cost backlink raster value will be interpreted based on the range of values and if it is integer or float. For a value range of 0-8, the Input cost backlink raster value will be treated as a backlink raster. For values 0-255 and integer, the Input cost backlink raster value will be treated as a flow direction raster. For a value range of 0-360 and floating point, the Input cost backlink raster value will be treated as a back direction raster.
  • Checked—The raster supplied for the Input cost backlink raster parameter will be treated as a flow direction raster. This is necessary if the flow direction raster has a maximum value of 8 or less.
Boolean

CostPathAsPolyline(in_destination_data, in_cost_distance_raster, in_cost_backlink_raster, out_polyline_features, {path_type}, {destination_field}, {force_flow_direction_convention})
NameExplanationData Type
in_destination_data

A raster or feature dataset that identifies those cells from which the least-cost path is determined to the least costly source.

If the input is a raster, it must consist of cells that have valid values for the destinations, and the remaining cells must be assigned NoData. Zero is a valid value.

Raster Layer; Feature Layer
in_cost_distance_raster

The cost distance raster to be used to determine the least-cost path from the sources to the destinations.

The cost distance raster is usually created with the Cost Distance, Cost Allocation, or Cost Back Link tools. The cost distance raster stores, for each cell, the minimum accumulative cost distance over a cost surface from each cell to a set of source cells.

Raster Layer
in_cost_backlink_raster

The cost backlink raster to be used to determine the path to return to a source via the least-cost path, or the shortest path.

For each cell in a backlink, back direction, or flow direction raster, the value identifies the neighbor that is the next cell on the path from that cell to a source cell.

Raster Layer
out_polyline_features

The output feature class that will hold the least cost path.

Feature Class
path_type
(Optional)

Specifies a keyword defining the manner in which the values and zones on the input destination data will be interpreted in the cost path calculations.

  • BEST_SINGLE For all cells on the input destination data, the least-cost path is derived from the cell with the minimum of the least-cost paths to source cells.
  • EACH_ZONE For each zone on the input destination data, a least-cost path is determined and saved on the output raster. With this option, the least-cost path for each zone begins at the cell with the lowest cost distance weighting in the zone.
  • EACH_CELL For each cell with valid values on the input destination data, a least-cost path is determined and saved on the output raster. With this option, each cell of the input destination data is treated separately, and a least-cost path is determined for each cell.
String
destination_field
(Optional)

The field to be used to obtain values for the destination locations.

Input feature data must contain at least one valid field.

Field
force_flow_direction_convention
(Optional)

Specifies whether the input backlink raster will be treated as a flow direction raster. Flow direction rasters can have integer values that range from 0-255.

  • INPUT_RANGEThe in_cost_backlink_raster value will be interpreted based on the range of values and if it is integer or float. For a value range of 0-8, the in_cost_backlink_raster value will be treated as a backlink raster. For values 0-255 and integer, the in_cost_backlink_raster value will be treated as a flow direction raster. For a value range of 0-360 and floating point, the in_cost_backlink_raster value will be treated as a back direction raster.
  • FLOW_DIRECTIONThe raster supplied for the in_cost_backlink_raster parameter will be treated as a flow direction raster. This is necessary if the flow direction raster has a maximum value of 8 or less.
Boolean

Code sample

CostPathAsPolyline example 1 (Python window)

The following Python window script demonstrates how to use this tool.

import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
CostPathAsPolyline("observers", "costdistraster", "backlink2", "c:/sapyexamples/output/outcostpth01.shp")
CostPathAsPolyline example 2 (stand-alone script)

Calculates the least-cost path from a source to a destination.

# Name: CostPathAsPolyline_Ex_02.py
# Description: Calculates the least-cost path from a source to 
#              a destination.
# 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
inDestination = "observers.shp"
inCostDistRaster = "costdistraster"
inBacklink = "backlink2"
outCostPathFeat = "c:/sapyexamples/output.gdb/outcostpathfeat02"
method = "EACH_CELL"
destField = "FID"

# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")

# Execute
CostPathAsPolyline(inDestination, inCostDistRaster, inBacklink, 
                   outCostPathFeat, method, destField)

Licensing information

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

Related topics