Ubuntu Manpage: grdcut - Extract subregion from a grid

Provided by: gmt-common_5.2.1+dfsg-3build1_all

NAME

       grdcut - Extract subregion from a grid

SYNOPSIS

       grdcut  ingrid  outgrid  region  [  [nodata] ] [ [n]lon/lat/radius[unit] ] [ [level] ] [ [n|r]min/max ] [
       -f<flags> ]

       Note: No space is allowed between the option flag and the associated arguments.

DESCRIPTION

       grdcut will produce a new outgrid file which is a subregion of ingrid. The subregion is specified with -R
       as in other programs; the specified range must not exceed the range of ingrid (but see -N).  If in doubt,
       run grdinfo to check range. Alternatively, define the subregion indirectly via a range check on the  node
       values  or  via  distances from a given point. Complementary to grdcut there is grdpaste, which will join
       together two grid files along a common edge.

REQUIRED ARGUMENTS

       ingrid This is the input grid file.

       -Goutgrid
              This is the output grid file.

OPTIONAL ARGUMENTS

       -N[nodata]
              Allow grid to be extended  if  new  -R  exceeds  existing  boundaries.   Append  nodata  value  to
              initialize nodes outside current region [Default is NaN].

       -R[unit]xmin/xmax/ymin/ymax[r] (more ...)
              Specify the region of interest. This defines the subregion to be cut out.

       -S[n]lon/lat/radius[unit]
              Specify  an  origin  and  radius;  append  a  distance  unit  (see  UNITS)  and  we  determine the
              corresponding rectangular region so that all grid nodes on or inside the circle are  contained  in
              the subset. If -Sn is used we set all nodes outside the circle to NaN.

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

       -Z[n|r]min/max
              Determine  the  new  rectangular region so that all nodes outside this region are also outside the
              given z-range [-inf/+inf]. To indicate no limit on min or max, specify a hyphen (-). Normally, any
              NaNs encountered are simply skipped and not considered in the decision.  Use -Zn to consider a NaN
              to be outside the z-range. This means the new subset will be NaN-free. Alternatively, use  -Zr  to
              consider  NaNs  to  be within the data range. In this case we stop shrinking the boundaries once a
              NaN is found [Default simply skips NaNs when making the range decision].

       -f[i|o]colinfo (more ...)
              Specify data types of input and/or output columns.

       -^ or just -
              Print a short message about the syntax of the command, then exits (NOTE: on Windows use just -).

       -+ 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 options, then exits.

       --version
              Print GMT version and exit.

       --show-datadir
              Print full path to GMT share directory and exit.

UNITS

       For  map  distance  unit,  append unit d for arc degree, m for arc minute, and s for arc second, or e for
       meter [Default], f for foot, k for km, M for statute mile, n for nautical mile, and u for US survey foot.
       By default we compute such distances using a spherical approximation with great circles. Prepend -  to  a
       distance  (or  the  unit  is no distance is given) to perform "Flat Earth" calculations (quicker but less
       accurate) or prepend + to perform exact geodesic calculations (slower but more accurate).

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. To
specify the precision, scale and offset, the user should add the suffix =id[/scale/offset[/nan]], where
id is a two-letter identifier of the grid type and precision, and scale and offset are optional scale
factor and offset to be applied to all grid values, and nan is the value used to indicate missing data.
In case the two characters id is not provided, as in =/scale than a id=nf is assumed. When reading
grids, the format is generally automatically recognized. If not, the same suffix can be added to input
grid file names. See grdconvert and Section grid-file-format of the GMT Technical Reference and Cookbook
for more information.

When reading a netCDF file that contains multiple grids, GMT will read, by default, the first
2-dimensional grid that can find in that file. To coax GMT into reading another multi-dimensional
variable in the grid file, append ?varname to the file name, where varname is the name of the variable.
Note that you may need to escape the special meaning of ? in your shell program by putting a backslash in
front of it, or by placing the filename and suffix between quotes or double quotes. The ?varname suffix
can also be used for output grids to specify a variable name different from the default: "z". See
grdconvert and Sections modifiers-for-CF and grid-file-format of the GMT Technical Reference and Cookbook
for more information, particularly on how to read splices of 3-, 4-, or 5-dimensional grids.

GEOGRAPHICAL AND TIME COORDINATES

       When the output grid type is netCDF, the coordinates will be labeled "longitude", "latitude",  or  "time"
       based  on the attributes of the input data or grid (if any) or on the -f or -R options. For example, both
       -f0x -f1t and -R90w/90e/0t/3t will result in a longitude/time grid. When the x, y,  or  z  coordinate  is
       time, it will be stored in the grid as relative time since epoch as specified by TIME_UNIT and TIME_EPOCH
       in  the  gmt.conf  file or on the command line. In addition, the unit attribute of the time variable will
       indicate both this unit and epoch.

EXAMPLES

       Suppose you have used surface to grid ship gravity in the region between 148E - 162E and 8N  -  32N,  and
       you  do  not trust the gridding near the edges, so you want to keep only the area between 150E - 160E and
       10N - 30N, then:

              gmt grdcut grav_148_162_8_32.nc -Ggrav_150_160_10_30.nc -R150/160/10/30 -V

       To return the subregion of a grid such that any boundary strips where all values are entirely above 0 are
       excluded, try

              gmt grdcut bathy.nc -Gtrimmed_bathy.nc -Z-/0 -V

       To return the subregion of a grid that contains all nodes within a distance of  500  km  from  the  point
       45,30 try

              gmt grdcut bathy.nc -Gsubset_bathy.nc -S45/30/500k -V

COPYRIGHT

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

5.2.1                                           January 28, 2016                                    GRDCUT(1gmt)