I am trying to get a unique ID for contiguous raster objects with the same value, like what the Region Group tool from ArcGIS does. However I need an open source solution using python/numpy/gdal/whatever. I have searched for a while but haven't come up with anything particularly useful. Any leads/direction for a possible solution out there? With the note that the rasters are rather large, ~50,000 x 50,000 pixels, so I am anticipating memory issues.

I am looking at using the GRASS r.clump tool from this answer, but I have never used GRASS within Python (or at all) and so I am unfamiliar with how to implement it.

1 Answer 1


You may use the Clump tool in the open-source geospatial data analysis platform WhiteboxTools. This can be scripted in Python as follows:

from WBT.whitebox_tools import WhiteboxTools

wbt = WhiteboxTools()
wbt.work_dir = "/path/to/data/"

in_file = "input_raster.tif"
out_file = "output_raster.tif"
wbt.clump(in_file, out_file, diag=True, zero_back=False)

See the WhiteboxTools User Manual for more information on operation or the WhiteboxTools Python Tutorial. For the tool's source code, see here. The WhiteboxTools binary executable (~8 MB) can be downloaded from the Geomorphometry and Hydrogeomatics Research Group page.

The Clump tool re-categorizes data in a raster image by grouping cells that form physically discrete, connected areas into unique categories. Essentially this will produce a patch map from an input categorical image. The input image should either be Boolean (1's and 0's) or categorical. The 'diag' flag is used to include/exclude diagonal neighbour connections. Set the 'zero_back' flag to True if you would like to only assign contiguous groups of non-zero values in the input image unique identifiers.

If you would prefer to call the tool directly from the command line (no Python), then you can do so by first changing the directory (cd'ing) to the WhiteboxTools folder, and using the following command:

./whitebox_tools -r=Clump -v --wd="/path/to/data/" -i=input.tif -o=output.tif --diag

If you're on Windows, the executable will be named whitebox_tools.exe instead. There is a tutorial on how to run WhiteboxTools from the command line here.

  • Thanks so much! I will try to install this and give it a shot. One potential problem I see is that I'm using Python 2.7, not 3.0. In your experience will this still work?
    – user20408
    Jun 7, 2018 at 14:42
  • 1
    The Python API for WhiteboxTools is based on the whitebox_tools.py script, which I'm afraid I have developed with Python 3 in mind. I'm not sure if it would work with Python 2.7. You can give it a try. Otherwise, you can avoid Python altogether and just call the Clump tool from the command line: >>./whitebox_tools -r=Clump -v --wd="/path/to/data/" -i=input.tif -o=output.tif --diag Jun 7, 2018 at 14:52
  • Okay so, on the command line the clump tool worked well and fairly fast on a machine 60GB RAM (failed with 20gb). However, the result is 8-bit, which does not capture the many unique objects in my input image. My input image has 5 classes (1 - 5) and a 'no data' class (10), and as there are 10s of millions of unique objects I really need my output to be 32-bit in order to get a unique ID for every object. Is this possible with this tool?
    – user20408
    Jun 7, 2018 at 16:49
  • @user20408 The tool determines the bit-depth of the output from the input raster. I can change it so that it is always a 32-bit int output. In the meantime, can you change the input file. By the way, that must be one massive raster that you are processing. How big is it? Jun 7, 2018 at 17:13
  • 1
    @user20408 Yes, BigTiff is not supported. In order to keep WhiteboxTools free of dependencies, I need to write my own GeoTIFF encoder/decoder, which is no small feat (GeoTIFF is an insane format). You might try one of the other supported file formats instead (e.g. the ESRI .flt format). Jun 7, 2018 at 17:54

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.