Provided by: gmt-common_5.2.1+dfsg-3build1_all 
NAME
grdimage - Project grids or images and plot them on maps
SYNOPSIS
grdimage grd_z | grd_r grd_g grd_b [ out_img=driver ] [ cpt ] [ [r] ] [ i[|dpi] ]
parameters [ [f|b]color ] [ intensfile|intensity ] [ z|-Zparameters ] [ ] [ ] [ ] [ ]
[ ] [ ] [ west/east/south/north[/zmin/zmax][r] ] [ ] [ [just/dx/dy/][c|label] ] [
[level] ] [ x_offset ] [ y_offset ] [ -ccopies ] [ -f<flags> ] [ -n<flags> ] [ -p<flags> ]
[ -tr ]
Note: No space is allowed between the option flag and the associated arguments.
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. Yet as a third alternative available
when GMT is build with GDAL support the grd_z file can be an image referenced or not (than
see -Dr). In this case the images can be illuminated with the file provided via the -I
option. Here if image has no coordinates those of the intensity file will be used.
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 -n 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.
REQUIRED ARGUMENTS
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.)
-Jparameters (more ...)
Select map projection.
OPTIONAL ARGUMENTS
-Aout_img=driver
With GDAL aware versions: save image in a raster format instead of PostScript.
Append out_img=driver to select the file name and image format. The driver is the
driver code name used by GDAL. For example, -Aimg.tif=GTiff will write a GeoTiff
image if the subset of GMT syntax projections that is currently possible to
translate into the PROJ4 syntax allows it, or a plain tiff file otherwise. Note:
any vector elements are lost.
-B[p|s]parameters (more ...)
Set map boundary intervals.
-Ccpt Name of the CPT file (for grd_z only). Alternatively, supply the name of a GMT
color master CPT [rainbow] and let grdimage automatically determine a 16-level
continuous CPT from the grid's z-range. Yet another option is to specify
-Ccolor1,color2[,color3,...] to build a linear continuous CPT from those colors
automatically. In this case colorn can be a r/g/b triplet, a color name, or an
HTML hexadecimal color (e.g. #aabbcc ).
-D[r] 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).
-Ei[|dpi]
Sets the resolution of the projected grid that will be created if a map projection
other than Linear or Mercator was selected [100]. 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[f|b]color
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.
-Iintensfile|intensity
Gives the name of a grid file with intensities in the (-1,+1) range, or a constant
intensity to apply everywhere. [Default is no illumination].
-Jz|Zparameters (more ...)
Set z-axis scaling; same syntax as -Jx.
-K (more ...)
Do not finalize the PostScript plot.
-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 (more ...)
Append to existing PostScript plot.
-P (more ...)
Select "Portrait" plot orientation.
-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[unit]xmin/xmax/ymin/ymax[r] (more ...)
Specify the region of interest.
For perspective view p, optionally append /zmin/zmax. (more ...) 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].
-U[just/dx/dy/][c|label] (more ...)
Draw GMT time stamp logo on plot.
-V[level] (more ...)
Select verbosity level [c].
-X[a|c|f|r][x-shift[u]]
-Y[a|c|f|r][y-shift[u]] (more ...)
Shift plot origin.
-ccopies (more ...)
Specify number of plot copies [Default is 1].
-f[i|o]colinfo (more ...)
Specify data types of input and/or output columns.
-n[b|c|l|n][+a][+bBC][+c][+tthreshold] (more ...)
Select interpolation mode for grids.
-p[x|y|z]azim/elev[/zlevel][+wlon0/lat0[/z0]][+vx0/y0] (more ...)
Select perspective view.
-t[transp] (more ...)
Set PDF transparency level in percent.
-^ 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.
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.
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.
CONSEQUENCES OF GRID RESAMPLING
Except for Cartesian cases, we need to resample your geographic grid onto an equidistant
projected grid. In doing so various algorithms come into play that projects data from one
lattice to another while avoiding anti-aliasing, leading to possible distortions. One
expected effect of resampling with splines is the tendency for the new resampled grid to
slightly exceed the global min/max limits of the original grid. If this is coupled with
tight CPT file limits you may find that some map areas may show up with fore- or
background color due to the resampling. In that case you have two options: (1) Modify
your CPT file to fit the resampled extrema (reported with -V) or (2) Impose clipping of
resampled values so they do not exceed the input min/max values (add +c to your -n
option).
EXAMPLES
For a quick-and-dirty color map of the data in the file stuff.nc, with the maximum map
dimension limited to be 6 inches, try
gmt grdimage stuff.nc -JX6i+ > quick.ps
To gray-shade the file hawaii_grav.nc 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:
gmt grdimage hawaii_grav.nc -Jl18/24/1.5c -Cshades.cpt -B1 > hawaii_grav_image.ps
To create an illuminated color PostScript plot of the gridded data set image.nc, using the
intensities provided by the file intens.nc, and color levels in the file colors.cpt, with
linear scaling at 10 inch/x-unit, tickmarks every 5 units:
gmt grdimage image.nc -Jx10i -Ccolors.cpt -Iintens.nc -B5 > image.ps
To create an false color PostScript plot from the three grid files red.nc, green.nc, and
blue.nc, with linear scaling at 10 inch/x-unit, tickmarks every 5 units:
gmt grdimage red.nc green.nc blue.nc -Jx10i -B5 > rgbimage.ps
When GDAL support is built in: To create a sinusoidal projection of a remotely located
Jessica Rabbit
gmt grdimage -JI15c -Rd -Dr
http://larryfire.files.wordpress.com/2009/07/untooned_jessicarabbit.jpg \
-P > jess.ps
SEE ALSO
gmt, gmt.conf, grd2rgb, grdcontour, grdview, grdgradient, grdhisteq
COPYRIGHT
2015, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe