Update on August 16th, 2021: Another set of scripts with some application-specific up-scaling focus has been created in the repository PebbleCounts-Application. The manuscript associated with this application is: https://doi.org/10.1029/2021JF006260.
PebbleCounts is a Python based application for the identification and sizing of gravel from either orthorectified, georeferenced (UTM projected) images with known resolution or simple non-orthorectified images taken from directly overhead with the image resolution approximated by the camera parameters and shot height. Read about it (and cite it!) here:
Purinton, B. and Bookhagen, B.: Introducing PebbleCounts: a grain-sizing tool for photo surveys of dynamic gravel-bed rivers, Earth Surf. Dynam., 7, 859–877, https://doi.org/10.5194/esurf-7-859-2019, 2019.
FULL MANUAL INCLUDING INSTALL AND RUNNING
Purinton, Benjamin; Bookhagen, Bodo (2019): PebbleCounts: a Python grain-sizing algorithm for gravel-bed river imagery. V. 1.0. GFZ Data Services. http://doi.org/10.5880/fidgeo.2019.007
GNU General Public License, Version 3, 29 June 2007
Copyright © 2019 Benjamin Purinton, University of Potsdam, Potsdam, Germany
PebbleCounts is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. PebbleCounts is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
PebbleCounts is a free (released under GNU General Public License v3.0) and open-source application written by a geologist / amateur programmer. If you have any problems contact me purinton@uni-potsdam.de and I can help!
Georeferenced ortho-photos should be in a UTM projection, providing the scale in meters. You can use the gdal command line utilities to translate rasters between various projections. Because PebbleCounts doesn't allow you to save work in the middle of clicking it's recommended that you don't use images covering areas of more than 2 by 2 meters or so. Furthermore, the algorithm is most effective on images of 0.8-1.2 mm/pixel resolution, where a lower cutoff of 20-pixels is appropriate. Resampling can also be accomplished quickly in gdal. For higher resolution (< 0.8 mm/pixel) imagery it's recommended not to go above 1 by 1 meter areas, particularly if there are many < 1 cm pebbles. If you want to cover a larger area simply break the image into smaller parts and process each individually, so you can give yourself a break. If at anytime you want to end the application simply press CTRL + C.
In addition to the manual-clicking version of PebbleCounts based on k-means segmentation, we have also developed and included an automated version that has higher uncertainties. We recommend using PebbleCounts in a subset of data to validate larger areas run in PebbleCountsAuto. The description of the automatic algorithm and uncertainties can be found in the publication: https://doi.org/10.5194/esurf-7-859-2019. Validation steps using both methods are shown in detail in another publication: https://doi.org/10.1029/2021JF006260.
The first step is downloading the GitHub repository somewhere on your computer, and unzipping it. There you will find the Python algorithms (e.g., PebbleCounts.py), a folder example_data with two example images one orthorectified and the other raw, a jupyter notebook Read_and_Plot_PebbleCounts_CSV.ipynb with a tutorial on how to manipulate output grain-size distribution .csv files, and a folder docs containing the full manual.
For newcomers to Python, no worries! Installation should be a cinch on most machines. First, you'll want the Miniconda Python package manager to setup a new Python environment for running the algorithm (see this good article on Python package management). Download either the 32- or 64-bit Miniconda installer of Python 3.x then follow the instructions (either using the .exe file for Windows, .pkg for Mac, or bash installer for Linux). Add Miniconda to the system PATH variable when prompted.
PebbleCounts has a number of important dependencies including gdal for georeferenced raster manipulation, openCV for image manipulation and GUI operation, scikit-image for filtering and measuring, scikit-learn for k-means segmentation, shapely for geometry operations, along with a number of standard Python libraries including numpy, scipy, matplotlib, and tkinter.
Once you've got conda commands installed, you can open a command-line terminal and create a conda environment with:
conda create --name pebblecounts python=3.6 opencv shapely scikit-image scikit-learn numpy gdal scipy matplotlib tk
and once installation is complete (and assuming no errors during the install) activate the new environment to run PebbleCounts by:
activate pebblecounts
Deactivate the environment to exit anytime by:
deactivate
Those using Mac OS or Linux shouldn't have much trouble modifying the above commands slightly (just add a leading conda to the activate and deactivate commands above). Also we need to install opencv separately from within the virtual environment using the pip package manager.
Similar to the above, once you have conda installed we create the virtual environment:
conda create --name pebblecounts python=3.6 shapely scikit-image scikit-learn numpy gdal scipy matplotlib tk
and once installation is complete (and assuming no errors during the install) activate the new environment by:
conda activate pebblecounts
We've left out the opencv package which must be installed with the following pip command in the activated pebblecounts environment:
pip install opencv-python
Deactivate the environment to exit anytime by:
conda deactivate
Note that installing openCV and getting it to function properly can be a pain sometimes, especially in the case of Linux. In that case it is recommended to find some instructions for installing openCV's Python API for your specific Linux operating system online.