Optimal Path As Line (Raster Analysis)—ArcGIS Pro

Summary

Calculates the optimal path from a source to a destination as a line.

Learn more about connecting locations with optimal paths

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 Optimal Path As Line tool produces an output line feature service that records the optimal path, or paths, from destinations to the closest source defined within the accumulative cost surface or Euclidean distance surface.
When the input destination data is a raster, the set of destination cells consists of all cells in the Input Raster or Feature Destinations 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 using feature data for the input destinations, care must be taken with how the output cell size is managed, particularly when it is coarse relative to the detail present in the input. An internal rasterization process using the Feature to Raster tool is applied. 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 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.
Before generating an optimal path, usually one of the following tools is used to create a distance accumulation raster and a back direction raster: Distance Accumulation or Distance Allocation. These are required inputs to generate an optimal path.
The optimal path created can be a flow path based on D8 flow direction. To generate an optimal path in this way, use a D8 flow direction raster as input for the Input Back Direction or Flow Direction Raster. You also need to supply an Input Distance Accumulation Raster; the Input Distance Accumulation 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.
The output feature service includes a DestID field that identifies the destination to which each line leads.
Unlike most other Raster Analysis tools, Optimal Path As Line 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

Label	Explanation	Data Type
Input Raster or Feature Destinations	A raster or feature dataset identifying locations from which the least accumulative cost path is determined to the least costly source. For a raster, the input type must be integer, and it must consist of cells that have valid values (zero is a valid value). The remaining cells must be assigned NoData. For a feature service, the input type can be point, line or polygon.	Raster Layer; Image Service; Feature Layer; String
Input Distance Accumulation Raster	The distance accumulation raster is used to determine the optimal path from the sources to the destinations. The distance accumulation raster is usually created with the Distance Accumulation or Distance Allocation tool. Each cell in the distance accumulation raster represents the minimum accumulative cost distance over a surface from each cell to a set of source cells.	Raster Layer; Image Service; String
Input Back Direction or Flow Direction Raster	The back direction raster contains calculated directions in degrees. The direction identifies the next cell along the optimal path back to the least accumulative cost source while avoiding barriers. The range of values is from 0 degrees to 360 degrees. The value 0 is reserved for the source cells. Due east (right) is 90 degrees, and the values increase clockwise (180 is south, 270 is west, and 360 is north).	Raster Layer; Image Service; String
Output Optimal Path as Line Name	The name of the output feature service that contains the optimal paths.	String
Destination Field (Optional)	The field that will be used to obtain values for the destination locations. This field must be an integer.	Field
Path Type (Optional)	Specifies a keyword defining the manner in which the values and zones in the input destination data will be interpreted in the cost path calculations. Each zone—For each zone in the input destination data, a least-cost path will be 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. This is the default. Best single—For all cells in 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 cell—For each cell with valid values in the input destination data, a least-cost will be 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
Create Network Paths (Optional)	Specifies whether complete, and possibly overlapping, paths from the destinations to the sources are calculated or if nonoverlapping network paths are created. Unchecked—Complete paths from the destinations to the sources are calculated, which can be overlapping. This is the default. Checked—Nonoverlapping network paths are calculated.	Boolean

Derived Output

Label	Explanation	Data Type
Output Polyline Feature	The feature service output of the optimal paths.	Feature Layer

arcpy.ra.OptimalPathAsLine(inputDestinationRasterOrFeatures, inputDistanceAccumulationRaster, inputBackDirectionRaster, outputPolylineName, {destinationField}, {pathType}, {createNetworkPaths})

Name	Explanation	Data Type
inputDestinationRasterOrFeatures	A raster or feature dataset identifying locations from which the least accumulative cost path is determined to the least costly source. For a raster, the input type must be integer, and it must consist of cells that have valid values (zero is a valid value). The remaining cells must be assigned NoData. For a feature service, the input type can be point, line or polygon.	Raster Layer; Image Service; Feature Layer; String
inputDistanceAccumulationRaster	The distance accumulation raster is used to determine the optimal path from the sources to the destinations. The distance accumulation raster is usually created with the Distance Accumulation or Distance Allocation tool. Each cell in the distance accumulation raster represents the minimum accumulative cost distance over a surface from each cell to a set of source cells.	Raster Layer; Image Service; String
inputBackDirectionRaster	The back direction raster contains calculated directions in degrees. The direction identifies the next cell along the optimal path back to the least accumulative cost source while avoiding barriers. The range of values is from 0 degrees to 360 degrees. The value 0 is reserved for the source cells. Due east (right) is 90 degrees, and the values increase clockwise (180 is south, 270 is west, and 360 is north).	Raster Layer; Image Service; String
outputPolylineName	The name of the output feature service that contains the optimal paths.	String
destinationField (Optional)	The field that will be used to obtain values for the destination locations. This field must be an integer.	Field
pathType (Optional)	Specifies a keyword defining the manner in which the values and zones in the input destination data will be interpreted in the cost path calculations. EACH_ZONE—For each zone in the input destination data, a least-cost path will be 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. This is the default. BEST_SINGLE—For all cells in 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_CELL—For each cell with valid values in the input destination data, a least-cost will be 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
createNetworkPaths (Optional)	Specifies whether complete, and possibly overlapping, paths from the destinations to the sources are calculated or if nonoverlapping network paths are created. DESTINATIONS_TO_SOURCES—Complete paths from the destinations to the sources are calculated, which can be overlapping. This is the default. NETWORK_PATHS—Nonoverlapping network paths are calculated.	Boolean

Derived Output

Name	Explanation	Data Type
outputPolylineFeatures	The feature service output of the optimal paths.	Feature Layer

Code sample

Optimal Path As Line example 1 (Python window)

The following Python window script demonstrates how to use the OptimalPathAsLine tool.

import arcpy

arcpy.ra.OptimalPathAsLine(
    "https://myserver/rest/services/destination/ImageServer", 
    "https://myserver/rest/services/accumulationraster/ImageServer", 
    "https://myserver/rest/services/backdirection/ImageServer", 
    "outpath")

Optimal Path As Line example 2 (stand-alone script)

Calculates the optimal path from a destination to a source.

#-------------------------------------------------------------------------------
# Name: OptimalPathAsLine_Ex_02.py
# Description: Calculates the optimal 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'
inputAccumulationLayer =
    'https://MyPortal.esri.com/server/rest/services/Hosted/costaccumulation/ImageServer'
inputDirectionLayer = 
    'https://MyPortal.esri.com/server/rest/services/Hosted/backdirection/ImageServer'
outputName = 'outTravelPaths'


arcpy.ra.OptimalPathAsLine(inputDestinationLayer, inputAccumulationLayer,
                            inputDirectionLayer, outputName)

Environments

Output Coordinate System

Licensing information

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

Summary

Illustration

Usage

Parameters

Derived Output

Derived Output

Code sample

Environments

Licensing information

Related topics

In this topic