Region Group (Spatial Analyst)

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

OutRas = RegionGroup(InRas1, FOUR, WITHIN, #, #)

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:

  

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

Parameters

Dialog

Label	Explanation	Data Type
Input raster	The input raster for which unique connected regions of cells will be identified. It must be of integer type.	Raster Layer
Number of neighbors to use (Optional)	Specifies the number of neighboring cells to use when evaluating connectivity between cells that define a region. Four—Connectivity is evaluated for the four nearest (orthogonal) neighbors of each input cell. Only the cells with the same value that share at least one side will contribute to an individual region. If two cells with the same value are diagonal from one another, they are not considered connected. This is the default. Eight—Connectivity is evaluated for the eight nearest neighbors (both orthogonal and diagonal) of each input cell. Cells with the same value that are connected either along a common edge or corner to each other will contribute to an individual region.	String
Zone grouping method (Optional)	Defines which cell values should be considered when testing for connectivity. Within—Connectivity for a region is evaluated for input cells that are part of the same zone (cell value). The only cells that can be grouped are cells from the same zone that meet the spatial requirements of connectivity specified by the Number of neighbors to use parameter (four or eight). This is the default. Cross—Connectivity for a region is evaluated between cells of any value, except for the zone cells identified to be excluded by the Excluded value parameter, and subject to the spatial requirements specified by the Number of neighbors to use parameter. Groupings of regions in the input that are separated from other groupings by a buffer of NoData cells will be processed independently from each other.	String
Add link field to output (Optional)	Specifies whether a link field will be added to the table of the output when the Zone grouping method parameter is set to Within. It is ignored if that parameter is set to Cross. Checked—A LINK field will be added to the table of the output raster. This field stores the value of the zone to which the cells of each region in the output belong, according to the connectivity rule defined in the Number of neighbors to use parameter. This is the default. Unchecked—A LINK field will not be added. The attribute table for the output raster will only contain the Value and Count fields.	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

Label	Explanation	Data Type
Output raster	The output region group raster. The output is always of integer type.	Raster

Python

RegionGroup(in_raster, {number_neighbors}, {zone_connectivity}, {add_link}, {excluded_value})

Name	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. FOUR—Connectivity is evaluated for the four nearest (orthogonal) neighbors of each input cell. Only the cells with the same value that share at least one side will contribute to an individual region. If two cells with the same value are diagonal from one another, they are not considered connected. This is the default. EIGHT—Connectivity is evaluated for the eight nearest neighbors (both orthogonal and diagonal) of each input cell. Cells with the same value that are connected either along a common edge or corner to each other will contribute to an individual region.	String
zone_connectivity (Optional)	Defines which cell values should be considered when testing for connectivity. WITHIN—Connectivity for a region is evaluated for input cells that are part of the same zone (cell value). The only cells that can be grouped are cells from the same zone that meet the spatial requirements of connectivity specified by the number_neighbors parameter (four or eight). This is the default. CROSS—Connectivity for a region is evaluated between cells of any value, except for the zone cells identified to be excluded by the excluded_value parameter, and subject to the spatial requirements specified by the number_neighbors parameter. Groupings of regions in the input that are separated from other groupings by a buffer of NoData cells will be processed independently from each other.	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. ADD_LINK—A LINK field will be added to the table of the output raster. This field stores the value of the zone to which the cells of each region in the output belong according to the connectivity rule defined in the number_neighbors parameter. This is the default. NO_LINK—A LINK field will not be added. The attribute table for the output raster will only contain the Value and Count fields.	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

# Execute RegionGroup
outRegionGrp = RegionGroup(inRaster, "EIGHT", "CROSS", 
                           "NO_LINK", valToIgnore)

# Save the output 
outRegionGrp.save("C:/sapyexamples/output/reggrpout")

Environments

Auto Commit, Cell Size, Cell Size Projection Method, Compression, Current Workspace, Extent, Geographic Transformations, Mask, Output CONFIG Keyword, Output Coordinate System, Scratch Workspace, Snap Raster, Tile Size

Licensing information

• Basic: Requires Spatial Analyst
• Standard: Requires Spatial Analyst
• Advanced: Requires Spatial Analyst