grdvolume

Calculate grid volume and area constrained by a contour

Synopsis

gmt grdvolume ingrid [ -Ccval or -Clow/high/delta or -Crlow/high or -Crcval] [ -D ] [ -Lbase ] [ -Rregion ] [ -S[unit] ] [ -T[c|h] ] [ -V[level] ] [ -Zfact[/shift] ] [ -fflags ] [ -hheaders ] [ -oflags ] [ --PAR=value ]

Note: No space is allowed between the option flag and the associated arguments.

Description

grdvolume reads a 2-D grid file and calculates the volume contained below the surface and above the plane specified by the given contour (or zero if not given) and reports the contour, area, volume, and maximum mean height (volume/area). Alternatively, specify a range of contours to be tried and grdvolume will determine the volume and area inside the contour for all contour values. Using -T, the contour that produced the maximum mean height (or maximum curvature of heights vs contour value) is reported as well. This feature may be used with grdfilter in designing an Optimal Robust Separator [Wessel, 1998].

Required Arguments

ingrid[=ID|?varname][+bband][+ddivisor][+ninvalid] [+ooffset][+sscale]

2-D gridded data file. Optionally, append =ID for reading a specific file format [Default is =nf] or ?varname for a specific netCDF variable [Default is the first 2-D grid found by GMT] (See full description). The following modifiers are supported:

  • +b - Select a band (for images only) [Default is 0].

  • +d - Divide data values by the given divisor [Default is 1].

  • +n - Replace data values matching invalid with NaN.

  • +o - Offset data values by the given offset [Default is 0].

  • +s - Scale data values by the given scale [Default is 1].

Note: Any offset is added after any scaling.

Optional Arguments

-C[cval|low/high/delta] or -Cr[cval|low/high]

By default, report the area, volume, and mean height (where height = volume / area) of the entire grid. While the value in the first column will be 0, this does not mean that a zero-contour was traced (unless -C0 is used). Alternatively, use one of the following to report a different statistic:

  • -Ccval - Report the area, volume, and mean height above the cval contour and below the grid surface.

  • -Clow/high/delta - Report the area, volume, and mean height above each contour from low to high in steps of delta and below the grid surface. The area is calculated in the plane of the contour.

  • -Crcval - Report the area, volume, and mean height below the cval contour and above the grid surface. Note: This defines an outside volume.

  • -Crlow/high - Report the area, volume, and mean height between low and high and above the grid surface. For example, use this form to compute the volume of water between to contours.

-D

Requires -Clow/high/delta and will compute the area and volume of each horizontal slice as defined by the contours. The reported contour and area values refer to the base of the slice, and the height is set to delta (since that is the thickness of all slices).

-Lbase

Also add in the volume from the level of the contour down to base [Default base is contour].

-S[unit]

For geographical grids, append a unit from e|f|k|M|n|u [Default is meter (e)].

-T[c|h]

Determine the single contour that maximized the average height (= volume/area). Select -Tc to use the maximum curvature of heights versus contour value rather than the contour with the maximum height to pick the best contour value (requires -C).

-Rxmin/xmax/ymin/ymax[+r][+uunit]

Specify the region of interest. (See full description) (See cookbook information).

-V[level]

Select verbosity level [w]. (See full description) (See cookbook information).

-Zfact[/shift]

Optionally subtract shift before scaling data by fact. [Default is no scaling]. (Numbers in -C, -L refer to values after this scaling has occurred).

-f[i|o]colinfo (more …)

Specify data types of input and/or output columns.

-h[i|o][n][+c][+d][+msegheader][+rremark][+ttitle] (more …)

Skip or produce header record(s).

-ocols[,…][,t[word]] (more …)

Select output columns (0 is first column; t is trailing text, append word to write one word only).

-^ or just -

Print a short message about the syntax of the command, then exit (NOTE: on Windows just use -).

-+ or just +

Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.

-? or no arguments

Print a complete usage (help) message, including the explanation of all options, then exit.

--PAR=value

Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Examples

Note: Below are some examples of valid syntax for this module. The examples that use remote files (file names starting with @) can be cut and pasted into your terminal for testing. Other commands requiring input files are just dummy examples of the types of uses that are common but cannot be run verbatim as written.

To determine area (in km^2), volume (in km^3), and mean height (in km) of all land areas (above zero contour) in the Hawaiian Islands from the remote grid @earth_relief_05m (height in m), use:

gmt grdvolume @earth_relief_05m -R190/210/15/25 -C0 -Sk -Z0.001

To find the volume below the surface peaks.nc and above the contour z = 250 m in meters, use

gmt grdvolume peaks.nc -Se -C250

To search for the contour, ranging from 100 to 300 in steps of 10, that maximizes the ratio of volume to surface area for the file peaks.nc, use

gmt grdvolume peaks.nc -C0/300/10 -Th > results.d

To see the areas and volumes for all the contours in the previous example, use

gmt grdvolume peaks.nc -C100/300/10 > results.d

To find the volume of water in a lake with its free surface at 0 and max depth of 300 meters, use

gmt grdvolume lake.nc -Cr-300/0

Volume integration

The surface will be approximated using a bilinear expression for the z-value inside each grid box defined by four grid nodes: \(z(x,y) = z_0 + z_x^{'}x + z_y^{'}y + z_{xy}^{''}xy\), where the first term is the grid value at the lower left corner of the cell (where our relative coordinates x = y = 0). The primed z-values are derivatives in x, y, and both directions, respectively. We analytically integrate this expression within each box, allowing for straight line contour intersections to go through a box and affect the integration domain and limits.

Notes

  1. The output of grdvolume is one or more records (one per contour if -C is set to search multiple contours) containing contour area volume volume/area. These records are written to standard output.

  2. For geographical grids we convert degrees to “Flat Earth” distances in meter. You can use -S to select another distance unit. The area is then reported in this unit squared while the volume is reported in unit^2 * z_unit quantities.

  3. grdvolume distinguishes between gridline and pixel-registered grids. In both cases the area and volume are computed up to the grid boundaries. That means that in the first case the grid cells on the boundary only contribute half their area (and volume), whereas in the second case all grid cells are fully used. The exception is when the -C flag is used: since contours do not extend beyond the outermost grid point, both grid types are treated the same. That means the outer rim in pixel oriented grids is ignored when using the -C flag.

References

Wessel, P., 1998, An empirical method for optimal robust regional-residual separation of geophysical data, Math. Geol., 30(4), 391-408.