Optimal Region Connections (Raster Analysis)

Summary

Calculates the optimal connection of paths between two or more input regions.

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.

• In a raster, a region is a group of cells with the same value that are contiguous to one another (adjacent). When your input regions are identified by a raster, if any zones (cells with the same value) are composed of multiple regions, first run the Spatial Analyst Region Group tool as a preprocessing step to assign unique values to each region. Use the resulting raster as the input regions to the Optimal Region Connections tool.

• If the input regions are raster and the range of the row IDs is very large (even if there are only a few regions), the performance of this tool may be negatively impacted.

• When the region input is a feature service, the regions are converted internally to a raster before performing the analysis.

  The resolution of the raster can be controlled with the Cell Size environment. By default, if no other rasters are specified in the tool, the resolution will be determined by the shorter of the width or height of the extent of the input feature, in the input spatial reference, divided by 250.

• When the region input is a feature, the ObjectID field will be used as the region identifiers.

• Locations identified by the Input Raster or Feature Barriers parameter or cell locations with NoData in the Input Cost Raster parameter act as barriers.

• The default processing extent is the same as that of the Input Cost Raster if one is provided; otherwise, it will be set to the extent of the input regions.

• Cost raster values that are negative or zero are invalid but will be treated as small positive values. The accumulative cost algorithm is a multiplicative process, and it cannot calculate accumulative cost correctly if cost values are negative or zero. If the cost raster contains those values, and those locations represent areas that are to be excluded from the analysis, turn those cells into NoData before running the tool. You can do this using the ArcGIS Spatial Analyst extension Set Null tool. The NoData value is treated as a barrier in this analysis, so any locations that are NoData in the input will be NoData in the result.

• For the Output Neighboring Connection Lines Name parameter, if a cost surface is not specified, the neighbors are identified by Euclidean distance and a region's closest neighbor is the one that is closest in distance. However, when a cost surface is provided, the neighbors are identified by cost distance and a region's closest neighbor is the least expensive one to travel to. A cost allocation operation is performed to identify which regions are neighbors to one another.

• The analysis Mask environment can be set to a feature or a raster dataset. If the mask is a feature, it will be converted to a raster. The cells that have a value define the locations that are within the mask area. NoData cells define the locations that are outside the mask area and will be treated as a barrier.

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

Parameters

Dialog

Label	Explanation	Data Type
Input Raster or Feature Regions	The input regions to be connected by the optimal network. Regions can be defined by either raster or feature data. If the region input is raster, the regions are defined by groups of contiguous (adjacent) cells of the same value. Each region must be uniquely numbered. The cells that are not part of any region must be NoData. The raster type must be integer, and the values can be either positive or negative. If the region input is feature data, it can be polygons, lines, or points. Polygon feature regions cannot be composed of multipart polygons.	Raster Layer; Image Service; Feature Layer; String
Output Optimal Connection Lines Name	The name of the output line feature service that connects each input region. Each path (or line) is uniquely numbered and additional fields in the attribute table store specific information about the path. Those additional fields are the following: PATHID—The unique identifier for the path PATHCOST—The total accumulative distance or cost for the path REGION1—The first region the path connects REGION2—The other region the path connects This information provides insight into the paths within the network. Since each path is represented by a unique line, there will be multiple lines in locations where paths travel the same route.	String
Input Raster or Feature Barriers (Optional)	The dataset that defines the barriers. The barriers can be defined by an integer or a floating-point image service, or by a feature service. For a feature service, the input type can be point, line or polygon. For an image service barrier, the barrier must have a valid value, including zero, and the areas that are not barriers must be NoData.	Raster Layer; Image Service; Feature Layer; String
Input Cost Raster	An image service defining the impedance or cost to move planimetrically through each cell. The value at each cell location represents the cost-per-unit distance for moving through the cell. Each cell location value is multiplied by the cell resolution while also compensating for diagonal movement to obtain the total cost of passing through the cell. The values of the cost raster can be integer or floating point. Cost raster values that are negative or zero are invalid but will be treated as small positive cost values.	Raster Layer; Image Service; String
Output Neighboring Connection Lines Name (Optional)	The output polyline feature class identifying all paths from each region to each of its closest or cost neighbors. Each path (or line) is uniquely numbered and additional fields in the attribute table store specific information about the path. Those additional fields are the following: PATHID—The unique identifier for the path PATHCOST—The total accumulative distance or cost for the path REGION1—The first region the path connects REGION2—The other region the path connects This information provides insight into the paths within the network and is useful when deciding which paths should be removed if necessary. Since each path is represented by a unique line, there will be multiple lines in locations where paths travel the same route.	String
Distance Method (Optional)	Specifies whether the distance will be calculated using a planar (flat earth) or a geodesic (ellipsoid) method. Planar—The distance calculation will be performed on a projected flat plane using a 2D Cartesian coordinate system. This is the default. Geodesic—The distance calculation will be performed on the ellipsoid. Regardless of input or output projection, the results will not change.	String
Connections Within Regions (Optional)	Specifies whether the paths will continue and connect within the input regions. Generate connections—Paths will continue within the input regions to connect all paths that enter a region. No connections—Paths will stop at the edges of the input regions and will not continue or connect within them.	String

Derived Output

Label	Explanation	Data Type
Output Optimal Connection Lines	The lines that optimally connect the regions.	Feature Class
Output Neighboring Connection Lines	The output neighbor connection features.	Feature Class

Python

arcpy.ra.OptimalRegionConnections(inputRegionRasterOrFeatures, outputOptimalLinesName, {inputBarrierRasterOrFeatures}, inputCostRaster, {outputNeighborConnectionsName}, {distanceMethod}, {connectionsWithinRegions})

Name	Explanation	Data Type
inputRegionRasterOrFeatures	The input regions to be connected by the optimal network. Regions can be defined by either raster or feature data. If the region input is raster, the regions are defined by groups of contiguous (adjacent) cells of the same value. Each region must be uniquely numbered. The cells that are not part of any region must be NoData. The raster type must be integer, and the values can be either positive or negative. If the region input is feature data, it can be polygons, lines, or points. Polygon feature regions cannot be composed of multipart polygons.	Raster Layer; Image Service; Feature Layer; String
outputOptimalLinesName	The name of the output line feature service that connects each input region. Each path (or line) is uniquely numbered and additional fields in the attribute table store specific information about the path. Those additional fields are the following: PATHID—The unique identifier for the path PATHCOST—The total accumulative distance or cost for the path REGION1—The first region the path connects REGION2—The other region the path connects This information provides insight into the paths within the network. Since each path is represented by a unique line, there will be multiple lines in locations where paths travel the same route.	String
inputBarrierRasterOrFeatures (Optional)	The dataset that defines the barriers. The barriers can be defined by an integer or a floating-point image service, or by a feature service. For a feature service, the input type can be point, line or polygon. For an image service barrier, the barrier must have a valid value, including zero, and the areas that are not barriers must be NoData.	Raster Layer; Image Service; Feature Layer; String
inputCostRaster	An image service defining the impedance or cost to move planimetrically through each cell. The value at each cell location represents the cost-per-unit distance for moving through the cell. Each cell location value is multiplied by the cell resolution while also compensating for diagonal movement to obtain the total cost of passing through the cell. The values of the cost raster can be integer or floating point. Cost raster values that are negative or zero are invalid but will be treated as small positive cost values.	Raster Layer; Image Service; String
outputNeighborConnectionsName (Optional)	The output polyline feature class identifying all paths from each region to each of its closest or cost neighbors. Each path (or line) is uniquely numbered and additional fields in the attribute table store specific information about the path. Those additional fields are the following: PATHID—The unique identifier for the path PATHCOST—The total accumulative distance or cost for the path REGION1—The first region the path connects REGION2—The other region the path connects This information provides insight into the paths within the network and is useful when deciding which paths should be removed if necessary. Since each path is represented by a unique line, there will be multiple lines in locations where paths travel the same route.	String
distanceMethod (Optional)	Specifies whether the distance will be calculated using a planar (flat earth) or a geodesic (ellipsoid) method. PLANAR—The distance calculation will be performed on a projected flat plane using a 2D Cartesian coordinate system. This is the default. GEODESIC—The distance calculation will be performed on the ellipsoid. Regardless of input or output projection, the results will not change.	String
connectionsWithinRegions (Optional)	Specifies whether the paths will continue and connect within the input regions. GENERATE_CONNECTIONS—Paths will continue within the input regions to connect all paths that enter a region. NO_CONNECTIONS—Paths will stop at the edges of the input regions and will not continue or connect within them.	String

Derived Output

Name	Explanation	Data Type
outputOptimalLinesFeatures	The lines that optimally connect the regions.	Feature Class
outputNeighborConnectionFeatures	The output neighbor connection features.	Feature Class

Code sample

Optimal Region Connections example 1 (Python window)

This example calculates the optimum connections between regions.

import arcpy

arcpy.ra.OptimalRegionConnections(
    "https://myserver/rest/services/regions/ImageServer", "outOptimalConnections",
    "https://myserver/rest/services/barriers/ImageServer",
    "https://myserver/rest/services/cost/ImageServer",
    "outNeighborConnections")

Optimal Region Connections example 2 (stand-alone script)

This example calculates the optimum connections between regions.

#-------------------------------------------------------------------------------
# Name: OptimalRegionConnections_Ex_02.py
# Description: Calculates the optimal connections between regions.
# Requirements: ArcGIS Image Server

# Import system modules
import arcpy

# Set local variables
inputRegionsLayer =
    'https://MyPortal.esri.com/server/rest/services/Hosted/regions/ImageServer'
outputName = 'outOptimalConnections'
inputBarriersLayer =
    'https://MyPortal.esri.com/server/rest/services/Hosted/barriers/ImageServer'
inputCostLayer = 
    'https://MyPortal.esri.com/server/rest/services/Hosted/cost/ImageServer'
outputName02 = 'outNeighborConnections'
distanceMethod = 'GEODESIC'
connectionsWithinRegions = 'GENERATE_CONNECTIONS' 

arcpy.ra.OptimalRegionConnections(inputRegionsLayer, outputName, inputBarriersLayer,
                                  inputCostLayer, outputName02, distanceMethod,connectionsWithinRegions)

Environments

Cell Size, Extent, Mask, Output Coordinate System, Snap Raster

Licensing information

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