package

imea.measure_2d

2-dimensional shape measurements.

module

imea.measure_2d.macro

2-dimensional macrodescriptors.

Functions
  • area_equal_diameter(projection_area) (float) — Calculate area-equal diameter.
  • circumscribing_and_inscribing_circle(centroid, contour) (tuple) — Calculate circumscribing and inscribing circle of an object shape [1].
  • convex_perimeter(bw_convex) (float) — Calculate perimeter of 2D convex hull based on an binary image of convex hull.
  • geodeticlength_and_thickness(area, perimeter) (tuple) — Calculate geodetic length and thickness based on area and diameter according to DIN ISO 9276-6.
  • max_2d_dimensions(max_chords, angles) (tuple) — Calculates the max 2d dimensions of an object shape. x_max is the overall max chord of the object in all possible orientations. y_max is the longest chord orthogonal to x_max [1].
  • max_inclosing_circle(bw) (tuple) — Calculate maximum inclosing circle of an object.
  • min_2d_bounding_box(bw) (tuple) — Calculate minimal 2-dimensional bounding box of an binary image.
  • min_enclosing_circle(contour) (tuple) — Calculate minimum enclosing circle of an object based on its list of coordinates.
  • perimeter_equal_diameter(perimeter) (float) — Calculate perimeter-equal diameter.
function

imea.measure_2d.macro.min_2d_bounding_box(bw)

Calculate minimal 2-dimensional bounding box of an binary image.

Parameters
  • bw (numpy.ndarray, type bool) — 2-dimensional binary image.
Returns (tuple)
  • length (float): Length of minimal 2-dimensional bounding box.
  • width (float): Width of minimal 2-dimensional bounding box.
  • center (numpy.ndarray, type float): Center of 2-dimensional minimal bounding box in shape [x, y].
  • cornerpoints (numpy.ndarray, type float): 2-dimensional array of four cornerpoints of the minimal bounding box in shape [[x0, y0], [x1, y1], [x2, y2], [x3, y3]].
function

imea.measure_2d.macro.area_equal_diameter(projection_area)

Calculate area-equal diameter.

Parameters
  • projection_area (float) — Projection area.
Returns (float)
  • area_equal_diameter (float): 2D area-equal diameter.
function

imea.measure_2d.macro.perimeter_equal_diameter(perimeter)

Calculate perimeter-equal diameter.

Parameters
  • perimeter (float) — Perimeter.
Returns (float)
  • perimeter_equal_diameter (float): Perimeter-equal diameter.
function

imea.measure_2d.macro.max_inclosing_circle(bw)

Calculate maximum inclosing circle of an object.

Parameters
  • bw (numpy.ndarray, type bool) — 2-dimensional binary image.
Returns (tuple)
  • center (numpy.ndarray, type float): Center position of maximum inclosing circle in shape [x, y].
  • diameter (float): Diameter of maximum inclosing circle.
function

imea.measure_2d.macro.min_enclosing_circle(contour)

Calculate minimum enclosing circle of an object based on its list of coordinates.

Parameters
  • contour (numpy.ndarray, type int) — Array of contour points in shape [[x0, y0], [x1, y1], ...].
Returns (tuple)
  • center (numpy.ndarray, type float): Center of minimum enclosing circle.
  • diameter (float): Diameter of minimum enclosing circle.
function

imea.measure_2d.macro.circumscribing_and_inscribing_circle(centroid, contour)

Calculate circumscribing and inscribing circle of an object shape [1].

Parameters
  • centroid (numpy.ndarray, type float) — Centroid of object in shape [x,y].
  • contour (numpy.ndarray, type int) — Array of contour points in shape [[x0, y0], [x1, y1], ...].
Returns (tuple)
  • diameter_circumscribing_circle (float): Diameter of circumscribing circle.
  • diameter_inscribing_circle (float): Diameter of inscribing circle.
References

[1] X. Li, Z. Wen, H. Zhu, Z. Guo and Y. Liu (2020). "An improved algorithm for evaluation of the minimum circumscribed circle and maximum inscribed circle based on the local minimax radius". In: The Review of scientific instruments 91(3), pp. 035103. DOI: https://doi.org/10.1063/5.0002233

function

imea.measure_2d.macro.geodeticlength_and_thickness(area, perimeter)

Calculate geodetic length and thickness based on area and diameter according to DIN ISO 9276-6.

Parameters
  • area (float) — Projection area of shape.
  • perimeter (float) — Perimeter of shape.
Returns (tuple)
  • geodeticlength (float): Geodetic length of shape.
  • thickness (float): Thickness of shape.

Notes

Calculation according to DIN ISO 9276-6: The geodetic lengths and thickness are approximated by an rectangle with the same area and perimeter: (1) area = geodeticlength * thickness (2) perimeter = 2 * (geodetic_length + thickness)

function

imea.measure_2d.macro.max_2d_dimensions(max_chords, angles)

Calculates the max 2d dimensions of an object shape. x_max is the overall max chord of the object in all possible orientations. y_max is the longest chord orthogonal to x_max [1].

Parameters
  • max_chords_2d (numpy.ndarray, type float) — 1-dimensional array of max chords at different angles (angles_2d).
  • angles_2d (numpy.ndarray, type float) — Respective angles to the max_chords_2d in ascending order.
Returns (tuple)
  • x_max (float): Larger max dimension of object (definition see above).
  • y_max (float): Smaller max dimension of object (definition see above).
References

[1] M. Steuer (2010). "Serial classification". In: AT Mineral Processing 51(1).

function

imea.measure_2d.macro.convex_perimeter(bw_convex)

Calculate perimeter of 2D convex hull based on an binary image of convex hull.

Parameters
  • bw_convex (numpy.ndarray, type bool) — 2-dimensional binary convex image.
Returns (float)
  • convex_perimeter (float): Convex perimeter.
module

imea.measure_2d.meso

2-dimensional mesodescriptors.

Functions
  • erosions_till_erase(bw, pad_width, selem, return_counts) (tuple) — Determine number of erosions that are necessary to fully erase all True elements in a binary image [1].
  • erosions_till_erase_complement(bw, bw_convex, pad_width, selem, return_counts) (tuple) — Determine number of erosions that are necessary to erase all pixels from the complement between the binary image of an object and the binary image of its convex hull [1].
function

imea.measure_2d.meso.erosions_till_erase_complement(bw, bw_convex, pad_width=1, selem=None, return_counts=False)

Determine number of erosions that are necessary to erase all pixels from the complement between the binary image of an object and the binary image of its convex hull [1].

Parameters
  • bw (numpy.ndarray, type bool) — 2-dimensional binary image.
  • bw_convex (numpy.ndarray, type bool) — 2-dimensional binary image of convex hull corresponding to bw.
  • pad_width (int, optional) — Number of false pixels to pad around the image, by default 1.
  • selem (numpy.ndarray, type bool, optional) — Neighborhood expressed as a 2-D array of ones and zeros, by default None. If None, use a cross-shaped structuring element (connectivity=1) is used.
  • return_counts (bool, optional) — If True, a list with the number of true pixels for each iteration is returned, by default False.
Returns (tuple)
  • n_erosions_2d (int): Number of erosions to fully erase complement between bw and bw_convex.
  • true_pixels_per_erosion (numpy.ndarray, optional): Number of true pixels after each erosion. Only provided if return_counts is True.
References

[1] Deutsches Institut für Normung e. V. (2012). DIN ISO 9276-6 - Darstellung der Ergebnisse von Par-tikelgrößenanalysen: Teil 6: Deskriptive und quantitative Darstellung der Form und Morphologie von Partikeln.

function

imea.measure_2d.meso.erosions_till_erase(bw, pad_width=1, selem=None, return_counts=False)

Determine number of erosions that are necessary to fully erase all True elements in a binary image [1].

Parameters
  • bw (numpy.ndarray, type bool) — 2-dimensional binary image.
  • pad_width (int, optional) — Number of false pixels to pad around the image, by default 1.
  • selem (numpy.ndarray, type bool, optional) — Neighborhood expressed as a 2-D array of ones and zeros, by default None. If None, use a cross-shaped structuring element (connectivity=1) is used.
  • return_counts (bool, optional) — If True, a list with the number of true pixels for each iteration is returned, by default False.
Returns (tuple)
  • n_erosions_2d (int): Number of erosions to fully erase true pixels from image.
  • true_pixels_per_erosion (numpy.ndarray, optional): Number of true pixels after each erosion. Only provided if return_counts is True.
References

[1] Deutsches Institut für Normung e. V. (2012). DIN ISO 9276-6 - Darstellung der Ergebnisse von Par-tikelgrößenanalysen: Teil 6: Deskriptive und quantitative Darstellung der Form und Morphologie von Partikeln.

module

imea.measure_2d.micro

2-dimensional microdescriptors.

Functions
function

imea.measure_2d.micro.fractal_dimension_boxcounting(bw, pad_width=1)

Approximate fractal dimension by boxcounting method [1].

Parameters
  • bw (numpy.ndarray, type bool) — 2-dimensional binary image.
  • pad_width (int, optional) — Width of applied zero-padding around the image, by default 1.
Returns (float)
  • fractal_dimension (float): Approximated fractal dimension.
References

[1] G.-B. So, H.-R. So, G.-G. Jin (2017): "Enhancement of the Box-Counting Algorithm for fractal dimension estimation". In: Pattern Recognition Letters, 98, pp. 53-58. https://doi.org/10.1016/j.patrec.2017.08.022

function

imea.measure_2d.micro.fractal_dimension_perimeter(contour, max_feret, n_stepsizes=10, step_size_min=2.0)

Approximate fractal dimension with perimeter method. [1]

Parameters
  • contour (numpy.ndarray, type float) — Array of contourpoints in shape (n, 2) (e.g. [[x0, y0], [x1, y1], [x2, y2], ...]).
  • max_feret (float) — Max feret diameter of object shape for norming the perimeters.
  • n_stepsizes (int, optional) — Number of different stepsizes to take, by default 10
  • step_size_min (float, optional) — Minimum stepsize, by default 2.0.
Returns (float)
  • fractal_dimension (float): Approximated fractal dimension.

Notes

Stepsizes range from step_size_min to step_size_max in a log2 grid. step_size_max is set to 0.3 * max_feret according to DIN ISO 9276-6.

References

[1] Deutsches Institut für Normung e. V. (2012). DIN ISO 9276-6 - Darstellung der Ergebnisse von Par-tikelgrößenanalysen: Teil 6: Deskriptive und quantitative Darstellung der Form und Morphologie von Partikeln.

module

imea.measure_2d.statistical_length

2-dimensional statistical length.

Functions
  • compute_statistical_lengths(bw, daplha) (tuple) — Calculate statistical length distributions by rotating binary image bw in dalpha steps [1].
  • distribution_parameters(distribution) (tuple) — Calculate distribution parameters of an array.
  • feret(bw) (tuple) — Calculate Feret diameter of an object (orthogonal to y-direction) [1].
  • find_all_chords(bw) (tuple) — Calculate chords of an object shape in y-direction [1].
  • find_max_chord(bw) (tuple) — Calculate the maximum chords of an object shape in y-direction [1].
  • martin(bw, area_share_from_bottom) (tuple) — Calculate Martin diameter of an object (in y-direction) [1].
  • nassenstein(bw) (tuple) — Calculates the Nassenstein diameter of an object shape [1].
function

imea.measure_2d.statistical_length.compute_statistical_lengths(bw, daplha=9)

Calculate statistical length distributions by rotating binary image bw in dalpha steps [1].

Parameters
  • bw (numpy.ndarray, type bool) — 2-dimensional binary image.
  • daplha (number) — Rotation stepsize in degrees (0 - 180°), by default 9.
Returns (tuple)
  • feret_diameters (numpy.ndarray, type int): 1-dimensional array of Feret diameters for each rotation angle [1].
  • martin_diameters (numpy.ndarray, type int): 1-dimensional array of Martin diameters for each rotation [1].
  • nassenstein_diameters (numpy.ndarray, type int): 1-dimensional array of Nassenstein diameters for each rotation.
  • max_chords (numpy.ndarray, type int): 1-dimensional array of maximum chord for each rotation [1].
  • all_chords (numpy.ndarray, type int): 1-dimensional array of all chords for each rotation [1].
  • angles (numpy.ndarray, type float): 1-dimensional array of measured angles in degree as determinated by daplha.
References

[1] M. Pahl, G. Schädel und H. Rumpf (1973a). "Zusammenstellung von Teilchenformbeschreibungsmethoden: 1. Teil". In: Aufbereitungstechnik, 14(5), pp. 257–264.

function

imea.measure_2d.statistical_length.nassenstein(bw)

Calculates the Nassenstein diameter of an object shape [1].

Parameters
  • bw (numpy.ndarray, type bool) — 2-dimensional binary image.
Returns (tuple)
  • nassenstein_diameter (int): Nassenstein diameter.
  • idx (numpy.ndarray, type int): Indexes of the start (0) and endpoint (1) of the Nassenstein diameter in shape [[x0,y0], [x1,y1]].
References

[1] M. Pahl, G. Schädel und H. Rumpf (1973a). "Zusammenstellung von Teilchenformbeschreibungsmethoden: 1. Teil". In: Aufbereitungstechnik, 14(5), pp. 257–264.

Notes

There might be several touching points in the lowest row. In this implementation we will evaluate the Nassenstein Durchmesser at the middle of the first continuous contact surface from left.

function

imea.measure_2d.statistical_length.feret(bw)

Calculate Feret diameter of an object (orthogonal to y-direction) [1].

Parameters
  • bw (numpy.ndarray, type bool) — 2-dimensional binary image.
Returns (tuple)
  • feret_diameter (int): 2D Feret diameter.
  • idx_x (numpy.ndarray, type int): x-coordinates of the two Feret calipers in shape [x0, x1].
References

[1] M. Pahl, G. Schädel und H. Rumpf (1973a). "Zusammenstellung von Teilchenformbeschreibungsmethoden: 1. Teil". In: Aufbereitungstechnik, 14(5), pp. 257–264.

function

imea.measure_2d.statistical_length.martin(bw, area_share_from_bottom=0.5)

Calculate Martin diameter of an object (in y-direction) [1].

Parameters
  • bw (numpy.ndarray, type bool) — 2-dimensional binary image.
  • area_share_from_bottom (float, optional) — Area share, where the Martin diameter is measured, by default 0.5 (original definition of the Martin diameter.)
Returns (tuple)
  • martin_diameter (int): Martin diameter.
  • idx (numpy.ndarray, type int): Indexes of the start (0) and endpoint (1) of the Martin diameter in shape [[x0,y0], [x1,y1]].
References

[1] M. Pahl, G. Schädel und H. Rumpf (1973a). "Zusammenstellung von Teilchenformbeschreibungsmethoden: 1. Teil". In: Aufbereitungstechnik, 14(5), pp. 257–264.

Notes

The original Martin diameter is is measured at the x-position, where the object is split into 50% / 50% area share. However, we can also calculate a diameter at a flexible area share. This is given by area_share_from_bottom: area_share_from_bottom = 1 - area_share_from_top

function

imea.measure_2d.statistical_length.find_all_chords(bw)

Calculate chords of an object shape in y-direction [1].

Parameters
  • bw (numpy.ndarray, type bool) — 2-dimensional binary image.
Returns (tuple)
  • all_chords (numpy.ndarray, type int): 1-dimensional array of found chords c in shape [c0, c1, ...].
  • all_edgepoints (numpy.ndarray, type int): 2-dimensional array of edgepoints corresponding to all_chords in shape [[x0a, y0a], [x0b, y0b], [x1a, y1a], [x1b, y1b], ...], where a is the start and b is the endpoint of the corresponding edge and 0, 1, ... the index of the corresponing chords.
References

[1] M. Pahl, G. Schädel und H. Rumpf (1973a). "Zusammenstellung von Teilchenformbeschreibungsmethoden: 1. Teil". In: Aufbereitungstechnik, 14(5), pp. 257–264.

function

imea.measure_2d.statistical_length.find_max_chord(bw)

Calculate the maximum chords of an object shape in y-direction [1].

Parameters
  • bw (numpy.ndarray, type bool) — 2-dimensional binary image.
Returns (tuple)
  • max_chord (int): Maximum chord in y-direction.
  • idx (numpy.ndarray, type int): Start (0) and endpoint (1) of max chord in shape [[x0, y0], [x0, y0]].
References

[1] M. Pahl, G. Schädel und H. Rumpf (1973a). "Zusammenstellung von Teilchenformbeschreibungsmethoden: 1. Teil". In: Aufbereitungstechnik, 14(5), pp. 257–264.

function

imea.measure_2d.statistical_length.distribution_parameters(distribution)

Calculate distribution parameters of an array.

Parameters
  • distribution (numpy.ndarray, type float) — An array.
Returns (tuple)
  • max_value (float): Max value in distribution.
  • min_value (float): Min value in distribution.
  • median_value (float): Median value in distribution.
  • mean_value (float): Mean value in distribution.
  • mode (float): Mode value in distribution.
  • std (float): Standard deviation of distribution.
module

imea.measure_2d.utils

Helping functions for 2-dimensional shape measurements.

Functions
  • find_contour(bw) (numpy.ndarray, type int) — Find external contour points of an object shape.
  • skimage_measurements(bw) (tuple) — Calculate object shape measurements based on skimage.measure.regionprops.
function

imea.measure_2d.utils.find_contour(bw)

Find external contour points of an object shape.

Parameters
  • bw (numpy.ndarray, type bool) — 2-dimensional binary image.
Returns (numpy.ndarray, type int)
  • contour (numpy.ndarray, type int): 2-dimensional array of contourpoints in shape [[x0, y0], [x1, y1], [x2, y2], ...].
function

imea.measure_2d.utils.skimage_measurements(bw)

Calculate object shape measurements based on skimage.measure.regionprops.

Parameters
  • bw (numpy.ndarray, type bool) — 2-dimensional binary image.
Returns (tuple)
  • area_projection (int): Projection area.
  • perimeter (float): Perimeter.
  • area_filled (int): Filled area.
  • area_convex (int): Convex area.
  • major_axis_length (float): Major axis length.
  • minor_axis_length (float): Minor axis length.
  • centroid (numpy.ndarray, type float): Centroid in shape [x, y].
  • coords (numpy.ndarray, type int): 2-dimensional array of object coordinates in shape [[x0, y0], [x1, y1], ...].
  • bw_cropped (numpy.ndarray, type bool): Cropped version of bw.
  • bw_convex (numpy.ndarray, type bool): Cropped 2-dimensional convex binary image of bw.

Notes

Extracts only shape measurement of largest object in bw_org, since multi object shape extraction is handled by higher functions in imea.