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

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