## NAME

           grdraster  -  extract  subregion  from a binary raster and
           write a grd file

## SYNOPSIS

           grdraster  [  filenumber  ]  -Rwest/east/south/north[r]  [
           -Ggrdfilename ] [ -Ix_inc[m|c][/y_inc[m|c]] ] [ -Jparams ]
           [ -V ] [ -bo[s][n] ]

## DESCRIPTION

           grdraster reads a  file  called  grdraster.info  from  the
           directory   pointed   to   by  the  environment  parameter
           $GMT_GRIDDIR (if this parameter is not set it defaults  to
           $GMTHOME/share/dbase). The info file defines binary arrays
           of data stored in scan-line format  in  data  files.  Each
           file  is  given  a  filenumber in the info file. grdraster
           figures out how to load the raster data into  a  grd  file
           spanning  a  region  defined  by  -R.  By default the grid
           spacing equals the raster spacing. The -I  option  may  be
           used to sub-sample the raster data. No filtering or inter
           polating is done, however; the x_inc and y_inc of the  grd
           file  must  be  multiples  of the increments of the raster
           file and grdraster simply takes  every  n'th  point.   The
           output  of  grdraster  is either grid or' pixel registered
           depending on the registration of the raster used. It is up
           to  the  GMT  system person to maintain the grdraster.info
           file in accordance with  the  available  rasters  at  each
           site.  Raster  data sets are not supplied with GMT but can
           be obtained by anonymous ftp and  on  cd-rom  (see  README
           page  in  dbase directory). grdraster will list the avail
           able files if no arguments are given.  Finally,  grdraster
           will  write  xyz-triplets  to stdout if no output gridfile
           name is given

           filenumber
                  An integer matching one of the files listed in  the
                  grdraster.info file.

           -R     west,  east, south, and north specify the Region of
                  interest. To specify boundaries in degrees and min
                  utes  [and  seconds],  use  the  dd:mm[:ss] format.
                  Append r if lower left and upper right map  coordi
                  nates are given instead of wesn.  If r is appended,
                  you may also specify a map projection to define the
                  shape  of  your  region.  The output region will be
                  rounded off to the nearest whole grid-step in  both
                  dimensions.

## OPTIONS

           -G     Name of output grid file. If not set, the grid will
                  be written as ASCII (or binary; see -boxyz-triplets
                  to stdout instead.

           -I     x_inc  [and  optionally y_inc] is the grid spacing.
                  Append m to indicate minutes or c to indicate  sec
                  onds.

           -J     Selects  the  map projection. Scale is UNIT/degree,
                  1:xxxxx, or width in UNIT  (upper  case  modifier).
                  UNIT  is  cm,  inch,  or  m,  depending on the MEA
                  SURE_UNIT setting in .gmtdefaults, but this can  be
                  overridden  on the command line by appending the c,
                  i, or m to the scale/width value.

                  CYLINDRICAL PROJECTIONS:

                  -Jclon0/lat0/scale (Cassini)
                  -Jjlon0/scale (Miller)
                  -Jmscale (Mercator - Greenwich and Equator as  ori
                  gin)
                  -Jmlon0/lat0/scale  (Mercator  -  Give meridian and
                  standard parallel)
                  -Joalon0/lat0/azimuth/scale  (Oblique  Mercator   -
                  point and azimuth)
                  -Joblon0/lat0/lon1/lat1/scale  (Oblique  Mercator -
                  two points)
                  -Joclon0/lat0/lonp/latp/scale (Oblique  Mercator  -
                  point and pole)
                  -Jqlon0/scale  (Equidistant  Cylindrical Projection
                  (Plate Carree))
                  -Jtlon0/scale (TM - Transverse Mercator, with Equa
                  tor as y = 0)
                  -Jtlon0/lat0/scale  (TM  - Transverse Mercator, set
                  origin)
                  -Juzone/scale (UTM - Universal Transverse Mercator)
                  -Jylon0/lats/scale (Basic Cylindrical Projection)

                  AZIMUTHAL PROJECTIONS:

                  -Jalon0/lat0/scale (Lambert).
                  -Jelon0/lat0/scale (Equidistant).
                  -Jflon0/lat0/horizon/scale (Gnomonic).
                  -Jglon0/lat0/scale (Orthographic).
                  -Jslon0/lat0/[slat/]scale (General Stereographic)

                  CONIC PROJECTIONS:

                  -Jblon0/lat0/lat1/lat2/scale (Albers)
                  -Jdlon0/lat0/lat1/lat2/scale (Equidistant)
                  -Jllon0/lat0/lat1/lat2/scale (Lambert)

                  MISCELLANEOUS PROJECTIONS:

                  -Jhlon0/scale (Hammer)
                  -Jilon0/scale (Sinusoidal)
                  -Jk[f|s]lon0/scale (Eckert IV (f) and VI (s))
                  -Jnlon0/scale (Robinson)
                  -Jrlon0/scale (Winkel Tripel)
                  -Jvlon0/scale (Van der Grinten)
                  -Jwlon0/scale (Mollweide)

                  NON-GEOGRAPHICAL PROJECTIONS:

                  -Jp[a]scale[/origin]  (polar (theta,r) coordinates,
                  optional a for azimuths and offset theta [0])
                  -Jxx-scale[l|ppow][/y-scale[l|ppow]] (Linear,  log,
                  and power scaling)
                  More  details  can  be  found in the psbasemap man
                  pages.

           -V     Selects verbose  mode,  which  will  send  progress
                  reports to stderr [Default runs "silently"].

           -bo    Selects  binary  output. Append s for single preci
                  sion [Default is double].  This option applies only
                  if no -G option has been set.

## EXAMPLES

           To  extract  data from raster 1, taking one point every 30
           minutes, in an area extended beyond 360 degrees  to  allow
           later filtering, try

           grdraster 1 -R-4/364/-62/62 -I30m -Gdata.grd

           To  obtain data for an oblique Mercator projection we need
           to extract more data that is actually used. This is neces
           sary  because the output of grdraster has edges defined by
           parallels and meridians, while the oblique map in  general
           does  not.  Hence,  to  get  all  the data from data set 3
           needed to make a contour map for the region defined by its
           lower left and upper right corners and the desired projec
           tion, try

           grdraster   3    -R160/20/220/30r    -Joc190/25.5/292/69/1
           -Gdata.grd

           To  extract data from raster 3 and write it as binary dou
           ble precision xyz-triplets to standard output, try

           grdraster 3 -R20/25/-10/5 -bo >! triplets.b
           gmtdefaults(l), gmt(l), grdsample(l), grdfilter(l)

## REFERENCES

           Wessel, P., and W. H. F. Smith, 2001, The Generic  Mapping
           Tools  (GMT)  version  3.4 Technical Reference & Cookbook,
           SOEST/NOAA.
           Wessel, P., and W. H. F. Smith, 1998, New,  Improved  Ver
           sion  of  Generic Mapping Tools Released, EOS Trans., AGU,
           79 (47), p. 579.
           Wessel, P., and W. H. F. Smith, 1995, New Version  of  the
           Generic  Mapping Tools Released, EOS Trans., AGU, 76 (33),
           p. 329.
           Wessel, P., and W. H. F. Smith, 1995, New Version  of  the
           Generic Mapping Tools Released, http: American Geophysical
           Union.
           Wessel, P., and W. H. F. Smith, 1991, Free Software  Helps
           Map and Display Data, EOS Trans., AGU, 72 (41), p. 441.

                                1 Mar 2002               GRDRASTER(l)