NAME

       grdvolume - Calculate grid volume and area constrained by a contour

SYNOPSIS

       grdvolume grdfile [  -Ccval or  -Clow/high/delta or  -Crlow/high or  -Crcval] [  -Lbase ] [  -Rregion ] [
       -S[unit] ] [  -T[c|h] ] [  -V[level] ] [  -Zfact[/shift] ] [ -fflags ] [ -oflags ]

       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 between the surface and the plane
       specified by the given contour (or zero if not given) and reports the  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

       grdfile
              The name of the input 2-D binary grid file. (See GRID FILE FORMAT below.)

OPTIONAL ARGUMENTS

       -Ccval or -Clow/high/delta or -Crlow/high or -Crcval
              find area, volume and mean height (volume/area) inside the  cval  contour.  Alternatively,  search
              using  all  contours  from  low  to high in steps of delta. [Default returns area, volume and mean
              height of the entire grid]. The area is measured in the plane of the contour. The Cr form  on  the
              other  hand computes the volume between the grid surface and the plans defined by low and high, or
              below cval and grid’s minimum. Note that this is an outside volume whilst the other forms  compute
              an  inside  (below  the  surface)  area volume. Use this form to compute for example the volume of
              water between two contours.

       -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] (more …)
              Specify the region of interest.

       -V[level] (more …)
              Select verbosity level [c].

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

       -ocols[,…] (more …)
              Select output columns (0 is first column).

       -^ or just -
              Print a short message about the syntax of the command, then exits (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 exits.

       -? or no arguments
              Print a complete usage (help) message, including the explanation of all options, then exits.

GRID FILE FORMATS

       By  default  GMT  writes  out  grid  as single precision floats in a COARDS-complaint netCDF file format.
       However, GMT is able to produce grid files in many  other  commonly  used  grid  file  formats  and  also
       facilitates so called “packing” of grids, writing out floating point data as 1- or 2-byte integers. (more
       …)

EXAMPLES

       To determine the volume in km^3 under the surface hawaii_topo.nc (height in km), use

              gmt grdvolume hawaii_topo.nc -Sk

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

              gmt grdvolume peaks.nc -Se -C250

       To  search  for  the  contour,  between 100 and 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

NOTES

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

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

SEE ALSO

       gmt, grdfilter, grdmask, grdmath

REFERENCES

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

COPYRIGHT

       2018, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe

5.4.3                                             Jan 03, 2018                                   GRDVOLUME(1gmt)