Sedimetrics® Digital Gravelometer™ documentation (version 1.0)

Reference

File menu

The File menu is used to manage project files and create/edit lens-correction parameters files

File > New Project…

Creates a new Digital Gravelometer project file.

Opens the Edit project properties dialogue to collect general information about the project then prompts for a filename.

File > Open Project…

Opens an existing Digital Gravelometer project file.

File > Close

Closes the current project.

If the project has changed since it as last saved you will be prompted to save it.

File > Save Project

Saves the current project file.

File > Save As…

Saves the current project to a new file.

File > Edit Project Properties…

Opens the Edit project properties dialogue to collect general information about the project.

Edit project properties dialogue

The Edit project properties dialogue collects general information about the project:

  • Project title - the title of the project defined by the user
  • Company name - the organisation responsible for the project
  • Department - the department responsible for the project
  • Project manager - the person responsible for the project
  • Client - the organisation for whom the project is being undertaken
  • Notes - any additional information about the project

Once all of the information has been added, click OK to add the information to the project and return to the main program window.

File > Lens Correction Parameters...

Opens the Define lens-correction parameters dialogue to enable the creation or editing of a lens-correction parameters file.

Define lens-correction parameters dialogue

The Define lens-correction parameters dialogue facilitates the creation and editing of a lens-correction parameters (*.dgl) file. These files contain the parameters required to correct the effects of radial distortion, the most significant distortion associated with lenses.

The correction of radial lens distortion is likely to have only a small effect on the derived grain-size distribution. However, it may be significant for some cameras with very wide-angle lenses.

Radial lens distortion varies between different cameras and with focal length. If the user chooses to apply a correction, it is necessary to create a lens-correction parameters file for each camera used. The creation of the file requires a series of photographs collected at different focal lengths under controlled conditions. Refer to the Technical information (lens correction) section of this documentation for instructions on how to obtain these images.

Once the images have been obtained, the correction parameters are calculated for each in turn:

  • Click Add image... and select the first image file to begin the process of calculating the parameters. This will open the Select calibration points dialogue with the selected image.
  • Maximise the window.
  • Starting in the centre, click on equally spaced points within the image, moving radially towards the upper-left corner. The Correction function panel will be updated as each new point is added.
  • The correction function curve should be a smooth line passing close to all of the data points. If any of the points lie far from the curve, click Clear to start again.
  • Once all of the points have been selected, click Continue to calculate the correction parameters for that particular focal length and return to the Define lens-correction parameters dialogue.
  • Repeat the procedure for each image.

Individual images may be removed by clicking Remove image. Once all of the images have been added, click Save to file to generate the lens-correction parameters file.

The procedure outlined above assumes that the camera being used stores information about the focal length used to take each image in the image header. If this is not the case, it is only possible to add a single image to the parameters file. It is recommended that this image has a focal length similar to that used to collect the images of the sediment to be measured (i.e. the images are taken from approximately the same height and cover a similar area on the ground).

Existing lens-correction parameters files may be loaded by clicking Load from file. Images may then be added or removed from the parameters file.

File > [recent files list]

A list of recently used project files is provided on the File menu. Click on the name of any file to open it.

File > Exit

Closes the current project and exit Digital Gravelometer.

If the project has changed since it was last saved you will be prompted to save it.

^ top

Image Management menu

The Image management menu is used to add, remove, modify the properties of, and view information about images associated with the current project.

Image Management > Add Image

Add a new image to the current project.

You will be prompted to select an image file. If the file is not in the project folder you will be asked whether it should be copied there (recommended). If you answer yes and a file with the same name already exist in the project folder the filename will be prefixed with 'new_'. The Control-point identification dialogue will then be opened.

Control-point identification dialogue

The Control-point identification dialogue is opened whenever a new image is added to a project. The dialogue enables the identification of the four control points in the image.

Click on each of the four control points in turn (clockwise, starting in the top-left corner). If a point falls outside of the area visible at any time, the scroll bars may be used to move around the image. Alternatively, the blue box in the thumbnail image may be dragged using the mouse.

Once the four points have been identified, the Continue button will become active. Click this to continue or Clear to start again.

The Edit image properties dialogue will then open to enable the entry of information about the image.

Once all of the information has been added, click OK to add the image to the project and return to the main program window.

Image Management > Remove Image

Remove the selected image(s) from the project.

You will be asked to confirm that you wish to remove the image. This facility is also available by right clicking on an entry in the Image information panel and selecting Remove Image or by pressing the [delete] key.

Note that removing an image from the project does not delete the image file.

Image Management > Edit Image Properties…

Open the Edit image properties dialogue to edit the information about the selected image(s).

If multiple images are selected, the dialogue is opened repeatedly, once for each image. This facility is also available by right clicking on an entry in the Image information panel and the dialogue is called whenever a new image is added to the project.

Edit image properties dialogue

Certain mandatory information is required for each image:

  • Site name - this should represent the location at which the image was taken. This might be a particular river or bar depending on the scale of the study being undertaken. For the second and subsequent images in the project this will be entered automatically (but may be changed by the user).
  • Sample ID - this should be a unique identifier for the image.
  • Width / Height of Controlled area - this should be the dimensions (in mm) of the rectangle that defines the sampling area (i.e. the distance between the controlled points in the image). For the second and subsequent images in the project this will be entered automatically (but may be changed by the user).

It is possible to add various pieces of additional information that may be included in the grain-size distribution report:

  • Image information - most of the information in the Image information panel is automatically extracted by the software from the image header information (if present). There is the option to add the name of the photographer and edit the date and time the photograph was taken (in case the clock in the camera was incorrect).
  • Notes - any information that the user wishes to attach to the image.

Image Management > Update Image Location

Update the project file with the correct location of the images associated with it. If the images associated with a project are moved outside of Digital Gravelometer, the locations of the images stored within the project file will be incorrect. Use the Image Management > Update Image Location > Selected Images... menu to open the Browse for folder dialogue and select the correct location for the selected images. If all of the images associated with the project are in the same folder, use the Image Management > Update Image Location > All Images... menu to update the location of all of the images at once.

Image Management > View Image Data

Opens the Image data dialogue to view information about the selected image(s) and the parameters used for grain measurement.

If multiple images are selected, the dialogue is opened repeatedly, once for each image. This facility is also available by right clicking on the image in the list and selecting View Image Data.

Image data dialogue

This presents various information about the selected images. There are four panels:

  • Thumbnail - this shows a small representation of the selected image. Clicking Open image in viewer will open the Image viewer dialogue.
  • Image information - this shows a summary of the information known about the selected image. The information includes that extracted from the imager header and that entered by the user. The available information is:
    • the file location
    • the date and time the image was taken
    • the size of the image in pixels
    • the size of the sample area in mm
    • the photographer's name
    • the exposure time in seconds
    • the aperture
    • the focal length in mm
    • the equivalent focal length for a 35 mm camera
    • the ISO equivalent ('film speed')
    • whether a flash was used
    • the camera make and model
    • any notes entered by the user
  • Grain measurement information - this shows details of the last time the grains in the image were measured. The available information is (further information about each parameter is in the Technical information (measurement procedure) in this documentation):
    • the date and time that measurements were last made
    • the time taken to do the measurement
    • the operator who undertook the measurement
    • whether custom or default processing parameters were applied
    • the lens correction parameters file applied (if any)
    • the scale of the image (number of pixels per mm)
    • the size of the median filter applied to smooth the image (in pixels)
    • the two thresholds applied to the image (percent)
    • the size of the structuring element used to enhance the image (in pixels)
    • the minima suppression value for watershed segmentation
    • the edges of the sample area along which grains should be included
  • Grain-size distribution report information - this indicates the date and time at which a grain-size report was last generated.

To close the dialogue and return to the main program window, click Close.

Image viewer dialogue

The Image viewer provides a simple means of examining the images contained within the current project. It is opened by clicking Open image in viewer in the Image data dialogue. The image may be zoomed in and out using the controls in the Zoom panel. Click Fit to fit the image to the size of the window, or directly enter a zoom value in the Zoom to edit box.

When the image is zoomed in, the scroll bars may be used to move around the image. Alternatively, the blue box in the thumbnail image may be dragged using the mouse.

To close the Image viewer and return to the Image data dialogue, click Close.

^ top

Measure Grains menu

The Measure Grains menu is used to open the Measure grains dialogue to initiate measurements of the grains within the chosen images.

Measure Grains > All Images

Opens the Measure grains dialogue and applies the selected options to all of the images in the project.

Measure Grains > Selected Images

Opens the Measure grains dialogue and applies the selected options to the images currently selected in the Image information panel of the main program window.

Measure Grains > Unmeasured Images

Opens the Measure grains dialogue and applies the selected options to all of the images that have not yet been measured.

Measure grains dialogue

All of the options on the Measure Grains menu open the Measure grains dialogue. It is from here that identification and measurement of the grains within the chosen images is initiated and the desired output and processing options are set. The dialogue has three panels:

  • Output options - displays the intermediate steps in the grain identification and measurement procedure that are to be displayed on the screen and saved to file. The panel indicates whether default or custom options have been selected. Click Change to open the Output options dialogue to modify these settings.
  • Processing options - displays the currently selected options to be used to identify the grains in the chosen images. The panel indicates whether default or custom options have been selected. Click Change to open the Processing options dialogue to modify these settings.
  • Operator - this provides the opportunity to add a record of the name of the person who is undertaking the measurement.

To begin measuring the grains using the selected options, click Measure grains. A progress indicator will be displayed. When measurement is completed, the Measure grains dialogue will be closed and control returned to the main program window.

Output options dialogue

The Output options dialogue allows the user to specify which intermediate steps in the grain identification and measurement procedure will be displayed on the screen and saved to file.

Check the appropriate boxes to either view or save each intermediate step. If a save box is checked, it is possible to specify an image filename and type. Images are always saved in the same folder as the project file.

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 held 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.

Once the desired options have been set, click OK to return to the Measure grains dialogue.

Further information about the stages in the grain identification and measurement procedure are contained in the Technical information (measurement procedure) section of this documentation.

Processing options dialogue

The Processing options dialogue allows the user to specify the parameters that will be used by the grain identification and measurement procedures. For a full description of the significance and purpose of all of the parameters, refer to the Technical information (measurement procedure) section of this documentation. It is strongly recommended that the 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.

The dialogue has five panels:

  • Image transform - specifies the scaling applied to the image in pixels per mm. Click Reset to default to return this parameter to its original value.
  • Grain identification - these parameters control the way that the software identifies the grains in the chosen images. Click Reset to default to return the parameters to their original values. The parameters are:
    • Structuring element size (pixels) - for image enhancement
    • Median filter size (pixels) - for noise reduction
    • Threshold 1 (percent)
    • Threshold 2 (percent)
  • Watershed segmentation - specifies the minima suppression parameter used to prevent oversegmentation of the grains by the watershed segmentation procedure. Click Reset to default to return this parameter to its original value.
  • Boundary parameters - specifies whether grains that intersect the boundary of the sample area are measured and included as part of the grain-size distribution. Click Reset to default to return these parameters to their original values.
  • Radial lens correction - specifies the file containing the radial lens correction parameters to be applied to the chosen images. Click Reset to default to return this parameter to its original value (no correction).

To return all of the parameters to their original values, click Reset all. Once the desired options have been set, click OK to return to the Measure grains dialogue.

^ top

Report menu

The Report menu is used to open the Report options dialogue to initiate the generation of a report on the grain-size distribution of the chosen images.

Report > Selected Images > Individual Analysis...

Opens the Report options dialogue and applies the selected options to the images currently selected in the Image information panel of the main program window. Treats each of the images as separate samples and provide separate information on the grain-size distribution of each.

Report > Selected Images > Aggregate Analysis...

Opens the Report options dialogue and applies the selected options to the images currently selected in the Image information panel of the main program window. Aggregates the information for all of the images, treating them as a single sample.

Report > All Measured Images > Individual Analysis...

Opens the Report options dialogue and applies the selected options to all of the images in the project for which grain-size information is currently available. Treats each of the images as separate samples and provide separate information on the grain-size distribution of each.

Report > All Measured Images > Aggregate Analysis...

Opens the Report options dialogue and applies the selected options to all of the images in the project for which grain-size information is currently available. Aggregates the information for all of the images, treating them as a single sample.

Report options dialogue

All of the options on the Report menu open the Report options dialogue. It is from here that the generation of reports on the grain-size distribution of the chosen images is initiated and the information to include and the method of calculation are set.

The dialogue has six panels:

  • Template options - these options provide the opportunity to save the current options to a template file and load existing options from a template file. This makes it easier to generate numerous reports using the same options. All of the other report options, with the exception of the Export options, are stored in the template file. The two buttons in this panel are:
    • Load template
    • Save template
  • Export options - this provides the option to export the grain-size distribution information. There are two sub options:
    • Export analysis - this exports the grain-size distribution report to a comma-separated variable (*.csv) file. If the box is checked the Set location button is activated. Click this to define the filename and location to which the file will be saved.
    • Export distribution plot - this exports the grain-size distribution plot as an image file. If the box is checked the Set location button is activated. Click this to define the filename and location to which the file will be saved.
  • Calculation options - the parameters in this panel define the way in which the grain-size distribution is calculated from the raw size information:
    • Use percent finer/coarser than - defines whether the grain-size percentiles are calculated based on the proportion of grains that are finer or coarser than a particular value.
    • Basis of distribution calculation - specifies whether the grain-size distribution is calculated to be comparable with a grid-by-number (Wolman) or area-by-number sample. See the Technical information (distribution calculation) section of this documentation for further details.
    • Apply square-hole sieve correction - applies a correction to the size distribution to make it directly comparable to distributions based on the sieving of sediment using square-hole sieves. Click Change settings... to open the Square-hole sieve correction dialogue to specify the parameters to be applied in applying the correction.
  • Truncations - specifies the truncations to apply to the tails of the distribution. A recommended lower (fine end) truncation is specified based on the scale of the image. Upper and lower truncations may be entered in mm, Psi or Phi units: use the drop-down menus to specify the units. Click Apply to update the settings.
  • Cumulative plot preview - shows the effect of the calculation and truncation settings on the cumulative grain-size distribution. The preview plot is updated each time one of the settings is changed.
  • Report contents - enables the user to specify which information to include in the report. Options are:
    • Project information - include general information about the project (e.g. file name, client).
    • Image information - include general information about each of the images (e.g. file name, focal length) .
    • Processing parameters - include information about the parameters used to identify and measure the grains in each image.
    • Grain-size information - include details of the grain-size distribution for each image. Click Change grain-size options to open the Report-options - grain-size information dialogue to specify exactly which information is included.
    • Plot grain-size distribution - include a plot of the grain-size distribution in report. Click Change plot options to open the Report-options - plot dialogue to determine what is plotted and how it appears.

Once the desired options have been set, click Generate report to create the report and send it to the web browser (and export any files specified in the Export options panel).

Further information about the different methods of calculating the grain-size distribution are contained in the Technical information (distribution calculation) section of this documentation.

Square-hole sieve correction dialogue

The Square-hole sieve correction dialogue enables the user to specify the parameters to be used to apply a correction to the grain-size information to make it directly comparable to information obtained using square-hole sieves. Full details of the correction are provided in the Technical information (sieve correction) section of this documentation.

The Square-hole sieve correction dialogue may be accessed from the Report options and the Export options dialogues.

The user may enter either the mean grain flatness (c-axis/b-axis) for the site, in which case the correction factor is automatically calculated, or the correction factor directly. If no values are entered, default values are used (which should be appropriate for most sites).

Click Apply to apply the correction and return to the Report options or Export options dialogue.

Report options - grain-size information dialogue

The Report-options - grain-size information dialogue permits the selection of which grain-size information to be included in the report. The dialogue is divided into four panels, each representing one section of the grain-size report. Particular information can be included or excluded by using the checkbox in the top-left corner of panel. The four panels are:

  • Grain-size percentiles - this enables customization of the display of the grain-size percentiles in the report. The user may opt to define the particular percentiles to present (which must be provided as a comma-separated list) or to present all integer (i.e. 1, 2, 3, … 100) percentiles. The percentiles may be presented in mm, Psi or Phi units by checking the appropriate boxes.
  • Distribution statistics - this enables customization of the display of a range of grain-size distribution statistics. The following statistics may be calculated:
    • mean
    • sorting
    • skewness
    • kurtosis
    Each of these may be calculated by the method of moments or by the Folk and Ward inclusive graphical method. They may be calculated logarithmically (using Phi and Psi units), geometrically (using mm units) or, for moment statistics, arithmetically (using mm units).
  • Data summary - this enable the customization of a table of the proportion of grains in defined size classes. The class boundaries may be set at half Psi/Phi, quarter Psi/Phi, or user-defined intervals. User defined class boundaries must be presented as a comma-separated list and may be defined in mm, Psi or Phi units depending on the setting in the drop-down menu. Class boundaries may be shown in the report in mm, Psi and Phi units by checking the appropriate boxes. Data may be presented as:
    • count/area in class (count used for area-by-number distributions; area for grid-by-number distributions)
    • percent in class
    • cumulative percent finer/coarser (based on settings in the Report options dialogue box)
    by checking the appropriate boxes. There is also an option to present the proportion of grains in each Wentworth size class by checking the appropriate box.

Click OK to apply the options and return to the Report options dialogue.

Report options - plot dialogue

The Report-options - plot dialogue permits the customisation of the appearance of the grain-size distribution histogram and cumulative curve if this is included in the report or exported to a file. The dialogue is divided into three panels:

  • Plot preview - this updates in response to changes in the other panels.
  • Size axes - this permits changes to the appearance of the size (horizontal; x-) axis in the plot. Options are:
    • Show axis in Phi/Psi - permits an axis with logarithmic scaling to be toggled on and off. By default this appears on the bottom axis.
    • Show axis in mm - permits an axis with geometric scaling to be toggled on and off. By default this appears on the top axis.
    • Flip top & bottom axes - moves the logarithmic axis to the top and the geometric axis to the bottom of the plot.
    • Reverse axes direction - by default grain size increases from left to right. This option is used to reverse the axis direction.
  • Data axes - this permits the user to specify whether the grain-size histogram, cumulative plot, or both, are plotted and alter the appearance of the data (vertical, y-) axis. Options are:
    • Show grain-size histogram - toggles the display of the grain-size distribution histogram on and off.
    • Maximum value - allows the user to specify the vertical scaling for the histogram by selecting a maximum value for the axis. This may make it easier to compare multiple histograms. The software may be left to calculate an appropriate value by selecting the default option.
    • Show cumulative grain-size distribution curve - toggles the display of the cumulative distribution curve on and off.
    • Flip left & right axes - toggles the location of the histogram data and cumulative curve data axes.

Click OK to apply the options and return to the Report options dialogue.

^ top

Export Data menu

The Export Data menu is used to open the Export data dialogue to initiate the export of raw data to a comma-separated variable (*.csv) file readable by many other software packages.

Export > Selected Images > Individual Analysis...

Opens the Export data dialogue and applies the selected options to the images currently selected in the Image information panel of the main program window. Treats each of the images as separate samples and provide separate information on each.

Export > Selected Images > Aggregate Analysis...

Opens the Export data dialogue and applies the selected options to the images currently selected in the Image information panel of the main program window. Aggregates the information for all of the images, treating them as a single sample.

Export > All Measured Images > Individual Analysis...

Opens the Export data dialogue and applies the selected options to all of the images in the project for which grain-size information is currently available. Treats each of the images as separate samples and provide separate information on each.

Export > All Measured Images > Aggregate Analysis...

Opens the Export data dialogue and applies the selected options to all of the images in the project for which grain-size information is currently available. Aggregates the information for all of the images, treating them as a single sample.

Export data dialogue

The Export data dialogue permits the export of raw data to a comma-separated variable (*.csv) file readable by many other software packages. The dialogue is divided into two panels:

  • File location - click Set location to define the file to which the data should be exported.
  • Export options - enables the user to specify which attributes to export:
    • 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 graded using square-hole sieves. Click Change settings to open the Square-hole sieve correction dialogue. See the Technical information (sieve correction) in this documentation for further information.

Click Export to export the data to the specified file and return to the main program window.

^ top

Help menu

Help > Get Started

Opens the documentation in the default web browser at the Get started page.

Help > Documentation

Opens the documentation in the default web browser.

Help > Sedimetrics on the Web

Goes to http://www.sedimetrics.com/.

Help > About Digital Gravelometer

Displays information about the software, including the version number and copyright information. Also provides a link to the Sedimetrics web site.

^ top

Please report software bugs or documentation errors to bugs@sedimetrics.com
Visit Sedimetrics.com | © 2005-6 Loughborough University Enterprises Limited