.\" Man page generated from reStructuredText.
.
.TH "GRDVOLUME" "1gmt" "Jan 10, 2019" "5.4.5" "GMT"
.SH NAME
grdvolume \- Calculate grid volume and area constrained by a contour
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBgrdvolume\fP \fIgrdfile\fP [  \fB\-C\fP\fIcval\fP or  \fB\-C\fP\fIlow/high/delta\fP or  \fB\-C\fP\fBr\fP\fIlow/high\fP or  \fB\-C\fP\fBr\fP\fIcval\fP]
[  \fB\-L\fP\fIbase\fP ]
[  \fB\-R\fP\fIregion\fP ]
[  \fB\-S\fP[\fIunit\fP] ] [  \fB\-T\fP[\fBc\fP|\fBh\fP] ]
[  \fB\-V\fP[\fIlevel\fP] ]
[  \fB\-Z\fP\fIfact\fP[/\fIshift\fP] ]
[ \fB\-f\fPflags ]
[ \fB\-o\fPflags ]
.sp
\fBNote:\fP No space is allowed between the option flag and the associated arguments.
.SH DESCRIPTION
.sp
\fBgrdvolume\fP 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 \fBgrdvolume\fP will determine the volume and area inside
the contour for all contour values. Using \fB\-T\fP, 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 [\fIWessel\fP, 1998].
.SH REQUIRED ARGUMENTS
.INDENT 0.0
.TP
.B \fIgrdfile\fP
The name of the input 2\-D binary grid file. (See GRID FILE FORMAT below.)
.UNINDENT
.SH OPTIONAL ARGUMENTS
.INDENT 0.0
.TP
\fB\-C\fP\fIcval\fP or \fB\-C\fP\fIlow/high/delta\fP or \fB\-Cr\fP\fIlow/high\fP or \fB\-Cr\fP\fIcval\fP
find area, volume and mean height (volume/area) inside the \fIcval\fP contour. Alternatively, search using
all contours from \fIlow\fP to \fIhigh\fP in steps of \fIdelta\fP\&. [Default returns area, volume and mean height
of the entire grid]. The area is measured in the plane of the contour. The \fBCr\fP form on the other
hand computes the volume between the grid surface and the plans defined by \fIlow\fP and \fIhigh\fP,
or below \fIcval\fP and grid\(aqs minimum. Note that this is an \fIoutside\fP volume whilst the other forms
compute an \fIinside\fP (below the surface) area volume. Use this form to compute for example the volume
of water between two contours.
.UNINDENT
.INDENT 0.0
.TP
\fB\-L\fP\fIbase\fP
Also add in the volume from the level of the contour down to \fIbase\fP [Default base is contour].
.UNINDENT
.INDENT 0.0
.TP
\fB\-S\fP[\fIunit\fP]
For geographical grids, append a unit from
\fBe\fP|\fBf\fP|\fBk\fP|\fBM\fP|\fBn\fP|\fBu\fP
[Default is meter (\fBe\fP)].
.UNINDENT
.INDENT 0.0
.TP
\fB\-T\fP[\fBc\fP|\fBh\fP]
Determine the single contour that maximized the average height (=
volume/area). Select \fB\-Tc\fP 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 \fB\-C\fP).
.UNINDENT
.INDENT 0.0
.TP
\fB\-R\fP\fIxmin\fP/\fIxmax\fP/\fIymin\fP/\fIymax\fP[\fB+r\fP][\fB+u\fP\fIunit\fP] (more ...)
Specify the region of interest.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-V\fP[\fIlevel\fP] (more ...)
Select verbosity level [c].  
.UNINDENT
.INDENT 0.0
.TP
\fB\-Z\fP\fIfact\fP[/\fIshift\fP]
Optionally subtract \fIshift\fP before scaling data by \fIfact\fP\&. [Default
is no scaling]. (Numbers in \fB\-C\fP, \fB\-L\fP refer to values after
this scaling has occurred).
.UNINDENT
.INDENT 0.0
.TP
\fB\-f\fP[\fBi\fP|\fBo\fP]\fIcolinfo\fP (more ...)
Specify data types of input and/or output columns.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-o\fP\fIcols\fP[,...] (more ...)
Select output columns (0 is first column).
.UNINDENT
.INDENT 0.0
.TP
\fB\-^\fP or just \fB\-\fP
Print a short message about the syntax of the command, then exits (NOTE: on Windows just use \fB\-\fP).
.TP
\fB\-+\fP or just \fB+\fP
Print an extensive usage (help) message, including the explanation of
any module\-specific option (but not the GMT common options), then exits.
.TP
\fB\-?\fP or no arguments
Print a complete usage (help) message, including the explanation of all options, then exits.
.UNINDENT
.SH GRID FILE FORMATS
.sp
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 ...)
.SH EXAMPLES
.sp
To determine the volume in km^3 under the surface hawaii_topo.nc (height in km), use
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt grdvolume hawaii_topo.nc \-Sk
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
To find the volume between the surface peaks.nc and the contour z = 250 m in meters, use
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt grdvolume peaks.nc \-Se \-C250
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
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
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt grdvolume peaks.nc \-C0/300/10 \-Th > results.d
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
To see the areas and volumes for all the contours in the previous example, use
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt grdvolume peaks.nc \-C100/300/10 > results.d
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
To find the volume of water in a lake with its free surface at 0 and max depth of 300 meters, use
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt grdvolume lake.nc \-Cr\-300/0
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH NOTES
.INDENT 0.0
.IP 1. 3
For geographical grids we convert degrees to "Flat Earth" distances in
meter.  You can use \fB\-S\fP 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.
.IP 2. 3
\fBgrdvolume\fP 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
\fB\-C\fP 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 \fB\-C\fP flag.
.UNINDENT
.SH SEE ALSO
.sp
gmt,
grdfilter,
grdmask,
grdmath
.SH REFERENCES
.sp
Wessel, P., 1998, An empirical method for optimal robust
regional\-residual separation of geophysical data, \fIMath. Geol.\fP, \fB30\fP(4), 391\-408.
.SH COPYRIGHT
2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
.\" Generated by docutils manpage writer.
.