1.. index:: ! img2grd 2.. include:: ../module_supplements_purpose.rst_ 3 4******* 5img2grd 6******* 7 8|img2grd_purpose| 9 10Synopsis 11-------- 12 13.. include:: ../../common_SYN_OPTs.rst_ 14 15**gmt img2grd** *imgfile* |-G|\ *grdfile* 16|SYN_OPT-R| 17[ |-D|\ [*minlat/maxlat*] ] [ |-E| ] [ |-I|\ *inc* ] 18[ |-F| ] 19[ |-M| ] [ |-N|\ *navg* ] [ |-S|\ [*scale*] ] 20[ |-T|\ *type* ] 21[ |SYN_OPT-V| ] 22[ |-W|\ *maxlon* ] 23[ |SYN_OPT-n| ] 24[ |SYN_OPT--| ] 25 26|No-spaces| 27 28Description 29----------- 30 31**img2grd** reads an img format file, extracts a subset, and writes it 32to a grid file. The **-M** option dictates whether or not the Spherical 33Mercator projection of the img file is preserved or if a Geographic grid 34should be written by undoing the Mercator projection. If geographic grid 35is selected you can also request a resampling onto the exact **-R** given. 36 37Required Arguments 38------------------ 39 40*imgfile* 41 A Mercator img format file such as the marine gravity or seafloor 42 topography fields estimated from satellite altimeter data by 43 Sandwell and Smith. If the user has set an environment variable 44 **$GMT_DATADIR**, then **img2grd** will try to find *imgfile* in 45 **$GMT_DATADIR**; else it will try to open *imgfile* directly. 46 47.. _-G: 48 49.. |Add_outgrid| replace:: Give the name of the output grid file. 50.. include:: /explain_grd_inout.rst_ 51 :start-after: outgrid-syntax-begins 52 :end-before: outgrid-syntax-ends 53 54.. _-R: 55 56.. |Add_-Rgeo| unicode:: 0x20 .. just an invisible code 57.. include:: ../../explain_-Rgeo.rst_ 58 59Optional Arguments 60------------------ 61 62.. _-D: 63 64**-D**\ [*minlat/maxlat*] 65 Use the extended latitude range -80.738/+80.738. Alternatively, 66 append *minlat/maxlat* as the latitude extent of the input img file. 67 [Default is -72.006/72.006]. Not usually required since we can 68 determine the extent from inspection of the file size. 69 70.. _-E: 71 72**-E** 73 Can be used when **-M** is not set to force the final grid to have 74 the exact same region as requested with **-R**. By default, the 75 final region is a direct projection of the original Mercator region 76 and will typically extend slightly beyond the requested latitude 77 range, and furthermore the grid increment in latitude does not match 78 the longitude increment. However, the extra resampling introduces 79 small interpolation errors and should only be used if the output 80 grid must match the requested region and have x_inc = y_inc. In 81 this case the region set by **-R** must be given in multiples of the 82 increment (e.g., **-R**\ 0/45/45/72). 83 84.. _-F: 85 86**-F** 87 Translate the x and y Mercator coordinates so that they are relative 88 to the lower left corner, which then is (0,0). Requires **-M**. 89 90.. _-I: 91 92**-I** 93 Indicate *inc* as the width of an input img pixel in minutes of 94 longitude [Default is 2]. Append **m** [Default] or **s** to 95 indicate unit. Not usually required since we can 96 determine the pixel size from inspection of the size. 97 98.. _-M: 99 100**-M** 101 Output a Spherical Mercator grid [Default is a geographic lon/lat 102 grid]. The Spherical Mercator projection of the img file is 103 preserved, so that the region **-R** set by the user is modified 104 slightly; the modified region corresponds to the edges of pixels [or 105 groups of *navg* pixels]. The grid file header is set so that the x 106 and y axis lengths represent distance relative to projection center 107 using a **-Jm**\ 1 projection. See **-F** to set coordinates to 108 instead be distances from the west and south edges 109 of the image, measured in user default units, with **-Jm**\ 1 and 110 the adjusted **-R**. By setting the default **PROJ_ ELLIPSOID** = 111 Sphere, the user can make overlays with the adjusted **-R** so that 112 they match. See **EXAMPLES** below. The adjusted **-R** is also 113 written in the grid header remark, so it can be found later. 114 115.. _-N: 116 117**-N**\ *navg* 118 Average the values in the input img pixels into *navg* by *navg* 119 squares, and create one output pixel for each such square. If used 120 with **-T**\ *3* it will report an average constraint between 0 and 121 1. If used with **-T**\ *2* the output will be average data value or 122 NaN according to whether average constraint is > 0.5. *navg* must 123 evenly divide into the dimensions of the imgfile in pixels. [Default 124 *1* does no averaging]. 125 126.. _-S: 127 128**-S**\ [*scale*] 129 Multiply the img file values by *scale* before storing in grid file. 130 [Default is 1.0]. For recent img files: img topo files are stored in 131 (corrected) meters [**-S**\ 1]; free-air gravity files in mGal\*10 132 [**-S**\ 0.1 to get mGal]; vertical deflection files in 133 micro-radians\*10 [**-S**\ 0.1 to get micro-radians], vertical gravity 134 gradient files in Eotvos\*10 [**-S**\ 0.1 to get Eotvos, or 135 **-S**\ 0.01 to get mGal/km]). If no *scale* is given we try to 136 determine the scale by examining the file name for clues. 137 138.. _-T: 139 140**-T**\ *type* 141 *type* handles the encoding of constraint information. *type* = 0 142 indicates that no such information is encoded in the img file (used 143 for pre-1995 versions of the gravity data) and gets all data. *type* 144 > 0 indicates that constraint information is encoded (1995 and later 145 (current) versions of the img files) so that one may produce a grid 146 file as follows: **-T**\ *1* gets data values at all points, 147 **-T**\ *2* gets data values at constrained points and NaN at 148 interpolated points; **-T**\ *3* gets 1 at constrained points and 0 149 at interpolated points [Default is 1]. 150 151.. |Add_-V| replace:: Particularly recommended here, as it is 152 helpful to see how the coordinates are adjusted. |Add_-V_links| 153.. include:: /explain_-V.rst_ 154 :start-after: **Syntax** 155 :end-before: **Description** 156 157.. _-W: 158 159**-W**\ *maxlon* 160 Indicate *maxlon* as the maximum longitude extent of the input img 161 file. Versions since 1995 have had *maxlon* = 360.0, while some 162 earlier files had *maxlon* = 390.0. [Default is 360.0]. 163 164.. include:: ../../explain_-n.rst_ 165 166.. include:: ../../explain_help.rst_ 167 168Geographic Examples 169------------------- 170 171The **-M** option should be excluded if you need the output grid to be 172in geographic coordinates. To extract data in the region 173**-R**-40/40/-70/-30 from *world_grav.img.7.2* and reproject to yield 174geographic coordinates, you can try 175 176 :: 177 178 gmt img2grd world_grav.img.16.1 -Gmerc_grav.nc -R-40/40/-70/-30 -V 179 180Because the latitude spacing in the img file is equidistant in Mercator 181units, the resulting grid will not match the specified **-R** exactly, 182and the latitude spacing will not equal the longitude spacing. If you 183need an exact match with your **-R** and the same spacing in longitude 184and latitude, use the **-E** option: 185 186 :: 187 188 gmt img2grd world_grav.img.16.1 -Gmerc_grav.nc -R-40/40/-70/-30 -E -V 189 190Mercator Examples 191----------------- 192 193Since the img files are in a Mercator projection, you should NOT extract 194a geographic grid if your plan is to make a Mercator map. If you did 195that you end of projecting and reprojection the grid, losing 196short-wavelength detail. Better to use **-M** and plot the grid using a 197linear projection with the same scale as the desired Mercator projection 198(see GMT Example 29). 199To extract data in the region **-R**-40/40/-70/-30 from 200*world_grav.img.7.2*, run 201 202 :: 203 204 gmt img2grd -M world_grav.img.7.2 -Gmerc_grav.nc -R-40/40/-70/-30 -V 205 206Note that the **-V** option tells us that the range was adjusted to 207**-R**-40/40/-70.0004681551/-29.9945810754. For scripting purposes we 208can extract this original region string using :doc:`grdinfo </grdinfo>` **-Ii**. 209Furthermore, we can also use :doc:`grdinfo </grdinfo>` 210to find that the grid file header shows its region to be 211**-R**\ -40/40/-99.4333333333/-31.4666666667. This is the range of x,y we will get from a 212Spherical Mercator projection using 213**-R**-40/40/-70.0004681551/-29.9945810754 and **-Jm**\ 1. Thus, to take 214ship.lonlatgrav and use it to sample the merc_grav.nc, we can do this: 215 216 :: 217 218 gmt set PROJ_ELLIPSOID Sphere 219 220 gmt mapproject -R-40/40/-70.0004681551/-29.9945810754 -Jm1i -C ship.lonlatgrav | \ 221 gmt grdtrack -Gmerc_grav.nc | \ 222 gmt mapproject -R-40/40/-70.0004681551/-29.9945810754 -Jm1i -I -C > ship.lonlatgravsat 223 224It is recommended to use the above method of projecting and unprojecting 225the data in such an application, because then there is only one 226interpolation step (in :doc:`grdtrack </grdtrack>`). If one first tries to convert the 227grid file to lon,lat and then sample it, there are two interpolation 228steps (in conversion and in sampling). 229 230To make a lon,lat grid from the above grid we can use 231 232 :: 233 234 gmt grdproject merc_grav.nc -R-40/40/-70.0004681551/-29.9945810754 -Jm1i -I -D2m -Ggrav.nc 235 236In some cases this will not be easy as the **-R** in the two coordinate 237systems may not align well. When this happens, we can also use (in fact, 238it may be always better to use) 239 240 :: 241 242 gmt grd2xyz merc_grav.nc | \ 243 gmt mapproject -R-40/40/-70.0004681551/-29.994581075 -Jm1i -I | \ 244 gmt surface -R-40/40/-70/70 -I2m -Ggrav.nc 245 246To make a Mercator map of the above region, suppose our gmt.conf value 247for :term:`PROJ_LENGTH_UNIT` is inch. Then since the above merc_grav.nc 248file is projected with **-Jm**\ 1i it is 80 inches wide. We can make a 249map 8 inches wide by using **-Jx**\ 0.1i on any map programs applied to 250this grid (e.g., :doc:`grdcontour </grdcontour>`, 251:doc:`grdimage </grdimage>`, :doc:`grdview </grdview>`), and then 252for overlays which work in lon,lat (e.g., :doc:`plot </plot>`, :doc:`coast </coast>`) we can 253use the above adjusted **-R** and **-Jm**\ 0.1 to get the two systems to 254match up. 255 256However, we can be smarter than this. Realizing that the input img file 257had pixels 2.0 minutes wide (or checking the nx and ny with :doc:`grdinfo </grdinfo>` 258merc_grav.nc) we realize that merc_grav.nc used the full resolution of 259the img file and it has 2400 by 2039 pixels, and at 8 inches wide this 260is 300 pixels per inch. We decide we do not need that many and we will be 261satisfied with 100 pixels per inch, so we want to average the data into 2623 by 3 squares. (If we want a contour plot we will probably choose to 263average the data much more (e.g., 6 by 6) to get smooth contours.) Since 2642039 isn't divisible by 3 we will get a different adjusted **-R** this time: 265 266 :: 267 268 gmt img2grd -M world_grav.img.7.2 -Gmerc_grav_2.nc -R-40/40/-70/-30 -N3 -V 269 270This time we find the adjusted region is 271**-R**-40/40/-70.023256525/-29.9368261101 and the output is 800 by 601 272pixels, a better size for us. Now we can create an artificial 273illumination file for this using :doc:`grdgradient </grdgradient>`: 274 275 :: 276 277 gmt grdgradient merc_grav_2.nc -Gillum.nc -A0/270 -Ne0.6 278 279and if we also have a CPT called "grav.cpt" we can create a color 280shaded relief map like this: 281 282 :: 283 284 gmt begin 285 gmt grdimage merc_grav_2.nc -Iillum.nc -Cgrav.cpt -Jx0.1i 286 gmt basemap -R-40/40/-70.023256525/-29.9368261101 -Jm0.1i -Ba10 287 gmt end 288 289Suppose you want to obtain only the constrained data values from an img 290file, in lat/lon coordinates. Then run **img2grd** with the **-T**\ 2 291option, use :doc:`grd2xyz </grd2xyz>` to dump the values, pipe through grep -v NaN to 292eliminate NaNs, and pipe through :doc:`mapproject </mapproject>` with the inverse projection as above. 293 294See Also 295-------- 296 297:doc:`gmt </gmt>` 298