| Label | Explanation | Data Type |
Input raster or feature region data | The input regions to be connected by the optimal network. Regions can be defined by either a raster or a feature dataset. If the region input is a 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 a feature dataset, it can be polygons, polylines, or points. Polygon feature regions cannot be composed of multipart polygons. | Raster Layer; Feature Layer |
Output optimal connectivity lines | The output polyline feature class of the optimal network of paths that connect each of the input regions. 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:
This information provides insight into the paths in the network. Since each path is represented by a unique line, there will be multiple lines in locations where paths travel the same route. | Feature Class |
Input barrier raster or feature data (Optional) | The dataset that defines the barriers. The barriers can be defined by an integer or a floating-point raster, or by a point, line, or polygon feature. | Raster Layer; Feature Layer |
Input cost raster (Optional) | A raster 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, but they cannot be negative or zero (you cannot have a negative or zero cost). | Raster Layer |
Output feature class of neighboring connections (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:
This information provides insight into the paths in 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. | Feature Class |
Distance Method (Optional) | Specifies whether the distance will be calculated using a planar (flat earth) or a geodesic (ellipsoid) method.
| String |
Connections within regions (Optional) | Specifies whether the paths will continue and connect within the input regions.
| String |
Available with Spatial Analyst license.
Summary
Calculates the optimal connectivity network between two or more input regions.
Learn more about connecting regions with the optimal network
Usage
The input regions can be either raster or feature data.
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 Region Group tool as a preprocessing step to assign unique values to each region. Then use the resulting raster as the input regions to the Optimal Region Connections tool.
When input regions are identified by polygon, line, or point data, they are converted to raster using the feature ID to ensure that the resulting regions have unique values. Multipart polygons cannot be used as input. When multipoint data is entered, Optimal Region Connections randomly selects one of the points at the location as the region value.
You can control the resolution of the rasterized input feature regions with the Cell Size environment. By default, the resolution will be set to the resolution of the input cost raster if one is provided.
When using polygon feature data for the input region data, care must be taken with how the output cell size is handled when it is coarse, relative to the detail present in the input. The internal rasterization process uses the same default Cell assignment type method as the Polygon to Raster tool, which is Cell center. This means that data that is not located at the center of the cell will not be included in the intermediate rasterized region and will not be represented in the distance calculations. For example, if your regions are a series of small polygons, such as building footprints that are small relative to the output cell size, only a few of them may fall under the centers of the output raster cells, seemingly causing most of the others to be lost in the analysis.
To avoid this situation, as an intermediate step, rasterize the input features directly with the Polygon to Raster tool, set a Priority field value, and use the resulting output as input to the Optimal Region Connections tool. Alternatively, select a small enough cell size to capture the appropriate amount of detail from the input features.
When the region input is a feature, the ObjectID field will be used as the region identifiers.
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 the Optimal Region Connections tool may be negatively impacted.
Locations identified by the Input barrier raster or feature data parameter, cell locations with NoData in the Input cost raster parameter, or locations that are not within the Mask all act as barriers.
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.
The default processing extent is the same as that of the Input cost raster value if one is provided; otherwise, it will be set to the extent of the input regions.
The Input cost raster parameter cannot contain zero values since the algorithm is a multiplicative process. If your cost raster does contain zero values, and these values represent areas of lowest cost, change the zero values to a small positive value (such as 0.01) before running this tool.
You can use the Con tool to change the zero cells to a different value. If areas with a zero value represent areas that should be excluded from the analysis, convert these values to NoData first by running the Set Null tool.
For the Output feature class of neighboring connections parameter, if a cost surface is not specified, the neighbors are identified by Euclidean distance. In which case, 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 making a region's closest neighbor the cheapest one to travel to. A cost allocation operation is performed to identify which regions are neighbors to one another.
The optimal output network is created from the paths produced in the optional neighboring connections output. The paths in the optional neighboring connections output are converted to graph theory. The regions are the vertices, the paths are the edges, and the accumulative distances or costs are the weights for the edges. The minimum spanning tree is calculated from the graph representation of the paths to determine the optimal path network necessary to travel between the regions.
Each optimal path first reaches the outer boundary of the polygon or multicell region. From the perimeter of the region, the tool continues the paths with additional line segments, allowing for points of entry and exit between regions, and movement within them. There is no additional distance or cost of movement along these line segments.
Depending on the configuration of the input regions and their allocation neighbors, a path can pass through an intermediate region to reach a neighboring region. That path will incur costs as it moves through that intermediate region.
The optional neighboring connections output can be used as an alternative network to the minimum spanning tree network. This output connects each region to its neighboring cost regions, producing a more complex network with many paths. The feature class can be used as is or as the base from which to create your own network. To do that, select the specific paths you want within the network using the Select By Attributes button, the Select group on the Map tab, or the Select Layer By Attributes tool. Selection of the paths can be based on knowledge of the area and the statistics associated with the paths in the resulting attribute table.
The resulting network, from either the minimum spanning tree or the optional neighboring connections, can be converted to a Network Analyst network for additional network analysis.
See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.
Parameters
OptimalRegionConnections(in_regions, out_feature_class, {in_barrier_data}, {in_cost_raster}, {out_neighbor_paths}, {distance_method}, {connections_within_regions})| Name | Explanation | Data Type |
in_regions | The input regions to be connected by the optimal network. Regions can be defined by either a raster or a feature dataset. If the region input is a 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 a feature dataset, it can be polygons, polylines, or points. Polygon feature regions cannot be composed of multipart polygons. | Raster Layer; Feature Layer |
out_feature_class | The output polyline feature class of the optimal network of paths that connect each of the input regions. 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:
This information provides insight into the paths in the network. Since each path is represented by a unique line, there will be multiple lines in locations where paths travel the same route. | Feature Class |
in_barrier_data (Optional) | The dataset that defines the barriers. The barriers can be defined by an integer or a floating-point raster, or by a point, line, or polygon feature. | Raster Layer; Feature Layer |
in_cost_raster (Optional) | A raster 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, but they cannot be negative or zero (you cannot have a negative or zero cost). | Raster Layer |
out_neighbor_paths (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:
This information provides insight into the paths in 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. | Feature Class |
distance_method (Optional) | Specifies whether the distance will be calculated using a planar (flat earth) or a geodesic (ellipsoid) method.
| String |
connections_within_regions (Optional) | Specifies whether the paths will continue and connect within the input regions.
| String |
Code sample
The following Python window script demonstrates how to use the OptimalRegionConnections function.
import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
outOptRegConnect = OptimalRegionConnections("source.shp", "elevation")
outOptRegConnect.save("C:/sapyexamples/output/optregconnect.tif")Produce the least-cost optimum network of paths connecting the input regions to one another.
# Name: OptimalRegionConnections_Ex_02.py
# Description: Calculates for each cell the optimum region connections.
#
# 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
inSourceData = "source.shp"
inCostRaster = "elevation"
maxDistance = 20000000
outBkLinkRaster = "C:/sapyexamples/output/outbklink.tif"
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Execute the tool
outOptRegConnect = OptimalRegionConnections(inSourceData, inCostRaster)
# Save the output
outOptRegConnect.save.save("C:/sapyexamples/output/optregconnect.tif")