Provided by: gmt_4.5.11-1build1_amd64 bug

NAME

       grdproject - Forward and Inverse map transformation of 2-D grid files

SYNOPSIS

       grdproject  in_grdfile  -Gout_grdfile  -Jparameters  [  -A[k|m|n|i|c|p]  ] [ -C[dx/dy] ] [
       -Dxinc[unit][=|+][/yinc[unit][=|+]] ] [ -Edpi ] [ -F ] [ -I ] [ -Mc|i|m|p ] [ -Nnx/ny ]  [
       -Rwest/east/south/north[r] ] [ -S[-]b|c|l|n[/threshold] ] [ -V ]

DESCRIPTION

       grdproject  will  do one of two things depending whether -I has been set.  If set, it will
       transform a gridded data set from a rectangular  coordinate  system  onto  a  geographical
       system  by  resampling  the  surface  at  the  new  nodes.   If not set, it will project a
       geographical gridded data set onto a rectangular grid.  To obtain the value  at  each  new
       node,  its location is inversely projected back onto the input grid after which a value is
       interpolated between the surrounding input grid values. By default bi-cubic  interpolation
       is  used.   Aliasing is avoided by also forward projecting the input grid nodes. If two or
       more nodes are projected onto the same new  node,  their  average  will  dominate  in  the
       calculation  of  the  new node value. Interpolation and aliasing is controlled with the -S
       option.  The new node spacing may be determined in one of several ways by  specifying  the
       grid spacing, number of nodes, or resolution.  Nodes not constrained by input data are set
       to NaN.
       The -R option can be used to select a map region larger or smaller than  that  implied  by
       the extent of the grid file.

       in_grdfile
              2-D binary grid file to be transformed.  (See GRID FILE FORMATS below.)

       -G     Specify the name of the output grid file.  (See GRID FILE FORMATS below.)

       -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 MEASURE_UNIT  setting  in
              .gmtdefaults4, but this can be overridden on the command line by appending c, i, or
              m to the scale/width value.  When central meridian is optional, default  is  center
              of  longitude  range  on -R option.  Default standard parallel is the equator.  For
              map height, max dimension, or min dimension, append  h,  +,  or  -  to  the  width,
              respectively.
              More details can be found in the psbasemap man pages.

              CYLINDRICAL PROJECTIONS:

              -Jclon0/lat0/scale (Cassini)
              -Jcyl_stere/[lon0/[lat0/]]scale (Cylindrical Stereographic)
              -Jj[lon0/]scale (Miller)
              -Jm[lon0/[lat0/]]scale (Mercator)
              -Jmlon0/lat0/scale (Mercator - Give meridian and standard parallel)
              -Jo[a]lon0/lat0/azimuth/scale (Oblique Mercator - point and azimuth)
              -Jo[b]lon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
              -Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and pole)
              -Jq[lon0/[lat0/]]scale (Cylindrical Equidistant)
              -Jtlon0/[lat0/]scale (TM - Transverse Mercator)
              -Juzone/scale (UTM - Universal Transverse Mercator)
              -Jy[lon0/[lat0/]]scale (Cylindrical Equal-Area)

              CONIC PROJECTIONS:

              -Jblon0/lat0/lat1/lat2/scale (Albers)
              -Jdlon0/lat0/lat1/lat2/scale (Conic Equidistant)
              -Jllon0/lat0/lat1/lat2/scale (Lambert Conic Conformal)
              -Jpoly/[lon0/[lat0/]]scale ((American) Polyconic)

              AZIMUTHAL PROJECTIONS:

              -Jalon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)
              -Jelon0/lat0[/horizon]/scale (Azimuthal Equidistant)
              -Jflon0/lat0[/horizon]/scale (Gnomonic)
              -Jglon0/lat0[/horizon]/scale (Orthographic)
              -Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale (General Perspective).
              -Jslon0/lat0[/horizon]/scale (General Stereographic)

              MISCELLANEOUS PROJECTIONS:

              -Jh[lon0/]scale (Hammer)
              -Ji[lon0/]scale (Sinusoidal)
              -Jkf[lon0/]scale (Eckert IV)
              -Jk[s][lon0/]scale (Eckert VI)
              -Jn[lon0/]scale (Robinson)
              -Jr[lon0/]scale (Winkel Tripel)
              -Jv[lon0/]scale (Van der Grinten)
              -Jw[lon0/]scale (Mollweide)

              NON-GEOGRAPHICAL PROJECTIONS:

              -Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))
              -Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]] (Linear, log, and power scaling)

OPTIONS

       No space between the option flag and the associated arguments.

       -A     Force  1:1  scaling,  i.e.,  output (or input, see -I) data are in actual projected
              meters.  To specify other units, append k  (km),  m  (mile),n  (nautical  mile),  i
              (inch),  c  (cm),  or p (points).  Without -A, the output (or input, see -I) are in
              the units specified by MEASURE_UNIT (but see -M).

       -C     Let projected coordinates be relative to projection center [Default is relative  to
              lower left corner].  Optionally, add offsets in the projected units to be added (or
              subtracted when -I is set) to (from)  the  projected  coordinates,  such  as  false
              eastings and northings for particular projection zones [0/0].

       -D     x_inc  [and  optionally  y_inc]  is  the  grid spacing. Optionally, append a suffix
              modifier.  Geographical (degrees) coordinates: Append m to indicate arc minutes  or
              c  to indicate arc seconds.  If one of the units e, k, i, or n is appended instead,
              the increment is assumed to be given  in  meter,  km,  miles,  or  nautical  miles,
              respectively,  and  will  be  converted  to the equivalent degrees longitude at the
              middle latitude of the region (the conversion depends on ELLIPSOID).  If /y_inc  is
              given  but set to 0 it will be reset equal to x_inc; otherwise it will be converted
              to degrees latitude.  All coordinates: If = is appended then the corresponding  max
              x  (east)  or y (north) may be slightly adjusted to fit exactly the given increment
              [by default the increment may be  adjusted  slightly  to  fit  the  given  domain].
              Finally, instead of giving an increment you may specify the number of nodes desired
              by appending + to the supplied integer argument; the increment is then recalculated
              from  the number of nodes and the domain.  The resulting increment value depends on
              whether you have selected  a  gridline-registered  or  pixel-registered  grid;  see
              Appendix  B  for details.  Note: if -Rgrdfile is used then grid spacing has already
              been initialized; use -D to override the values.

       -E     Set the resolution for the new grid in dots per inch.

       -F     Toggle between pixel and gridline node registration [Default is same as input].

       -I     Do the Inverse transformation, from rectangular to geographical.

       -M     Append c, i, or m to indicate that cm, inch,  or  meter  should  be  the  projected
              measure  unit  [Default  is  set by MEASURE_UNIT in .gmtdefaults4].  Cannot be used
              with -A.

       -N     Set the number of grid nodes in the new grid.

       -R     xmin, xmax, ymin, and ymax specify the Region of interest.  For geographic regions,
              these limits correspond to west, east, south, and north and you may specify them in
              decimal degrees or in [+-]dd:mm[:ss.xxx][W|E|S|N] format.  Append r if  lower  left
              and  upper  right map coordinates are given instead of w/e/s/n.  The two shorthands
              -Rg and -Rd stand for global domain (0/360 and -180/+180 in longitude respectively,
              with  -90/+90  in  latitude).   Alternatively, specify the name of an existing grid
              file and the -R settings (and grid spacing, if  applicable)  are  copied  from  the
              grid.   For  calendar  time  coordinates  you  may  either  give  (a) relative time
              (relative to the selected TIME_EPOCH and in the selected  TIME_UNIT;  append  t  to
              -JX|x),  or  (b)  absolute time of the form [date]T[clock] (append T to -JX|x).  At
              least one of date and clock must be present; the T is always  required.   The  date
              string must be of the form [-]yyyy[-mm[-dd]] (Gregorian calendar) or yyyy[-Www[-d]]
              (ISO week calendar), while the clock string must be  of  the  form  hh:mm:ss[.xxx].
              The  use  of  delimiters  and their type and positions must be exactly as indicated
              (however, input, output and plot formats are customizable; see  gmtdefaults).   You
              may  ask to project only a subset of the grid by specifying a smaller input w/e/s/n
              region [Default is the region given by the grid file].  Special case  for  the  UTM
              projection:  If  -C  and  -I are used and -R is not given then the region is set to
              coincide with the given UTM zone so as to preserve the  full  ellipsoidal  solution
              (See RESTRICTIONS for more information).

       -S     Select  the  interpolation  mode  by adding b for B-spline smoothing, c for bicubic
              interpolation, l for bilinear interpolation, or n for nearest-neighbor  value  (for
              example   to   plot  categorical  data).   Optionally,  prepend  -  to  switch  off
              antialiasing.  Add  /threshold  to  control  how  close  to  nodes  with  NaNs  the
              interpolation will go.  A threshold of 1.0 requires all (4 or 16) nodes involved in
              interpolation to be non-NaN. 0.5 will interpolate about half  way  from  a  non-NaN
              value;  0.1  will  go about 90% of the way, etc.  [Default is bicubic interpolation
              with antialiasing and a threshold of 0.5].

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

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 2- or 4-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.  When
       reading grids, the format is generally automatically recognized. If not, the  same  suffix
       can  be  added  to  input grid file names.  See grdreformat(1) and Section 4.17 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
       grdreformat(1)  and  Section  4.18  of  the  GMT Technical Reference and Cookbook for more
       information, particularly on how to read splices of 3-, 4-, or 5-dimensional grids.

EXAMPLES

       To transform the geographical grid dbdb5.grd onto a pixel Mercator grid at 300 dpi, run

       grdproject dbdb5.grd -R 20/50/12/25 -Jm 0.25i -E 300 -F -G dbdb5_merc.grd

       To inversely transform the file topo_tm.grd back onto a geographical grid, use

       grdproject topo_tm.grd -R-80/-70/20/40 -Jt-75/1:500000 -I -D 5m -V -G topo.grd

       This assumes, of course, that the coordinates in topo_tm.grd were created  with  the  same
       projection parameters.
       To  inversely  transform  the  file  topo_utm.grd  (which  is  in  UTM  meters)  back to a
       geographical grid we specify a one-to-one mapping with meter as the measure unit:

       grdproject topo_utm.grd -R 203/205/60/65 -Ju 5/1:1 -I -Mm -G topo.grd -V

RESTRICTIONS

       The boundaries of a projected (rectangular) data set will not necessarily give rectangular
       geographical  boundaries  (Mercator  is  one exception).  In those cases some nodes may be
       unconstrained (set to NaN).  To get a full grid back, your input grid may have to cover  a
       larger area than you are interested in.
       For some projections, a spherical solution may be used despite the user having selected an
       ellipsoid.  This occurs when the users -R setting implies a region that exceeds the domain
       in  which  the  ellipsoidal  series  expansions  are valid.  These are the conditions: (1)
       Lambert Conformal Conic (-JL) and Albers Equal-Area (-JB) will use the spherical  solution
       when  the  map scale exceeds 1.0E7.  (2) Transverse Mercator (-JT) and UTM (-JU) will will
       use the spherical solution when either the west or east boundary given in -R is more  than
       10  degrees  from the central meridian, and (3) same for Cassini (-JC) but with a limit of
       only 4 degrees.

SEE ALSO

       GMT(1), gmtdefaults(1), mapproject(1)