API Reference

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.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.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.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.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.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.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.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.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.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.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.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.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.get_area_weighted_distribution(grain_sizes, areas)

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.

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.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.

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.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.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.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.

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.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.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_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_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

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_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_large_image(fname, model, sam, min_area, patch_size=2000, overlap=300, remove_large_objects=False)

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.

Returns:

• All_Grains (list) – A list of grains represented as polygons.

• image_pred (numpy.ndarray) – The Unet predictions for the entire image.

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.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.sam_segmentation(sam, image, image_pred, coords, labels, min_area, plot_image=False, remove_edge_grains=False, remove_large_objects=False)

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.

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.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

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

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