It is recommended that new users refer to the Get started section of the documentation where the structure and key principles of operation of the software are explained.
The main program window is used to manage your projects. It contains summary information about the current project, details of the images it contains, and the progress made towards obtaining a grain-size report for each. The main program window also contains the menus that are used to initiate each of the steps towards obtaining a grain-size report and to access the documentation (help) files.
The Project information panel
The panel in the top-left part of the window contains information about the current project, including the project name, details of the project owner and client, and when the project was created and last saved.
The Image information panel
The bottom part of the window contains a list of the images in the project and is used to select those images to which different operations should be applied. By default, all of the images contained within the project are listed. Subsets of the images, based on the processing stage reached, may be shown by changing the options in the Options panel.
Individual images may be selected by clicking on their entry in the list. A continuous group of images in the list may be selected by clicking the first entry in the group then holding the [Shift] key whilst clicking the last entry. Multiple images may also be selected by holding the [Ctrl] key whilst clicking on each entry to be included. Some of the options in the Reference section of this documentation., and menus operate on the currently selected images. A complete description of the menu options is contained in the
Some operations available from the Image information panel.menu are also accessible from the context menu obtained by right clicking on an entry in the
In addition to basic information about each image in the project, the panel also indicates when the grains in individual images were last measured and a grain-size report generated. If measurements or reports were made today, the time is shown, otherwise the date is listed. More information about individual images may be obtained by hovering the mouse pointer over one of the entries in the image list (unless this option has been turned off in the Options panel).
To make it easier to identify those images that are awaiting various stages of processing, subsets of the images may be listed using the radio buttons in the Options panel:
- select All to show all of the images in the project (default)
- select Awaiting measurement to show only those images in which the grains have not yet been measured
- select Awaiting report to show only those images for which a grain-size report has not yet been generated.
If the image information tooltips (displayed when the mouse pointer is held over an entry in the image list) interfere with the operation of the program, these may be turned off by clearing the Show image information on mouse hover checkbox.
Guidelines for projects
Whether you work with a few large projects containing many images, or divide your work into numerous smaller projects containing a few images, is a matter of personal preference. However, the following guidelines may be of assistance to new users:
- Consider creating a new project for each job or client
- Consider dividing the work so that images collected with different models of camera, at different pixel resolutions, or at different scales are stored in separate projects.
Opening an existing project
To open an existing project, select Image information panel.and select the project file that you wish to open. If a project is already open and it has been modified since it was last saved, you will be asked if you wish to save it before continuing. The project information panel will be updated and the images in the project (if any) will be listed in the
If the project you wish to work on has been used recently it may be listed on themenu.
Creating a new project
To create a new project, select Edit project properties dialogue will open to enable the entry of various items of information about the project. Once these are completed to your satisfaction, select to continue. The Save project as dialogue will open. Navigate to where you wish to save the new project file, enter the filename and select . The new project file will then be saved and the Project information panel updated.. If a project is already open and it has been modified since it was last saved, you will be asked if you wish to save it before continuing. Once any existing project has been saved, the
Modify the project properties
The Edit project properties dialogue is shown when a new project is created and may also be accessed by selecting . All of the items are optional, but it is recommended that at the very least a protect title should be provided. All of the items entered will be included in any grain-size reports generated by the software. The individual responsible for the project (the ‘project manager’), department and company may be entered if desired, as may the client. Notes may be added. Click to update the project information and return to the main program window.
Other project management options
The project may be saved with the existing or a different file name and closed by selecting the appropriate options on the Reference (lens correction) section in this documentation for full details.menu. Files containing parameters for the correction of radial lens distortion in images may be created and edited by selecting . See the
To avoid the project file becoming unmanageably large, when images are added to a project a reference to the location of the image is included in the project file (rather than a copy of the image itself). Once an image has been added to a project, moving the image itself should be avoided as this will result in the software being unable to find it.
Adding images to a project
To add an image to the the current project select. Navigate to the image location and click . If the image is not located in the same folder as the project file you will be asked if you wish to make a copy of the image in this folder. If you click , and a file of the same name already exists in the folder, a warning will be shown and the filename will be prefixed with 'new_'.
The Control-point identification dialogue will then open showing the top-left corner of the image. Click to indicate the location of the first control point. If the control point is not visible on the screen, use the scroll bars or drag the small blue rectangle in the thumbnail to move around the image. Once the first control point has been identified, the status area on the right of the dialogue is updated and the program automatically moves to the top-right corner of the image. Click to indicate the location of the second control point, and repeat for the third and fourth points. When the final point has been selected, the program will show the whole image with the controlled area outlined in red. Click to proceed or to select the control points again.
The Edit image properties dialogue will open to allow entry of various items of essential and optional information about the image. The Site name (essential) should be used to identify the location at which the image was collected. Depending on the scale of the project, this may be an individual bar or a particular river. The Sample ID (essential) should be used to uniquely identify the grain-size sample represented by the image. The Width and Height of the controlled area (both essential) specify the dimensions of the controlled area contained within the four control points. This information enables the software to determine the size of individual grains and correct for perspective distortion associated with the camera axis not being perfectly perpendicular to the ground during image collection. Once all of the information has been added, click to update the project and return to the main program window.
Removing images from a project
To remove an image or images from the project, select the appropriate entries in the Image information panel then select . Click to confirm removal. Images may also be removed by right clicking the appropriate entry in the Image information panel and selecting from the context menu.
Note that removing an image from a project does not delete the image file from your hard disk.
Modifying the properties of an image
The Edit image properties dialogue is shown when an image is added to the project and may also be accessed by selecting the appropriate image in the Image information panel then selecting (or selecting from the right-click context menu). The Site name, Sample ID, and the Width and Height of the controlled area are all mandatory. Most of the data in the Image information panel is obtained from the header information contained within the image file and is not editable. The name of the photographer may be entered if desired and the date and time on which the photograph was taken may be modified by clicking . This option is provided in case the date and time stored on the camera were incorrect. Optionally, notes about the image may be added. All of the items entered will be included in any grain-size reports generated by the software. Click to update the image properties and return to the main program window.
Updating the location of images
If images are moved outside of Digital Gravelometer, the software will not be able to find them. The correct location may be updated using themenu.
Viewing information about an image
Basic information about the images in the current project is contained in the Image information panel. Some additional information is displayed as a tooltip when the mouse pointer is hovered over one of the entries in the list (unless this option has been disabled in the Options panel).
To view detailed information about an image, select its entry in the Image information panel and then select to open the Image data dialogue (or select from the right-click context menu). From here, you can view the image itself by clicking .
Themenu is used to initiate the measurement of the grains in all or some of the images in the current project.
Opening the Measure grains dialogue
The Measure grains dialogue box:menu has three options, all of which open the
- Measure grains dialogue box to measure the grains in all of the images contained within the current project. opens the
- Image Information panel. operates on only those images that are currently selected in the
- operates only on those images that have not yet been measured.
Customizing the measurement options
The Measure grains dialogue enables the user to customize the parameters used to identify the grains and the output that is shown on screen and saved to file during the measurement process.
Clicking Output options panel opens the Output options dialogue box. The checkboxes enable the user to specify which of the intermediate stages in the measurement process are displayed on the screen and saved as image files. Each of the panels represents the results of one stage of the grain identification and measurement procedure. It is recommended that the user reviews the results of these procedures in case of the unlikely event that the software fails to adequately identify the grains. By default, appropriate images are displayed on the screen to enable this assessment to be made. Images representing other intermediate stages may be viewed by checking the appropriate boxes. It is possible to save any of the intermediate stages to disk as an image file by checking the appropriate box. In this event, an image filename and type may be specified. Images are always saved in the same folder as the project file.in the
The stages for which output may be viewed are:
- Grayscale image - this is the original image after conversion to grayscale.
- Rectified image - the grayscale image after the correction of radial lens distortion (if this option is specified in the Processing options dialogue) and the perspective effect resulting from the camera not being help perfectly vertically above the centre of the sample patch.
- Initial segmentation - a binary (black and white) image showing the identified grains after the initial segmentation procedure.
- Watershed segmentation - a binary image showing the identified grains after they have been tidied by the application of the watershed segmentation procedure.
- Boundary rules applied (final image) - a binary image showing only those grains that fall within the sampling area. These are the grains that will be measured to generate a grain-size distribution.
- Rectified image with grain-boundary overlay - the rectified grayscale image with an overlay showing the locations of the identified grains.
Further information about the stages in the grain identification and measurement procedure are contained in the Technical information (measure grains) section of this documentation.
Clicking Processing options panel opens the Processing options dialogue box.in the
The user may wish to specify a file containing parameters for the correction of radial lens distortion. Digital Gravelometer lens correction (*.dgl) files may be generated by selectingfrom the main program window. However, the correction of radial lens distortion is likely to result in only a small improvement in the derived grain-size distribution
It is strongly recommended that the other default processing options are not modified as the parameters have been defined to achieve optimal results after extensive testing on images collected at a range of different field sites.
A complete description of the options is contained in the Reference (processing options) section of this documentation and information about the significance of the different parameters is contained in the Technical information (measurement procedure) section.
Measuring the grains
Once the required output and processing options have been defined, grain measurement is initiated by clicking Measure grains dialogue. A progress box will be displayed indicating the stage reached in processing each of the selected images. Once the processing of each image is completed, the selected output images will be displayed on the screen and saved to file. Once the processing of all images is completed the Measure grains dialogue is closed and the Image information panel updated to indicate the time at which the measurements were made.in the
A report on the results of the grain-size measurement (along with general information about the project and the images it contains) are available from themenu. From here you can produce a report, viewable using the default web browser, and export the report to a file to facilitate analysis using other software packages.
Opening the Report options dialogue
Themenu has two options which specify which images to generate a report on:
- Report options dialogue to produce a grain-size report on those images that are currently selected in the Image information panel. opens the
- operates on all of the images in the project for which grain-size information is currently available.
Both options have two sub options which specify the type of report to be generated:
- generates a grain-size report with separate sections for each of the selected images. Choose this option if each image represents a separate sample for which grain-size information is required.
- generates a single grain-size report by aggregating the information for all of the selected images. Choose this option if all of the selected images together represent a single sample for which grain-size information is required. This option might be used, for example, where several photographs are collected of different parts of the same bar and a single grain-size distribution is required to characterise the entire surface.
Customizing the report contents
The Report options dialogue box enables the user to customise the contents of the grain-size information report.
To save the user having to modify the options every time a report is produced, Digital Gravelometer uses templates to control the report contents. The default report options are controlled by the default template file (default.dgt), if it exists. To load an alternative template, click and select the template file that you wish to use. The contents of the Analysis report options dialogue will be updated to reflect the contents of the template. To save the current report settings to a template file, click and enter an appropriate filename. If the template is saved as default.dgt, these options will be loaded automatically next time the dialogue is opened.
If Export analysis is checked the contents of the report will be exported to the specified comma-separated variable (*.csv) file when is clicked. The content of the exported report is controlled by the other settings in the dialogue box. CSV is a widely supported standard for data files and can be imported by many spreadsheet and statistical packages or by a text editor or word processor (see the File types section of the documentation for further information). CSV files cannot contain graphics of any kind, so the grain-size distribution plot will not be included. However, the plot will be exported to the specified graphics file if Export distribution plot is checked.
The Calculation options panel contains various options that control how the grain-size distribution is calculated and presented. To help the user set appropriate parameters, the Cumulative plot overview panel contains a small representation of the cumulative grain-size distribution curves for the images selected (or the aggregated curve as appropriate). This plot is automatically updated to reflect changes made to the calculation options.
The Use percent: finer than/coarser than radio buttons control whether the grain-size percentiles (and cumulative grain-size plot) are presented based on the cumulative percent finer or coarser than a particular percentile of the grain-size distribution. Note that this option does not affect the derived graphical statistics that, for consistency with the original literature (e.g. Folk and Ward, 1957), are always calculated on a percent coarser-than basis.
The Basis of distribution calculation radio buttons control whether the grain-size distribution is presented to be compatible with data collected on an area-by-number basis (e.g. a paint-and-pick sample) or a grid-by-number basis (e.g. a Wolman sample). Selection of the appropriate option is critical because the shape of the distribution is significantly different for the two methods. Further information about these options is contained in the Technical information (distribution calculation) in this documentation.
If Apply square-hole sieve correction is checked, the grain b-axes are adjusted to make them consistent with data derived by grading with square-hole sieves. Further information about this correction is provided in the Technical information (sieve correction) in this documentation. To apply the correction, an appropriate shape factor must be defined for the sample by clicking to open the Square-hole sieve correction dialogue. See the Reference (sieve correction) section of this documentation for further details.
The Lower and Upper truncation options permit the truncation of the size distribution at the lower (i.e. small grain) and upper (i.e. large grain) end. The truncations may be specified in mm, Phi or Psi units using the drop-down menus, or left blank if no truncation is desired. Once appropriate values have been set, click to update the truncation limits. It should be noted that the grain-size distribution is unlikely to be reliable if grains that are smaller than 23 pixels across in the image are included in the distribution. The minimum recommended lower truncation (based on the 23 pixel criteria) is specified in the Truncations panel.
The Report contents panel enables the user to define which items to include in the report. Checkboxes enable the inclusion of general project information (e.g. file name, number of images in project, client), general information about each of the selected images (e.g. file name, date, photographer), information about the parameters used for the measurement of the grains in each of the images. Checkboxes also enable the inclusion of detailed grain-size information and a plot of the grain-size distribution, the specifications of which may be modified by clicking and respectively.
Clicking Report options dialogue box opens the Report options - Grain-size information dialogue and permits the selection of the specific grain-size parameters to be included in the report. The parameters are divided into four panels, the contents of which may be turned on and off using the checkbox in the top-left corner of each. When the desired changes have been made, click to return to the Report options dialogue.in the
If the Grain-size percentiles panel is activated, either user-defined or all integer (i.e. 1, 2, 3, … 100) percentiles will be provided defined in mm, Phi or Psi units based on the checkboxes selected. If user-defined percentiles are chosen, these must be provided as a comma-separated list. Whether the output is presented on a cumulative percent finer or coarser basis is dependent on the appropriate selection in the Report options dialogue. Further information about the method by which percentiles are calculated is provided in the Technical information (distribution calculation).
The option to provide a full suite of moment and graphical grain-size statistics is available from the Distribution statistics panel. Checkboxes enable the selection of which statistics to include (mean, sorting, skewness, kurtosis), the method by which they are calculated and the units in which they are presented.
The graphical statistics calculated by Digital Gravelometer are the inclusive graphical statistics of Folk and Ward (1957). The user may choose to specify that both the moment and Folk and Ward statistics be calculated logarithmically (based on a log-normal distribution with either Phi or Psi units) or geometrically (based on a log-normal distribution with mm units). Additionally, the moment statistics may be calculated arithmetically (based on a normal distribution with mm units). This final option is rarely used, but is provided for comparison with the output of some Coulter sizing instruments (Blott and Pye, 2001).
The Data summary panel provides the opportunity to present information about the proportion of grains in individual size classes. Radio buttons enable the selection of pre-defined half or quarter Phi/Psi classes boundaries or user-defined class boundaries. User defined class boundaries may be provided in mm, Phi or Psi (depending on the selection in the drop-down menu) and should be provided as a comma-separated list. The interval between boundaries does not need to be equal.
The units in which the class boundaries should be presented in the report may be specified by checking the appropriate boxes. Checkboxes are also used to specify the information to include in the data table (count/area in class; percent in class; cumulative percent finer/coarser). Whether the data presented are for the number of grains in each class or the total area in each class depends on whether the basis of the distribution calculation is grid-by-number or area-by-number (specified in the Report options dialogue).
The class boundaries selected in the Data summary panel will also be used for the grain-size histogram (if the user chooses to include this).
Wentworth size classes
If Include Wentworth size classes is checked the report will include a table indicating the proportion of grains in each of the major Wentworth size classes.
Clicking Report options dialogue box opens the Report options - Plot dialogue and permits customisation of the appearance of the grain-size distribution histogram and cumulative curve.in the
The Size axes panel permits the units in which the grain sizes are specified to be modified, the direction of the axes to be reversed, and the top and bottom axes to be flipped.
The Data axes panel enables the user to specify whether the grain-size distribution histogram or cumulative curve (or both) are displayed. The scaling of the data axis for the histogram may be modified and the left and right axes flipped. Class boundaries for the histogram are those specified in the Report options - Grain-size information dialogue.
When the desired changes have been made, click Report options dialogue.to return to the
Viewing and using the report
When all of the desired options have been set, click Report options dialogue). The report will be generated and loaded in the default web browser on the system. The report may be printed or saved from within the web browser. If the appropriate option was selected in the Report options dialogue, a file suitable for importing into a spreadsheet or statistics package will also be saved.(in the
In addition to generating detailed reports about the grain-size distributions within images, Digital Gravelometer can export raw data about the individual grains for analysis in other software packages. Data are exported in a comma-separated variable (*.csv) file. CSV is a widely supported standard for data files and can be imported by many spreadsheet and statistical packages or by a text editor or word processor (see the File types section of the documentation for further information).
Exporting data is initiated from the menu, allowing the user to specify whether to export data for all of the measured images or only those that have been selected, and whether the data should be aggregated or presented separately for each image. All of the options open the Export data dialogue.menu. The options are identical to those on the
Clickto select the file to which the data will be exported. The various checkboxes enable the user to specify which properties to include in the file:
- b-axis (mm) - the measured minor axis of each grain. The measurement is actually the minor axis of an ellipse with the same second-moments as the grain.
- a-axis (mm) - the measured major axis of each grain. The measurement is actually the major axis of an ellipse with the same second-moments as the grain.
- Area (mm2) - the measured area of each grain. The measurement is based on counting the number of pixels in the grain.
- Equivalent diameter (mm) - the diameter of a circle with the same area as the grain.
- Orientation (degrees) - the orientation of the a-axis (as defined above) relative to horizontal line drawn across the image parallel to the edge of the sampling area. Range is -90 to +90 degrees.
- Eccentricity - the eccentricity of the ellipse that has the same second-moments as the grain. The eccentricity is the ratio of the distance between the foci of the ellipse and its major axis length. Range is 0 (a circle) to 1 (a line).
- Square-hole sieve corrected b-axis (mm) - the b-axis measurement modified to make it comparable with grains that have been sieved using square-hole sieves. See the Technical information (sieve correction) in this documentation for further information.
If Square-hole sieve corrected b-axis is checked, an appropriate shape factor must be defined for the sample by clicking to open the Square-hole sieve correction dialogue. See the Reference (sieve correction) section of this documentation for further information.
To export the file based on the options selected, click.
Information about the export file format is provided in the Technical information (export format) section of this documentation.