grdimage(1) GMT grdimage(1)
NAME
grdimage - Project grids or images and plot them on maps
SYNOPSIS
grdimage grd_z | grd_r grd_g grd_b [ -Aout_img[=driver] ] [
-B[p|s]parameters ] [ -Ccpt ] [ -D[r] ] [ -E[i|dpi] ] -Jparameters
[ -G[f|b]color ] [ -I[intensfile|intensity|modifiers] ] [ -Jz|-Zpa-
rameters ] [ -K ] [ -M ] [ -N ] [ -O ] [ -P ] [ -Q ] [
-Rwest/east/south/north[/zmin/zmax][+r] ] [ -U[stamp] ] [ -V[level] ]
[ -Xx_offset ] [ -Yy_offset ] [ -fflags ] [ -nflags ] [ -pflags ] [
-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 col-
ored) map by plotting rectangles centered on each grid node and assign-
ing 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 com-
ponents directly (all must be in the 0-255 range). Optionally, illumi-
nation 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, modi-
fied 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 refer-
enced 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 coordi-
nates those of the intensity file will be used.
When using map projections, the grid is first resampled on a new rect-
angular 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 pro-
jected back onto the input grid after which a value is interpolated
between the surrounding input grid values. By default bi-cubic interpo-
lation 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 a|)
Select map projection.
OPTIONAL ARGUMENTS
-Aout_img[=driver]
Save an image in a raster format instead of PostScript. Use
extension Append out_img to select the image file name and
extension. If the extension is one of .bmp, .gif, .jpg, .png,
or .tif then no driver information is required. For other out-
put formats you must append the required GDAL driver. The
driver is the driver code name used by GDAL; see your GDAL
installationas documentation for available drivers. Notes: (1)
If a tiff file (.tif) is selected then we will write a GeoTiff
image if the GMT projection syntax translates into a PROJ4 syn-
tax, otherwise a plain tiff file is produced. (2) Any vector
elements will be lost.
-B[p|s]parameters (more a|)
Set map boundary frame and axes attributes.
-Ccpt Name of the CPT (for grd_z only). Alternatively, supply the name
of a GMT color master dynamic CPT [rainbow] to automatically
determine a continuous CPT from the gridas z-range. If the
dynamic CPT has a default range then that range will be imposed
instead. Yet another option is to specify
-Ccolor1,color2[,color3,a|] to build a linear continuous CPT
from those colors automatically. In this case color1 etc 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
ayour_proxy:porta 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 inter-
est of this mode is that you can project a raw image (an image
without referencing coordinates).
-E[i|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 Post-
Script 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.
-I[intensfile|intensity|modifiers]
Gives the name of a grid file with intensities in the (-1,+1)
range, or a constant intensity to apply everywhere; this simply
affects the ambient light. If just + is given then we derive an
intensity grid from the input data grid grd_z via a call to grd-
gradient using the arguments -A-45 and -Nt1 for that module. You
can append +aazimuth and **+n*args to override those values. If
you want more specific intensities then run grdgradient sepa-
rately first. [Default is no illumination].
-Jz|Zparameters (more a|)
Set z-axis scaling; same syntax as -Jx.
-K (more a|)
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 a|)
Append to existing PostScript plot.
-P (more a|)
Select aPortraita 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).
-Rxmin/xmax/ymin/ymax[+r][+uunit] (more a|)
Specify the region of interest.
For perspective view p, optionally append /zmin/zmax. (more a|) 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 a|)
Draw GMT time stamp logo on plot.
-V[level] (more a|)
Select verbosity level [c].
-X[a|c|f|r][x-shift[u]]
-Y[a|c|f|r][y-shift[u]] (more a|)
Shift plot origin.
-f[i|o]colinfo (more a|)
Specify data types of input and/or output columns.
-n[b|c|l|n][+a][+bBC][+c][+tthreshold] (more a|)
Select interpolation mode for grids.
-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more a|)
Select perspective view.
-t[transp] (more a|)
Set PDF transparency level in percent.
-^ or just -
Print a short message about the syntax of the command, then
exits (NOTE: on Windows just use -).
-+ or just +
Print an extensive usage (help) message, including the explana-
tion 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 all options, then exits.
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 apackinga of grids, writing out floating point
data as 1- or 2-byte integers. (more a|)
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 Post-
Script 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 lin-
ear 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 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 to fit the resam-
pled 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 illuminated 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+ -I+ > 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(1), gmt.conf(5), grd2rgb(1), grdcontour(1), grdview(1),
grdgradient(1), grdhisteq(1)
COPYRIGHT
2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
5.4.2 Jun 24, 2017 grdimage(1)
gmt5 5.4.2 - Generated Wed Jun 28 20:19:05 CDT 2017