Provided by: gmt_4.5.11-1build1_amd64 bug

NAME

       grdimage - Create grayshaded or colored image from a 2-D netCDF grid file

SYNOPSIS

       grdimage  grd_z | grd_r grd_g grd_b -Ccptfile [ -D[r] ] -Jparameters [ -B[p|s]parameters ]
       [ -Ei|dpi ] [ -G[f|b]color ] [ -Iintensfile ] [ -K ] [ -M ] [ -N ] [ -O ] [ -P ] [ -Q ]  [
       -Rwest/east/south/north[r]    ]    [    -S[-]b|c|l|n[/threshold]    ]    [    -T    ]    [
       -U[just/dx/dy/][c|label] ] [ -V ] [ -X[a|c|r][x-shift[u]] ] [  -Y[a|c|r][y-shift[u]]  ]  [
       -ccopies ] [ -f[i|o]colinfo ] [ -r ]

DESCRIPTION

       grdimage  reads  one 2-D grid file and produces a gray-shaded (or colored) map by plotting
       rectangles centered on each grid node and assigning them a gray-shade (or color) based  on
       the  z-value.  Alternatively, grdimage reads three 2-D grid files with the red, green, and
       blue components directly (all must be in the 0-255 range). Optionally, illumination may be
       added  by  providing  a  file  with intensities in the (-1,+1) range.  Values outside this
       range will be  clipped.   Such  intensity  files  can  be  created  from  the  grid  using
       grdgradient and, optionally, modified by grdmath or grdhisteq.
       When using map projections, the grid is first resampled on a new rectangular grid with the
       same dimensions. Higher resolution images can be obtained by  using  the  -E  option.   To
       obtain  the  resampled value (and hence shade or color) of each map pixel, 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 pixel, their average will dominate in the calculation of the pixel
       value. Interpolation and aliasing is controlled with the -S option.
       The -R option can be used to select a map region larger or smaller than  that  implied  by
       the extent of the grid.
       A (color) PostScript file is output.

       grd_z | grd_r grd_g grd_b
              2-D  gridded  data  set  (or  red,  green,  blue grids) to be imaged (See GRID FILE
              FORMATS below.)

       -C     name of the color palette table (for grd_z only).

       -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.

       -B     Sets map boundary annotation and tickmark intervals; see the psbasemap man page for
              all the details.

       -D     Specifies  that  the  grid supplied is an image file to be read via GDAL. Obviously
              this option will work only with GMT versions built with GDAL support. The image can
              be  indexed  or true color (RGB) and can be an URL of a remotely located file. That
              is -D http://www.somewhere.com/image.jpg is a valid file  syntax.   Note,  however,
              that to use it this way you must not be blocked by a proxy. If you are, chances are
              good that it can work by setting the environmental  variable  http_proxy  with  the
              value  'your_proxy:port' Append r to use the region specified by -R to apply to the
              image.  For example, if you have used -Rd then  the  image  will  be  assigned  the
              limits  of a global domain. The interest of this mode is that you can project a raw
              image (an image without referencing coordinates).

       -E     Sets the resolution of the projected grid that will be created if a map  projection
              other than Linear or Mercator was selected.  By default, the projected grid will be
              of the same size (rows and columns) as the  input  file.   Specify  i  to  use  the
              PostScript image operator to interpolate the image at the device resolution.

       -G     This  option  only applies when the resulting image otherwise would consist of only
              two colors: black (0) and white (255).  If so, this option  will  instead  use  the
              image  as a transparent mask and paint the mask (or its inverse, with -Gb) with the
              given color combination.  (See SPECIFYING COLOR below).

       -I     Gives the name of a grid file with intensities in the (-1,+1) range. [Default is no
              illumination].

       -K     More PostScript code will be appended later [Default terminates the plot system].

       -M     Force  conversion  to  monochrome  image using the (television) YIQ transformation.
              Cannot be used with -Q.

       -N     Do not clip the image at the map boundary (only relevant for non-rectangular maps).

       -O     Selects Overlay plot mode [Default initializes a new plot system].

       -P     Selects Portrait plotting mode [Default is Landscape,  see  gmtdefaults  to  change
              this].

       -Q     Make  grid  nodes  with  z  =  NaN  transparent,  using the colormasking feature in
              PostScript Level 3 (the PS device must support PS Level 3).

       -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  for  a  larger w/e/s/n region to have more room between the image and the
              axes.  A smaller region than specified in the grid file will result in a subset  of
              the grid [Default is the region given by the grid file].

       -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].

       -T     This option has become OBSOLETE. Use grdview -T instead.  Use  -Sn  to  plot  near-
              neighbor  values  only  (use  -E to increase the resolution).  Use -Sn -Q to obtain
              something similar to the old option -Ts.  The option -To is no longer supported.

       -U     Draw Unix System time stamp on plot.  By adding just/dx/dy/, the user  may  specify
              the justification of the stamp and where the stamp should fall on the page relative
              to lower left corner of the plot.  For example, BL/0/0 will align  the  lower  left
              corner  of  the  time  stamp  with  the lower left corner of the plot.  Optionally,
              append a label, or c (which will plot the command  string.).   The  GMT  parameters
              UNIX_TIME,  UNIX_TIME_POS,  and UNIX_TIME_FORMAT can affect the appearance; see the
              gmtdefaults man page for details.  The time string will be in the locale set by the
              environment variable TZ (generally local time).

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

       -X -Y  Shift  plot  origin  relative  to  the  current  origin  by  (x-shift,y-shift)  and
              optionally  append  the  length  unit (c, i, m, p).  You can prepend a to shift the
              origin back to the original position after plotting, or  prepend   r  [Default]  to
              reset  the  current origin to the new location.  If -O is used then the default (x-
              shift,y-shift)  is  (0,0),  otherwise  it  is  (r1i,  r1i)   or   (r2.5c,   r2.5c).
              Alternatively,  give c to align the center coordinate (x or y) of the plot with the
              center of the page based on current page size.

       -c     Specifies the number of plot copies. [Default is 1].

       -f     Special formatting of input and/or output  columns  (time  or  geographical  data).
              Specify  i  or  o  to  make  this apply only to input or output [Default applies to
              both].  Give one or more columns (or column ranges) separated by commas.  Append  T
              (absolute calendar time), t (relative time in chosen TIME_UNIT since TIME_EPOCH), x
              (longitude), y (latitude), or f (floating point) to each  column  or  column  range
              item.  Shorthand -f[i|o]g means -f[i|o]0x,1y (geographic coordinates).

GRID FILE FORMATS

       GMT  is  able  to  recognize  many  of the commonly used grid file formats, as well as the
       precision, scale and offset of the values contained in the grid file.  When  GMT  needs  a
       little help with that, you can 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.  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.  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.

IMAGING GRIDS WITH NANS

       Be aware that if your input grid contains patches of NaNs, these patches can become larger
       as  a  consequence  of  the  resampling  that  must  take place with most map projections.
       Because grdimage uses the PostScript colorimage operator, for most non-linear  projections
       we  must resample your grid onto an equidistant rectangular lattice.  If you find that the
       NaN areas are not treated adequately, consider (a) use a linear  projection,  or  (b)  use
       grdview -Ts instead.

EXAMPLES

       To gray-shade the file hawaii_grav.grd with shades given in shades.cpt on a Lambert map at
       1.5 cm/degree along the standard parallels 18 and 24, and using 1 degree tickmarks:

       grdimage hawaii_grav.grd -Jl 18/24/1.5c -C shades.cpt -B 1 > hawaii_grav_image.ps

       To create an illuminated color PostScript plot of the gridded data  set  image.grd,  using
       the  intensities provided by the file intens.grd, and color levels in the file colors.cpt,
       with linear scaling at 10 inch/x-unit, tickmarks every 5 units:

       grdimage image.grd -Jx 10i -C colors.cpt -I intens.grd -B 5 > image.ps

       To create an false color PostScript plot from the three grid files red.grd, green.grd, and
       blue.grd, with linear scaling at 10 inch/x-unit, tickmarks every 5 units:

       grdimage red.grd green.grd blue.grd -Jx 10i -B 5 > rgbimage.ps

       When  GDAL  support  is  built in: To create a sinusoidal projection of a remotely located
       Jessica Rabbit

       grdimage                       -JI15c                       -Rd                        -Dr
       http://larryfire.files.wordpress.com/2009/07/untooned_jessicarabbit.jpg -P > jess.ps

SEE ALSO

       GMT(1), gmt2rgb(1), grdcontour(1), grdview(1), grdgradient(1), grdhisteq(1)