| Label | Explanation | Data Type |
Input Raster or Feature Regions | The input regions that will be connected by the optimal corridors. 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 Corridor Polygons | The output polygon or line feature class of the optimal corridors that connect each of the input regions. Corridors (or lines) will overlap in locations where corridors travel the same route. Each corridor (or line) is uniquely numbered and additional fields in the attribute table store specific information about the path. Those additional fields are the following:
| Feature Class |
Input Raster or Feature Barriers (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. Cost raster values that are negative or zero are invalid but will be treated as small positive cost values. | Raster Layer |
Output Optimal Connection Lines (Optional) | The output line feature class identifies the optimal lines to connect each of the input regions. Lines will overlap in locations where paths travel the same route. 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:
| Feature Class |
Output Neighboring Corridor Polygons (Optional) | The output polygon or line feature class identifying the optimal corridors that connect each region to each of its closest or cost neighbors. Corridors (or lines) will overlap in locations where corridors travel the same route. Each corridor is uniquely numbered and additional fields in the attribute table store specific information about the path. Those additional fields are the following:
| Feature Class |
Output Neighboring Connection Lines (Optional) | The output line feature class identifying the optimal line from each region to each of its closest or cost neighbors. Each corridor (or polygon) is uniquely numbered and additional fields in the attribute table store specific information about the path. Those additional fields are the following:
Since each path is represented by a unique line, there will be multiple lines in locations where the same route is optimal. | Feature Class |
Corridor Method (Optional) | Specifies how the corridor will be created.
Note:At this release, there is only one method to create corridors: fixed width. Since there is only a single default option, this parameter will be inactive, and will not appear on the tool dialog box. | String |
Corridor Width (Optional) | A linear distance that defines the width of the resulting corridors. The value must be greater than or equal to zero. The default is zero. | Double |
Distance Method (Optional) | Specifies whether the distance will be calculated using a planar (flat earth) or a geodesic (ellipsoid) method.
| String |
Available with Spatial Analyst license.
Summary
Calculates the optimal corridor connections between two or more input regions.
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 the input regions are identified by a raster, if any zones (cells with the same value) are composed of multiple regions, run the Region Group tool first as a preprocessing step to assign unique values to each region. Then use the resulting raster as the input regions to this 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 provided, the tool 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 the 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, rasterize the input features directly using the Polygon to Raster tool, set a Priority field value, and use the resulting output as input to the this 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.
Locations identified by the Input Raster or Feature Barriers parameter, cell locations with NoData in the Input Cost Raster parameter value, or locations that are not within the environment 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 parameter value 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 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.
When the Input Cost Raster parameter value is provided, the tool performs calculations on that cost surface based on the value of the Corridor Width parameter. This ensures that optimal corridors are created for the specified width and it may lead to regions located near the edge of the surface to be unconnected to the other results.
Specifying regions located near the Input Raster or Feature Barriers parameter value may also result in unconnected corridors.
For the Output Neighboring Corridor Polygons and Output Neighboring Connection Lines parameters, if a cost surface is not provided, the neighbors will be 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 will be 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 Output Neighboring Corridor Polygons parameter value is created from the paths produced in the optional neighboring connection lines output. The paths in the optional neighboring connection lines 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 connection lines network necessary to travel between the regions. Then the optimal corridor polygons network is created from the optimal connection lines network.
The Output Optimal Connect Lines parameter value is a subset of the paths produced by the Output Optional Neighboring Connection Lines parameter . To calculate this subset, the neighboring connection lines 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 subset of optimal connection lines necessary to travel between the regions.
Each optimal line 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 Output Neighboring Connection Lines parameter value 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 corridors created by this tool are fixed-width corridors. The Corridor Width parameter identifies the fixed width of the corridors as a linear distance. When the Corridor Width parameter value is 0, the output corridors will be the optimal path lines.
See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.
Parameters
OptimalCorridorConnections(in_regions, out_optimal_polygons, {in_barriers}, {in_cost_raster}, {out_optimal_lines}, {out_neighbor_polygons}, {out_neighbor_lines}, {corridor_method}, {corridor_width}, {distance_method})| Name | Explanation | Data Type |
in_regions | The input regions that will be connected by the optimal corridors. 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_optimal_polygons | The output polygon or line feature class of the optimal corridors that connect each of the input regions. Corridors (or lines) will overlap in locations where corridors travel the same route. Each corridor (or line) is uniquely numbered and additional fields in the attribute table store specific information about the path. Those additional fields are the following:
| Feature Class |
in_barriers (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. Cost raster values that are negative or zero are invalid but will be treated as small positive cost values. | Raster Layer |
out_optimal_lines (Optional) | The output line feature class identifies the optimal lines to connect each of the input regions. Lines will overlap in locations where paths travel the same route. 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:
| Feature Class |
out_neighbor_polygons (Optional) | The output polygon or line feature class identifying the optimal corridors that connect each region to each of its closest or cost neighbors. Corridors (or lines) will overlap in locations where corridors travel the same route. Each corridor is uniquely numbered and additional fields in the attribute table store specific information about the path. Those additional fields are the following:
| Feature Class |
out_neighbor_lines (Optional) | The output line feature class identifying the optimal line from each region to each of its closest or cost neighbors. Each corridor (or polygon) is uniquely numbered and additional fields in the attribute table store specific information about the path. Those additional fields are the following:
Since each path is represented by a unique line, there will be multiple lines in locations where the same route is optimal. | Feature Class |
corridor_method (Optional) | Specifies how the corridor will be created. Note:At this release, there is only one method to create corridors: fixed width. Since there is only a single default option, this parameter will be inactive, and will not appear on the tool dialog box.
| String |
corridor_width (Optional) | A linear distance that defines the width of the resulting corridors. The value must be greater than or equal to zero. The default is zero. | Double |
distance_method (Optional) | Specifies whether the distance will be calculated using a planar (flat earth) or a geodesic (ellipsoid) method.
| String |
Code sample
The following Python window script demonstrates how to use the OptimalCorridorConnections function.
import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/arcpyexamples/data"
out_OCC_raster = OptimalCorridorConnections("InRegions.tif",
"OutCorridors.shp", "InBarriers.tif", "InCostRaster.tif",
"OutOptimalPaths.shp", "OutNbrPoly.shp", "OutNbrLines.shp",
"FIXED_WIDTH_CORRIDOR", 5000, "PLANAR")Calculate an optimal network of wildlife corridors between known inhabited areas.
# Name: OptimalCorridorConnections_standalone.py
# Description: Calculates corridor.
# Requirements: Spatial Analyst Extension
# Import system modules
import arcpy
from arcpy import env
from arcpy.sa import *
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Set environment settings
env.workspace = "C:/arcpyexamples/data"
# Set local variables
regions = "Lakes.tif"
outCorridors = "NewCorridors.shp"
roadBarriers = "Roads.shp"
costSurface = "CostSurface.tif"
optimalLines = "OutCorridorCenterLines.shp"
outAllCorridors = "OutAllCorridors.shp"
outAllLines = "OutAllCenterLines.shp"
corridorMethod = "FIXED_WIDTH_CORRIDOR"
corridorWidth = 5000
distanceMethod = "GEODESIC"
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Execute OptimalCorridorConnections
OptimalCorridorConnections(regions, outCorridors, roadBarriers,
costSurface, optimalLines,
outAllCorridors, outAllLines,
corridorMethod, corridorWidth, distanceMethod)Environments
Licensing information
- Basic: Requires Spatial Analyst
- Standard: Requires Spatial Analyst
- Advanced: Requires Spatial Analyst