imea 0.2.2

Introduction

Quantitative measurement of particle shapes based on 2D binary images as well as 3D images are used in many research fields, for example chemistry (Lau et al. 2013), mineral engineering (Andersson et al. 2012), medicine (Nguyen et al. 2005), biology (Smith et al. 1996) or environmental engineering (Kandlbauer et al. 2021; Weissenbach & Sarc 2021). Furthermore, a variety of different shape measurements is proposed in scientific literature (e.g. DIN ISO 9276-6; Pahl et al. 1973a, 1973b, 1973c; Pabst & Gregorova 2007; Steuer 2010).

In contrast, existing Python packages for image analysis like scikit-image (Walt et al. 2014) or opencv (Itseez, 2015) cover only a few of the 2D and 3D shape measurements proposed in scientific literature. To utilize different shape measurements researchers often have to combine the results of different libaries which means dealing with different coordinate systems, data formats and conventions or implement shape measurements on their own. Both scenarios lead to unnecessary "reinventing the wheel" and can cause significant frustrations and/or potential errors in the results.

imea solves this problem: Based on a binary images (2D case) or a grayscale heightmaps (3D case) 53 different 2D shape measurements and 13 different 3D shape measurements are extracted and returned as an pandas dataframe (McKinney, 2010). With imea shape measurements can be extracted with a single line of code:

# 2D case
df_2d = extract_all_shape_measurements_2d(bw, spatial_resolution_xy_mm_per_px)

# 3D case
df_2d, df_3d = extract_all_shape_measurements_2d_and_3d(img_3d_org, threshold_3d, spatial_resolution_xy_mm_per_px):

In the background imea deals with different coordinate systems and conventions to utilize the implementations of existing functions for shape measurements in scikit-image and opencv. Furthermore, custom implementations based on NumPy and SciPy are integrated in imea for shape measurements that have not been implemented in those libaries yet.

Installation

Installing using pip

You can install imea using the pip package manager:

pip install imea

Installing from sources

An other option is to clone this repository:

git clone https://git.rwth-aachen.de/ants/sensorlab/imea

Dependencies

imea is tested in Python 3.7+. To use imea the following packages are required:

• NumPy
• SciPy
• scikit-image
• opencv-python
• pandas
• matplotlib (only for visualization in demo notebooks)

Usage

You can use imea either to extract 2D shape measurements from 2D binary images or to extract 2D as well as 3D shape measurements from grayscale images (heightmaps). Under the folder demo you can find two Jupyter notebooks that demonstrate the usage of imea, as well as several example images.

2D measurements

For 2D shape measurements insert a binary image bw and the spatial resolution spatial_resolution_xy_mm_per_px in [mm/px] into the function extract_all_shape_measurements_2d:

df_2d = extract_all_shape_measurements_2d(bw, spatial_resolution_xy_mm_per_px)

As a result you get a pandas dataframe, in which each row represents one particle in the binary image and each column an extracted shape measurement.

Image calibration and spatial resolution: If your image is not calibrated (i.e. no "square" pixels) you may use skimage.transform.rescale to calibrate your image. If you want your results just in pixels then set spatial_resolution_xy_mm_per_px=1.

Optional parameters: Optional parameters include the rotation stepsize dalpha (in degrees) for determinating statistical length and two boolean variables for experts to return the original distribution of statistical lengths (set return_statistical_lengths_distributions=True) and all chords (set return_all_chords=True).

3D measurements

For 3D shape measurements insert a 3D grayscale image (img_3d_org), define a threshold (threshold_3d) and the spatial resolution of one pixel (spatial_resolution_xy_mm_per_px). Pixels with grayvalues lower then threshold_3d are treated as background, the other ones are considered as regions.

df_2d, df_3d = extract_all_shape_measurements_2d_and_3d(img_3d_org, threshold_3d, spatial_resolution_xy_mm_per_px):

As a result you get two pandas dataframes df_2d and df_3d, in which each row represents one particle in the binary image and each column an extracted shape measurement.

Image calibration and spatial resolution: Per default we assume that your img_3d_org is already calibrated, i.e. 1 grayvalue step is one millimeter, otherwise you can define the spatial resolution in height direction with the optional parameter spatial_resolution_z_mm_per_gv. For calibration and spatial resolution the same recommandations as for the 2D case apply (see above).

Optional parameters: Optional parameters include the rotation stepsize dalpha for determinating shape measurements like the feret diameter, the minimum number of pixels per object to be considered (min_object_area_px) and the maximum number of objects n_objects_to_extract_max you want to extract from img_3d_org. Set n_objects_to_extract_max=-1 if you want to extract all objects, for n_objects_to_extract_max > 0 the n_objects_to_extract_max largest objects (determinated by area) are extracted.

License

imea is published under the MIT-License.

Contribution

If you want to contribute to imea, feel free to contact Nils Kroell via nils.kroell@ants.rwth-aachen.de. Moreover, you can do so by reporting bugs and/or suggesting new shape measurements.

Reporting bugs

If you encounter any issues or inconsistent results using imea: Please report them via our issue tracker, so we can work on them. Please give details on the used version of Python and other dependencies as well as provide exemplary data together with the output of imea and your expected output, so we can reproduce your error.

Suggesting new shape measurements

If you miss any 2D or 3D shape measurement feel free to open an issue providing the following details:

• Scientific paper, where the shape measurement is introduced and defined,
• evidence why this shape measurement is of scientific relevance (cite at least one scientific paper where the shape measurement is used),
• suggestions and/or references for implementation (optional).

Current available shape measurements

2d shape measurements

Currently, 53 twodimensional shape measurements are implemented in imea, as shown in the table below.

3d shape measurements

For 3D recordings, there are 13 threedimensional shape measurements implemented in imea, as shown in the table below.

Conventions

Coordinate system

imea uses right hand cardesian coordinate system, which is also used in scikit-image:

# (row, col, channel)
# 
# o------------> y
#     /|
#    / |
#   /  |
# z    |
#      v
#      x

Literature

T. Andersson, M. J. Thurley and J. E. Carlson (2012). "A machine vision system for estimation of size distributions by weight of limestone particles". In: Minerals Engineering, 25(1), pp. 38–46. https://doi.org/10.1016/j.mineng.2011.10.001

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

Itseez. (2015). Open source computer vision library. https://github.com/opencv/opencv.

L. Kandlbauer, K. Khodier, D. Ninevski, R. Sarc (2021). "Sensor-based Particle Size Determination of Shredded MixedCommercial Waste based on two-dimensional Images". In: Waste Management, 120, pp. 794-794. https://doi.org/10.1016/j.wasman.2020.11.003

Y. M. Lau, N. G. Deen and J. A. M. Kuipers (2013). "Development of an image measurement technique for size distribution in dense bubbly flows". In: Chemical Engineering Science, 94, pp. 20–29. https://doi.org/10.1016/j.ces.2013.02.043

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

W. McKinney (2010). "Data Structures for Statistical Computing in Python". In: Stéfan 54 van der Walt & Jarrod Millman (Eds.): Proceedings of the 9th Python in Science Conference. (pp. 56–61). https://doi.org/10.25080/Majora-92bf1922-00a

T. M. Nguyen and R. M. Rangayyan (2005). "Shape Analysis of Breast Masses in Mammograms via the Fractal Dimension". In: 2005 IEEE Engineering in Medicine and Biology 27th Annual Conference, Shanghai, pp. 3210-3213. https://doi.org/10.1109/IEMBS.2005.1617159

W. Pabst und E. Gregorova (2007). Characterization of particles and particle systems.

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

M. Pahl, G. Schädel und H. Rumpf (1973b). "Zusammenstellung von Teilchenformbeschreibungs-methoden: 2. Teil". In: Aufbereitungstechnik, 14(10), pp. 672–683.

M. Pahl, G. Schädel und H. Rumpf (1973c). "Zusammenstellung von Teilchenformbeschreibungs-methoden: 3. Teil". In: Aufbereitungstechnik, 14(11) , pp. 759–764.

T. G. Smith, G. D. Lange and W. B. Marks (1996). "Fractal methods and results in cellular morphology — dimensions, lacunarity and multifractals". In: Journal of Neuroscience Methods, 69(2), pp. 123–136. https://doi.org/10.1016/s0165-0270(96)00080-5

M. Steuer (2010). "Serial classification". In: AT Mineral Processing 51(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

S. Walt, J. Schönberger, J. Nunez-Iglesias, F. Boulogne, J. Warner, N. Yager, E. Gouillart, T. Yu and the scikit-image contributors. "scikit-image: Image processing in Python". In: PeerJ 2:e453 (2014) https://doi.org/10.7717/peerj.453

T. Weissenbach, R. Sarc (2021). "Investigation of particle-specific characteristics of non-hazardous, fine shredded mixed waste". In: Waste Management, 119, pp. 162-171. https://doi.org/10.1016/j.wasman.2020.09.033