1IMG2GRD(1) GMT IMG2GRD(1)
2
6 img2grd - Extract subset of img file in Mercator or Geographic format
7
9 img2grd imgfile -Ggrdfile
10 -Rregion
11 -Ttype [ -C ] [ -D[minlat/maxlat] ] [ -E ] [ -Iminutes ] [ -M ] [
12 -Nnavg ] [ -S[scale] ] [ -V[level] ] [ -Wmaxlon ] [ -nflags ]
13 Note: No space is allowed between the option flag and the associated
15 arguments.
16
18 img2grd reads an img format file, extracts a subset, and writes it to a
19 grid file. The -M option dictates whether or not the Spherical Mercator
20 projection of the img file is preserved or if a Geographic grid should
21 be written by undoing the Mercator projection. If geographic grid is
22 selected you can also request a resampling onto the exact -R given.
23
25 imgfile
26 A Mercator img format file such as the marine gravity or
27 seafloor topography fields estimated from satellite altimeter
28 data by Sandwell and Smith. If the user has set an environment
29 variable $GMT_DATADIR, then img2grd will try to find imgfile in
30 $GMT_DATADIR; else it will try to open imgfile directly.
31 -Ggrdfile
33 grdfile is the name of the output grid file.
34 -Rwest/east/south/north[/zmin/zmax][+r][+uunit]
36 west, east, south, and north specify the region of interest, and
37 you may specify them in decimal degrees or in
38 [±]dd:mm[:ss.xxx][W|E|S|N] format Append +r if lower left and
39 upper right map coordinates are given instead of w/e/s/n. The
40 two shorthands -Rg and -Rd stand for global domain (0/360 and
41 -180/+180 in longitude respectively, with -90/+90 in latitude).
42 Alternatively for grid creation, give Rcodelon/lat/nx/ny, where
43 code is a 2-character combination of L, C, R (for left, center,
44 or right) and T, M, B for top, middle, or bottom. e.g., BL for
45 lower left. This indicates which point on a rectangular region
46 the lon/lat coordinate refers to, and the grid dimensions nx and
47 ny with grid spacings via -I is used to create the corresponding
48 region. Alternatively, specify the name of an existing grid
49 file and the -R settings (and grid spacing, if applicable) are
50 copied from the grid. Appending +uunit expects projected (Carte‐
51 sian) coordinates compatible with chosen -J and we inversely
52 project to determine actual rectangular geographic region. For
53 perspective view (-p), optionally append /zmin/zmax. In case of
54 perspective view (-p), a z-range (zmin, zmax) can be appended to
55 indicate the third dimension. This needs to be done only when
56 using the -Jz option, not when using only the -p option. In the
57 latter case a perspective view of the plane is plotted, with no
58 third dimension.
59
61 -C Set the x and y Mercator coordinates relative to projection cen‐
62 ter [Default is relative to lower left corner of grid]. Requires
63 -M.
64 -D[minlat/maxlat]
66 Use the extended latitude range -80.738/+80.738. Alternatively,
67 append minlat/maxlat as the latitude extent of the input img
68 file. [Default is -72.006/72.006]. Not usually required since
69 we can determine the extent from inspection of the file size.
70 -E Can be used when -M is not set to force the final grid to have
72 the exact same region as requested with -R. By default, the
73 final region is a direct projection of the original Mercator
74 region and will typically extend slightly beyond the requested
75 latitude range, and furthermore the grid increment in latitude
76 does not match the longitude increment. However, the extra
77 resampling introduces small interpolation errors and should only
78 be used if the output grid must match the requested region and
79 have x_inc = y_inc. In this case the region set by -R must be
80 given in multiples of the increment (.e.g, -R0/45/45/72).
81 -I Indicate minutes as the width of an input img pixel in minutes
83 of longitude. [Default is 2.0]. Not usually required since we
84 can determine the pixel size from inspection of the size.
85 -M Output a Spherical Mercator grid [Default is a geographic
87 lon/lat grid]. The Spherical Mercator projection of the img file
88 is preserved, so that the region -R set by the user is modified
89 slightly; the modified region corresponds to the edges of pixels
90 [or groups of navg pixels]. The grid file header is set so that
91 the x and y axis lengths represent distance from the west and
92 south edges of the image, measured in user default units, with
93 -Jm1 and the adjusted -R. By setting the default PROJ_ ELLIPSOID
94 = Sphere, the user can make overlays with the adjusted -R so
95 that they match. See EXAMPLES below. The adjusted -R is also
96 written in the grid header remark, so it can be found later. See
97 -C to set coordinates relative to projection center.
98 -Nnavg Average the values in the input img pixels into navg by navg
100 squares, and create one output pixel for each such square. If
101 used with -T3 it will report an average constraint between 0 and
102 1. If used with -T2 the output will be average data value or NaN
103 according to whether average constraint is > 0.5. navg must
104 evenly divide into the dimensions of the imgfile in pixels.
105 [Default 1 does no averaging].
106 -S[scale]
108 Multiply the img file values by scale before storing in grid
109 file. [Default is 1.0]. For recent img files: img topo files
110 are stored in (corrected) meters [-S1]; free-air gravity files
111 in mGal*10 [-S0.1 to get mGal]; vertical deflection files in
112 micro-radians*10 [-S0.1 to get micro-radians], vertical gravity
113 gradient files in Eotvos*10 [-S0.1 to get Eotvos, or -S0.01 to
114 get mGal/km]). If no scale is given we try to determine the
115 scale by examining the file name for clues.
116 -Ttype type handles the encoding of constraint information. type = 0
118 indicates that no such information is encoded in the img file
119 (used for pre-1995 versions of the gravity data) and gets all
120 data. type > 0 indicates that constraint information is encoded
121 (1995 and later (current) versions of the img files) so that one
122 may produce a grid file as follows: -T1 gets data values at all
123 points, -T2 gets data values at constrained points and NaN at
124 interpolated points; -T3 gets 1 at constrained points and 0 at
125 interpolated points [Default is 1].
126 -V[level] (more ...)
128 Select verbosity level [c]. Particularly recommended here, as it
129 is helpful to see how the coordinates are adjusted.
130 -Wmaxlon
132 Indicate maxlon as the maximum longitude extent of the input img
133 file. Versions since 1995 have had maxlon = 360.0, while some
134 earlier files had maxlon = 390.0. [Default is 360.0].
135 -n[b|c|l|n][+a][+bBC][+c][+tthreshold] (more ...)
137 Select interpolation mode for grids.
138 -^ or just -
140 Print a short message about the syntax of the command, then
141 exits (NOTE: on Windows just use -).
142 -+ or just +
144 Print an extensive usage (help) message, including the explana‐
145 tion of any module-specific option (but not the GMT common
146 options), then exits.
147 -? or no arguments
149 Print a complete usage (help) message, including the explanation
150 of all options, then exits.
151
153 The -M option should be excluded if you need the output grid to be in
154 geographic coordinates. To extract data in the region -R-40/40/-70/-30
155 from world_grav.img.7.2 and reproject to yield geographic coordinates,
156 you can try
157 img2grd world_grav.img.16.1 -Gmerc_grav.nc -R-40/40/-70/-30 -V
159 Because the latitude spacing in the img file is equidistant in Mercator
161 units, the resulting grid will not match the specified -R exactly, and
162 the latitude spacing will not equal the longitude spacing. If you need
163 an exact match with your -R and the same spacing in longitude and lati‐
164 tude, use the -E option:
165 img2grd world_grav.img.16.1 -Gmerc_grav.nc -R-40/40/-70/-30 -E -V
167
169 Since the img files are in a Mercator projection, you should NOT
170 extract a geographic grid if your plan is to make a Mercator map. If
171 you did that you end of projecting and reprojection the grid, losing
172 short-wavelength detail. Better to use -M and plot the grid using a
173 linear projection with the same scale as the desired Mercator projec‐
174 tion (see GMT Example 29). To extract data in the region
175 -R-40/40/-70/-30 from world_grav.img.7.2, run
176 gmt img2grd -M world_grav.img.7.2 -Gmerc_grav.nc -R-40/40/-70/-30 -V
178 Note that the -V option tells us that the range was adjusted to
180 -R-40/40/-70.0004681551/-29.9945810754. For scripting purposes we can
181 extract this original region string using grdinfo -Ii. Furthermore, we
182 can also use grdinfo to find that the grid file header shows its region
183 to be -R0/80/0/67.9666667. This is the range of x,y we will get from a
184 Spherical Mercator projection using
185 -R-40/40/-70.0004681551/-29.9945810754 and -Jm1. Thus, to take
186 ship.lonlatgrav and use it to sample the merc_grav.nc, we can do this:
187 gmt set PROJ_ELLIPSOID Sphere
189 gmt mapproject -R-40/40/-70.0004681551/-29.9945810754 -Jm1i ship.lonlatgrav | \
191 gmt grdtrack -Gmerc_grav.nc | gmt mapproject \
192 -R-40/40/-70.0004681551/-29.9945810754 -Jm1i -I > ship.lonlatgravsat
193 It is recommended to use the above method of projecting and unproject‐
195 ing the data in such an application, because then there is only one
196 interpolation step (in grdtrack). If one first tries to convert the
197 grid file to lon,lat and then sample it, there are two interpolation
198 steps (in conversion and in sampling).
199 To make a lon,lat grid from the above grid we can use
201 gmt grdproject merc_grav.nc -R-40/40/-70.0004681551/-29.9945810754 -Jm1i -I -D2m -Ggrav.nc
203 In some cases this will not be easy as the -R in the two coordinate
205 systems may not align well. When this happens, we can also use (in
206 fact, it may be always better to use)
207 gmt grd2xyz merc_grav.nc | gmt mapproject \
209 -R-40/40/-70.0004681551/-29.994581075 -Jm1i -I | \
210 gmt surface -R-40/40/-70/70 -I2m -Ggrav.nc
211 To make a Mercator map of the above region, suppose our gmt.conf value
213 for PROJ_LENGTH_UNIT is inch. Then since the above merc_grav.nc file is
214 projected with -Jm1i it is 80 inches wide. We can make a map 8 inches
215 wide by using -Jx0.1i on any map programs applied to this grid (e.g.,
216 grdcontour, grdimage, grdview), and then for overlays which work in
217 lon,lat (e.g., psxy, pscoast) we can use the above adjusted -R and
218 -Jm0.1 to get the two systems to match up.
219 However, we can be smarter than this. Realizing that the input img file
221 had pixels 2.0 minutes wide (or checking the nx and ny with grdinfo
222 merc_grav.nc) we realize that merc_grav.nc used the full resolution of
223 the img file and it has 2400 by 2039 pixels, and at 8 inches wide this
224 is 300 pixels per inch. We decide we do not need that many and we will
225 be satisfied with 100 pixels per inch, so we want to average the data
226 into 3 by 3 squares. (If we want a contour plot we will probably choose
227 to average the data much more (e.g., 6 by 6) to get smooth contours.)
228 Since 2039 isn't divisible by 3 we will get a different adjusted -R
229 this time:
230 gmt img2grd -M world_grav.img.7.2 -Gmerc_grav_2.nc -R-40/40/-70/-30 -N3 -V
232 This time we find the adjusted region is
234 -R-40/40/-70.023256525/-29.9368261101 and the output is 800 by 601 pix‐
235 els, a better size for us. Now we can create an artificial illumination
236 file for this using grdgradient:
237 gmt grdgradient merc_grav_2.nc -Gillum.nc -A0/270 -Ne0.6
239 and if we also have a CPT called "grav.cpt" we can create a color
241 shaded relief map like this:
242 gmt grdimage merc_grav_2.nc -Iillum.nc -Cgrav.cpt -Jx0.1i -K > map.ps
244 gmt psbasemap -R-40/40/-70.023256525/-29.9368261101 -Jm0.1i -Ba10 -O >> map.ps
245 Suppose you want to obtain only the constrained data values from an img
247 file, in lat/lon coordinates. Then run img2grd with the -T2 option, use
248 grd2xyz to dump the values, pipe through grep -v NaN to eliminate NaNs,
249 and pipe through mapproject with the inverse projection as above.
250
252 gmt
253
255 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
2565.4.5 Feb 24, 2019 IMG2GRD(1)