Welcome to the Rgrains usage guide!

Particle shape is essential information for understanding particle characteristics. It is used in various fields, including powder engineering and sedimentology. Because particle shape and size are strongly related to particle behaviour and history, they are treated as important information in sedimentology.

There have been many attempts to quantitatively describe particle shape. One particularly well-known parameter is "roundness", as defined by Wadell (1932). Roundness is calculated as the ratio of the average radius of small circles fitted to the convex parts of a particle contour to the radius of the largest inscribed circle. It ranges from 0 to 1. Because roundness is based on the average of small circles, it is a relatively robust parameter. It focuses on convex parts of the particle contour and is therefore more sensitive to local shape changes than indices calculated from the entire particle shape, such as circularity. Thus, roundness provides valuable information for identifying sediment particles and interpreting sedimentary processes.

However, measuring the roundness of natural particles with complex shapes is difficult and time-consuming. Before the widespread use of digital cameras and computers, semi-quantitative measurements were commonly performed using the comparison chart proposed by Krumbein (1941). This chart introduced a degree of objectivity to the previously subjective evaluation of particle shape, enabling comparative analysis and significantly expanding the scope of research. Although this approach played an important role at the time, it was not fully objective and did not represent the continuous nature of roundness.

With recent advances in digital technologies, such as cameras and computers, it has become possible to measure various shape parameters, including the theoretical roundness defined by Wadell, more objectively and rapidly. For example, Zheng & Hryciw (2015) calculated roundness by fitting small circles to particle contours extracted from images. In addition, Fukuda & Naruse (2020) quantified particle shapes by applying elliptic Fourier analysis to particle contours in images. Thus, advances in digital technology have enabled particle shape analysis with unprecedented precision and speed.

Rgrains is image analysis software equipped with a series of functions for extracting contours from images, measuring particle shapes, and exporting results as images or tables. Rgrains can calculate particle area, circularity, major and minor axis lengths, aspect ratio, and other shape parameters. Furthermore, based on the innovative techniques of Zheng & Hryciw (2015), Rgrains can also calculate roundness according to Wadell's definition. In this sense, Rgrains can be considered wrapper software for the program developed by Zheng & Hryciw (2015). Ishimura & Yamada (2019) used Rgrains to analyse the shapes of gravel particles in tsunami deposits and estimated the magnitude of past tsunamis based on the relationship between topography and particle shape. In this way, Rgrains provides researchers with a detailed understanding of particle dynamics and supports deeper exploration of particle behaviour. We hope that Rgrains will broaden the scope of scientific inquiry, open new avenues for research, and contribute to a deeper and more comprehensive understanding of particle shape analysis.

Rgrains can measure and calculate particle shapes in images. Binarised images are used for measurement, and the images must adequately represent particle contours. Images suitable for binarisation have sufficient resolution, homogeneous brightness, a large depth of field, and high contrast between particles and the background. Specifically, the major axis length of each particle should be at least 200 px. To obtain homogeneous brightness and high-contrast particle silhouettes, backlight panels, such as tracing stands, are suitable. However, any method is acceptable as long as the final result is a binarised image with well-reproduced particle contours. After image acquisition, images are binarised using MATLAB's built-in imbinarize function. Please apply an appropriate binarisation method for each image. See the linked documentation for details.

After binarisation, Rgrains crops each particle and its surrounding area. If the PCD_normalisation option is enabled, Rgrains calculates the particle's circumscribed circle and resizes the image so that the circumscribed circle has the specified diameter. The cropped binarised image is then used to measure area, major axis length, minor axis length, aspect ratio, and circularity using MATLAB's built-in regionprops function. See the linked documentation for details.

Circularity can be calculated using the method specified by the circularity_type option. If circularity_type is set to "legacy", circularity is calculated as 4*pi*Area/Perimeter.^2. This is equivalent to the circularity calculation used in MATLAB R2022b and earlier. If circularity_type is set to "new", circularity is calculated using regionprops.

Roundness is a useful parameter for describing grain shape. Its definition is extremely simple:

$$Roundness = \left({1 \over n} \sum_{k=1}^n r_k \right)/R_{max}$$

where $R_{max}$ is the radius of the maximum inscribed circle, $n$ is the number of corners along the particle contour, and $r_k$ is the radius of the $k$-th corner curvature.

Red: maximum inscribed circle

Orange: corner convex curve

Green: small circles fitted to the corner convex curve

Rgrains calculates roundness using a modified version of the program developed by Zheng & Hryciw (2015). See the linked resources for details. Briefly, the main procedure consists of three steps:

1. Detecting contours
   The program uses the particle's centre of gravity to convert the contour into polar coordinates. The coordinate-transformed contour is discrete because it is based on image pixels. Therefore, the program uses MATLAB's built-in smooth function with the loess method to smooth the discrete contour. In this process, Rgrains uses a parameter called trace_precision (α) to adjust the fitting. The figure below shows variations in α and the corresponding edge-tracing results (α = 0.3: underfitted; α = 0.06: well fitted; α = 0.01: overfitted). Reducing α allows the contour to be reproduced more accurately. However, overly precise contours may also reflect particle surface texture, which can adversely affect the fitting of small circles. It is important to select an appropriate parameter value that reflects particle shape at the target scale.

2. Detecting convex curves
   The program extracts only convex curves from the smoothed contour using a parameter called corner_sensitivity in Rgrains. This parameter represents the maximum allowable distance between the arc of the curve and its corresponding chord. It determines the number of straight-line segments required to approximate the curve with sufficient accuracy. The figure below shows the relationship between corner sensitivity and the results of small-circle detection. Reducing the value of corner sensitivity allows corners with lower curvature to be detected. It is necessary to choose the optimal value of corner sensitivity according to the scale of observation.

3. Fitting small circles
   The best-fit circle for each particle corner is determined by minimising the sum of squared distances from the contour points to the circle. The suitability of the circle is then assessed by comparing its radius with the minimum distance from the circle centre to the particle boundary, using a threshold value called circle_precision in Rgrains. The figure below shows the relationship between circle precision and small-circle fitting. Increasing the value of circle precision allows small circles to be fitted more accurately to the contour. However, overly precise circle fitting often leads to underestimation when detecting optimal small circles. Conversely, too small a value of circle precision leads to inaccurate small-circle fitting. It is therefore important to choose an appropriate value for circle precision.

• MATLAB > 9.13
• Image Processing Toolbox > 11.6
• Curve Fitting Toolbox > 3.8
• Statistics and Machine Learning Toolbox > 12.4 (not required from Rgrains v5.0.3)
• Computer Vision Toolbox > 10.3 (not required from Rgrains v5.0.3)

• Windows 10 or 11 (Intel)
• MATLAB Runtime (MATLAB Runtime is free. Rgrains includes the online installer.)

Rgrains is available in three formats: a MATLAB toolbox version for command-line and script-based use, a MATLAB app version, and a standalone GUI application.

1. Download all files in this repository.
2. After unzipping the files, add the downloaded repository to the MATLAB path.

1. Download Rgrains_vx.x.x_for_matlab.zip from Releases.
2. Start MATLAB and install the downloaded file from the "Apps" tab.

1. Download Rgrains_vx.x.x_for_windows.zip from Releases.
2. After unzipping the file, run Rgrains_vx.x.x_for_windows.exe and follow the setup wizard.

Rgrains is available in three formats: a MATLAB toolbox version, a MATLAB app version, and a standalone GUI application. Rgrains is implemented using object-oriented programming. All versions depend on the encapsulated core process, rcalculator. The usage of each version is described below.

Rgrains is implemented using object-oriented programming. A simple example is shown in Simple_example.m. The following subsections explain this example.

First, create an Rgrains instance because Rgrains is encapsulated as an object. Creating an instance in MATLAB is simple:

% Make instance
rg = rgrains();

Next, load the target image to be analysed. To load an image into Rgrains, use the loadImage method and specify the path to the image. The image formats supported by Rgrains depend on MATLAB's imread function. See the linked documentation for supported formats. If necessary, use uigetfile to obtain the image path. The loaded image is stored in the im_in property.

% Get image path
[im_name, im_dir] = uigetfile();

% Load image
rg.loadImage(fullfile(im_dir, im_name));

% Show loaded image
figure
imshow(rg.im_in)
title('Input image')

Rgrains requires binarisation to measure particle shape. Binarisation is based on imbinarize. By default, binarisation is performed adaptively by imbinarize; however, depending on image contrast, particle edges may not be reproduced accurately. You should always check the binarised image and select the best settings for each image. Binarisation can be controlled using opts_binarise. The binarised image is stored in the im_bw property.

% Set binarisation options
rg.opts_binarise.upconvert                   = true;
rg.opts_binarise.particle_color              = 'Dark';
rg.opts_binarise.method                      = 'Otsu';
rg.opts_binarise.adaptive_sensitivity        = 0.35;
rg.opts_binarise.noise_thresholds            = [490 Inf];
rg.opts_binarise.ignore_particles_on_borders = true;

% Apply binarisation
rg.binariseImage();

% Show binarisation results
figure
subplot(1,2,1)
    imshow(rg.im_in)
    title('Input image')
subplot(1,2,2)
    imshow(rg.im_bw)
    title('Binarised image')

The supported options are as follows.

• upconvert ["true", "false" (default: "true")] (heavy option)
  To reduce the effects of image jaggies, Rgrains enlarges the image by a factor of 2 and interpolates it using imresize. This process is not always necessary.

• particle_color ["Dark", "Bright" (default: "Dark")]
  Specifies the relative brightness of particles in the image to distinguish particles from the background.

• method ["Adaptive", "Otsu", "Absolute", "Edge", "None" (default: "Adaptive")]
  "Adaptive": This method divides the image into local regions and performs binarisation using the optimal threshold for each region. It is suitable when brightness is uneven across the image. See imbinarize for more information.
  "Otsu": This method creates a histogram of image intensities and binarises the image using the overall optimal threshold. It is suitable when particles occupy a relatively large area in the image. See imbinarize for more information.
  "Absolute": This method performs binarisation based on a specified threshold. The threshold is specified from 0 to 1.
  "Edge": This is an original binarisation method. It may be suitable for semitransparent particles. It detects edges using the Canny method and extracts particle shapes using morphological processing of the detected edges. It is also combined with the Otsu method to improve the reproducibility of fine contour details. However, fine structures are likely to be lost. The sensitivity corresponds to the Canny edge-detection sensitivity. The lower limit is 0.03, and the upper limit can be specified; the default value is 0.05.
  "None": This method does nothing. It can be used when the input image has already been binarised. However, even if an image appears binarised, RGB information may remain, so please check the image properties before using this option.

• adaptive_sensitivity [0–1 (default: 0.35)]
  Specifies the binarisation threshold. If method is "Adaptive", this value is used as sensitivity. If method is "Absolute", it is used as the threshold. If method is "Edge", it is used as the upper sensitivity limit for edge detection. See imbinarize for more information.

• noise_thresholds [0–Inf (default: [490 Inf])] ($pix^2$)
  Specifies the lower and upper area limits ($pix^2$) of particles to be detected. For example, if [490 Inf] is specified, particles smaller than or equal to $490 pix^2$ are ignored.

• ignore_particles_on_borders ["true", "false" (default: "true")]
  Specifies whether to exclude particles located at the image boundaries, where the overall particle shape cannot be extracted. In general, "true" is recommended.

Roundness is calculated from the binarised image. See "Methods of measurement and calculation" for details and references. In particular, trace_precision, corner_sensitivity, and circle_precision are critical parameters for calculating particle roundness. Therefore, these parameters should be carefully determined using support tools such as RoundnessForAI.

% Calculate roundness
rg.opts_roundness.calc_roundness            = true;
rg.opts_roundness.trace_precision           = 0.0600;
rg.opts_roundness.corner_sensitivity        = 0.0170;
rg.opts_roundness.circle_precision          = 0.9960;
rg.opts_roundness.image_scale               = 340;
rg.opts_roundness.PCD_normalisation         = true;
rg.opts_roundness.PCD_size                  = 200;
rg.opts_roundness.filter_inaccurate_outline = false;
rg.opts_roundness.circularity_type          = 'legacy';

% Calculate with progress bar
f = uifigure();
rg.calcRoundness(f);
close(f)

The supported options are as follows.

• calc_roundness ["true", "false" (default: "true")]
  Specifies whether to calculate roundness. If set to "false", Rgrains returns circularity, major axis length (cm), minor axis length (cm), aspect ratio, and area ($cm^2$). In general, this is significantly faster than calculating roundness.

• trace_precision [0–1 (default: 0.0600)]
  Parameter used to convert a discrete edge composed of pixels into a smooth function. For example, 0.06 means that smoothing is performed using a window corresponding to 6% of the entire contour. See smooth for more information.

• corner_sensitivity [0–1 (default: 0.0170)]
  Sensitivity for detecting convex corners from smoothed contours.

• circle_precision [0–1 (default: 0.9960)]
  Fitting accuracy of the small circles fitted to detected convex corners.

• image_scale [0–Inf (default: 340)] ($pix/cm$)
  Rgrains returns dimensional results, such as area ($cm^2$) and major axis length (cm), as well as dimensionless results, such as roundness and aspect ratio. To convert pixel-based measurements into actual lengths, specify how many pixels correspond to 1 cm.

• PCD_normalisation ["true", "false" (default: "true")]
  Large differences in particle size can affect calculation performance and results. To avoid this effect, the particle image size can be normalised using the particle's circumscribed circle diameter. This process can improve small-particle fitting and speed up processing for large particles. When this option is used, image_scale is automatically adjusted internally and does not need to be changed.

• PCD_size [0–Inf (default: 200)] ($pix$)
  The diameter of the circumscribed circle used for normalisation. A value of at least 200 px is recommended.

• filter_inaccurate_outline ["true", "false" (default: "false")]
  Specifies whether to exclude particles with inaccurately detected outlines from the results (beta).

• circularity_type ["legacy", "new" (default: "legacy")]
  The method used to calculate circularity. Select "legacy" to use the previous calculation method or "new" to use the updated method.

The calculated results are stored in the rprops property, but direct access to this property is not required to view or export the results. To obtain general results, use the makeResultImage, makeResultTable, and makeSummaryImage methods.

makeResultImage()
Draws extracted edges and fitted circles on the image.

% Show results
rg.opts_plot.base_image                              = 'original';
rg.opts_plot.colour_smoothed_particle_boundaries     = 'magenta';
rg.opts_plot.thickness_smoothed_particle_boundaries  = 1.5;
rg.opts_plot.colour_max_inscribed_circle             = 'red';
rg.opts_plot.thickness_max_inscribed_circle          = 1.5;
rg.opts_plot.colour_corner_circles                   = 'cyan';
rg.opts_plot.thickness_corner_circles                = 0.5;
rg.opts_plot.colour_info_text                        = 'yellow';
rg.opts_plot.font_size_info_text                     = 15;
rg.opts_plot.font                                    = 'Arial';
rg.opts_plot.plot_info                               = 'Particlenumber';

figure
rg.makeResultImage(gca);

The supported options are as follows.

• base_image ["original", "bw" (default: "original")]
  Base image on which results are drawn.

• colour_smoothed_particle_boundaries [(default: "magenta")]
  Colour of smoothed particle boundaries. Supported options are listed here: plot colours.

• thickness_smoothed_particle_boundaries [(default: 1.5)]
  Line thickness of particle boundaries.

• colour_max_inscribed_circle [(default: "red")]
  Colour of the maximum inscribed circle.

• thickness_max_inscribed_circle [(default: 1.5)]
  Line thickness of the maximum inscribed circle.

• colour_corner_circles [(default: "cyan")]
  Colour of corner small circles.

• thickness_corner_circles [(default: 0.5)]
  Line thickness of corner circles.

• plot_info ["Particlenumber", "Roundness" (default: "Particlenumber")]
  Information drawn on the image.

• colour_info_text [(default: "yellow")]
  Colour of information text.

• font [(default: "Arial")]
  Font of information text. Available fonts depend on the user's system. You can check the available fonts using listfonts.

• font_size_info_text [(default: 15)]
  Font size of information text.

makeResultTable()
Creates a table of results.

% Make results table
results_table = rg.makeResultTable();

makeSummaryImage()
Draws statistical information from the results, such as histograms.

% Make summary
SS = get(0, 'ScreenSize');

figure('visible','on','Position',[SS(1) SS(2) SS(3) SS(4)]);
rg.makeSummaryImage(gca)

Writes the calculation results to files. The supported options are as follows.

% Set export settings
rg.opts_export.save_bw_image                    = true;
rg.opts_export.save_fitted_image_with_No        = true;
rg.opts_export.save_fitted_image_with_Roundness = true;
rg.opts_export.save_fitted_image_vector         = true;
rg.opts_export.save_summary_image               = true;
rg.opts_export.save_csv                         = true;
rg.opts_export.save_each_circles_csv            = true;
rg.opts_export.save_annotation                  = true;
rg.opts_export.save_edge_annotation             = true;
rg.opts_export.annotation_target                = 'Roundness';
rg.opts_export.save_settings                    = true;

% Export results
save_dir = uigetdir();
rg.export(save_dir)

• save_bw_image ["true", "false" (default: "true")]
  Saves the binarised image as a JPEG file.

• save_fitted_image_with_No ["true", "false" (default: "true")]
  Saves the fitted image with particle numbers as a JPEG file.

• save_fitted_image_with_Roundness ["true", "false" (default: "true")]
  Saves the fitted image with roundness values as a JPEG file.

• save_fitted_image_vector ["true", "false" (default: "true")]
  Saves the fitted image in editable EPS format.

• save_summary_image ["true", "false" (default: "true")]
  Saves the statistical summary image as a PNG file.

• save_csv ["true", "false" (default: "true")]
  Saves the results table as a CSV file.

• save_each_circles_csv ["true", "false" (default: "true")]
  Saves information on the small circles fitted to each particle as a CSV file.

• save_annotation ["true", "false" (default: "true")]
  Saves the measurement and calculation results as annotation files.

• save_edge_annotation ["true", "false" (default: "true")]
  Saves particle-edge annotations.

• annotation_target ["Roundness", "Circularity", "Major axis", "Minor axis" (default: "Roundness")]
  Specifies the target parameter exported as annotations.

• save_settings ["true", "false" (default: "true")]
  Saves the calculation settings as a CSV file. The L*a*b* output is based on the RGB values of the image. To obtain correct L*a*b* values, the entire image must have uniform brightness, and the colours must be calibrated in advance.

Note that the GUI version implements only a subset of the available options. For more advanced operations, please use the MATLAB toolbox version.

All Rgrains settings can be saved from [File > Save settings]. The settings file is saved with the extension .rgrains. The file is internally a MATLAB MAT-file. During batch processing, the settings file is automatically saved after processing. A saved settings file (.rgrains) can be loaded from [File > Load settings] to restore previous settings.

Even when batch-processing multiple images, it is important to first process a single image and determine the optimal analysis parameters. Images can be loaded using the load button at the top of the window. Pressing the load button opens the file chooser, which allows you to select an image with the specified extension (e.g. JPG). The specified extension can be changed from [Settings > Acquisition > Image type].

Rgrains requires binarisation to measure particle shape. This is the most important process for accurately extracting particle contours. You must confirm that particle edges are detected sufficiently and that unnecessary objects, such as dust, are not detected. Press the Binarise button to start binarisation. Binarisation is based on imbinarize. By default, binarisation is performed adaptively using the "Adaptive" setting; however, depending on image contrast, particle edges may not be reproduced accurately. You should always check the binarised image and select the best settings for each image. Binarisation can be controlled using the options below.

The supported options are as follows.

• Particle color ["Dark", "Bright" (default: "Dark")]
  Specifies the relative brightness of particles in the image to distinguish particles from the background.

• Method ["Adaptive", "Otsu", "Absolute", "Edge", "None" (default: "Adaptive")]
  "Adaptive": This method divides the image into local regions and performs binarisation using the optimal threshold for each region. It is suitable when brightness is uneven across the image. See imbinarize for more information.
  "Otsu": This method creates a histogram of image intensities and binarises the image using the overall optimal threshold. It is suitable when particles occupy a relatively large area in the image. See imbinarize for more information.
  "Absolute": This method performs binarisation based on a specified threshold. The threshold is specified from 0 to 1.
  "Edge": This is an original binarisation method. It may be suitable for semitransparent particles. It detects edges using the Canny method and extracts particle shapes using morphological processing of the detected edges. It is also combined with the Otsu method to improve the reproducibility of fine contour details. However, fine structures are likely to be lost. The sensitivity corresponds to the Canny edge-detection sensitivity. The lower limit is 0.03, and the upper limit can be specified; the default value is 0.05.
  "None": This method does nothing. It can be used when the input image has already been binarised. However, even if an image appears binarised, RGB information may remain, so please check the image properties before using this option.

• Sensitivity [0–1 (default: 0.35)]
  Specifies the binarisation threshold. If "Adaptive" is selected, this value is used as sensitivity. If "Absolute" is selected, it is used as the threshold. If "Edge" is selected, it is used as the upper sensitivity limit for edge detection. See imbinarize for more information.

• Noise thresholds [0–Inf (default: [490 Inf])] ($pix^2$)
  Specifies the lower and upper area limits ($pix^2$) of particles to be detected. For example, if [490 Inf] is specified, particles smaller than or equal to $490 pix^2$ are ignored. This is useful for removing small dust particles.

• Image scale [0–Inf (default: 340)] ($pix/cm$)
  Rgrains returns measurement results, such as diameter and area, in actual length units. Therefore, it is necessary to accurately specify how many pixels correspond to 1 cm in the image. For example, take a photograph of a ruler and measure the scale using image-editing software.

• Settings > Binarisation > Upconvert ["true", "false" (default: "false")] (heavy option)
  Images are composed of pixels, and if the resolution is insufficient, image jaggies may affect the result. This option enlarges the image by a factor of 2 using interpolation to reduce this effect. Because this process is computationally heavy, use it only when necessary. When this option is used, Image scale is automatically adjusted internally and does not need to be changed. See imresize for more information.

• Settings > Binarisation > Ignore particles on borders ["true", "false" (default: "true")]
  Specifies whether to exclude particles located at image boundaries, where the overall particle shape cannot be captured. Because such particles cannot be analysed accurately, "true" is generally recommended.

Roundness is calculated from the binarised image. Press the Analysis button to calculate roundness and other parameters. See "Methods of measurement and calculation" for details and references. In particular, trace_precision, corner_sensitivity, and circle_precision are critical parameters for calculating particle roundness. Therefore, these parameters should be carefully determined using support tools such as RoundnessForAI.

The supported options are as follows.

• Trace precision [0–1 (default: 0.0600)]
  Parameter used to convert a discrete edge composed of pixels into a smooth function. For example, 0.06 means that smoothing is performed using a window corresponding to 6% of the entire contour. See smooth for more information.

• Corner sensitivity [0–1 (default: 0.0170)]
  Sensitivity for detecting convex corners from smoothed contours.

• Circle precision [0–1 (default: 0.9960)]
  Fitting accuracy of the small circles fitted to detected convex corners.

• Settings > Analysis > Apply PCD normalisation ["true", "false" (default: "true")]
  Large differences in particle size can affect calculation performance and results. To avoid this effect, the particle image size can be normalised using the particle's circumscribed circle diameter. This process can improve small-particle fitting and speed up processing for large particles. When this option is used, Image scale is automatically adjusted internally and does not need to be changed.

• PCD size [0–Inf (default: 200)] ($pix$)
  The diameter of the circumscribed circle used for normalisation. A value of at least 200 px is recommended.

After roundness calculation, Rgrains automatically plots the results on the right side of the window. Plot options, such as line colours, are available in [Settings > Plot]. Press the Replot button to redraw the result figure according to your settings.

The supported options are as follows.

• Settings > Plot > Base image ["original", "bw" (default: "original")]
  Base image on which results are plotted. "bw" refers to the binarised image.

• Settings > Plot > Particle boundaries colour [(default: "magenta")]
  Colour of plotted particle boundaries.

• Settings > Plot > Maximum inscribed circle colour [(default: "red")]
  Colour of the plotted maximum inscribed circle.

• Settings > Plot > Corner small circles colour [(default: "cyan")]
  Colour of plotted corner small circles.

• Settings > Plot > Text colour [(default: "yellow")]
  Colour of plotted text.

• Settings > Plot > Plot font [(default: "Arial")]
  Font of plotted text. Available options depend on the user's system.

To write the calculation results to files, press the Export button. The types of exported data can be specified from [Settings > Export].

The supported options are as follows.

• Settings > Export > Save BW image ["true", "false" (default: "true")]
  Saves the binarised image as a JPEG file.

• Settings > Export > Save fitted image with Number ["true", "false" (default: "true")]
  Saves the fitted image with particle numbers as a JPEG file.

• Settings > Export > Save fitted image with Roundness ["true", "false" (default: "true")]
  Saves the fitted image with roundness values as a JPEG file.

• Settings > Export > Save fitted image as vector ["true", "false" (default: "false")]
  Saves the fitted image, including contours, maximum inscribed circles, and small circles used for roundness calculation, in editable EPS format for software such as Adobe Illustrator.

• Settings > Export > Save summary image ["true", "false" (default: "true")]
  Saves the measurement and calculation results as histograms.

• Settings > Export > Save csv ["true", "false" (default: "true")]
  Saves the measurement and calculation results as table data. The mean L*a*b* values of particles calculated from the image can also be output. To obtain correct values, the entire image must have uniform brightness, and the colours must be calibrated in advance.

• Settings > Export > Save settings ["true", "false" (default: "false")]
  Saves all parameter settings used for measurement and calculation for each image. If you only want to output a settings file for each batch during batch processing, leave this option set to "false".

• Settings > Export > Save annotation [___] ["Roundness", "Circularity", "Major axis", "Minor axis" (default: "Roundness")]
  Exports measurement and calculation results in VOC format (.xml) for use in deep learning.

Click [Batch > Run from folder] to start batch processing. During this process, specify the Source Folder containing the images and the Save Folder for saving the results. Rgrains then processes all images with the specified extension in the source folder using the predefined settings.

An example citation is shown below.

• Rgrains, or the full workflow including binarisation and export

  • Yamada, K. (2023). Rgrains [Computer software]. https://github.com/keitaroyamada/Rgrains.
  • We used Rgrains (Version 5.0.0) to calculate roundness.

• Core method for roundness calculation from binarised images

  • Zheng, J., & Hryciw, R. D. (2015). Traditional soil particle sphericity, roundness and surface roughness by computational geometry. Géotechnique, 65(6), 494–506. https://www.icevirtuallibrary.com/doi/abs/10.1680/geot.14.P.192

• Wadell (1932) Volume, Shape, and Roundness of Rock Particles
• Krumbein (1941) Measurement and geological significance of shape and roundness of sedimentary particles
• Zheng & Hryciw (2015) Traditional soil particle sphericity, roundness and surface roughness by computational geometry
  • Source code
• Ishimura & Yamada (2019) Palaeo-tsunami inundation distances deduced from roundness of gravel particles in tsunami deposits
• Fukuda & Naruse (2020) Shape difference of mud clasts depending on depositional facies: application of newly modified elliptic Fourier analysis to hybrid event beds