ehseg

This is a python package to do edge-highlight image segmentation.

Introduction

This package is an implement of Edge-highlight Image Segmentation (EHSEG) to do image segmentation. It roughly has five steps and an optional step:

1. First uses mean-shift with iterations to filter the image.
2. Then calculate the average of edge gradient magnitudes generated by multiple methods. The methods include sobel, scharr, roberts, prewitt, laplace, and laplace gaussian.
3. Extract skeleton using adaptive threshold.
4. Highlight the image using the skeleton.
5. Run region_growing image segmentation from GRASS GIS to finish the segmentation.
6. (Optional) simplify the segmentation polygons using Douglas-Peucker Algorithm.

The method allows doing segmentation on one image, or a pair of images (e.g. growing-season image and off-season image).

Besides the segmentation, the package also includes function to resign values for each segment (e.g. based on land-cover types) and/or discard segments for specific value(s).

Installation

git clone https://github.com/LLeiSong/ehseg.git
cd ehseg
pip install .

Warning

Due to the bug of supporting macOS in grass-session, it cannot set gisbase correctly. So before package grass-session gets updated, macOS users have to do an extra manual makeup step. After installing ehseg, go to venv/libs/python3.*/site-packages/grass-session ( or other equivalent path), then edit file session.py:

Comment line 144 gisbase = out.decode().strip() and add this line instead gisbase = 'gitbase_of_your_machine'

Usage

Segmentation

The function ehseg is the main function to do segmentation. Here is an example of how to use it:

The user must install GRASS GIS first, and provide GRASSBIN and gisbase.

img_paths = ['planet_medres_normalized_analytic_2017-12_2018-05_mosaic_1219-998.tif',
             'planet_medres_normalized_analytic_2018-06_2018-11_mosaic_1219-998.tif']
dst_path = '/Users/leisong/downloads'
opt_name = 'segments_1219-998'
bands = [1, 2, 3, 4]
grassbin = '/Applications/GRASS-7.8.app/Contents/MacOS/Grass.sh'  # for Mac
gisbase = '/Applications/GRASS-7.8.app/Contents/Resources'  # for Mac
n_iter = 3  # number of iteration for mean-shift filter
max_window = 5  # maximum window size for mean-shift filter
window_size_thred = 101  # window size of local threshold calculation to skeletonize edges.
method = 'separate'  # method of segmentation using two season images.
ram = 16  # RAM size for usage
threshold = 0.2  # similarity threshold for segment growing.
similarity = "manhattan"  # method to calculate similarity.
minsize = 10  # minimum segment size
iterations = 200  # iteration number for segmentation. Too small value might cause not converge.
vectorize = True  # option to get vector polygons for segments or just keep categorical raster.
simplify_thred = 3.0  # threshold for vector simplification.
keep = False  # option to keep interim results or not.

ehseg(img_paths=img_paths,
      dst_path=dst_path,
      opt_name=opt_name,
      bands=bands,
      grassbin=grassbin,
      gisbase=gisbase,
      n_iter=n_iter, max_window=max_window,
      window_size_thred=window_size_thred,
      method=method,
      ram=ram,
      threshold=threshold,
      similarity=similarity,
      minsize=minsize,
      iterations=iterations,
      vectorize=vectorize,
      simplify_thred=simplify_thred,
      keep=keep)

You could check more details about the arguments from function help documentation.

Post-segmentation

The function revalue_segments can resign values for each segment and/or filter segments based on user-defined values. Similarly, the user must install GRASS GIS first, and provide GRASSBIN and gisbase.

segments_path = 'segments_1218-998_window7.geojson'  # path of segments
categorical_mask_path = 'probability_1218-998.tif'  # path of categorical mask raster.
dst_epsg = 4326  # destination EPSG code
category_filter = [0]  # values in categorical mask to discard.
thred_clean = 500  # threshold of area size to clean.
grassbin = '/Applications/GRASS-7.8.app/Contents/MacOS/Grass.sh'  # for Mac
gisbase = '/Applications/GRASS-7.8.app/Contents/Resources'  # for Mac
keep = True  # option to replace input segments path or not.

revalue_segments(segments_path=segments_path,
                 categorical_mask_path=categorical_mask_path,
                 dst_epsg=dst_epsg,
                 category_filter=category_filter,
                 thred_clean=thred_clean,
                 grassbin=grassbin,
                 gisbase=gisbase,
                 keep=keep)

Author

Lei Song (lsong@clarku.edu)

Warmly welcome contributors to make pull request.

Acknowledgement

The primary support for this work was provided by Omidyar Network’s Property Rights Initiative, now PLACE. This package is also part of project "Combining Spatially-explicit Simulation of Animal Movement and Earth Observation to Reconcile Agriculture and Wildlife Conservation", which is funded by NASA FINESST program (award number: 80NSSC20K1640).