ArcGIS for Desktop

  • Documentation
  • Pricing
  • Support

  • My Profile
  • Help
  • Sign Out
ArcGIS for Desktop

ArcGIS Online

The mapping platform for your organization

ArcGIS for Desktop

A complete professional GIS

ArcGIS for Server

GIS in your enterprise

ArcGIS for Developers

Tools to build location-aware apps

ArcGIS Solutions

Free template maps and apps for your industry

ArcGIS Marketplace

Get apps and data for your organization

  • Documentation
  • Pricing
  • Support
Esri
  • Sign In
user
  • My Profile
  • Sign Out

Help

  • Home
  • Get Started
  • Map
  • Analyze
  • Manage Data
  • Tools
  • More...

Region Group

Available with Spatial Analyst license.

  • Summary
  • Illustration
  • Usage
  • Syntax
  • Code Sample
  • Environments
  • Licensing Information

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

Region Group illustration
OutRas = RegionGroup(InRas1)

Usage

  • The first region scanned receives the value one, the second two, and so forth, 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.

  • By default, the Add link field to output (ADD_LINK in Python) option is enabled. This will create an item called LINK in the attribute table of the output raster, which retains the original value for each cell from the input raster.

  • The LINK field allows you to trace the parentage of each of the newly created regions for queries or analysis.

    For example, the attribute table for the output raster shown in the illustration above is the following:

    Example of LINK item in attribute table
    Example of LINK item in attribute table
  • It will significantly speed up the processing if the LINK field is not created. If the original value of each region is no longer needed, uncheck this option.

  • If a mask has been set in the environment, those cells that have been masked will receive NoData on the output raster. With a mask, the spatial configuration and the number of regions may be altered on the output raster. If a region was continuous and the imposition of a mask breaks the continuity, the region will be divided into two regions with different values or grouping identifiers on the output raster.

    The mask cannot only create additional regions by dividing a region into two or more separate regions, it can also reduce the number of regions on the output. If a mask totally covers or eliminates a potential region of connected cells, these cells will not be considered as a new zone on the output; they will receive NoData values.

  • Region Group is especially useful when the analysis is on regions and not on zones. Since the input zone value is maintained, the original zonal class can also be used in the analysis.

  • 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 Region Group begins numbering with the value 1, the cells that are excluded from the regroup are considered background. These background cells can be reclassed or manipulated as any other value. The locations containing excluded values can easily be converted to NoData using the Con tool.

  • 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})
ParameterExplanationData Type
in_raster

The input raster whose unique connected regions will be identified.

It must be of integer type.

Raster Layer
number_neighbors
(Optional)

The number of neighboring cells to use in evaluating connectivity between cells.

  • FOUR — Defines connectivity between cells of the same value only if the cells are directly to the left, right, above, or below each of the four nearest neighbors. If two cells with the same value are diagonal from one another, they are not considered connected.
  • EIGHT — Defines connectivity between cells of the same value if they are within the immediate eight-cell neighborhood (eight nearest neighbors) of each other. This includes to the right, left, above, or diagonal to each other.
String
zone_connectivity
(Optional)

Defines which cell values should be considered when testing for connectivity.

  • WITHIN — Tests connectivity between input values that are the same within the same zone. The only cells that can be grouped are cells from the same zone (value) that meet the spatial requirements of connectivity specified by the FOUR and EIGHT keywords.
  • CROSS — Tests connectivity by the spatial requirements specified by the keywords FOUR and EIGHT between cells with any values, except for the value identified to be excluded.When CROSS is used, a value for the {excluded_value} argument must be input.
String
add_link
(Optional)

Specifies whether a link field is added to the table of the output.

  • ADD_LINK — An ADD_LINK item will be added to the table of the output raster. This item stores the original values for each newly created zone, from disconnected regions, from the input raster before they are regrouped. This is the default.
  • NO_LINK — The attribute table for the output raster will only contain the Value and Count items.
Boolean
excluded_value
(Optional)

Identifies a value such that if a cell location contains the value, no spatial connectivity will be evaluated regardless how the number of neighbors is specified (FOUR or EIGHT).

Cells with the excluded value will be treated as NoData and are eliminated from calculations. Cell locations that contain the excluded value will receive 0 on the output raster.

The excluded value is similar to the concept of a background value, or setting a mask in the environment for a single run of the tool. A value must be specified for this parameter if the CROSS keyword is specified.

Long

Return Value

NameExplanationData 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

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

Licensing Information

  • ArcGIS for Desktop Basic: Requires Spatial Analyst
  • ArcGIS for Desktop Standard: Requires Spatial Analyst
  • ArcGIS for Desktop Advanced: Requires Spatial Analyst

Related Topics

  • An overview of the Generalization toolset
Feedback on this topic?

ArcGIS for Desktop

  • Home
  • Documentation
  • Pricing
  • Support

ArcGIS Platform

  • ArcGIS Online
  • ArcGIS for Desktop
  • ArcGIS for Server
  • ArcGIS for Developers
  • ArcGIS Solutions
  • ArcGIS Marketplace

About Esri

  • About Us
  • Careers
  • Insiders Blog
  • User Conference
  • Developer Summit
Esri
© Copyright 2016 Environmental Systems Research Institute, Inc. | Privacy | Legal