segmenteverygrain

Description

segmenteverygrain is a Python package that aims to detect sedimentary grains (or grain-like objects) in images, originally created by Dr. Zoltan Sylvester at UT Austin. Please see the original repo for details and guidance. This project is a fork of the original, and is in no way approved or supported by the creator(s), maintainer(s), or sponsors of segmenteverygrain.

This fork was independently created to support upcoming work by Dr. Emma Lodes at Arizona State University. It is not approved or supported by Arizona State University, any employees or representatives thereof, or anyone other than the creator of this fork.

This project is in active development. Utility, accuracy, and safety are not guaranteed. Use this code at your own risk.

Features

This unofficial fork attempts to build on the core features of segmenteverygrain by improving user interactivity and adding auxiliary features.

Automated grain detection

The original automated grain detection and segmentation process as laid out in Segment_every_grain.ipynb has not been significantly modified except for how results are saved. The notebook itself has not been modified at all.

Usage

The original notebook (above) can be executed directly, but results will not be wholly compatible with the features below. Compatible results can be generated by editing and running the auto_detection.ipynb or auto_large.ipynb notebook for the normal or large-image methods from Segment_every_grain.ipynb, respectively.

U-Net model training

A U-Net model is used for generating prompts in the first stage of automatic grain detection, and this model can be retrained for specific projects with relatively little time and training data. The original segmenteverygrain project now includes its own notebook for this purpose, Train_Unet_model.ipynb. The notebook previously created for this purpose, unet_training.ipynb is deprecated, but still included for projects that may have used it.

Usage

Run either the segmenteverygrain notebook at Train_Unet_model.ipynb or the deprecated notebook previously made for this fork at unet_training.ipynb.

Interactive interface

The original manual editing interface has been modified to facilitate:

• Increased FPS (using blitting), especially with high grain counts
• Large images, displaying a downscaled image while still operating on the full-resolution image
• Using the same interface to create, delete, merge, and measure grains
• Unit conversion from pixels to meters using a given scale length or by measuring a scale bar
• More control over grain detection, including a selection box and arbitrary number of foreground/background prompts
• A toggleable info box to display information about the last-selected grain
• Undoing the most recently-created grain
• Minor bugfixes like not resetting the zoom level when creating a grain

Usage

Run the new interactive interface using the interactive_edit.ipynb notebook. Navigation within the interface is described in the matplotlib documentation. Additional controls are:

• Left click: Select/unselect existing grain, or place foreground prompt for grain detection
• Shift + left click/drag: Create or adjust box prompt for grain detection
• Right click: Place background prompt for grain detection
• Middle click: Display measurement information about the indicated grain
• Middle click + drag: Measure scale bar to calibrate pixels per meter
• Control: Hold to temporarily hide selected grains
• Escape: Remove all prompts and unselect all grains
• c: Attempt to detect a grain using current prompts
• d: Delete selected (highlighted) grains
• m: Merge selected grains (must be touching)
• z: Delete the most recently-created grain

Automated grid count

The results of segmenteverygrain can be used to simulate the results of a manual grid count. This provides less information than segmentation of a complete image, but is more comparable to traditional methods. Currently there is no fine-grain cutoff threshold. Some configuation options include:

• When multiple grid points land on the same grain, the report can contain only instance of that grain, or count it once for each point.
• When a grid point does not land on a grain, optionally search within a given distance to report the nearest detected grain.
• Instead of centering the grid on the image (default), it can be offset by a given amount for each axis. This facilitates multiple grid counts on the same image with the same spacing.

Usage

After using segmenteverygrain to generate a grain info (.geojson) file, generate a grid count through the GUI or by directly editing and running grid_count.ipynb.

Graphical interface (experimental)

The core functions of segmenteverygrain have been wrapped into an optional, experimental GUI in order to provide a user-friendly experience.

Usage

The GUI was created using Kivy, which adds additional dependencies. Kivy and matplotlib integration (required) can be installed using pip install kivy kivy_garden.matplotlib --extra-index-url https://kivy-garden.github.io/simple/. Refer to the official Kivy site for more details.

Run the GUI from segment_gui.py, use the buttons at the top to load an image and/or a grain info file that was generated by another method, and access the desired functions from the toolbar on the bottom. If you want to modify the GUI itself, note that its layout is defined in segment.kv

Current status

This fork of segmenteverygrain is tentatively feature-complete for its intended usage, though questions and suggestions are always welcome via the issue queue.

Current work is focused on bugfixing and documentation, as well as upstreaming any features that the creator(s) of the original project might find useful.