Available with Spatial Analyst license.
Summary
For each cell in the output, the identity of the connected region to which that cell belongs is recorded. A unique number is assigned to each region.
Learn more about creating individual zones with Region Group
Illustration
Usage
In general, the first region scanned receives the value one, the second two, and so on, until all regions are assigned a value. The scan moves from left to right, top to bottom. The values assigned to the output zones are based on when they are encountered in the scanning process.
There are two parameters that control how connectivity between regions is established. The Number of neighbors to use parameter determines the geometry of the connectivity, either as orthogonal (four way) only, or as diagonal as well as orthogonal (eight way). The Zone grouping method parameter determines which cell values are considered when evaluating connectivity.
By default, the Add link field to output (ADD_LINK in Python) parameter is enabled. This will create a LINK field in the attribute table of the output raster, which retains the original zone value for each cell from the input raster.
This parameter only applies when the Zone grouping method (zone_connectivity in Python) parameter is set to Within. If it is set to Cross, the attribute table of the output raster will only contain the usual Value and Count fields.
When available, the LINK field allows you to trace the parentage of each newly created region back to the original input zone values, to be used for additional analysis.
For example, the attribute table for the output raster shown in the illustration above is the following:
Processing speed is improved if no LINK field is created. If the original value of each region is no longer needed, uncheck this option.
If the Mask environment is set, the spatial configuration and the number of regions may be altered in the output raster.
Cell locations that contain the excluded value receive zero on the output so that these zones are not confused with existing NoData cell locations. Since the numbering begins with the value 1, the cells that are excluded from the regroup are considered background. These background cells can be reclassed or manipulated in the same way as any other value.
See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.
Syntax
RegionGroup(in_raster, {number_neighbors}, {zone_connectivity}, {add_link}, {excluded_value})| Parameter | Explanation | Data Type |
in_raster | The input raster for which unique connected regions of cells will be identified. It must be of integer type. | Raster Layer |
number_neighbors (Optional) | Specifies the number of neighboring cells to use when evaluating connectivity between cells that define a region.
| String |
zone_connectivity (Optional) | Defines which cell values should be considered when testing for connectivity.
| String |
add_link (Optional) | Specifies whether a link field will be added to the table of the output when the zone_connectivity parameter is set to WITHIN. It is ignored if that parameter is set to CROSS.
| Boolean |
excluded_value (Optional) | A value that excludes all cells of that zone from the connectivity evaluation. If a cell location contains the value, no spatial connectivity will be evaluated, regardless of how the number of neighbors is specified. Cells with the excluded value will be treated in a similar way to NoData cells, and are eliminated from consideration in the operation. Input cells that contain the excluded value will receive 0 on the output raster. The excluded value is similar to the concept of a background value. By default, there is no value defined for this parameter, which means that all of the input cells will be considered in the operation. | Long |
Return Value
| Name | Explanation | Data Type |
| out_raster | The output region group raster. The output is always of integer type. | Raster |
Code sample
RegionGroup example 1 (Python window)
This example assigns a unique number to each region of the input raster using eight-way connectivity.
import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
outRgnGrp = RegionGroup("land", "EIGHT", "", "", 5)
outRgnGrp.save("c:/sapyexamples/output/reggrp_ex5")
RegionGroup example 2 (stand-alone script)
This example assigns a unique number to each region of the input raster using eight-way connectivity with an excluded value.
# Name: RegionGroup_Ex_02.py
# Description: Records, for each cell in the output, the
# identity of the connected region to which
# it belongs within the Analysis window. A
# unique number is assigned to each region.
# 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
inRaster = "land"
valToIgnore = 5
# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")
# Execute RegionGroup
outRegionGrp = RegionGroup(inRaster, "EIGHT", "CROSS",
"NO_LINK", valToIgnore)
# Save the output
outRegionGrp.save("C:/sapyexamples/output/reggrpout")
Environments
Licensing information
- Basic: Requires Spatial Analyst
- Standard: Requires Spatial Analyst
- Advanced: Requires Spatial Analyst