Package: imea
IntroductionQuantitative measurement of 2D and 3D shapes based on 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 likescikit-image(Walt et al. 2014) oropencv(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 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.imeasolves this problem: Based on binary images (2D case) or grayscale images where the grayvalue of each pixel represents its height (3D case), 53 different 2D shape measurements and 13 different 3D shape measurements are extracted and returned as anpandasdataframe (McKinney, 2010). Withimeashape measurements can be extracted with a single line of code:# 2D casedf_2d=imea.shape_measurements_2d(bw,spatial_resolution_xy)# 3D casedf_2d,df_3d=imea.shape_measurements_3d(img_3d,threshold_mm,spatial_resolution_xy,spatial_resolution_z)In the backgroundimeadeals with different coordinate systems and conventions to utilize the implementations of existing functions for shape measurements inscikit-imageandopencv. Furthermore, custom implementations based onNumPyandSciPyare integrated inimeafor shape measurements that have not been implemented in those libaries yet.CitationIf you useimea, please cite ourJOSS paper:@article{Kroell2021,doi={10.21105/joss.03091},url={https://doi.org/10.21105/joss.03091},year={2021},publisher={The Open Journal},volume={6},number={60},pages={3091},author={Nils Kroell},title={imea: A Python package for extracting 2D and 3D shape measurements from images},journal={Journal of Open Source Software}}DocumentationFor detailed documentation and the API references ofimeaplease visit our documentation site:imea.readthedocs.ioInstallationWe recommend usingimeain anAnacondaenviroment.Install with pip (recommended)You can installimeausing thepip package manager:pipinstallimeaInstall from sourcesAn other option is to clone theimearepositoryand install it manually:gitclonehttps://git.rwth-aachen.de/ants/sensorlab/imeacdimea
pipinstall.Dependenciesimeais tested in Python3.7+. To useimeathe following packages are required:numpy>=1.18scipy>=1.10scikit-image>=0.16opencv-python>=4.5pandas>=1.0.5matplotlib>=3.2(only for visualization in demo notebooks)pytest>=5.4(only for running tests)Requierements are also listed inrequirements.txt(for usingimea) andrequirements-dev.txt(for development and running tests).TestsUnit tests are available in thetestsfolder. To execute the tests withpytestyou can run the following command:python-mpytesttestsUsageYou can useimeaeither 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 folderdemoyou can find two Jupyter notebooks that demonstrate the usage ofimea, as well as severalexample images.2D measurementsFor 2D shape measurements insert a binary imagebwand the spatial resolution in xy-direction (spatial_resolution_xy) in [mm/px] into the functionextract_df_2d:df_2d=imea.shape_measurements_2d(bw,spatial_resolution_xy)As a result you get apandasdataframe, 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 useskimage.transform.rescaleto calibrate your image. If you want your results just in pixels then setspatial_resolution_xy=1.Optional parameters:Optional parameters include the rotation stepsizedalpha(in degrees) for determinating statistical length and two boolean variables for experts to return the original distribution of statistical lengths (setreturn_statistical_lengths=True) and all chords (setreturn_all_chords=True).3D measurementsFor 3D shape measurements insert a 3D grayscale image (img_3d), define a threshold (threshold_mmin [mm]) and the spatial resolution of one pixel in x/y-direction (spatial_resolution_xyin [mm/Pixel]) and z-direction (spatial_resolution_zin [mm/Grayvalue]). Pixels with heights lower thenthreshold_mmare treated as background, the other ones are considered as objects. With the following function call you can extract 2D and 3D shape measurements from a 3D grayscale image (img_3d):df_2d,df_3d=imea.shape_measurements_3d(img_3d,threshold_mm,spatial_resolution_xy,spatial_resolution_z)As a result you get twopandasdataframesdf_2danddf_3d, in which each row represents one particle in the binary image and each column an extracted shape measurement.Image calibration and spatial resolution:You can define the spatial resolution of your image with the parametersspatial_resolution_xyandspatial_resolution_z. For calibration and spatial resolution the same recommandations as for the 2D case apply (see above).Optional parameters:Optional parameters include the rotation stepsizedalphafor determinating shape measurements like the feret diameter, the minimum number of pixels per object to be considered (min_object_area) and the maximum number of objectsn_objects_maxyou want to extract fromimg_3d. Setn_objects_max=-1if you want to extract all objects, forn_objects_max > 0then_objects_maxlargest objects (determinated by area) are extracted.Licenseimeais published under theMIT-License.ContributionIf you want to contribute toimea, feel free to contact Nils Kroell vianils.kroell@ants.rwth-aachen.de. Moreover, you can do so by reporting bugs and/or suggesting new shape measurements.Reporting bugsIf you encounter any issues or inconsistent results usingimea: Please report them via ourissue 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 ofimeaand your expected output, so we can reproduce your error.Suggesting new shape measurementsIf 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 three scientific papers where the shape measurement is used),suggestions and/or references for implementation (optional).Current available shape measurements2D shape measurementsCurrently, 53 twodimensional shape measurements are implemented inimea, as shown in the tables below. According to DIN ISO 9276-6 these are structured in macro-, meso- and microdescriptors as well as statistical lengths, as illustrated below.Macro measurements (imea.measure_2d.macro)Macrodescriptors represent the overall, external shape of a particle. The following macrodescriptors are currently available inimea:Naming   in imeaDescriptionImplementationReferenceperimeterPerimeter.skimage.measure.regionprops(DIN ISO 9276-6)convex_perimeterPerimeter of the convex hull.custom based onskimage.measure.regionprops(DIN ISO 9276-6)area_projectionProjection area.skimage.measure.regionprops(DIN ISO 9276-6)area_filledFilled projection area.skimage.measure.regionprops(DIN ISO 9276-6)area_convexArea of the convex hull.skimage.measure.regionprops(DIN ISO 9276-6)major_axis_lengthMajor axis length of the   legendre ellipse of inertia (ellipse that has the same normalized second   central moments as the particle shape).skimage.measure.regionprops(DIN ISO 9276-6)minor_axis_lengthMinor axis length of the   legendre ellipse of inertia.skimage.measure.regionprops(DIN ISO 9276-6)diameter_max_inclosing_circleDiameter of the maximum   incircleof the projection area.based oncv2.distanceTransform(Pahl et al. 1973a)diameter_min_enclosing_circleDiameter of the minimum   circumferenceof the projection area.cv2.minEnclosingCircle(Pahl et al. 1973a)diameter_circumscribing_circleDiameter of the circumcircle   withsame center as theparticle contour and maximumarea, which touches the particle contourfrom the inside.custom based onspatial.distance.cdist(Li et al. 2020)diameter_inscribing_circleDiameter of the circumcircle   withsame center as theparticle contour and minimumarea, which touches the particle contourfrom the outside.custom based onspatial.distance.cdist(Li et al. 2020)diameter_equal_areaDiameter of a circle of   equalprojection area.custom based on DIN ISO 9276-6(DIN ISO 9276-6)diameter_equal_perimeterDiameter of a circle of   equalperimeter.custom based on DIN ISO 9276-6(DIN ISO 9276-6)x_maxMaximumlongest chord.custom(Steuer 2010)y_maxLongest chord orthogonal toy_maxcustom(Steuer 2010)width_min_bbWidth of minimal 2D bounding   box.cv2.minAreaRect(Steuer 2010)length_min_bbLength of minimal 2D bounding   box (width_min_bb <= length_min_bb).cv2.minAreaRect(Steuer 2010)geodeticlengthGeodetic length.custom based on DIN ISO 9276-6(DIN ISO 9276-6; Pons et al. 1999)thicknessThickness.custom based on DIN ISO 9276-6(DIN ISO 9276-6; Pons et al. 1999)Meso measurements (imea.measure_2d.meso)Mesodescriptors describe details in the particle shape and/or surface structure whose magnitude are not much smaller than the particle proportions. The following mesodescriptors are currently available inimea:Naming   in imeaDescriptionImplementationReferencen_erosionsNumber of pixel erosions   tocompletely erase the silhouette of a particle in the binary image.custom based onskimage.morphology.binary_erosion(DIN ISO 9276-6)n_erosions_complementNumber of pixel erosions to   completelyerase the complement between convex hull and object.custom based onskimage.morphology.binary_erosion(DIN ISO 9276-6)Micro measurements (imea.measure_2d.micro)Microdescriptors describe the roughness of particle contours. The following microdescriptors are currently available inimea:Naming   in imeaDescriptionImplementationReferencefractal_dimension_boxcounting_methodFractal dimension determined by the box counting methodcustom based on (So et al. 2017)(So et al. 2017)fractal_dimension_perimeter_methodFractal dimension determined by   the perimeter method according to DIN ISO 9276-6 (evenly structured gait).custom based on DIN ISO 9276-6(DIN ISO 9276-6)Statistical lengths (imea.measure_2d.statistical_length)Statistical lengths are macrodescriptors that are evaluated at different rotation angles of the shape. Based on the resulting distribution of statistical length different metrics like the minimum or maximum value can be obtained. The following statistical length are currently available inimea:Naming   in imeaDescriptionImplementationReferenceferet_maxMaximum Feret diameter.custom(Pahl et al. 1973a)feret_minMinimum Feret diameter.custom(Pahl et al. 1973a)feret_medianMedian of all Feret diameters.custom(Pahl et al. 1973a)feret_meanArithmetic mean of all Feret   diameters.custom(Pahl et al. 1973a)feret_modeMode of all Feret diameters.custom(Pahl et al. 1973a)feret_stdStandard deviation of all Feret   diameters.custom(Pahl et al. 1973a)martin_maxMaximum Martin diameter.custom(Pahl et al. 1973a)martin_minMinimum Martin diameter.custom(Pahl et al. 1973a)martin_medianMedian of all Martin diameters.custom(Pahl et al. 1973a)martin_meanArithmetic mean of all Martin   diameters.custom(Pahl et al. 1973a)martin_modeMode of all Martin diameters.custom(Pahl et al. 1973a)martin_stdStandard deviation of all Martin   diameters.custom(Pahl et al. 1973a)nassenstein_maxMaximum Nassenstein diameter.custom(Pahl et al. 1973a)nassenstein_minMinimum Nassenstein diameter.custom(Pahl et al. 1973a)nassenstein_medianMedian of all Nassenstein   diameters.custom(Pahl et al. 1973a)nassenstein_meanArithmetic mean of all   Nassenstein diameters.custom(Pahl et al. 1973a)nassenstein_modeMode of all Nassenstein   diameters.custom(Pahl et al. 1973a)nassenstein_stdStandard deviation of all   Nassenstein diameters.custom(Pahl et al. 1973a)maxchords_maxMaximum of max chords (max chord   = max of all chords for one particle rotation).custom(Pahl et al. 1973a)maxchords_minMinimum of max chords.custom(Pahl et al. 1973a)maxchords_medianMedian of max chords.custom(Pahl et al. 1973a)maxchords_meanMean of max chords.custom(Pahl et al. 1973a)maxchords_modeMode of max chords.custom(Pahl et al. 1973a)maxchords_stdStandard deviation of max   chords.custom(Pahl et al. 1973a)allchords_maxMaximum of all chords for all   rotations.custom(Pahl et al. 1973a)allchords_minMinimum of all chords for all   rotations.custom(Pahl et al. 1973a)allchords_medianMedian of all chords for all   rotations.custom(Pahl et al. 1973a)allchords_meanMean of all chords for all   rotations.custom(Pahl et al. 1973a)allchords_modeMode of all chords for all   rotations.custom(Pahl et al. 1973a)allchords_stdStandard deviation of all chords   for all rotations.custom(Pahl et al. 1973a)3D shape measurementsFor 3D recordings, there are 13 threedimensional shape measurements implemented inimea, as shown in the table below.Naming   in imeaDescriptionImplementationReferencevolumeVolume.np.sum(Pahl et al. 1973a)volume_convexhullVolume of convex hull.scipy.spatial.ConvexHull-surface_areaSurface area (determined by convex hull).scipy.spatial.ConvexHull(Pahl et al. 1973a)diameter_volume_equivalentDiameter of a volume-equivalent sphere.custom based on (StieÃŸ 2009)(StieÃŸ 2009)diameter_surfacearea_equivalentDiameter of a sphere with the same surface area.custom based on (StieÃŸ 2009)(StieÃŸ 2009)width_3d_bbWidth of minimal 3D bounding box   (equal to minimal 2D bounding box, as minimum 3D bounding box is assumed to   lay on conveyer surface).cv2.minAreaRect(Steuer 2010)length_3d_bbLength of minimal 3D bounding   box (width_3d_bb <= length_3d_bb, ).cv2.minAreaRect(Steuer 2010)height_3d_bbHeight of minimal 3D bounding   box in z-direction.np.max(Steuer 2010)feret_3d_maxMaximum 3D feret diameter.custom based onscipy.spatial.ConvexHull(Pahl et al. 1973a)feret_3d_minMinimum 3D feret diameter.custom based onscipy.spatial.ConvexHull(Pahl et al. 1973a)x_max_3dMaximum particle dimension   (equal toferet_3d_max)custom(Steuer 2010)y_max_3dMean particle dimension   (y_max_3d >= x_max_3d,y_max_3dorthogonal tox_max_3d)custom(Steuer 2010)z_max_3dM particle dimension   (z_max_3d <= y_max_3d,z_max_3dorthogonal toy_max_3dandx_max_3d)custom(Steuer 2010)ConventionsCoordinate systemimeauses right hand cardesian coordinate system, which is also used inscikit-image(o: origin of coordinate system):# (row, col, channel)##      o ----------> y#     /|#    / |#   /  |# z    |#      v#      xLiteratureT. 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.001Deutsches 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.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.003Y. 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.043X. 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 instruments91(3), pp. 035103. DOI:https://doi.org/10.1063/5.0002233W. 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-00aT. 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.1617159W. 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-5M. Steuer (2010). "Serial classification". In:AT Mineral Processing51(1).M. StieÃŸ (2009).Mechanische Verfahrenstechnik - Partikeltechnologie 1. 3rd edition. Springer-Verlag: Berlin, Heidelberg.http://doi.org/10.1007/978/3-540-32552-9G.-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.022S. Walt, J. SchÃ¶nberger, J. Nunez-Iglesias, F. Boulogne, J. Warner, N. Yager, E. Gouillart, T. Yu and the scikit-image contributors (2014). "scikit-image: Image processing in Python". In:PeerJ2:e453https://doi.org/10.7717/peerj.453T. 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