API Reference¶

Interactive Editing (interactions module)¶

The interactions module provides an interactive interface for editing grain segmentations.

Classes¶

class segmenteverygrain.GrainPlot(grains: list = [], image: ndarray | None = None, predictor: SamPredictor | None = None, blit: bool = True, px_per_m: float = 1.0, scale_m: float = 1.0, minspan: int = 10, image_alpha: float = 1.0, image_max_size: tuple[float, float] = array([2160, 4096]), color_palette: str = 'tab20', color_by: str | None = None, **kwargs)¶

Interactive plot to create, delete, and merge grains.

Mouse Controls: - Left-click on mask-free area: Create grain immediately (auto-create) - Left-click on existing grain: Select/unselect grain - Right-click on mask-free area: Add background prompt and create grain - Alt + Left-click: Add foreground prompt (hold Alt for multiple prompts) - Alt + Right-click: Add background prompt (hold Alt for multiple prompts) - Shift+Left-click: Show grain measurement info (alternative to middle-click) - Shift+Left-drag: Draw scale bar line (red line shows the scale reference) - Middle-click: Show grain measurement info

Keyboard Controls: - Alt (hold): Enable multiple prompt mode (click to place prompts, release Alt to create) - M: Merge selected grains - Shift (hold): Enable scale bar drawing mode - Ctrl (hold): Hide all grain segmentations temporarily - C: Create grain from existing prompts (alternative to auto-create) - D/Delete: Delete selected grains - Z: Undo last created grain - Escape: Clear all selections and prompts

activate()¶: Enable interactive features.

clear_all()¶: Clear prompts, unselect all grains, and hide the info box.

clear_box()¶: Alias for self.box_selector.clear().

clear_grains()¶: Unselect all selected grains.

clear_info()¶: Clear the grain info box.

clear_points()¶: Clear all prompt points.

create_grain() → Grain¶

Attempt to detect a grain based on given prompts.

Returns:: new_grain – Grain detected using previously-input prompts.
Return type:: Grain

deactivate()¶: Disable interactive features.

delete_grains()¶: Delete all selected grains.

draw_axes()¶

Draw the major and minor axes on each grain patch.

This method collects all axis data first, then plots them all at once on top of the grain masks to ensure proper z-ordering.

Note: Call this after deactivate() to draw axes on top of grain masks.

draw_scale_line(start, end)¶

Draw a scale bar line and calculate the scale based on its length.

Parameters:

start (tuple) – Starting point (x, y) of the scale line.
end (tuple) – Ending point (x, y) of the scale line.

get_grains() → list¶

Get the current list of grains.

This returns the live grain list that reflects all interactive edits (created, deleted, merged grains). You can use this to save the current state without needing to write to disk first.

Returns:: grains – Current list of Grain objects, including all edits.
Return type:: list

hide_grains(hide: bool = True)¶

Hide or unhide all grains.

Parameters:: hide (bool) – Whether to hide (True) or unhide (False) all grains.
Returns:: hide – New hidden status.
Return type:: bool

merge_grains() → Grain¶

Attempt to merge all selected grains.

Returns:: new_grain – Merged grain, if merge is successful. None otherwise.
Return type:: Grain

onclick(event: MouseEvent)¶

Handle clicking anywhere on plot. Places foreground or background prompts for grain creation. Shift + Left drag draws a scale bar line.

Parameters:: event (MouseEvent) – Event details

onclickup(event: MouseEvent)¶

Handle click release events anywhere on plot. Completes scale bar line drawing if in progress. Displays info about any grain indicated with middle-click or Shift+left-click.

Parameters:: event (MouseEvent) – Event details

ondraw(event: DrawEvent)¶

Update saved background image whenever a full redraw is triggered.

Parameters:: event (DrawEvent) – Event details

onkey(event: KeyEvent)¶

Handle key presses as follows: c: Create a grain from existing prompts (alternative to auto-create). d: Delete a selected grain. alt (hold): Allow placing multiple prompts before creating grain. m: Merge selected grains. z: Undo the most recently created grain. control (hold): Temporarily hide all grains. escape: Remove all selections, prompts, and info. shift: Activate scale bar selector and grain selection box.

Parameters:: event (KeyEvent) – Event details

onkeyup(event: KeyEvent)¶

Handle key releases. Unhides hidden grains, creates grain from multiple prompts, or deactivates selectors.

Parameters:: event (KeyEvent) – Event details.

onmotion(event: MouseEvent)¶

Handle mouse motion events. Updates the scale line preview while dragging.

Parameters:: event (MouseEvent) – Event details

onpick(event: PickEvent)¶

Handle clicking on an existing grain. Left-click: Select/unselect the grain. Middle-click OR Shift+Left-click: Show measurement info for indicated grain. Right-click: Ignored (passes through to onclick for background prompts).

Parameters:: event (PickEvent) – Event details

savefig(fn: str)¶

Save figure to disk.

Parameters:: fn (str) – Filename for output image. File type is determined by extension.

set_point(xy: tuple[int, int], foreground: bool = True) → Circle¶

Set point prompt, either foreground or background.

Parameters:

xy ((x: int, y: int)) – Coordinates of newly-requested point.
foreground (bool) – Whether point represents a foreground (True) or background prompt.

Returns:

new_point

Return type:

mpatches.Circle

toggle_box(active: bool | None = None) → bool¶

Activate/deactivate selection box.

Parameters:: active (bool) – Whether to activate (True) or deactivate (False) the selection box. If not provided, will toggle current active status.
Returns:: active – Updated active status of the selection box.
Return type:: bool

undo_grain()¶: Remove latest created grain.

update()¶: Blit background image and draw animated artists.

update_info(grain: Grain | None = None)¶: Update info box for specified grain.

class segmenteverygrain.Grain(xy: ndarray, image: ndarray | None = None)¶

Stores data and plot representation for a single grain.

convert_units(scale: float) → Series¶

Return grian measurements scaled by a given factor.

Parameters:: scale (float) – Factor by which to scale grain properties.
Returns:: data – Rescaled grain measurements.
Return type:: pd.Series

draw_axes(ax: Axes, scale: float = 1.0) → list[<module 'matplotlib.artist' from '/Users/zoltan/miniforge3/envs/segmenteverygrain/lib/python3.9/site-packages/matplotlib/artist.py'>]¶

Draw centroid and major/minor axes on the provided matplotlib axes.

Parameters:

ax (matplotlib.Axes) – Axes instance on which to draw the grain properties.
scale (float) – Scaling factor, useful with downscaled GrainPlots.

Returns:

artists – Dict of Matplotlib artists, named by property that they represent.

Return type:

{ name : artist }

draw_patch(ax: Axes, scale: float = 1.0) → Polygon¶

Draw this grain on the provided matplotlib axes and save the result.

Parameters:

ax (matplotlib.Axes) – Axes instance on which to draw this grain.
scale (float) – Scaling factor, useful with downscaled GrainPlots.

Returns:

Object representing this grain on the plot.

Return type:

patch

erase()¶: Remove plot representation.

measure(raster: bool = False) → Series¶

Calculate grain information from image and matplotlib patch. Overwrites self.data.

Parameters:: raster (bool) – Whether to use the “old” method of measuring grain properties. If True, will measure all properties from a raster representation. If False, will prefer measurements directly from grain coords.
Returns:: self.data – Row for a DataFrame containing computed grain info.
Return type:: pd.Series

property polygon: Polygon¶

Return a shapely.Polygon representing the matplotlib patch.

Returns:: Polygon representing the boundaries of this grain.
Return type:: shapely.Polygon

select() → bool¶

Toggle whether grain is selected/unselected in a plot.

Returns:: self.selected – True if this grain is now selected.
Return type:: bool

Functions¶

segmenteverygrain.load_image(fn: str) → ndarray¶

Load an image from disk as a numpy array.

Parameters:: fn (str) – Filename for image to load.
Returns:: Memory representation of loaded image.
Return type:: np.ndarray

segmenteverygrain.polygons_to_grains(polygons: list, image: ndarray | None = None) → list¶

Construct grains from a list of polygons defining grain boundaries.

Parameters:: polygons (list of shapely.Polygon) – Polygons defining grain boundaries.
Returns:: Grain objects created from provided polygons.
Return type:: list

segmenteverygrain.save_grains(fn: str, grains: list)¶

Save grain boundaries to a GeoJSON file.

Parameters:

fn (str) – Filename for csv to be created.
grains (list) – List of grains to write to disk.

segmenteverygrain.get_summary(grains: list, px_per_m: float = 1.0) → DataFrame¶

Summarize grain information as a DataFrame.

Parameters:

grains (list) – List of grains to measure and summarize.
px_per_m (float, default 1.) – Optional conversion from pixels to meters.

Returns:

df – Dataframe of grain measurements.

Return type:

pd.DataFrame

segmenteverygrain.save_summary(fn: str, grains: list, px_per_m: float = 1.0)¶

Save grain measurements as a csv.

Parameters:

fn (str) – Filename for csv to be created.
grains (list) – List of grains to summarize.
px_per_m (float, default 1.) – Optional conversion from pixels to meters.

segmenteverygrain.save_histogram(fn: str, grains: list = [], px_per_m: float = 1.0, summary: DataFrame | None = None) → None¶

Save histogram of grain size measurements as an image.

Parameters:

fn (str) – Filename for image to be created. File type will be interpreted.
grains (list (optional, must provide summary if not given)) – List of grains to represent.
px_per_m (float, default 1.) – Conversion from pixels to meters. Ignored if also passing a pre-generated summary.
summary (pd.DataFrame (optional, must provide grains if not given)) – Grain summary, if already generated from get_summary().

segmenteverygrain.save_mask(fn: str, grains: list, image: ndarray, scale: bool = False)¶

Save binary mask of grain shapes to disk, optionally scaled to 0-255.

Parameters:

fn (str) – Filename for image to be created. File type will be interpreted.
grains (list) – List of grains to represent.
image (np.ndarray) – Original image.
scale (bool) – Whether to scale from 0-255 for human readability (True) or 0-1 for model training (False).

Grain Extraction and Clustering (grain_utils module)¶

The grain_utils module provides functions for extracting individual grain images, extracting features, and clustering grains.

segmenteverygrain.extract_grain_image(grain_polygon, image, image_pred=None, target_size=224, pad=10)¶

Extract a single grain from an image and create a square, unrotated image.

This function takes a grain polygon, extracts the corresponding region from the image, applies padding, rotates it to align the major axis vertically, makes it square by padding with zeros, and resizes it to the target size.

Parameters:

grain_polygon (shapely.Polygon) – The grain polygon from all_grains
image (numpy.ndarray) – The original image (H, W, 3)
image_pred (numpy.ndarray, optional) – The U-Net prediction (H, W, 3)
target_size (int) – Output image size (default: 224x224)
pad (int) – Padding around the grain bounding box in pixels

Returns:

grain_image (numpy.ndarray) – The extracted grain image (target_size, target_size, 3)
grain_mask (numpy.ndarray) – Binary mask of the grain (target_size, target_size)
grain_pred (numpy.ndarray or None) – The prediction for the grain region (target_size, target_size) if image_pred provided
original_size (int) – The size of the square crop before resizing

Examples

>>> grain_img, grain_mask, grain_pred, orig_size = extract_grain_image(
...     all_grains[0], image, image_pred, target_size=224, pad=10
... )

segmenteverygrain.extract_all_grains(all_grains, image, image_pred=None, target_size=224)¶

Extract all grains from an image.

This function processes all grains in a list and extracts standardized, square images for each grain suitable for classification or analysis tasks.

Parameters:

all_grains (list) – List of shapely.Polygon objects representing grains
image (numpy.ndarray) – The original image (H, W, 3)
image_pred (numpy.ndarray, optional) – The U-Net prediction (H, W, 3)
target_size (int) – Output image size (default: 224x224)

Returns:

grain_images (list) – List of grain images, each of shape (target_size, target_size, 3)
grain_masks (list) – List of grain masks, each of shape (target_size, target_size, 1)
grain_preds (list) – List of grain predictions (or None if image_pred not provided)

Examples

>>> grain_images, grain_masks, grain_preds = extract_all_grains(
...     all_grains, image, image_pred, target_size=224
... )
>>> print(f"Extracted {len(grain_images)} grains")

segmenteverygrain.make_square(im, reference_mask=None)¶

Pad an image to make it square.

This function pads an image with zeros to make its height and width equal. The padding is distributed evenly on both sides.

Parameters:

im (numpy.ndarray) – Image to pad (H, W) or (H, W, C)
reference_mask (numpy.ndarray, optional) – If provided, uses this mask’s shape for determining padding

Returns:

im_square – Square image with zero padding

Return type:

numpy.ndarray

Examples

>>> image = np.random.rand(100, 150, 3)
>>> square_image = make_square(image)
>>> square_image.shape
(150, 150, 3)

segmenteverygrain.extract_vgg16_features(grain_images, model_name='VGG16', layer_name='fc2', include_preprocessing=True, batch_size=32, verbose=0)¶

Extract deep learning features from grain images using a pre-trained CNN.

Images are automatically resized to 224x224 if they are not already that size.

Parameters:

grain_images (list or numpy.ndarray) – List of grain images, each of shape (H, W, 3). Images will be automatically resized to 224x224 if necessary.
model_name (str) – Name of the pre-trained model to use (‘VGG16’, ‘ResNet50’, etc.)
layer_name (str) – Layer to extract features from. Options: - ‘fc2’ or -2: Second-to-last layer (default, 4096 features for VGG16) - ‘fc1’ or -3: Third-to-last layer - ‘flatten’: Flattened convolutional features
include_preprocessing (bool) – Whether to apply model-specific preprocessing (recommended)
batch_size (int) – Batch size for prediction (default: 32)
verbose (int) – Verbosity level for model.predict (default: 0)

Returns:

features (numpy.ndarray) – Extracted features of shape (n_grains, n_features)
model (keras.Model) – The feature extraction model (useful for processing more grains later)

Examples

>>> features, model = extract_vgg16_features(grain_images)
>>> print(features.shape)
(336, 4096)

>>> # Works with any size images - they will be auto-resized
>>> features_640, model = extract_vgg16_features(grain_images_640x640)
>>> print(features_640.shape)
(336, 4096)

segmenteverygrain.extract_color_features(grain_images, color_space='rgb', mask_background=True, background_threshold=10)¶

Extract color-based features from grain images for clustering.

This function computes color statistics from grain images, optionally masking out the background. Features include mean, standard deviation, and histogram statistics for each color channel.

Parameters:

grain_images (list or numpy.ndarray) – List of grain images, each of shape (H, W, 3)
color_space (str) – Color space to use for feature extraction: - ‘rgb’: RGB color space (default) - ‘hsv’: HSV color space (better for color-based clustering) - ‘lab’: LAB color space (perceptually uniform) - ‘all’: Concatenate features from all color spaces
mask_background (bool) – If True, excludes very dark pixels (assumed to be background) from color statistics (default: True)
background_threshold (int) – Pixels with all channels below this value are considered background (default: 10, only used if mask_background=True)

Returns:

features – Color feature matrix of shape (n_grains, n_features) Features per channel: mean, std, median, min, max, 25th percentile, 75th percentile - RGB: 21 features (7 per channel × 3 channels) - HSV: 21 features (7 per channel × 3 channels) - LAB: 21 features (7 per channel × 3 channels) - all: 63 features (concatenation of RGB, HSV, LAB)

Return type:

numpy.ndarray

Examples

>>> # Extract RGB color features
>>> color_features = extract_color_features(grain_images, color_space='rgb')
>>> print(color_features.shape)
(336, 21)

>>> # Use HSV for better color discrimination
>>> hsv_features = extract_color_features(grain_images, color_space='hsv')
>>> labels, _, _, _ = cluster_grains(hsv_features, n_clusters=5, n_components=None)

>>> # Use all color spaces for comprehensive features
>>> all_features = extract_color_features(grain_images, color_space='all')
>>> print(all_features.shape)
(336, 63)

segmenteverygrain.cluster_grains(features, n_clusters=10, method='kmeans', n_components=25, random_state=42, **kwargs)¶

Cluster grain features using dimensionality reduction and clustering.

Parameters:

features (numpy.ndarray) – Feature matrix of shape (n_grains, n_features)
n_clusters (int) – Number of clusters to create
method (str) – Clustering method: ‘kmeans’, ‘dbscan’, ‘hierarchical’
n_components (int or None) – Number of PCA components. If None, no dimensionality reduction is applied
random_state (int) – Random seed for reproducibility
**kwargs (dict) – Additional arguments passed to the clustering algorithm

Returns:

labels (numpy.ndarray) – Cluster labels for each grain
reduced_features (numpy.ndarray) – Dimensionality-reduced features (or original if n_components is None)
pca (sklearn.decomposition.PCA or None) – Fitted PCA object (None if n_components is None)
clusterer (sklearn clustering object) – Fitted clustering model

Examples

>>> labels, reduced_feats, pca, kmeans = cluster_grains(
...     features, n_clusters=10, n_components=25
... )
>>> print(f"Found {len(np.unique(labels))} clusters")

segmenteverygrain.create_grain_panel(inds, all_images, n_rows, n_cols)¶

Create a visual panel of grain images from specified indices.

This function creates a rectangular grid panel containing grain images from the provided indices. Each grain image is assumed to be 224x224 pixels.

Parameters:

inds (array-like) – Indices of grains to include in the panel
all_images (numpy.ndarray) – Array of all grain images, shape (n_grains, 224, 224, 3)
n_rows (int) – Number of rows in the panel grid
n_cols (int) – Number of columns in the panel grid

Returns:

cl_panel – Combined panel image with shape (224*n_rows, 224*n_cols, 3)

Return type:

numpy.ndarray

Notes

The number of indices should equal n_rows * n_cols.

Examples

>>> selected_indices = [0, 5, 10, 15]
>>> panel = create_grain_panel(selected_indices, grain_images, 2, 2)
>>> plt.imshow(panel.astype(int))
>>> plt.show()

segmenteverygrain.create_grain_panel_cluster(cluster_number, labels, all_images)¶

Create a visual panel of grain images from a specific cluster.

This function creates a square grid panel containing randomly selected grain images from a specified cluster. Each grain image is assumed to be 224x224 pixels.

Parameters:

cluster_number (int) – The cluster number to create a panel for
labels (numpy.ndarray) – Array of cluster labels for each grain
all_images (numpy.ndarray) – Array of all grain images, shape (n_grains, 224, 224, 3)

Returns:

cl_panel (numpy.ndarray) – Combined panel image with shape (224*n_rows, 224*n_cols, 3)
grain_inds (numpy.ndarray) – 2D array containing the indices of grains used in the panel, shape (n_rows, n_cols)

Examples

>>> panel, indices = create_grain_panel_cluster(0, cluster_labels, grain_images)
>>> plt.imshow(panel.astype(int))
>>> plt.show()

segmenteverygrain.create_clustered_grain_montage(cluster_labels, grain_images, grid_cols=20, grain_size=224, padding=2, draw_boundaries=True, boundary_thickness=2, all_grains=None, sort_by_size=False)¶

Create a single montage image with all grains arranged by cluster.

Grains are arranged in a compact grid, ordered by cluster (cluster 0, then 1, etc.). Within each cluster, grains can optionally be sorted by size. Grains flow continuously across rows to minimize white space. Cluster boundaries can be visualized with colored borders around each grain.

Parameters:

cluster_labels (numpy.ndarray) – Array of cluster labels for each grain
grain_images (list or numpy.ndarray) – Array of all grain images, shape (n_grains, H, W, 3)
grid_cols (int) – Number of grain columns in the grid (default: 20)
grain_size (int) – Size of each grain image in pixels (default: 224)
padding (int) – Padding between grains in pixels (default: 2)
draw_boundaries (bool) – If True, draws colored borders around each grain to indicate cluster (default: True)
boundary_thickness (int) – Thickness of cluster boundary in pixels (default: 2)
all_grains (list of shapely.Polygon, optional) – List of grain polygons. Required if sort_by_size=True
sort_by_size (bool) – If True, sorts grains within each cluster by size (area) in descending order. Requires all_grains to be provided (default: False)

Returns:

montage (numpy.ndarray) – Single large image containing all grains arranged by cluster
cluster_info (dict) – Dictionary with information about each cluster: - ‘n_grains’: number of grains in cluster - ‘grain_indices’: indices of grains in this cluster - ‘positions’: list of (row, col) positions in the grid

Examples

>>> # With colored borders
>>> montage, info = create_clustered_grain_montage(labels, grain_images, grid_cols=20)
>>> plt.figure(figsize=(20, 15))
>>> plt.imshow(montage.astype('uint8'))
>>> plt.axis('off')
>>> plt.show()

>>> # Without borders (pure grid)
>>> montage, info = create_clustered_grain_montage(
...     labels, grain_images, grid_cols=20, draw_boundaries=False
... )

>>> # Sorted by size within each cluster
>>> montage, info = create_clustered_grain_montage(
...     labels, grain_images, all_grains=all_grains, sort_by_size=True
... )

>>> # Print cluster info
>>> for cluster_id, data in info.items():
...     print(f"Cluster {cluster_id}: {data['n_grains']} grains")

segmenteverygrain.plot_classified_grains(image, all_grains, classifications, class_colors=None, ax=None, plot_image=True, im_alpha=1.0, edge_color='black', edge_width=0.5, fill_alpha=0.5, legend=True)¶

Plot image with grain masks colored by their classification.

Parameters:

image (numpy.ndarray) – The input image to be plotted
all_grains (list) – List of shapely Polygon objects representing grain masks
classifications (list or numpy.ndarray) – Classification label for each grain (same length as all_grains)
class_colors (dict, optional) – Dictionary mapping class names to colors. If None, uses default colors. Colors can be matplotlib color names or RGB tuples. Example: {‘quartz’: ‘blue’, ‘feldspar’: ‘red’, ‘other’: ‘green’}
ax (matplotlib.axes.Axes, optional) – Axes object to plot on. If None, creates new figure
plot_image (bool) – Whether to plot the background image (default: True)
im_alpha (float) – Alpha value for background image (default: 1.0)
edge_color (str or tuple) – Color for grain edges (default: ‘black’)
edge_width (float) – Width of grain edges (default: 0.5)
fill_alpha (float) – Alpha value for grain fill colors (default: 0.5)
legend (bool) – Whether to add a legend (default: True)

Returns:

fig, ax – The figure and axes objects

Return type:

matplotlib Figure and Axes

Examples

>>> # After training classifier
>>> predictions = clf.predict(features)
>>> fig, ax = plot_classified_grains(
...     image, all_grains, predictions,
...     class_colors={'quartz': 'blue', 'feldspar': 'red', 'other': 'green'}
... )
>>> plt.show()

class segmenteverygrain.ClusterMontageSelector(cluster_labels, grain_images, all_grains, grid_cols=20, figsize=(20, 15), grain_size=224, padding=2, boundary_thickness=2, sort_by_size=False)¶

Interactive selector for clustered grain montage.

Allows interactive selection and removal of entire clusters or individual grains for quality control. Click on a cluster to select/deselect all grains in it, or Shift+Click to select/deselect individual grains.

Parameters:

cluster_labels (numpy.ndarray) – Array of cluster labels for each grain
grain_images (list or numpy.ndarray) – Array of all grain images
all_grains (list) – List of grain polygons (shapely.Polygon objects)
grid_cols (int) – Number of grain columns in the grid (default: 20)
figsize (tuple) – Figure size (default: (20, 15))
grain_size (int) – Size of each grain image in pixels (default: 224)
padding (int) – Padding between grains in pixels (default: 2)
boundary_thickness (int) – Thickness of cluster boundary in pixels (default: 2)
sort_by_size (bool) – If True, sorts grains within each cluster by size (area) in descending order (default: False)

selected_grain_indices¶

Set of grain indices that are selected for removal

Type:: set

selected_clusters¶

Set of cluster IDs that are fully selected

Type:: set

activate()¶: Activate interactive selection mode

deactivate()¶: Deactivate interactive mode

get_filtered_grains()¶: Get the list of grains after removing selected ones

get_filtered_labels()¶: Get the cluster labels after removing selected grains

get_filtered_images()¶: Get the grain images after removing selected grains

get_filtered_indices()¶: Get the indices of grains that remain after filtering

Interactive Controls

--------------------

- Left-click: Select/deselect entire cluster

- Shift + Left-click: Select/deselect individual grain

- 'd' key: Delete selected grains/clusters

- 'r' key: Reset (clear all selections)

- 'Esc' key: Clear all selections

Examples

>>> selector = ClusterMontageSelector(labels, grain_images, all_grains)
>>> selector.activate()
>>> # ... interact with the plot ...
>>> filtered_grains = selector.get_filtered_grains()
>>> print(f"Kept {len(filtered_grains)} out of {len(all_grains)} grains")

activate()¶: Activate interactive selection mode.

deactivate()¶: Deactivate interactive mode.

display_montage()¶: Display the current montage with selection overlays.

get_filtered_grains()¶

Get the list of grains after removing selected ones.

Returns:: filtered_grains – List of grain polygons with removed grains excluded
Return type:: list

get_filtered_images()¶

Get grain images after removing selected grains.

Returns:: filtered_images – List of grain images with removed grains excluded
Return type:: list

get_filtered_indices()¶

Get the indices of grains that remain after filtering (not removed).

This is useful for filtering other arrays (like all_grains) that are indexed the same way as the original grain_images/cluster_labels.

Returns:: filtered_indices – Array of indices for grains that were not removed
Return type:: numpy.ndarray

Examples

>>> selector = ClusterMontageSelector(labels, grain_images, all_grains)
>>> selector.activate()
>>> # ... interact with the plot to remove some grains ...
>>> filtered_idx = selector.get_filtered_indices()
>>> filtered_all_grains = [all_grains[i] for i in filtered_idx]

get_filtered_labels()¶

Get cluster labels after removing selected grains.

Returns:: filtered_labels – Cluster labels for remaining grains
Return type:: numpy.ndarray

onclick(event)¶: Handle mouse click events.

onkey(event)¶: Handle keyboard events.

class segmenteverygrain.ClusterMontageLabeler(cluster_labels, grain_images, all_grains, label_names, label_colors=None, grid_cols=20, figsize=(20, 15), grain_size=224, padding=2, boundary_thickness=2, sort_by_size=False, blit=True)¶

Interactive labeler for clustered grain montage (based on GrainPlot design).

Allows fast interactive labeling of grains or entire clusters with custom labels.

Parameters:

cluster_labels (numpy.ndarray) – Array of cluster labels for each grain
grain_images (list or numpy.ndarray) – Array of all grain images
all_grains (list) – List of grain polygons (shapely.Polygon objects)
label_names (list of str) – List of label names (e.g., [‘quartz’, ‘feldspar’, ‘other’])
label_colors (list of str or tuple, optional) – Colors for each label. If None, uses default colors.
grid_cols (int) – Number of columns in the grid (default: 20)
figsize (tuple) – Figure size (default: (20, 15))
grain_size (int) – Size of each grain image in pixels (default: 224)
padding (int) – Padding between grains (default: 2)
boundary_thickness (int) – Border thickness for labeled grains (default: 2)
sort_by_size (bool) – Sort grains by size within clusters (default: False)
blit (bool) – Use blitting for fast updates (default: True)
Controls (Interactive)
--------------------
Left-click (- Shift +)
Left-click
(1-9) (- Number keys)
'r' (-)

activate()¶: Activate interactive mode.

deactivate()¶: Deactivate interactive mode.

export_labels(filepath)¶: Export labels to CSV.

get_filtered_indices()¶: Get indices of labeled grains.

get_labeled_data()¶: Get labeled grain images and labels.

get_unlabeled_indices()¶: Get indices of unlabeled grains.

onclick(event)¶: Handle mouse clicks.

ondraw(event)¶: Handle draw events (recapture background after zoom/pan).

onkey(event)¶: Handle keyboard events.

save_labeled_images(output_dir)¶

Save labeled grain images to disk, organized by label.

Creates subdirectories for each label and saves images as: {output_dir}/{label_name}/grain_{grain_index}.png

Parameters:: output_dir (str) – Base directory where labeled images will be saved

Examples

>>> labeler.save_labeled_images('labeled_grains')
# Creates:
# labeled_grains/quartz/grain_0.png
# labeled_grains/quartz/grain_5.png
# labeled_grains/feldspar/grain_1.png
# etc.

update()¶: Update display (using blitting like GrainPlot).

Core Segmentation Functions¶

Model Prediction¶

segmenteverygrain.predict_image_tile(im_tile, model)¶

Predicts one image tile using a Unet model.

Parameters:

im_tile (3D array) – The image tile for which the prediction will be done.
model – Tensorflow model used for semantic segmentation.

Returns:

im_tile_pred – Predicted tile.

Return type:

3D array

segmenteverygrain.predict_image(image, model, I)¶

Segmantic segmentation of the entire image using a Unet model.

Parameters:

image (2D or 3D array) – The image that is being segmented. Can have one or more channels.
model – Tensorflow model used for semantic segmentation.
I (int) – Size of the square-shaped image tiles in pixels.

Returns:

image_pred – Semantic segmentation result for the input image.

Return type:

3D array

segmenteverygrain.predict_large_image(fname, model, sam, min_area, patch_size=2000, overlap=300, remove_large_objects=False, remove_edge_grains=True)¶

Predicts the location of grains in a large image using a patch-based approach.

Parameters:

fname (str) – The file path of the input image.
model (tensorflow.keras.Model) – The Unet model used for the preliminary grain prediction.
sam (SamPredictor) – The SAM model used for grain segmentation.
min_area (int) – The minimum area threshold for valid grains.
patch_size (int, optional) – The size of each patch. Defaults to 2000.
overlap (int, optional) – The overlap between patches. Defaults to 300.
remove_large_objects (bool, optional) – Whether to remove large objects from the segmentation. Defaults to False.
remove_edge_grains (bool, optional) – Whether to remove grains touching the edges. When False, grains are kept only if they touch the outer edges of the full image, but removed if they touch internal patch boundaries. When True, all edge-touching grains are removed. Defaults to True.

Returns:

All_Grains (list) – A list of grains represented as polygons.
image_pred (numpy.ndarray) – The Unet predictions for the entire image.
all_coords (numpy.ndarray) – The coordinates of the SAM prompts.

segmenteverygrain.label_grains(image, image_pred, dbs_max_dist=20.0)¶

Label grains in semantic segmentation result and generate prompts for SAM model.

Parameters:

image (2D or 3d array) – image that was segmented
image_pred (3D array) – semantic segmentation result
dbs_max_dist (float) – DBSCAN distance parameter; decreasing it results in more SAM prompts and longer processing times

Returns:

labels_simple – the labels as an image
all_coords – pixel coordinates of the prompts

segmenteverygrain.sam_segmentation(sam, image, image_pred, coords, labels, min_area, plot_image=False, remove_edge_grains=False, remove_large_objects=False, keep_edges=None)¶

Perform segmentation using the Segment Anything Model (SAM).

Parameters:

sam (SamPredictor) – The SAM model.
image (numpy.ndarray) – The input image.
image_pred (numpy.ndarray) – The output of the Unet segmentation.
coords (numpy.ndarray) – The coordinates of the SAM prompts.
labels (numpy.ndarray) – The labeled image that comes from the ‘label_grains’ function.
min_area (int) – The minimum area of the grains, in pixels.
plot_image (bool, optional) – Whether to plot the segmented image. Default is False.
remove_edge_grains (bool, optional) – Whether to remove grains that are touching the edge of the image. Default is False.
remove_large_objects (bool, optional) – Whether to remove large objects. Default is False. This is useful when the segmentation result is not very good.
keep_edges (dict, optional) – Dictionary specifying which edges to keep grains on: {‘top’: bool, ‘bottom’: bool, ‘left’: bool, ‘right’: bool}. If None, all edges are treated according to remove_edge_grains. Default is None.

Returns:

all_grains (list) – List of polygons representing the segmented grains.
labels (numpy.ndarray) – The labeled image.
mask_all (numpy.ndarray) – The mask of all grains.
grain_data (pandas.DataFrame) – DataFrame containing properties of each grain.
fig (matplotlib.figure.Figure or None) – The figure object if plot_image is True, otherwise None.
ax (matplotlib.axes.Axes or None) – The axes object if plot_image is True, otherwise None.

segmenteverygrain.one_point_prompt(x, y, image, predictor, ax=False)¶

Perform SAM segmentation using a single point prompt.

Parameters:

x (float) – the x-coordinate of the point
y (float) – the y-coordinate of the point
image (numpy.ndarray)) – the input image
predictor – the SAM predictor
ax (bool, default True) – whether to plot the segmentation result on an axis

Returns:

sx – the x-coordinates of the contour points
sy – the y-coordinates of the contour points
mask – the segmented mask

segmenteverygrain.two_point_prompt(x1, y1, x2, y2, image, predictor, ax=False)¶

Perform a two-point-prompt-based segmentation using the SAM model. Second point is used as background (label=0).

Parameters:

x1 (float) – x-coordinate of the first point
y1 (float) – y-coordinate of the first point
x2 (float) – x-coordinate of the second point
y2 (float) – y-coordinate of the second point
ax (matplotlib.axes.Axes) – The axes to plot the segmentation result
image (numpy.ndarray) – the input image
predictor – the SAM predictor

Returns:

sx (numpy.ndarray) – The x-coordinates of the contour points
sy (numpy.ndarray) – The y-coordinates of the contour points

Polygon Operations¶

segmenteverygrain.find_overlapping_polygons(polygons, min_overlap=0.4)¶

Finds and returns a list of overlapping polygons from the given list of polygons using spatial indexing.

Parameters:: polygons (list) – A list of polygons.
Returns:: overlapping_polygons – A list of tuples representing the indices of overlapping polygons.
Return type:: list

segmenteverygrain.find_connected_components(all_grains, min_area)¶

Finds connected components in a graph of overlapping polygons.

Parameters:

all_grains (list) – List of polygons representing all grains.
min_area (float) – Minimum area threshold for valid grains.

Returns:

new_grains (list) – List of polygons that do not overlap and have an area greater than min_area.
comps (list) – List of sets, where each set represents a connected component of overlapping polygons.
g (networkx.Graph) – The graph of overlapping polygons.

segmenteverygrain.merge_overlapping_polygons(all_grains, new_grains, comps, min_area, image_pred)¶

Merge overlapping polygons in a connected component.

This function takes a list of all polygons, a list of polygons that do not overlap with other polygons, a list of connected components, a minimum area threshold, and the Unet prediction. It iterates over each connected component and merges the overlapping polygons within that component. The most similar polygon is selected as the representative polygon for the merged region. If the area of the representative polygon is greater than the minimum area threshold, it is added to the new polygons list.

Parameters:

all_grains (list) – List of all polygons.
new_grains (list) – List of polygons that do not overlap each other.
comps (list) – List of connected components.
min_area (float) – Minimum area threshold.
image_pred (numpy.ndarray) – The Unet prediction.

Returns:

all_grains – List of merged polygons.

Return type:

list

segmenteverygrain.collect_polygon_from_mask(labels, mask, image_pred, all_grains, sx, sy, min_area=100, max_n_large_grains=10, max_bg_fraction=0.7)¶

Collect polygon from a mask and append it to a list of grains.

Parameters:

labels (ndarray) – Array of labels for each pixel in the image.
mask (ndarray) – Boolean mask indicating the region of interest.
image_pred (ndarray) – Predicted image from the Unet model.
all_grains (list) – List to append the resulting polygons to.
sx (ndarray) – X-coordinates of the polygon vertices.
sy (ndarray) – Y-coordinates of the polygon vertices.
min_area (int, optional) – Minimum area for a label to be considered significant (default is 100).
max_n_large_grains (int, optional) – Maximum number of large grains allowed in the mask (default is 10).
max_bg_fraction (float, optional) – Maximum fraction of the mask that can be background (default is 0.7).

Returns:

Updated list of polygons representing grains.

Return type:

list

segmenteverygrain.pick_most_similar_polygon(polygons)¶

Picks the ‘most similar’ polygon from a list of polygons based on the average IoU scores.

Parameters:: polygons (list) – A list of polygons.
Returns:: most_similar_polygon – The most similar polygon.
Return type:: Polygon

segmenteverygrain.calculate_iou(poly1, poly2)¶

Calculate the Intersection over Union (IoU) between two polygons.

Parameters:

poly1 (Polygon) – The first polygon.
poly2 (Polygon) – The second polygon.

Returns:

iou – The IoU value between the two polygons.

Return type:

float

segmenteverygrain.rasterize_grains(all_grains, image)¶

Rasterizes a list of polygons representing grains into an array of labels.

Parameters:

all_grains (list) – A list of polygons representing grains.
image (numpy.ndarray) – The input image.

Returns:

The rasterized array of labels.

Return type:

numpy.ndarray

segmenteverygrain.create_labeled_image(all_grains, image)¶

Create a labeled image based on the provided grains and input image.

Parameters:

all_grains (list) – List of shapely Polygon objects representing the grains.
image (numpy.ndarray) – Input image.

Returns:

rasterized (numpy.ndarray) – Labeled image where each grain is assigned a unique label.
mask_all (numpy.ndarray) – Binary mask indicating the presence of grains and their boundaries.

segmenteverygrain.read_polygons(fname)¶

Reads polygons from a GeoJSON file.

Parameters:: fname (str) – The file path to the GeoJSON file.
Returns:: A list of Shapely Polygon objects extracted from the GeoJSON file.
Return type:: list

segmenteverygrain.save_polygons(polygons, fname)¶

Save a list of polygons to a file in GeoJSON format.

Parameters:

polygons (list) – A list of Shapely polygon objects to be saved.
fname (str) – The filename where the GeoJSON data will be saved.

Return type:

None

Visualization¶

segmenteverygrain.plot_image_w_colorful_grains(image, all_grains, ax, cmap='viridis', plot_image=True, im_alpha=1.0)¶

Plot image with randomly colored grain masks.

Parameters:

image (numpy.ndarray) – The input image to be plotted.
all_grains (list) – A list of shapely Polygon objects representing the grain masks.
ax (matplotlib.axes.Axes) – The axes object on which to plot the image and grain masks.
cmap (str, optional) – The name of the colormap to use for coloring the grain masks. Default is ‘viridis’.
plot_image (bool, optional) – Whether to plot the image. Default is True.

Return type:

None

segmenteverygrain.plot_grain_axes_and_centroids(all_grains, labels, ax, linewidth=1, markersize=10)¶

Plot the axes and centroids of each grain on the given axis.

Parameters:

all_grains (list) – List of all grains.
labels (numpy.ndarray) – Array of labeled regions.
ax (matplotlib.axes.Axes) – The axis object to plot on.
linewidth (int, optional) – Width of the lines to plot (default is 1).
markersize (int, optional) – Size of the markers to plot (default is 10).

Return type:

None

segmenteverygrain.plot_histogram_of_axis_lengths(major_axis_length, minor_axis_length, area=[], binsize=0.1, xlimits=None)¶

Plots a histogram of the major and minor axis lengths in phi scale.

Parameters:

major_axis_length (array-like) – The lengths of the major axes of the grains in millimeters.
minor_axis_length (array-like) – The lengths of the minor axes of the grains in millimeters.
area (array-like, optional) – The areas of the grains in square millimeters. If provided, the axis lengths will be weighted by the area.
binsize (float, optional) – The size of the bins for the histogram. Default is 0.1.
xlimits (tuple, optional) – The limits for the x-axis in millimeters. If not provided, the limits will be determined from the data.

Returns:

fig (matplotlib.figure.Figure) – The figure object containing the plot.
ax (matplotlib.axes._subplots.AxesSubplot) – The axes object containing the plot.

segmenteverygrain.plot_images_and_labels(img, label)¶

Plot the input image and its corresponding label side by side. The third subplot shows the input image with the label overlayed.

Parameters:

img (numpy.ndarray) – The input image to be plotted.
label (numpy.ndarray) – The label image to be plotted.

Return type:

None

Model Training¶

segmenteverygrain.Unet()¶

Creates a U-Net model for image segmentation.

Returns:: model – The U-Net model.
Return type:: tensorflow.keras.Model

segmenteverygrain.weighted_crossentropy(y_true, y_pred)¶

Calculates the weighted cross-entropy loss between the true labels and predicted labels.

Parameters:

y_true (tensor) – True labels.
y_pred (tensor) – Predicted labels.

Returns:

loss – Weighted cross-entropy loss.

Return type:

tensor

segmenteverygrain.patchify_training_data(input_dir, patch_dir)¶

Extracts patches from training images and labels, and saves them to the specified directory.

Parameters:

input_dir (str) – The directory containing the input images and labels.
patch_dir (str) – The directory where the patches will be saved.

Returns:

A tuple containing the paths to the directories where the image patches and label patches are saved.

Return type:

tuple

Notes

The function expects the input directory to contain files with ‘image’ and ‘mask’ in their filenames.
The patches are extracted with a size of 256x256 pixels and a stride of 128 pixels.
The function creates subdirectories ‘images’ and ‘labels’ within the specified patch directory to save the patches.
If the input directory does not exist or contains no matching files, the function will print a warning and return.

segmenteverygrain.create_train_val_test_data(image_dir, mask_dir, augmentation=True)¶

Splits image and mask data into training, validation, and test datasets, with optional augmentation.

Parameters:

image_dir (str) – Directory containing the image files.
mask_dir (str) – Directory containing the mask files.
augmentation (bool, optional) – If True, applies data augmentation to the training dataset (default is True).

Returns:

train_dataset (tf.data.Dataset) – TensorFlow dataset for training.
val_dataset (tf.data.Dataset) – TensorFlow dataset for validation.
test_dataset (tf.data.Dataset) – TensorFlow dataset for testing.

segmenteverygrain.create_and_train_model(train_dataset, val_dataset, test_dataset, model_file=None, epochs=100)¶

Create and train a U-Net model.

Parameters:

model_file (str) – Path to the file containing the model weights.
train_dataset (tf.data.Dataset) – Training dataset.
val_dataset (tf.data.Dataset) – Validation dataset.
test_dataset (tf.data.Dataset) – Test dataset.
epochs (int, optional) – Number of epochs to train the model (default is 100).

Returns:

model – Trained U-Net model.

Return type:

tf.keras.Model

Notes

The function will plot the training and validation loss and accuracy over epochs.

segmenteverygrain.load_and_preprocess(image_path, mask_path, augmentations=False)¶

Load and preprocess an image and its corresponding mask.

Parameters:

image_path (str) – The file path of the image.
mask_path (str) – The file path of the mask.
augmentations (bool, optional) – Whether to apply augmentations to the image. Defaults to False.

Returns:

image (numpy.ndarray) – the preprocessed image.
mask (numpy.ndarray) – the preprocessed mask.

Utility Functions¶

segmenteverygrain.extract_patch(image, center, patch_size)¶

Extract a patch from the image centered on the given coordinates.

Parameters:

image (np.ndarray) – The large image from which to extract the patch.
center (tuple) – The (x, y) coordinates of the center of the patch.
patch_size (int) – The size of the patch (assumed to be square).

Returns:

The extracted patch.

Return type:

np.ndarray

segmenteverygrain.convert_to_large_image_coords(sx, sy, patch_origin)¶

Convert the coordinates from the patch to the large image.

Parameters:

sx (int) – The x-coordinate in the patch.
sy (int) – The y-coordinate in the patch.
patch_origin (tuple) – The (x, y) coordinates of the top-left corner of the patch in the large image.

Returns:

The (x, y) coordinates in the large image.

Return type:

tuple

segmenteverygrain.classify_points(feature1, feature2, x1, y1, x2, y2)¶

Classifies points based on their position relative to a line.

Parameters:

feature1 (list) – List of x-coordinates of the points.
feature2 (list) – List of y-coordinates of the points.
x1 (float) – x-coordinate of the first point on the line.
y1 (float) – y-coordinate of the first point on the line.
x2 (float) – x-coordinate of the second point on the line.
y2 (float) – y-coordinate of the second point on the line.

Returns:

List of classifications for each point. Each classification is either 0 (on or one side of the line) or 1 (the other side of the line).

Return type:

list

segmenteverygrain.compute_curvature(x, y)¶

Compute first derivatives and curvature of a curve.

Parameters:

x (1D array) – x-coordinates of the curve
y (1D array) – y-coordinates of the curve

Returns:

curvature – curvature of the curve (in 1/units of x and y)

Return type:

1D array

segmenteverygrain.find_grain_size_classes(grain_size_classes, value1, value2, xlimits=None)¶

Find grain size classes that overlap with a given range.

Parameters:

grain_size_classes (dict) – A dictionary where keys are grain size class names and values are tuples of (lower_bound, upper_bound) representing the size range of each class.
value1 (float) – One end of the range to check for overlapping grain size classes.
value2 (float) – The other end of the range to check for overlapping grain size classes.

Returns:

matching_classes (list) – A list of grain size class names that overlap with the given range.
bounds (list) – A list of unique bounds (both lower and upper) from the matching classes.

segmenteverygrain.get_area_weighted_distribution(grain_sizes, areas)¶

Generate an area-weighted distribution of grain sizes.

Parameters: grain_sizes (list): A list of grain sizes. areas (list): A list of corresponding areas for the grain sizes.

Returns: list: An area-weighted list of grain sizes.

segmenteverygrain.click_for_scale(event, ax)¶

Handles mouse click events to measure the distance between two points on a plot. Prints the distance between the two points in number of pixels.

Parameters:

event (matplotlib.backend_bases.MouseEvent) – The mouse click event object.
ax (matplotlib.axes.Axes) – The matplotlib Axes object representing the plot.

segmenteverygrain.get_grains_from_patches(ax, image, plotting=False)¶

Extract grains from patches on a plot and create a labeled image based on the updated set of grains.

Parameters:

ax (matplotlib.axes.Axes) – The matplotlib Axes object containing the patches.
image (numpy.ndarray) – The input image.

Returns:

all_grains (list) – A list of Polygon objects representing the extracted grains.
labels (numpy.ndarray) – The labeled image where each grain is assigned a unique label.
mask_all (numpy.ndarray) – The binary mask image where grains and their boundaries are marked.
fig (matplotlib.figure.Figure) – The matplotlib Figure object.
ax (matplotlib.axes.Axes) – The matplotlib Axes object.

Legacy Interactive Functions¶

These functions are from the original interactive editing interface. The new GrainPlot class from the interactions module is now the recommended approach.

segmenteverygrain.onclick(event, ax, coords, image, predictor)¶

Run the SAM segmentation based on the prompt that comes from a mouse click event. If left mouse button is clicked, the point is used as an object (label=1) and a mask is added. If right mouse button is clicked, the point is used as background (label=0) and the current mask is adjusted accordingly (if possible).

Parameters:

event (matplotlib.backend_bases.MouseEvent) – The mouse click event object.
ax (matplotlib.axes.Axes) – The matplotlib Axes object.
coords (list) – A list to store the coordinates of the clicked points.
image (numpy.ndarray) – The image data.
predictor (SamPredictor) – The predictor object for segmentation.

Return type:

None

segmenteverygrain.onclick2(event, all_grains, grain_inds, ax, select_only=False)¶

Event handler function for selecting and highlighting grains in a plot, based on mouse click events. The selected grains then are either deleted or merged, using the ‘onpress2’ function.

Parameters:

event (matplotlib.backend_bases.MouseEvent) – The mouse click event object.
all_grains (list) – A list of all the grains (polygons).
grain_inds (list) – A list to store the indices of the selected grains.
ax (matplotlib.axes.Axes) – The matplotlib Axes object representing the plot.

segmenteverygrain.onclick_large_image(event, ax, coords, image, predictor, patch_size=1000)¶

Handles mouse click events on a large image for segmentation purposes.

Parameters:

event (matplotlib.backend_bases.MouseEvent) – The mouse event that triggered the function.
ax (matplotlib.axes.Axes) – The axes object where the image is displayed.
coords (list of tuple) – List of coordinates where the user has clicked.
image (numpy.ndarray) – The large image on which segmentation is performed.
predictor (object) – The predictor object used for segmentation.
patch_size (int, optional) – The size of the patch to extract around the clicked point (default is 1000).

Notes

Left mouse button (event.button == 1) is used to add an object.
Right mouse button (event.button == 3) is used to remove the last added object.
The function updates the display with the segmented region.

segmenteverygrain.onpress(event, ax, fig)¶

Handle key press events for deleting or merging polygons.

Parameters:

event (matplotlib.backend_bases.KeyEvent) – The key press event object.
ax (matplotlib.axes.Axes) – The matplotlib Axes object.
fig (matplotlib.figure.Figure) – The matplotlib Figure object.

segmenteverygrain.onpress2(event, all_grains, grain_inds, fig, ax)¶

Handle key press events when deleting or merging grains.

Parameters:

event (matplotlib.backend_bases.KeyEvent) – The key press event object.
all_grains (list) – A list of all grains (polygons).
grain_inds (list) – A list of indices corresponding to the grains.
fig (matplotlib.figure.Figure) – The figure object.
ax (matplotlib.axes.Axes) – The axes object.

API Reference¶

Interactive Editing (interactions module)¶

Classes¶

Functions¶

Grain Extraction and Clustering (grain_utils module)¶

Core Segmentation Functions¶

Model Prediction¶

Polygon Operations¶

Visualization¶

Model Training¶

Utility Functions¶

Legacy Interactive Functions¶

segmenteverygrain

Navigation

Related Topics