Releases · Doodleverse/segmentation_gym

Synposis

This is the first major release of Gym. Includes a well-tested version that implements UNets and Residual-UNets, for segmentations of 2 or more classes, on 1-, 3- and N-band imagery. Models are trained using mixed precision by default, which allows for larger batches, and shorter duration training.
This version uses doodleverse-utils v0.0.11 (https://github.com/Doodleverse/doodleverse_utils and https://pypi.org/manage/project/doodleverse-utils/release/0.0.11/)
This version is supported by the test dataset published here: https://zenodo.org/record/7232051#.Y1HDKnbMIuU
This version is slightly modified from (but functionally equivalent to) that documented in the following paper: Buscombe, D., & Goldstein, E. B. (2022). A reproducible and reusable pipeline for segmentation of geoscientific imagery. Earth and Space Science, 9, e2022EA002332. https://doi.org/10.1029/2022EA002332

Implementation includes the following user choices

make_nd_datasets.py

use of datasets with or without augmentations, controlled by the 'mode' parameter
an efficient compressed file storage format, npz (see here)
images and labels are resized to a so-called 'TARGET SIZE' for the purposes of model training, but model inference can be applied to full-size imagery
creates a subset of augmented and non-augmented example image-label overlays for verification of npz file contents
supports on-the-fly label filtering using morphological operations to remove class islands and holes smaller than a threshold size
supports on-the-fly class-remapping (recoding integer label by merging classes)

train_model.py

available loss functions: a) Dice, b) weighted Dice, c) categorical crossentropy, d) hinge, e) kullback-Leibler divergence
single and multi-GPU training
highly configurable learning rate scheduler
models are evaluated by keeping track of multiple metrics including a) mean IoU (Intersection over Union), b) mean Dice (Jaccard), c) overall accuracy, d) mean frequency weighted IoU, e) Matthews Correlation Coefficient, f) per-class precision, g) per-class recall, and h) per-class F1 score
an efficient data throughput pipeline using tfdatasets, including batching and auto pre-fetching
available models: UNet, residual UNet, and 'satellite' UNet
training employs early stopping and checkpoints.
model weights are saved in h5 format, and utility script is available for conversion to a portable model

seg_images_in_folder.py

supports single model application, and model ensembling
supports simple softmax thresholding and per-image Otsu thresholding for 2-class problems (binary segmentation)
creates greyscale and color label outputs
supports per-label postprocessing using a Conditional Random Field

Package maintainers:

Contributors:

Planned future releases will incorporate planned extensions in at least 2 areas:

switching from keras image augmentation to a third party library such as albumentations
more control over use of train, validation, and test subsets in model training and evaluation
more model architectures such as U++ net, U^2 net, attention Unet (etc)