Optimal Path As Line (Spatial Analyst)

Summary

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

Learn more about connecting locations with optimal paths

Usage

  • The Optimal Path As Line tool produces an output polyline feature that is the optimal path from the source to the destination.

  • When the input destination data is a raster, the set of destination cells consists of all cells in the Input Raster or Feature Destination parameter value 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 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 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 the 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.

  • Prior to generating an optimal path, one of the following tools is typically 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. If the Create Network Paths parameter is not enabled then the Input Distance Accumulation Raster is not used to determine the path. Therefore, 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. However, if Create Network Paths are generated, then the Input Distance Accumulation Raster must be an Output flow accumulation raster. See the Flow Direction tool for more information on D8 flow direction rasters and Flow Accumulation tool to create the accumulation raster.

  • The output polyline feature includes a field called DestID and a field called PathCost. The DestID field identifies the destination to which each line leads. The PathCost field shows the total accumulative cost for each path. 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.

  • To generate an optimal path, the Cell size environment setting is ignored and the cell size of the Input cost backlink raster value is used to calculate the output raster. The pattern of the back link raster would be altered if it were resampled to a different resolution. To avoid confusion, do not set the cell size when using this tool.

Parameters

LabelExplanationData Type
Input Raster or Feature Destinations

An integer raster or feature (point, line, or polygon) that identifies locations from which the optimal path will be 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 Distance Accumulation Raster

The distance accumulation raster that will be 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
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, with 0 reserved for the source cells. Due east (right) is 90, and the values increase clockwise (180 is south, 270 is west, and 360 is north).

Raster Layer
Output Optimal Path as Line

The output feature class that is the optimal path or paths.

Feature Class
Destination Field
(Optional)

An integer field that will be used to obtain values for the destination locations.

Field
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.

  • Each zoneFor each zone on 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.
  • Best singleFor 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 cellFor each cell with valid values on the input destination data, a least-cost path will be 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

OptimalPathAsLine(in_destination_data, in_distance_accumulation_raster, in_back_direction_raster, out_polyline_features, {destination_field}, {path_type}, {create_network_paths})
NameExplanationData Type
in_destination_data

An integer raster or feature (point, line, or polygon) that identifies locations from which the optimal path will be 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_distance_accumulation_raster

The distance accumulation raster that will be 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
in_back_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, with 0 reserved for the source cells. Due east (right) is 90, and the values increase clockwise (180 is south, 270 is west, and 360 is north).

Raster Layer
out_polyline_features

The output feature class that is the optimal path or paths.

Feature Class
destination_field
(Optional)

An integer field that will be used to obtain values for the destination locations.

Field
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.

  • EACH_ZONEFor each zone on 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.
  • BEST_SINGLEFor 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_CELLFor each cell with valid values on the input destination data, a least-cost path will be 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.

  • DESTINATIONS_TO_SOURCESComplete paths from the destinations to the sources are calculated, which can be overlapping. This is the default.
  • NETWORK_PATHSNonoverlapping network paths are calculated.
Boolean

Code sample

OptimalPathAsLine 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"
OptimalPathAsLine("observers.shp", "distaccum.tif", "backdir.tif",
                  "c:/sapyexamples/output/outOptimalPath01.shp")
OptimalPathAsLine example 2 (stand-alone script)

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

# Name: OptimalPathAsLine_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"
inDistAccum = "accumraster.tif"
inBackDir = "backdir2.tif"
outPathFeat = "c:/sapyexamples/output.gdb/optimalfeaturepaths02"
destField = "FID"
method = "EACH_CELL"

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

# Execute
OptimalPathAsLine(inDestination, inDistAccum, inBackDir, 
                  outPathFeat, destField, method)

Related topics