1GRDIMAGE(1) Generic Mapping Tools GRDIMAGE(1)
2
6 grdimage - Create grayshaded or colored image from a 2-D netCDF grid
7 file
8
10 grdimage grd_z | grd_r grd_g grd_b -Ccptfile [ -D[r] ] -Jparameters [
11 -B[p|s]parameters ] [ -Ei|dpi ] [ -G[f|b]color ] [ -Iintensfile ] [ -K
12 ] [ -M ] [ -N ] [ -O ] [ -P ] [ -Q ] [ -Rwest/east/south/north[r] ] [
13 -S[-]b|c|l|n[/threshold] ] [ -T ] [ -U[just/dx/dy/][c|label] ] [ -V ] [
14 -X[a|c|r][x-shift[u]] ] [ -Y[a|c|r][y-shift[u]] ] [ -ccopies ] [
15 -f[i|o]colinfo ] [ -r ]
16
18 grdimage reads one 2-D grid file and produces a gray-shaded (or col‐
19 ored) map by plotting rectangles centered on each grid node and assign‐
20 ing them a gray-shade (or color) based on the z-value. Alternatively,
21 grdimage reads three 2-D grid files with the red, green, and blue com‐
22 ponents directly (all must be in the 0-255 range). Optionally, illumi‐
23 nation may be added by providing a file with intensities in the (-1,+1)
24 range. Values outside this range will be clipped. Such intensity
25 files can be created from the grid using grdgradient and, optionally,
26 modified by grdmath or grdhisteq.
27 When using map projections, the grid is first resampled on a new rec‐
28 tangular grid with the same dimensions. Higher resolution images can be
29 obtained by using the -E option. To obtain the resampled value (and
30 hence shade or color) of each map pixel, its location is inversely pro‐
31 jected back onto the input grid after which a value is interpolated
32 between the surrounding input grid values. By default bi-cubic interpo‐
33 lation is used. Aliasing is avoided by also forward projecting the
34 input grid nodes. If two or more nodes are projected onto the same
35 pixel, their average will dominate in the calculation of the pixel
36 value. Interpolation and aliasing is controlled with the -S option.
37 The -R option can be used to select a map region larger or smaller than
38 that implied by the extent of the grid.
39 A (color) PostScript file is output.
40 grd_z | grd_r grd_g grd_b
42 2-D gridded data set (or red, green, blue grids) to be imaged
43 (See GRID FILE FORMATS below.)
44 -C name of the color palette table (for grd_z only).
46 -J Selects the map projection. Scale is UNIT/degree, 1:xxxxx, or
48 width in UNIT (upper case modifier). UNIT is cm, inch, or m,
49 depending on the MEASURE_UNIT setting in .gmtdefaults4, but this
50 can be overridden on the command line by appending c, i, or m to
51 the scale/width value. When central meridian is optional,
52 default is center of longitude range on -R option. Default
53 standard parallel is the equator. For map height, max dimen‐
54 sion, or min dimension, append h, +, or - to the width, respec‐
55 tively.
56 More details can be found in the psbasemap man pages.
57 CYLINDRICAL PROJECTIONS:
59 -Jclon0/lat0/scale (Cassini)
61 -Jcyl_stere/[lon0/[lat0/]]scale (Cylindrical Stereographic)
62 -Jj[lon0/]scale (Miller)
63 -Jm[lon0/[lat0/]]scale (Mercator)
64 -Jmlon0/lat0/scale (Mercator - Give meridian and standard paral‐
65 lel)
66 -Jo[a]lon0/lat0/azimuth/scale (Oblique Mercator - point and
67 azimuth)
68 -Jo[b]lon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
69 -Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and
70 pole)
71 -Jq[lon0/[lat0/]]scale (Cylindrical Equidistant)
72 -Jtlon0/[lat0/]scale (TM - Transverse Mercator)
73 -Juzone/scale (UTM - Universal Transverse Mercator)
74 -Jy[lon0/[lat0/]]scale (Cylindrical Equal-Area)
75 CONIC PROJECTIONS:
77 -Jblon0/lat0/lat1/lat2/scale (Albers)
79 -Jdlon0/lat0/lat1/lat2/scale (Conic Equidistant)
80 -Jllon0/lat0/lat1/lat2/scale (Lambert Conic Conformal)
81 -Jpoly/[lon0/[lat0/]]scale ((American) Polyconic)
82 AZIMUTHAL PROJECTIONS:
84 -Jalon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)
86 -Jelon0/lat0[/horizon]/scale (Azimuthal Equidistant)
87 -Jflon0/lat0[/horizon]/scale (Gnomonic)
88 -Jglon0/lat0[/horizon]/scale (Orthographic)
89 -Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale
90 (General Perspective).
91 -Jslon0/lat0[/horizon]/scale (General Stereographic)
92 MISCELLANEOUS PROJECTIONS:
94 -Jh[lon0/]scale (Hammer)
96 -Ji[lon0/]scale (Sinusoidal)
97 -Jkf[lon0/]scale (Eckert IV)
98 -Jk[s][lon0/]scale (Eckert VI)
99 -Jn[lon0/]scale (Robinson)
100 -Jr[lon0/]scale (Winkel Tripel)
101 -Jv[lon0/]scale (Van der Grinten)
102 -Jw[lon0/]scale (Mollweide)
103 NON-GEOGRAPHICAL PROJECTIONS:
105 -Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))
107 -Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]] (Linear, log,
108 and power scaling)
109
111 No space between the option flag and the associated arguments.
112 -B Sets map boundary annotation and tickmark intervals; see the
114 psbasemap man page for all the details.
115 -D Specifies that the grid supplied is an image file to be read via
117 GDAL. Obviously this option will work only with GMT versions
118 built with GDAL support. The image can be indexed or true color
119 (RGB) and can be an URL of a remotely located file. That is -D
120 http://www.somewhere.com/image.jpg is a valid file syntax.
121 Note, however, that to use it this way you must not be blocked
122 by a proxy. If you are, chances are good that it can work by
123 setting the environmental variable http_proxy with the value
124 'your_proxy:port' Append r to use the region specified by -R to
125 apply to the image. For example, if you have used -Rd then the
126 image will be assigned the limits of a global domain. The inter‐
127 est of this mode is that you can project a raw image (an image
128 without referencing coordinates).
129 -E Sets the resolution of the projected grid that will be created
131 if a map projection other than Linear or Mercator was selected.
132 By default, the projected grid will be of the same size (rows
133 and columns) as the input file. Specify i to use the PostScript
134 image operator to interpolate the image at the device resolu‐
135 tion.
136 -G This option only applies when the resulting image otherwise
138 would consist of only two colors: black (0) and white (255). If
139 so, this option will instead use the image as a transparent mask
140 and paint the mask (or its inverse, with -Gb) with the given
141 color combination. (See SPECIFYING COLOR below).
142 -I Gives the name of a grid file with intensities in the (-1,+1)
144 range. [Default is no illumination].
145 -K More PostScript code will be appended later [Default terminates
147 the plot system].
148 -M Force conversion to monochrome image using the (television) YIQ
150 transformation.
151 -N Do not clip the image at the map boundary (only relevant for
153 non-rectangular maps).
154 -O Selects Overlay plot mode [Default initializes a new plot sys‐
156 tem].
157 -P Selects Portrait plotting mode [Default is Landscape, see gmtde‐
159 faults to change this].
160 -Q Make grid nodes with z = NaN transparent, using the colormasking
162 feature in PostScript Level 3 (the PS device must support PS
163 Level 3).
164 -R xmin, xmax, ymin, and ymax specify the Region of interest. For
166 geographic regions, these limits correspond to west, east,
167 south, and north and you may specify them in decimal degrees or
168 in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower left
169 and upper right map coordinates are given instead of w/e/s/n.
170 The two shorthands -Rg and -Rd stand for global domain (0/360
171 and -180/+180 in longitude respectively, with -90/+90 in lati‐
172 tude). Alternatively, specify the name of an existing grid file
173 and the -R settings (and grid spacing, if applicable) are copied
174 from the grid. For calendar time coordinates you may either
175 give (a) relative time (relative to the selected TIME_EPOCH and
176 in the selected TIME_UNIT; append t to -JX|x), or (b) absolute
177 time of the form [date]T[clock] (append T to -JX|x). At least
178 one of date and clock must be present; the T is always required.
179 The date string must be of the form [-]yyyy[-mm[-dd]] (Gregorian
180 calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock
181 string must be of the form hh:mm:ss[.xxx]. The use of delim‐
182 iters and their type and positions must be exactly as indicated
183 (however, input, output and plot formats are customizable; see
184 gmtdefaults). You may ask for a larger w/e/s/n region to have
185 more room between the image and the axes. A smaller region than
186 specified in the grid file will result in a subset of the grid
187 [Default is the region given by the grid file].
188 -S Select the interpolation mode by adding b for B-spline smooth‐
190 ing, c for bicubic interpolation, l for bilinear interpolation,
191 or n for nearest-neighbor value (for example to plot categorical
192 data). Optionally, prepend - to switch off antialiasing. Add
193 /threshold to control how close to nodes with NaNs the interpo‐
194 lation will go. A threshold of 1.0 requires all (4 or 16) nodes
195 involved in interpolation to be non-NaN. 0.5 will interpolate
196 about half way from a non-NaN value; 0.1 will go about 90% of
197 the way, etc. [Default is bicubic interpolation with antialias‐
198 ing and a threshold of 0.5].
199 -T This option has become OBSOLETE. Use grdview -T instead. Use
201 -Sn to plot near-neighbor values only (use -E to increase the
202 resolution). Use -Sn -Q to obtain something similar to the old
203 option -Ts. The option -To is no longer supported.
204 -U Draw Unix System time stamp on plot. By adding just/dx/dy/, the
206 user may specify the justification of the stamp and where the
207 stamp should fall on the page relative to lower left corner of
208 the plot. For example, BL/0/0 will align the lower left corner
209 of the time stamp with the lower left corner of the plot.
210 Optionally, append a label, or c (which will plot the command
211 string.). The GMT parameters UNIX_TIME, UNIX_TIME_POS, and
212 UNIX_TIME_FORMAT can affect the appearance; see the gmtdefaults
213 man page for details. The time string will be in the locale set
214 by the environment variable TZ (generally local time).
215 -V Selects verbose mode, which will send progress reports to stderr
217 [Default runs "silently"].
218 -X -Y Shift plot origin relative to the current origin by (x-shift,y-
220 shift) and optionally append the length unit (c, i, m, p). You
221 can prepend a to shift the origin back to the original position
222 after plotting, or prepend r [Default] to reset the current
223 origin to the new location. If -O is used then the default (x-
224 shift,y-shift) is (0,0), otherwise it is (r1i, r1i) or (r2.5c,
225 r2.5c). Alternatively, give c to align the center coordinate (x
226 or y) of the plot with the center of the page based on current
227 page size.
228 -c Specifies the number of plot copies. [Default is 1].
230 -f Special formatting of input and/or output columns (time or geo‐
232 graphical data). Specify i or o to make this apply only to
233 input or output [Default applies to both]. Give one or more
234 columns (or column ranges) separated by commas. Append T (abso‐
235 lute calendar time), t (relative time in chosen TIME_UNIT since
236 TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
237 to each column or column range item. Shorthand -f[i|o]g means
238 -f[i|o]0x,1y (geographic coordinates).
239
241 GMT is able to recognize many of the commonly used grid file formats,
242 as well as the precision, scale and offset of the values contained in
243 the grid file. When GMT needs a little help with that, you can add the
244 suffix =id[/scale/offset[/nan]], where id is a two-letter identifier of
245 the grid type and precision, and scale and offset are optional scale
246 factor and offset to be applied to all grid values, and nan is the
247 value used to indicate missing data. See grdreformat(1) and Section
248 4.17 of the GMT Technical Reference and Cookbook for more information.
249 When reading a netCDF file that contains multiple grids, GMT will read,
251 by default, the first 2-dimensional grid that can find in that file. To
252 coax GMT into reading another multi-dimensional variable in the grid
253 file, append ?varname to the file name, where varname is the name of
254 the variable. Note that you may need to escape the special meaning of ?
255 in your shell program by putting a backslash in front of it, or by
256 placing the filename and suffix between quotes or double quotes. See
257 grdreformat(1) and Section 4.18 of the GMT Technical Reference and
258 Cookbook for more information, particularly on how to read splices of
259 3-, 4-, or 5-dimensional grids.
260
262 Be aware that if your input grid contains patches of NaNs, these
263 patches can become larger as a consequence of the resampling that must
264 take place with most map projections. Because grdimage uses the Post‐
265 Script colorimage operator, for most non-linear projections we must
266 resample your grid onto an equidistant rectangular lattice. If you
267 find that the NaN areas are not treated adequately, consider (a) use a
268 linear projection, or (b) use grdview -Ts instead.
269
271 To gray-shade the file hawaii_grav.grd with shades given in shades.cpt
272 on a Lambert map at 1.5 cm/degree along the standard parallels 18 and
273 24, and using 1 degree tickmarks:
274 grdimage hawaii_grav.grd -Jl18/24/1.5c -Cshades.cpt -B1 >
276 hawaii_grav_image.ps
277 To create an illuminated color PostScript plot of the gridded data set
279 image.grd, using the intensities provided by the file intens.grd, and
280 color levels in the file colors.cpt, with linear scaling at 10 inch/x-
281 unit, tickmarks every 5 units:
282 grdimage image.grd -Jx10i -Ccolors.cpt -Iintens.grd -B5 > image.ps
284 To create an false color PostScript plot from the three grid files
286 red.grd, green.grd, and blue.grd, with linear scaling at 10 inch/x-
287 unit, tickmarks every 5 units:
288 grdimage red.grd green.grd blue.grd -Jx10i -B5 > rgbimage.ps
290 When GDAL support is built in: To create a sinusoidal projection of a
292 remotely located Jessica Rabbit
293 grdimage -JI15c -Rd -Dr http://larryfire.files.word‐
295 press.com/2009/07/untooned_jessicarabbit.jpg -P > jess.ps
296
298 GMT(1), gmt2rgb(1), grdcontour(1), grdview(1), grdgradient(1), grdhis‐
299 teq(1)
300GMT 4.5.6 10 Mar 2011 GRDIMAGE(1)
