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

SEE ALSO

       gmt, grdclip, grdpaste, grdinfo

COPYRIGHT

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