pyshepseg

Introduction

Python implementation of image segmentation algorithm of Shepherd et al (2019). Operational Large-Scale Segmentation of Imagery Based on Iterative Elimination. Remote Sensing 11(6).

This package is a tool for Python programmers to implement the segmentation algorithm. It is not a stand-alone solution for people with no Python experience.

We thank the authors of the paper for their algorithm. This implementation was created independently of them, and they are in no way to blame for any mistakes we have made.

Downloads

From GitHub. Release notes by version can be viewed in Pyshepseg Release Notes.

Dependencies

The package requires the scikit-learn package, and the numba package. These need to be installed before this package will run. These are installed automatically when using the conda-forge pyshepseg package (see below), but will need to be available when building from source.

Also recommended is the GDAL package for reading and writing raster file formats. It is not required by the core segmentation algorithm, but is highly recommended as a portable way to interface to a large range of raster formats. It is required by the tiling module to support segmentation of large rasters. This is installed when using the conda-forge pyshepseg package.

Installation

This package can be installed from conda-forge and is the recommended approach. Once you have installed Conda run the following commands to install pyshepseg into a new environment:

conda config --add channels conda-forge
conda config --set channel_priority strict
conda create -n mysegenv pyshepseg
conda activate mysegenv

Alternatively, this package can be installed directly from the source, using the setup.py script (see required dependencies above).

  1. The source code is available from https://github.com/ubarsc/pyshepseg. Either unpack the latest release bundle from https://github.com/ubarsc/pyshepseg/releases, or clone the repository.

  2. Run the setup.py script. This is best done by using pip as a wrapper around it, as follows. Note that pip has a --prefix option to allow installation in non-standard locations.

pip install .

Usage

from pyshepseg import shepseg

# Read in a multi-band image as a single array, img,
# of shape (nBands, nRows, nCols).
# Ensure that any null pixels are all set to a known
# null value in all bands. Failure to correctly identify
# null pixels can result in a poorer quality segmentation.

segRes = shepseg.doShepherdSegmentation(img, imgNullVal=nullVal)

The segimg attribute of the segRes object is an array of segment ID numbers, of shape (nRows, nCols).

See the help in the pyshepseg.shepseg module and pyshepseg.shepseg.doShepherdSegmentation() function for further details and tips.

Large Rasters

The basic usage outlined above operates entirely in-memory. For very large rasters, this can be infeasible. A tiled implementation is provided in the pyshepseg.tiling module, which divides a large raster into fixed-size tiles, segments each tile in-memory, and stitched the results together to create a single segment image. The tiles are stitched such that segments are matched and merged across tile boundaries, so the result is seamless.

This technique should be used with caution. See the docstring for the pyshepseg.tiling module and the pyshepseg.tiling.doTiledShepherdSegmentation() function for further discussion of usage and caveats.

Once a segmentation has been completed, statistics can be gathered per segment on large rasters using the functions defined in the pyshepseg.tilingstats module.

Command Line Scripts

A few basic command line scripts are also provided as entry points. Their main purpose is as test scripts during development, but they also serve as examples of how to write scripts which use the package. In addition, they can also be used directly for simple segmentation tasks.

The pyshepseg_run_seg entry point is a wrapper around the basic in-memory usage.

The pyshepseg_tiling entry point is a wrapper around the tiled segmentation for large rasters.

The pyshepseg_subset entry point uses the pyshepseg.subset.subsetImage() function to subset a segmentation image, re-labelling the segments to contiguous segment ID numbers.

The pyshepseg_variograms entry point uses the pyshepseg.tilingstats.calcPerSegmentSpatialStatsTiled() function to calculate the given number of variograms.

The pyshepseg_runtests entry point runs some tests on packages data and can be used to confirm that the behaviour of this package is as expected.

Use the --help option on each script for usage details.

Per-segment Statistics

It can be useful to calculate statistics of the pixels from the original input imagery on a per-segment basis. For example, for all the pixels in a single segment, one might calculate the mean value of one or more of the bands from the original imagery.

A routine is provided to do this in a memory-efficient way, given the original image and the completed segmentation image. A standard set of statistics are available, including mean, standard deviation, and arbitrary percentile values, amongst others. The selected per-segment statistics are written to the segment image file as columns of a raster attribute table (RAT).

For details, see the help on the pyshepseg.tilingstats.calcPerSegmentStatsTiled() and pyshepseg.tilingstats.calcPerSegmentSpatialStatsTiled() function.

Segment Colour Tables

The segment image contains a large number of individual segment values, and can be difficult to view in simple greyscale colouring. To improve this, two routines are provided in the pyshepseg.utils module which will attach a colour table.

The simplest routine is pyshepseg.utils.writeRandomColourTable(), which attaches a randomly-generated colour table, so that each segment is assigned a randomly chosen colour, which merely serves to distinguish it from the surrounding segments. See its help for details.

More sophisticated and more useful is the function pyshepseg.utils.writeColorTableFromRatColumns(), which uses previously calculated columns in the raster attribute table (RAT) to create a colour table which approximates the original imagery. See its help for details, and the preceding section on how to create suitable RAT columns.

Subsetting

For large segmentations sometimes it is necessary to subset the result into a smaller image so it is easier to work with, but have contiguous segment ids and a link back to the original segments. For doing this, see the pyshepseg.subset module and the pyshepseg.subset.subsetImage() function.

Modules in this Package

Indices and tables