Cost Path As Polyline (Raster Analysis)

Summary

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

Legacy:

This tool is deprecated and will be removed in a future release.

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

Learn more about creating the least cost path

Illustration

Usage

• This raster analysis portal tool is available when you are signed in to an ArcGIS Enterprise portal that has ArcGIS Image Server configured for Raster Analysis. When the tool is run, ArcGIS Pro serves as a client and the processing occurs in the servers federated with ArcGIS Enterprise. The portal tool accepts layers from your portal as input and creates output in your portal.

  The input raster layer supports a layer from the portal, a URI or URL to an image service, or the output from the Make Image Server Layer tool. The input feature layer can be a layer from the portal or a URI or URL to a feature service. This tool does not support local raster data or layers. While you can use local feature data and layers as input to this portal tool, best practice is to use layers from your portal as input.

• The Cost Path As Polyline tool produces an output polyline feature service that records the least-cost path, or paths, from sources the closest destination defined within the accumulative cost surface or Euclidean distance surface.

• If you have destination features, you can convert them to an image service using the Rasterize Features raster function. Use your existing Cost Distance Raster as the Raster input to the rasterization function. This will ensure that the features are properly converted to an image service using the same cell size, extent, and spatial reference.

• The NoData values that exist in the Destination Raster are not included as valid values in the function. The value 0 is considered a legitimate value in the destination raster.

• Two input image services are needed to run Cost Path As Polyline. How you generate these inputs depends on the type of analysis you want to complete.

  • Cost analysis generates a cost path. Run the Cost Back Link and Cost Distance raster functions to generate necessary inputs.
  • Euclidean analysis generates straight line paths and paths around barriers. Run the Calculate Distance tool to generate Euclidean Back Direction and Euclidean Distance. Alternatively run the Euclidean Back Direction and Euclidean Distance raster functions.
  • Flow analysis generates flow paths. Run the Flow Direction raster function using the D8 option. 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.

• The output feature service has an field called DestID that identifies the destination to which each line leads.

• Unlike most other Raster Analysis tools, Cost Path As Polyline will ignore the following environment settings: Output Coordinate System, Extent, Cell Size, and Snap Raster. The pattern of the back link raster would be significantly altered if it were resampled or reprojected, resulting in an incorrect path.

Parameters

Dialog

Label	Explanation	Data Type
Input Destination Raster or Features	An image service or feature service that identifies those locations from which the least-cost path is determined to the least costly source. If the input is an image service, the input consists of cells that have valid values (zero is a valid value), and the remaining cells must be assigned NoData.	Raster Layer; Image Service; Feature Layer; String
Input Cost Distance or Euclidean Distance Raster	The cost distance or Euclidean distance raster to be used to determine the least-cost path from the sources to the destinations.	Raster Layer; Image Service; String
Input Cost Backlink, Back Direction or Flow Direction Raster	The name of the raster used to determine the path to return to a source via the least-cost path or the shortest path. For each cell in the back link or direction raster, a value identifies the neighbor that is the next cell on the path from the cell to a source cell.	Raster Layer; Image Service; String
Output Polyline Name	The output feature service that will contain the least cost path.	String
Path type (Optional)	Specifies 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 will be 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 will begin 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 will be treated separately, and a least-cost path will be determined for each from cell.	String
Destination Field (Optional)	The field that will be used to obtain values for the destination locations.	Field

Derived Output

Label	Explanation	Data Type
Output Polyline Feature	The polyline features.	Feature Layer

Python

arcpy.ra.CostPathAsPolyline(inputDestinationRasterOrFeatures, inputCostDistanceRaster, inputCostBacklinkRaster, outputPolylineName, {pathType}, {destinationField})

Name	Explanation	Data Type
inputDestinationRasterOrFeatures	An image service or feature service that identifies those locations from which the least-cost path is determined to the least costly source. If the input is an image service, the input consists of cells that have valid values (zero is a valid value), and the remaining cells must be assigned NoData.	Raster Layer; Image Service; Feature Layer; String
inputCostDistanceRaster	The cost distance or Euclidean distance raster to be used to determine the least-cost path from the sources to the destinations.	Raster Layer; Image Service; String
inputCostBacklinkRaster	The name of the raster used to determine the path to return to a source via the least-cost path or the shortest path. For each cell in the back link or direction raster, a value identifies the neighbor that is the next cell on the path from the cell to a source cell.	Raster Layer; Image Service; String
outputPolylineName	The output feature service that will contain the least cost path.	String
pathType (Optional)	Specifies 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 will be 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 will begin 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 will be treated separately, and a least-cost path will be determined for each from cell.	String
destinationField (Optional)	The field that will be used to obtain values for the destination locations.	Field

Derived Output

Name	Explanation	Data Type
outputPolylineFeatures	The polyline features.	Feature Layer

Code sample

CostPathAsPolyline example 1 (Python window)

The following Python Window script demonstrates how to use the CostPathAsPoyline function.

import arcpy

arcpy.ra.CostPathAsPolyline(
    "https://myserver/rest/services/destination/ImageServer", 
    "https://myserver/rest/services/costsurface/ImageServer", 
    "https://myserver/rest/services/direction/ImageServer", 
    "outpath", "BEST_SINGLE")

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: ArcGIS Image Server

# Import system modules
import arcpy

# Set local variables
inputDestinationLayer =
    'https://MyPortal.esri.com/server/rest/services/Hosted/destination/ImageServer'
inputCostLayer =
    'https://MyPortal.esri.com/server/rest/services/Hosted/costraster/ImageServer'
inputDirectionLayer = 
    'https://MyPortal.esri.com/server/rest/services/Hosted/direction/ImageServer'
outputName = 'outTravelPaths'
pathType = 'BEST_SINGLE'

arcpy.ra.CostPathAsPolyline(inputDestinationLayer, inputCostLayer,
                            inputDirectionLayer, outputName, pathType)

Environments

Output Coordinate System

Licensing information

• Basic: Requires ArcGIS Image Server
• Standard: Requires ArcGIS Image Server
• Advanced: Requires ArcGIS Image Server