NAME

       grdvolume - Calculating volume under a surface within a contour

SYNOPSIS

       grdvolume  grdfile  [  -Ccval  or  -Clow/high/delta  ]  [  -Lbase  ]  [
       -Rwest/east/south/north[r]  ]  [  -S[k]  ]  [  -T  ]  [   -V[l]   ]   [
       -Zfact[/delta] ]

DESCRIPTION

       grdvolume  reads  a  2-D binary grd file and calculates the volume con-
       tained 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 con-
       tour for all contour values. The contour that produced the maximum mean
       height  is reported as well. This feature may be used with grdfilter in
       designing an Optimal Robust Separator [Wessel, 1998].

       grdfile
              The name of the input 2-D binary grd file.

OPTIONS

       No space between the option flag and the associated arguments.

       -C     find area and volume inside  the  cval  contour.  Alternatively,
              search  using  all  contours from low to high in steps of delta.
              [Default returns entire area and volume of grid].  The  area  is
              measured in the plane of the countour.

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

       -S     Convert degrees to meters, append k for km  [Default  is  Carte-
              sian].

       -T     Use  curvature  minimum  rather than maximum height to find best
              contour value (when contour search is selected with -C).

       -R     xmin, xmax, ymin, and ymax specify the Region of  interest.  For
              geographic  regions,  these  limits  correspond  to  west, east,
              south, and north and you may specify them in decimal degrees  or
              in  [+-]dd:mm[:ss.xxx][W|E|S|N]  format.  Append r if lower left
              and upper right map coordinates are given instead of  wesn.  The
              two  shorthands  -Rg  -Rd  stand  for  global  domain  (0/360 or
              -180/+180 in longitude respectively, with -90/+90 in  latitude).
              For  calendar time coordinates you may either give relative time
              (relative  to  the  selected  TIME_EPOCH  and  in  the  selected
              TIME_UNIT;  append  t  to  -JX|x),  or absolute time of the form
              [date]T[clock] (append T to -JX|x). At least  one  of  date  and
              clock must be present; the T is always required. The date string
              must be of the form [-]yyyy[-mm[-dd]]  (Gregorian  calendar)  or
              yyyy[-Www[-d]]  (ISO week calendar), while the clock string must
              be of the form hh:mm:ss[.xxx]. The use of delimiters  and  their
              type  and  positions must be as indicated (however, input/output
              and plotting formats are flexible).

       -V     Selects verbose mode, which will send progress reports to stderr
              [Default  runs "silently"].  Append l to see all the results for
              each  contour  level  tested  (when  contour  search  has   been
              selected).

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

EXAMPLES

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

       grdvolume hawaii_topo.grd -Sk

       To find the volume between the surface peaks.grd and the  contour  z  =
       250, use

       grdvolume peaks.grd -Sk -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.grd,
       use

       grdvolume peaks.grd -Sk -C100/300/10 > results.d

       To see the areas and volumes for all the contours in the previous exam-
       ple, use

       grdvolume peaks.grd -Sk -Vl -C100/300/10 > results.d

SEE ALSO

       gmt(l), grdfilter(l)

REFERENCES

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



GMT4.0                            1 Oct 2004                      GRDVOLUME(l)