Determine Travel Cost Paths To Destinations (Raster Analysis)

Summary

Calculates specific paths between known sources and known destinations.

Legacy:

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

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

Illustration

Determine Travel Cost Paths to Destinations tool 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.

  • One example application of this tool to find the travel cost to get to certain destinations.

  • The Determine Travel Cost Paths To Destinations tool produces an output raster that records the least-cost path or paths from selected locations to the closest source cell defined within the accumulative cost surface, in terms of cost distance.

  • Running Calculate Travel Cost is generally required prior to running Determine Travel Cost Paths To Destinations to create the input cost distance and back link image services. These are mandatory input image services to Determine Travel Cost Paths To Destinations.

  • Each least-cost path is assigned a value when encountered in the scanning process. The ending cell on the original source (from which the cost distance and back link were derived) of a cost path receives one, the first path receives three, the second four, and so on. The value two is reserved for the merged portion of paths that have portions of a common cost path.

  • When the input destination data is an image service, the set of destination cells consists of all cells in the input image service 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.

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

  • When multiple paths merge and follow the remaining distance back to a source on the same route, the segment where the two paths travel together is assigned the value 2. The merged portion of the path cannot be assigned the value of one of the paths, since the merged portion belongs to both routes.

    Example of Each zone option with merged paths
    Example of Each zone option with merged paths
  • Determine Travel Cost Paths To Destinations 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.

  • Determine Travel Cost Paths To Destinations can also be used to derive the path of least resistance down a digital elevation model (DEM). In this case, use the DEM for the Input cost distance raster and the output from the Flow Direction tool for the Input cost backlink raster. Valid flow direction raster values are 1, 2, 4, 8, 16, 32, 64, and 128; valid values in the back link raster are 0 to 360. Both of these image services are acceptable.

  • When the input destination data is feature, it must contain at least one valid field.

Parameters

LabelExplanationData Type
Input Destination Raster or Features

An image service or feature service that identifies the cells 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 Raster

The name of a cost distance image service to be used to determine the least-cost path from the destination locations to a source.

The cost distance raster is usually created with the Calculate Travel Cost tool. 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; Image Service; String
Input Cost Backlink Raster

The name of a cost back link raster used to determine the path to return to a source via the least-cost path.

For each cell in the back link raster, a value identifies the neighbor that is the next cell on the least accumulative cost path from the cell to a single source cell or set of source cells.

Raster Layer; Image Service; String
Output Name

The name of the output travel cost paths raster service.

The default name is based on the tool name and the input layer name. If the layer name already exists, you will be prompted to provide another name.

String
Destination Field
(Optional)

A field on the destination layer that holds the values that define each destination.

Input feature service must contain at least one valid field.

String
Path Type
(Optional)

Defines the manner in which the values and zones on the input destination data will be interpreted in the cost path calculations.

  • To each cellFor 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 from cell. This is the default.
  • To each zoneFor 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.
  • Best singleFor 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.
String

Derived Output

LabelExplanationData Type
Output Raster

The output raster.

Raster Layer

arcpy.ra.DetermineTravelCostPathsToDestinations(inputDestinationRasterOrFeatures, inputCostDistanceRaster, inputCostBacklinkRaster, outputName, {destinationField}, {pathType})
NameExplanationData Type
inputDestinationRasterOrFeatures

An image service or feature service that identifies the cells 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 name of a cost distance image service to be used to determine the least-cost path from the destination locations to a source.

The cost distance raster is usually created with the Calculate Travel Cost tool. 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; Image Service; String
inputCostBacklinkRaster

The name of a cost back link raster used to determine the path to return to a source via the least-cost path.

For each cell in the back link raster, a value identifies the neighbor that is the next cell on the least accumulative cost path from the cell to a single source cell or set of source cells.

Raster Layer; Image Service; String
outputName

The name of the output travel cost paths raster service.

The default name is based on the tool name and the input layer name. If the layer name already exists, you will be prompted to provide another name.

String
destinationField
(Optional)

A field on the destination layer that holds the values that define each destination.

Input feature service must contain at least one valid field.

String
pathType
(Optional)

Defines the manner in which the values and zones on the input destination data will be interpreted in the cost path calculations.

  • EACH_CELLFor 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 from cell. This is the default.
  • EACH_ZONEFor 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.
  • BEST_SINGLEFor 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.
String

Derived Output

NameExplanationData Type
outputRaster

The output raster.

Raster Layer

Code sample

DetermineTravelCostPathsToDestinations example 1 (Python window)

This example calculates the travel cost to destinations.

import arcpy

arcpy.ra.DetermineTravelCostPathstoDestinations(
    "https://myserver/rest/services/sources/ImageServer", 
    "https://myserver/rest/services/costsurface/ImageServer", 
    "https://myserver/rest/services/backlinkras/ImageServer", 
    "outpath", "destField", "EACH_ZONE")
DetermineTravelCostPathsToDestinations example 2 (stand-alone script)

This example calculates the travel cost to destinations.

#-------------------------------------------------------------------------------
# Name: DetermineTravelCostPathstoDestinations_Ex_02.py
# Description: Calculates the optimum travel cost path.
# Requirements: ArcGIS Image Server

# Import system modules
import arcpy

# Set local variables
inputSourceLayer =
    'https://MyPortal.esri.com/server/rest/services/Hosted/sources/ImageServer'
inputCostLayer =
    'https://MyPortal.esri.com/server/rest/services/Hosted/costraster/ImageServer'
inputBackLinkLayer = 
    'https://MyPortal.esri.com/server/rest/services/Hosted/backlinkras/ImageServer'
outputName = 'outTravelPathsRaster'
destField = 'dest1'
pathType = 'BEST_SINGLE'

arcpy.ra.DetermineTravelCostPathstoDestinations(inputSourceLayer, inputCostLayer,
                                                inputBackLinkLayer, outputName, 
                                                destField, pathType)

Licensing information

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

Related topics