1GRDVOLUME(1)                          GMT                         GRDVOLUME(1)
2
3
4

NAME

6       grdvolume - Calculate grid volume and area constrained by a contour
7

SYNOPSIS

9       grdvolume  grdfile  [   -Ccval  or  -Clow/high/delta or  -Crlow/high or
10       -Crcval] [  -Lbase ] [  -Rregion  ]  [   -S[unit]  ]  [   -T[c|h]  ]  [
11       -V[level] ] [  -Zfact[/shift] ] [ -fflags ] [ -oflags ]
12
13       Note:  No  space  is allowed between the option flag and the associated
14       arguments.
15

DESCRIPTION

17       grdvolume reads a 2-D grid file and  calculates  the  volume  contained
18       between  the  surface  and the plane specified by the given contour (or
19       zero if not given) and reports  the  area,  volume,  and  maximum  mean
20       height (volume/area).  Alternatively, specify a range of contours to be
21       tried and grdvolume will determine the volume and area inside the  con‐
22       tour  for  all  contour values. Using -T, the contour that produced the
23       maximum mean height (or maximum curvature of heights vs contour  value)
24       is reported as well. This feature may be used with grdfilter in design‐
25       ing an Optimal Robust Separator [Wessel, 1998].
26

REQUIRED ARGUMENTS

28       grdfile
29              The name of the input 2-D binary grid file. (See GRID FILE  FOR‐
30              MAT below.)
31

OPTIONAL ARGUMENTS

33       -Ccval or -Clow/high/delta or -Crlow/high or -Crcval
34              find  area, volume and mean height (volume/area) inside the cval
35              contour. Alternatively, search using all contours  from  low  to
36              high  in  steps of delta. [Default returns area, volume and mean
37              height of the entire grid]. The area is measured in the plane of
38              the  contour.  The Cr form on the other hand computes the volume
39              between the grid surface and the plans defined by low and  high,
40              or  below  cval and grid's minimum. Note that this is an outside
41              volume whilst the other forms compute an inside (below the  sur‐
42              face) area volume. Use this form to compute for example the vol‐
43              ume of water between two contours.
44
45       -Lbase Also add in the volume from the level of  the  contour  down  to
46              base [Default base is contour].
47
48       -S[unit]
49              For  geographical grids, append a unit from e|f|k|M|n|u [Default
50              is meter (e)].
51
52       -T[c|h]
53              Determine the single contour that maximized the  average  height
54              (=  volume/area).  Select  -Tc  to  use the maximum curvature of
55              heights versus contour value rather than the  contour  with  the
56              maximum height to pick the best contour value (requires -C).
57
58       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
59              Specify the region of interest.
60
61       -V[level] (more ...)
62              Select verbosity level [c].
63
64       -Zfact[/shift]
65              Optionally  subtract shift before scaling data by fact. [Default
66              is no scaling]. (Numbers in -C, -L refer to  values  after  this
67              scaling has occurred).
68
69       -f[i|o]colinfo (more ...)
70              Specify data types of input and/or output columns.
71
72       -ocols[,...] (more ...)
73              Select output columns (0 is first column).
74
75       -^ or just -
76              Print  a  short  message  about  the syntax of the command, then
77              exits (NOTE: on Windows just use -).
78
79       -+ or just +
80              Print an extensive usage (help) message, including the  explana‐
81              tion  of  any  module-specific  option  (but  not the GMT common
82              options), then exits.
83
84       -? or no arguments
85              Print a complete usage (help) message, including the explanation
86              of all options, then exits.
87

GRID FILE FORMATS

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

EXAMPLES

96       To  determine  the  volume  in  km^3  under  the surface hawaii_topo.nc
97       (height in km), use
98
99              gmt grdvolume hawaii_topo.nc -Sk
100
101       To find the volume between the surface peaks.nc and the contour z = 250
102       m in meters, use
103
104              gmt grdvolume peaks.nc -Se -C250
105
106       To  search  for  the  contour, between 100 and 300 in steps of 10, that
107       maximizes the ratio of volume to surface area for  the  file  peaks.nc,
108       use
109
110              gmt grdvolume peaks.nc -C0/300/10 -Th > results.d
111
112       To see the areas and volumes for all the contours in the previous exam‐
113       ple, use
114
115              gmt grdvolume peaks.nc -C100/300/10 > results.d
116
117       To find the volume of water in a lake with its free surface  at  0  and
118       max depth of 300 meters, use
119
120              gmt grdvolume lake.nc -Cr-300/0
121

NOTES

123       1. For  geographical grids we convert degrees to "Flat Earth" distances
124          in meter.  You can use -S to select another distance unit.  The area
125          is  then  reported in this unit squared while the volume is reported
126          in unit^2 * z_unit quantities.
127
128       2. grdvolume distinguishes between gridline and pixel-registered grids.
129          In both cases the area and volume are computed up to the grid bound‐
130          aries. That means that in the first  case  the  grid  cells  on  the
131          boundary  only  contribute  half their area (and volume), whereas in
132          the second case all grid cells are fully used. The exception is when
133          the  -C flag is used: since contours do not extend beyond the outer‐
134          most grid point, both grid types are treated the  same.  That  means
135          the  outer  rim in pixel oriented grids is ignored when using the -C
136          flag.
137

SEE ALSO

139       gmt, grdfilter, grdmask, grdmath
140

REFERENCES

142       Wessel,  P.,   1998,   An   empirical   method   for   optimal   robust
143       regional-residual  separation  of geophysical data, Math. Geol., 30(4),
144       391-408.
145
147       2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
148
149
150
151
1525.4.5                            Feb 24, 2019                     GRDVOLUME(1)
Impressum