Utilities (darsia.utils)#

Utility functionalities.

Submodules#

darsia.utils.box module#

bounding_box(voxels, padding=0, max_size=None)[source]#

Determine bounding box for a set of given coordinates.

Parameters:

  • voxels (VoxelArray) – voxel array of size N x dim, using matrix indexing in 2d.

  • padding (int) – padding to create a slightly larger bounding box. Might be of interest if the area that is prescribed in coords cover slightly less than strictly needed. Default is 0.

  • max_size (list or tuple, optional) – max size of bounding box in each dimension.

Returns:

slices with ranges from min to max value

per dimension.

Return type:

tuple of slices

bounding_box_inverse(bounding_box)[source]#

Returns an array that would produce the same bounding box from the bounding_box() function above.

Parameters:

slices (tuple of) – slices with ranges from min to max value per dimension.

Returns:

voxel array of size N x dim, using matrix indexing in 2d.

Return type:

voxels (VoxelArray)

perimeter(box)[source]#

Returns the perimeter of a box. Accepts both tuples of slices as well as arrays of coordinates as input.

Parameters:

box (tuple of slices or np.ndarray) – definition of a box, either as tuple of slices, or coordinates (can also use metric units)

Returns:

perimeter

Return type:

float or int (depending on input)

random_patches(mask, width, num_patches)[source]#

Utility to extract random patches from a mask.

Parameters:

  • mask (np.ndarray) – binary mask to extract patches from.

  • width (int) – width of the patches.

  • num_patches (int) – number of patches to extract.

Returns:

patches as slices. None: if the mask is too small to extract patches.

Return type:

list of tuples

NOTE: The function utilizes randomness. For reproducibility, the seed is fixed.

darsia.utils.coloranalysis module#

Module to assist in the analysis of color spectra.

hsv_spectrum(img, roi, bins=100)[source]#

Plot histograms for all HSV components present in a ROI of an image.

Parameters:

  • img (np.ndarray) – image array in RGB space with matrix indexing

  • roi (tuple of slices) – slice for y-components, and slice for x-components, defining a region of interest, to be cropped from img

darsia.utils.features module#

Class for feature detection.

class FeatureDetection[source]#

Bases: object

Class containing two class methods, once detecting features, and matching features.

classmethod extract_features(img, roi=None, mask=None, max_features=200)[source]#

Extract features from an image.

Parameters:

  • img (np.ndarray) – image array

  • roi (tuple of two slices, optional) – region of interest; by default the entire image is considered

  • max_features (int) – maximal number of features to be extracted

  • mask (np,ndarray, optional) – region of interest for features to be considered or ignored; default is None which identifies all features as relevant.

Returns:

tuple of
kps: keypoints of the features; note keypoints come in (col, row),

i.e., reversed matrix indexing

np.ndarray: descriptors of the features

bool: flag indicating whether features have been found

Return type:

tuple

classmethod match_features(features_src, features_dst, keep_percent=0.1, return_matches=False)[source]#

Match two sets of features via a homography.

Parameters:

  • features_src (tuple) – source features given as tuple of keypoints and descriptors

  • features_dst (tuple) – destination features given as tuple of keypoints and descriptors

  • keep_percent (float) – number between 0 and 1 indicating how many features should be considered for finding a match; 0 denotes none, while 1 denotes all.

  • return_matches (bool) – flag controlling whether also the matches are returned, which could e.g. be used for plotting

Returns:

homography matrix matching the features bool: flag indicating whether procedure has been successful matches (optional): matches between features # TODO type

Return type:

np.ndarray

darsia.utils.identity module#

darsia.utils.interpolation module#

Module containing interpolation functionality for scalar data.

illumination_interpolation(measurements, coordinate_system)[source]#

Determine a voxeled spatial map from measurements through polynomial interpolation.

Parameters:

  • measurements (tuple[np.ndarray, ...]) – tuple of x, y, and data measurements, providing the input for interpolation.

  • shape (tuple of int) – target shape of the output map.

  • coordinate_system (darsia.CoordinateSystem) – coordinate system of the correspoinding physical image.

  • degree (int) – degree of the polynomial interpolation.

Returns:

map

Return type:

np.ndarray

interpolate_measurements_2d(measurements, coordinate_system)[source]#

Determine a voxeled spatial map from measurements through RBF interpolation.

Parameters:

measurements – tuple of x, y, and data measurements, providing the input for interpolation.

Returns:

map

Return type:

np.ndarray

interpolate_to_image(data, image, method='rbf')[source]#

Interpolate data to image.

Parameters:

  • data (np.ndarray) – (x,y,measurements) data to be interpolated.

  • image (darsia.Image) – Image to which data shall be interpolated.

  • method (str) – Interpolation method to use. Options are: - “rbf”: Radial Basis Function interpolation (default). - “polynomial”: Polynomial interpolation. - “linear”: Linear interpolation. - “quadratic”: Quadratic interpolation. - “cubic”: Cubic interpolation. - “quartic”: Quartic interpolation.

Returns:

interpolated image.

Return type:

darsia.Image

interpolate_to_image_from_csv(csv_file, key, image, method='rbf')[source]#

Interpolate data from CSV to image.

Parameters:

  • csv_file (Path) – Path to the CSV file containing the data.

  • key (str) – Key to identify the data in the CSV file.

  • image (darsia.Image) – Image to which data shall be interpolated.

  • method (str) – Interpolation method to use. Options are: - “rbf”: Radial Basis Function interpolation (default). - “polynomial”: Polynomial interpolation. - “linear”: Linear interpolation. - “quadratic”: Quadratic interpolation. - “cubic”: Cubic interpolation. - “quartic”: Quartic interpolation.

Returns:

Interpolated image.

Return type:

darsia.Image

polynomial_interpolation(measurements, coordinate_system, degree=2)[source]#

Determine a voxeled spatial map from measurements through polynomial interpolation.

Parameters:

  • measurements (tuple[np.ndarray, ...]) – tuple of x, y, and data measurements, providing the input for interpolation.

  • shape (tuple of int) – target shape of the output map.

  • coordinate_system (darsia.CoordinateSystem) – coordinate system of the correspoinding physical image.

  • degree (int) – degree of the polynomial interpolation.

Returns:

map

Return type:

np.ndarray

darsia.utils.segmentation module#

Module containing utils for segmentation of layered media.

group_labels(labels, groups, values=None)[source]#

Unite labels in the given groups.

Parameters:

  • labels (darsia.Image) – labeled image with integer labels.

  • group (list[list[int]]) – list of groups, where each group is a list of labels to be united. The first label in each group is the label to which all other labels in the group will be united.

label_image(img, map=None, tol=0.01, ensure_connectivity=True, expand_labels=True, significance=None, max_iter=10)[source]#

Segment an image based on colors.

Parameters:

  • img (np.ndarray or darsia.Image) – input image in RGB color space

  • map (dict, optional) –

    dictionary mapping color names to labels and RGB values; default is None, in which case a predefined map is used: map = {

    ”white”: (0, (1, 1, 1)), “black”: (1, (0, 0, 0)), “red”: (2, (1, 0, 0)), “green”: (3, (0, 1, 0)), “blue”: (4, (0, 0, 1)), “cyan”: (5, (0, 1, 1)), “magenta”: (6, (1, 0, 1)), “yellow”: (7, (1, 1, 0)),

    } the keys are the color names (currently not used), the values are tuples containing the label (int) and the RGB value (tuple of floats in [0, 1]).

  • tol (float) – tolerance for color matching in float format; default is 0.1.

  • max_iter (int) – maximum number of iterations for filling unlabeled pixels; default is 10.

The labeling is done by comparing the RGB values of the input image with the RGB values in the map. If the absolute difference is less than the tolerance, the corresponding label is assigned to the pixel. After the labeling is complete, the connected components are identified and labeled using skimage.measure.label.

Returns:

labeled regions in the same format as img.

Return type:

np.ndarray or darsia.Image

make_consecutive(labels)[source]#

Ensure that labels in the image are consecutive integers starting from 0.

segment(img, markers_method='gradient_based', edges_method='gradient_based', mask=None, verbosity=False, **kwargs)[source]#

Prededfined workflow for segmenting an image based on watershed segmentation.

In addition, denoising is used.

Parameters:

  • img (np.ndarray, or darsia.Image) – input image in RGB color space

  • markers_method (str) – “gradient_based” or “supervised”, deciding which algorithm is used for detecting markers; the former allows for less input, while the latter allows to explicitly address regions of interest.

  • edges_method (str) – “gradient_based” or “scharr”, deciding which algorithm is used for determining edges; the former uses gradient filtering while the latter uses the Scharr algorithm.

  • mask (np.ndarray, optional) – binary array, only where true, segmentation is performed

  • verbosity (bool) – flag controlling whether relevant quantities are plotted which is useful in the tuning of the parameters; the default is False.

  • arguments (keyword) –

    tuning parameters for the watershed algorithm “method” (str): ‘median’ or ‘tvd’, while the latter uses a anisotropic

    TVD with fixed settings.

    ”median disk radius” (int): disk radius to be considered to smooth

    the image using rank based median, before the analysis.

    ”rescaling factor” (float): factor how the image is scaled before

    the actual watershed segmentation.

    ”monochromatic_color” (str): “gray”, “red”, “green”, “blue”, or “value”,

    identifying the monochromatic color space to be used in the analysis; default is gray.

    ”boundaries” (list of str): containing elements among “top”, “bottom”,

    ”right”, “left”. These will be omitted in the cleaning routine.

Returns:

labeled regions in the same format as img.

Return type:

np.ndarray or darsia.Image