.TH GRDIMAGE 1gmt "15 Jul 2011" "GMT 4.5.7" "Generic Mapping Tools"
.SH NAME
grdimage \- Create grayshaded or colored image from a 2-D netCDF grid file
.SH SYNOPSIS
\fBgrdimage\fP \fIgrd_z\fP | \fIgrd_r grd_g grd_b\fP \fB\-C\fP\fIcptfile\fP [ \fB\-D\fP[\fBr\fP] ] \fB\-J\fP\fIparameters\fP 
[ \fB\-B\fP[\fBp\fP|\fBs\fP]\fIparameters\fP ] [ \fB\-Ei\fP|\fIdpi\fP ] [ \fB\-G\fP[\fBf\fP|\fBb\fP]\fIcolor\fP ] [ \fB\-I\fP\fIintensfile\fP ] 
[ \fB\-K\fP ] [ \fB\-M\fP ] [ \fB\-N\fP ] [ \fB\-O\fP ] [ \fB\-P\fP ] [ \fB\-Q\fP ] [ \fB\-R\fP\fIwest\fP/\fIeast\fP/\fIsouth\fP/\fInorth\fP[\fBr\fP] ] 
[ \fB\-S\fP[\fB-\fP]\fBb\fP|\fBc\fP|\fBl\fP|\fBn\fP[\fB/\fP\fIthreshold\fP] ]
[ \fB\-T\fP ] [ \fB\-U\fP[\fIjust\fP/\fIdx\fP/\fIdy\fP/][\fBc\fP|\fIlabel\fP] ] [ \fB\-V\fP ] 
[ \fB\-X\fP[\fBa\fP|\fBc\fP|\fBr\fP][\fIx-shift\fP[\fBu\fP]] ] [ \fB\-Y\fP[\fBa\fP|\fBc\fP|\fBr\fP][\fIy-shift\fP[\fBu\fP]] ] [ \fB\-c\fP\fIcopies\fP ] [ \fB\-f\fP[\fBi\fP|\fBo\fP]\fIcolinfo\fP ] [ \fB\-r\fP ]
.SH DESCRIPTION
\fBgrdimage\fP 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, \fBgrdimage\fP 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 \fBgrdgradient\fP and, optionally, modified by \fBgrdmath\fP or \fBgrdhisteq\fP.
.br
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 \fB\-E\fP 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 \fB\-S\fP option.
.br
The \fB\-R\fP option can be used to select a map region larger or smaller than that
implied by the extent of the grid.
.br
A (color) \fIPostScript\fP file is output.
.TP
\fIgrd_z\fP | \fIgrd_r grd_g grd_b\fP
2-D gridded data set (or red, green, blue grids) to be imaged
(See GRID FILE FORMATS below.)
.TP
\fB\-C\fP
name of the color palette table (for \fIgrd_z\fP only).
.TP
\fB\-J\fP
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 \fBMEASURE_UNIT\fP setting in \.gmtdefaults4, but this can be
overridden on the command line by appending \fBc\fP, \fBi\fP, or \fBm\fP to the scale/width value.
When central meridian is optional, default is center of longitude range on \fB\-R\fP option.
Default standard parallel is the equator.
For map height, max dimension, or min dimension, append \fBh\fP, \fB+\fP, or \fB-\fP to the width,
respectively.
.br
More details can be found in the \fBpsbasemap\fP man pages.
.br
.sp
\fBCYLINDRICAL PROJECTIONS:\fP
.br
.sp
\fB\-Jc\fP\fIlon0/lat0/scale\fP (Cassini)
.br
\fB\-Jcyl_stere\fP/[\fIlon0/\fP[\fIlat0/\fP]]\fIscale\fP (Cylindrical Stereographic)
.br
\fB\-Jj\fP[\fIlon0/\fP]\fIscale\fP (Miller)
.br
\fB\-Jm\fP[\fIlon0\fP/[\fIlat0/\fP]]\fIscale\fP (Mercator)
.br
\fB\-Jm\fP\fIlon0/lat0/scale\fP (Mercator - Give meridian and standard parallel)
.br
\fB\-Jo\fP[\fBa\fP]\fIlon0/lat0/azimuth/scale\fP (Oblique Mercator - point and azimuth)
.br
\fB\-Jo\fP[\fBb\fP]\fIlon0/lat0/lon1/lat1/scale\fP (Oblique Mercator - two points)
.br
\fB\-Joc\fP\fIlon0/lat0/lonp/latp/scale\fP (Oblique Mercator - point and pole)
.br
\fB\-Jq\fP[\fIlon0/\fP[\fIlat0/\fP]]\fIscale\fP (Cylindrical Equidistant)
.br
\fB\-Jt\fP\fIlon0/\fP[\fIlat0/\fP]\fIscale\fP (TM - Transverse Mercator)
.br
\fB\-Ju\fP\fIzone/scale\fP (UTM - Universal Transverse Mercator)
.br
\fB\-Jy\fP[\fIlon0/\fP[\fIlat0/\fP]]\fIscale\fP (Cylindrical Equal-Area) 
.br
.sp
\fBCONIC PROJECTIONS:\fP
.br
.sp
\fB\-Jb\fP\fIlon0/lat0/lat1/lat2/scale\fP (Albers)
.br
\fB\-Jd\fP\fIlon0/lat0/lat1/lat2/scale\fP (Conic Equidistant)
.br
\fB\-Jl\fP\fIlon0/lat0/lat1/lat2/scale\fP (Lambert Conic Conformal)
.br
\fB\-Jpoly\fP/[\fIlon0/\fP[\fIlat0/\fP]]\fIscale\fP ((American) Polyconic)
.br
.sp
\fBAZIMUTHAL PROJECTIONS:\fP
.br
.sp
\fB\-Ja\fP\fIlon0/lat0\fP[\fI/horizon\fP]\fI/scale\fP (Lambert Azimuthal Equal-Area)
.br
\fB\-Je\fP\fIlon0/lat0\fP[\fI/horizon\fP]\fI/scale\fP (Azimuthal Equidistant)
.br
\fB\-Jf\fP\fIlon0/lat0\fP[\fI/horizon\fP]\fI/scale\fP (Gnomonic)
.br
\fB\-Jg\fP\fIlon0/lat0\fP[\fI/horizon\fP]\fI/scale\fP (Orthographic)
.br
\fB\-Jg\fP\fIlon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale\fP (General Perspective).
.br
\fB\-Js\fP\fIlon0/lat0\fP[\fI/horizon\fP]\fI/scale\fP (General Stereographic)
.br
.sp
\fBMISCELLANEOUS PROJECTIONS:\fP
.br
.sp
\fB\-Jh\fP[\fIlon0/\fP]\fIscale\fP (Hammer)
.br
\fB\-Ji\fP[\fIlon0/\fP]\fIscale\fP (Sinusoidal)
.br
\fB\-Jkf\fP[\fIlon0/\fP]\fIscale\fP (Eckert IV)
.br
\fB\-Jk\fP[\fBs\fP][\fIlon0/\fP]\fIscale\fP (Eckert VI)
.br
\fB\-Jn\fP[\fIlon0/\fP]\fIscale\fP (Robinson)
.br
\fB\-Jr\fP[\fIlon0/\fP]\fIscale\fP (Winkel Tripel)
.br
\fB\-Jv\fP[\fIlon0/\fP]\fIscale\fP (Van der Grinten)
.br
\fB\-Jw\fP[\fIlon0/\fP]\fIscale\fP (Mollweide)
.br
.sp
\fBNON-GEOGRAPHICAL PROJECTIONS:\fP
.br
.sp
\fB\-Jp\fP[\fBa\fP]\fIscale\fP[\fI/origin\fP][\fBr\fP|\fBz\fP] (Polar coordinates (theta,r))
.br
\fB\-Jx\fP\fIx-scale\fP[\fBd\fP|\fBl\fP|\fBp\fP\fIpow\fP|\fBt\fP|\fBT\fP][\fI/y-scale\fP[\fBd\fP|\fBl\fP|\fBp\fP\fIpow\fP|\fBt\fP|\fBT\fP]] (Linear, log, and power scaling)
.br
.SH OPTIONS
No space between the option flag and the associated arguments.
.TP
\fB\-B\fP
Sets map boundary annotation and tickmark intervals; see the
\fBpsbasemap\fP man page for all the details.
.TP
\fB\-D\fP
Specifies that the grid supplied is an image file to be read via GDAL. Obviously this option will work only with \fBGMT\fP
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 \fB\-D\fP 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 \fBr\fP to use the region specified by \fB\-R\fP to apply to the image.
For example, if you have used \fB\-Rd\fP 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).
.TP
\fB\-E\fP
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 \fBi\fP to use the \fIPostScript\fP
image operator to interpolate the image at the device resolution.
.TP
\fB\-G\fP
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 \fB\-Gb\fP) with the given color combination.
(See SPECIFYING COLOR below).
.TP
\fB\-I\fP
Gives the name of a grid file with intensities in the (-1,+1) range. [Default is no illumination].
.TP
\fB\-K\fP
More \fIPostScript\fP code will be appended later [Default terminates the plot system].
.TP
\fB\-M\fP
Force conversion to monochrome image using the (television) YIQ transformation.
Cannot be used with \fB\-Q\fP.
.TP
\fB\-N\fP
Do not clip the image at the map boundary (only relevant for non-rectangular maps).
.TP
\fB\-O\fP
Selects Overlay plot mode [Default initializes a new plot system].
.TP
\fB\-P\fP
Selects Portrait plotting mode [Default is Landscape, see \fBgmtdefaults\fP to change this].
.TP
\fB\-Q\fP
Make grid nodes with z = NaN transparent, using the colormasking feature in \fIPostScript\fP Level 3
(the PS device must support PS Level 3).
.TP
\fB\-R\fP
\fIxmin\fP, \fIxmax\fP, \fIymin\fP, and \fIymax\fP specify the Region of interest.  For geographic
regions, these limits correspond to \fIwest, east, south,\fP and \fInorth\fP and you may specify them
in decimal degrees or in [+-]dd:mm[:ss.xxx][W|E|S|N] format.  Append \fBr\fP if lower left and upper right
map coordinates are given instead of w/e/s/n.  The two shorthands \fB\-Rg\fP and \fB\-Rd\fP 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 \fB\-R\fP 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 \fBTIME_EPOCH\fP and in the selected \fBTIME_UNIT\fP; append \fBt\fP to
\fB\-JX\fP|\fBx\fP), or (b) absolute time of the form [\fIdate\fP]\fBT\fP[\fIclock\fP]
(append \fBT\fP to \fB\-JX\fP|\fBx\fP).  At least one of \fIdate\fP and \fIclock\fP
must be present; the \fBT\fP is always required.  The \fIdate\fP string must be of the form [-]yyyy[-mm[-dd]]
(Gregorian calendar) or yyyy[-Www[-d]] (ISO week calendar), while the \fIclock\fP 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 \fBgmtdefaults\fP). 
You may ask for a larger \fIw/e/s/n\fP 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].
.TP
\fB\-S\fP
Select the interpolation mode by adding \fBb\fP for B-spline smoothing,
\fBc\fP for bicubic interpolation, \fBl\fP for bilinear interpolation, or
\fBn\fP for nearest-neighbor value (for example to plot categorical data).
Optionally, prepend \fB-\fP to switch off antialiasing.
Add \fB/\fP\fIthreshold\fP to control how close to nodes with NaNs the interpolation will go.
A \fIthreshold\fP 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].
.TP
\fB\-T\fP
This option has become OBSOLETE. Use \fBgrdview\fP \fB\-T\fP instead.
Use \fB\-Sn\fP to plot near-neighbor values only (use \fB\-E\fP to increase the resolution).
Use \fB\-Sn\fP \fB\-Q\fP to obtain something similar to the old option \fB\-Ts\fP.
The option \fB\-To\fP is no longer supported.
.TP
\fB\-U\fP
Draw Unix System time stamp on plot.
By adding \fIjust/dx/dy/\fP, 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 \fIlabel\fP, or \fBc\fP (which will plot the command string.).
The \fBGMT\fP parameters \fBUNIX_TIME\fP, \fBUNIX_TIME_POS\fP, and \fBUNIX_TIME_FORMAT\fP can affect the appearance;
see the \fBgmtdefaults\fP man page for details.
The time string will be in the locale set by the environment variable \fBTZ\fP (generally local time).
.TP
\fB\-V\fP
Selects verbose mode, which will send progress reports to stderr [Default runs "silently"].
.TP
\fB\-X\fP \fB\-Y\fP
Shift plot origin relative to the current origin by (\fIx-shift,y-shift\fP) and
optionally append the length unit (\fBc\fP, \fBi\fP, \fBm\fP, \fBp\fP).
You can prepend \fBa\fP to shift the origin back to the original position after plotting,
or prepend  \fBr\fP [Default] to reset the current origin to the new location.
If \fB\-O\fP is used then the default (\fIx-shift,y-shift\fP) is (0,0), otherwise it is
(r1i, r1i) or (r2.5c, r2.5c).
Alternatively, give \fBc\fP to align the center coordinate (x or y) of the plot with the center of the page
based on current page size.
.TP
\fB\-c\fP
Specifies the number of plot copies. [Default is 1].
.TP
\fB\-f\fP
Special formatting of input and/or output columns (time or geographical data).
Specify \fBi\fP or \fBo\fP 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 \fBT\fP (absolute calendar time), \fBt\fP (relative time in chosen \fBTIME_UNIT\fP since \fBTIME_EPOCH\fP),
\fBx\fP (longitude), \fBy\fP (latitude), or \fBf\fP (floating point) to each column
or column range item.  Shorthand \fB\-f\fP[\fBi\fP|\fBo\fP]\fBg\fP means \fB\-f\fP[\fBi\fP|\fBo\fP]0\fBx\fP,1\fBy\fP
(geographic coordinates).
.SH GRID FILE FORMATS
\fBGMT\fP 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 \fBGMT\fP needs a little help with that, you can add the suffix \fB=\fP\fIid\fP[\fB/\fP\fIscale\fP\fB/\fP\fIoffset\fP[\fB/\fP\fInan\fP]],
where \fIid\fP is a two-letter identifier of the grid type and precision, and \fIscale\fP and \fIoffset\fP are optional scale factor
and offset to be applied to all grid values, and \fInan\fP is the value used to indicate missing data.
See \fBgrdreformat\fP(1) and Section 4.17 of the GMT Technical Reference and Cookbook for more information.
.P
When reading a netCDF file that contains multiple grids, \fBGMT\fP will read, by default, the first 2-dimensional grid that can find in that
file. To coax \fBGMT\fP into reading another multi-dimensional variable in the grid file, append \fB?\fP\fIvarname\fP to the file name, where
\fIvarname\fP is the name of the variable. Note that you may need to escape the special meaning of \fB?\fP 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 \fBgrdreformat\fP(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.
.SH 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
\fBgrdimage\fP uses the \fIPostScript\fP 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
\fBgrdview \-Ts\fP instead.
.SH 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:
.br
.sp
\fBgrdimage\fP hawaii_grav.grd \fB\-Jl\fP18/24/1.5\fBc\fP \fB\-C\fPshades.cpt \fB\-B\fP1 > hawaii_grav_image.ps
.br
.sp
To create an illuminated color \fIPostScript\fP 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:
.br
.sp
\fBgrdimage\fP image.grd \fB\-Jx\fP10\fBi\fP \fB\-C\fPcolors.cpt \fB\-I\fPintens.grd \fB\-B\fP5 > image.ps
.br
.sp
To create an false color \fIPostScript\fP 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:
.br
.sp
\fBgrdimage\fP red.grd green.grd blue.grd \fB\-Jx\fP10\fBi\fP \fB\-B\fP5 > rgbimage.ps
.br
.sp
When GDAL support is built in: To create a sinusoidal projection of a remotely located Jessica Rabbit
.br
.sp
\fBgrdimage\fP -JI15c -Rd -Dr http://larryfire.files.wordpress.com/2009/07/untooned_jessicarabbit.jpg -P > jess.ps
.SH "SEE ALSO"
.IR GMT (1),
.IR gmt2rgb (1),
.IR grdcontour (1),
.IR grdview (1),
.IR grdgradient (1),
.IR grdhisteq (1)