Provided by: gmt-common_5.2.1+dfsg-3build1_all 
NAME
img2grd - Extract subset of img file in Mercator or Geographic format
SYNOPSIS
img2grd imgfile grdfile region type [ ] [ [minlat/maxlat] ] [ ] [ minutes ] [ ] [ navg
] [ [scale] ] [ [level] ] [ maxlon ] [ -n<flags> ]
Note: No space is allowed between the option flag and the associated arguments.
DESCRIPTION
img2grd reads an img format file, extracts a subset, and writes it to a grid file. The -M
option dictates whether or not the Spherical Mercator projection of the img file is
preserved or if a Geographic grid should be written by undoing the Mercator projection. If
geographic grid is selected you can also request a resampling onto the exact -R given.
REQUIRED ARGUMENTS
imgfile
A Mercator img format file such as the marine gravity or seafloor topography fields
estimated from satellite altimeter data by Sandwell and Smith. If the user has set
an environment variable $GMT_DATADIR, then img2grd will try to find imgfile in
$GMT_DATADIR; else it will try to open imgfile directly.
-Ggrdfile
grdfile is the name of the output grid file.
-R[unit]west/east/south/north[/zmin/zmax][r]
west, east, south, and north specify the region of interest, and you may specify
them in decimal degrees or in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower
left and upper right map coordinates are given instead of w/e/s/n. The two
shorthands -Rg and -Rd stand for global domain (0/360 and -180/+180 in longitude
respectively, with -90/+90 in latitude). Alternatively for grid creation, give
Rcodelon/lat/nx/ny, where code is a 2-character combination of L, C, R (for left,
center, or right) and T, M, B for top, middle, or bottom. e.g., BL for lower left.
This indicates which point on a rectangular region the lon/lat coordinate refers
to, and the grid dimensions nx and ny with grid spacings via -I is used to create
the corresponding region. Alternatively, specify the name of an existing grid file
and the -R settings (and grid spacing, if applicable) are copied from the grid.
Using -Runit expects projected (Cartesian) coordinates compatible with chosen -J
and we inversely project to determine actual rectangular geographic region. For
perspective view (-p), optionally append /zmin/zmax. In case of perspective view
(-p), a z-range (zmin, zmax) can be appended to indicate the third dimension. This
needs to be done only when using the -Jz option, not when using only the -p option.
In the latter case a perspective view of the plane is plotted, with no third
dimension.
OPTIONAL ARGUMENTS
-C Set the x and y Mercator coordinates relative to projection center [Default is
relative to lower left corner of grid]. Requires -M.
-D[minlat/maxlat]
Use the extended latitude range -80.738/+80.738. Alternatively, append
minlat/maxlat as the latitude extent of the input img file. [Default is
-72.006/72.006]. Not usually required since we can determine the extent from
inspection of the file size.
-E Can be used when -M is not set to force the final grid to have the exact same
region as requested with -R. By default, the final region is a direct projection of
the original Mercator region and will typically extend slightly beyond the
requested latitude range, and furthermore the grid increment in latitude does not
match the longitude increment. However, the extra resampling introduces small
interpolation errors and should only be used if the output grid must match the
requested region and have x_inc = y_inc. In this case the region set by -R must be
given in multiples of the increment (.e.g, -R0/45/45/72).
-I Indicate minutes as the width of an input img pixel in minutes of longitude.
[Default is 2.0]. Not usually required since we can determine the pixel size from
inspection of the size.
-M Output a Spherical Mercator grid [Default is a geographic lon/lat grid]. The
Spherical Mercator projection of the img file is preserved, so that the region -R
set by the user is modified slightly; the modified region corresponds to the edges
of pixels [or groups of navg pixels]. The grid file header is set so that the x and
y axis lengths represent distance from the west and south edges of the image,
measured in user default units, with -Jm1 and the adjusted -R. By setting the
default PROJ_ ELLIPSOID = Sphere, the user can make overlays with the adjusted -R
so that they match. See EXAMPLES below. The adjusted -R is also written in the grid
header remark, so it can be found later. See -C to set coordinates relative to
projection center.
-Nnavg Average the values in the input img pixels into navg by navg squares, and create
one output pixel for each such square. If used with -T3 it will report an average
constraint between 0 and 1. If used with -T2 the output will be average data value
or NaN according to whether average constraint is > 0.5. navg must evenly divide
into the dimensions of the imgfile in pixels. [Default 1 does no averaging].
-S[scale]
Multiply the img file values by scale before storing in grid file. [Default is
1.0]. For recent img files: img topo files are stored in (corrected) meters [-S1];
free-air gravity files in mGal*10 [-S0.1 to get mGal]; vertical deflection files in
micro-radians*10 [-S0.1 to get micro-radians], vertical gravity gradient files in
Eotvos*50 [-S0.02 to get Eotvos, or -S0.002 to get mGal/km]). If no scale is given
we try to determine the scale by examining the file name for clues.
-Ttype type handles the encoding of constraint information. type = 0 indicates that no
such information is encoded in the img file (used for pre-1995 versions of the
gravity data) and gets all data. type > 0 indicates that constraint information is
encoded (1995 and later (current) versions of the img files) so that one may
produce a grid file as follows: -T1 gets data values at all points, -T2 gets data
values at constrained points and NaN at interpolated points; -T3 gets 1 at
constrained points and 0 at interpolated points [Default is 1].
-V[level] (more ...)
Select verbosity level [c]. Particularly recommended here, as it is helpful to see
how the coordinates are adjusted.
-Wmaxlon
Indicate maxlon as the maximum longitude extent of the input img file. Versions
since 1995 have had maxlon = 360.0, while some earlier files had maxlon = 390.0.
[Default is 360.0].
-^ 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.
GEOGRAPHIC EXAMPLES
The -M option should be excluded if you need the output grid to be in geographic
coordinates. To extract data in the region -R-40/40/-70/-30 from world_grav.img.7.2 and
reproject to yield geographic coordinates, you can try
img2grd world_grav.img.16.1 -Gmerc_grav.nc -R-40/40/-70/-30 -V
Because the latitude spacing in the img file is equidistant in Mercator units, the
resulting grid will not match the specified -R exactly, and the latitude spacing will not
equal the longitude spacing. If you need an exact match with your -R and the same spacing
in longitude and latitude, use the -E option:
img2grd world_grav.img.16.1 -Gmerc_grav.nc -R-40/40/-70/-30 -E -V
MERCATOR EXAMPLES
Since the img files are in a Mercator projection, you should NOT extract a geographic grid
if your plan is to make a Mercator map. If you did that you end of projecting and
reprojection the grid, loosing short-wavelength detail. Better to use -M and plot the grid
using a linear projection with the same scale as the desired Mercator projection (see GMT
Example 29). To extract data in the region -R-40/40/-70/-30 from world_grav.img.7.2, run
gmt img2grd -M world_grav.img.7.2 -Gmerc_grav.nc -R-40/40/-70/-30 -V
Note that the -V option tells us that the range was adjusted to
-R-40/40/-70.0004681551/-29.9945810754. We can also use grdinfo to find that the grid file
header shows its region to be -R0/80/0/67.9666667 This is the range of x,y we will get
from a Spherical Mercator projection using -R-40/40/-70.0004681551/-29.9945810754 and
-Jm1. Thus, to take ship.lonlatgrav and use it to sample the merc_grav.nc, we can do this:
gmt set PROJ_ELLIPSOID Sphere
gmt mapproject -R-40/40/-70.0004681551/-29.9945810754 -Jm1i ship.lonlatgrav | \
gmt grdtrack -Gmerc_grav.nc | gmt mapproject \
-R-40/40/-70.0004681551/-29.9945810754 -Jm1i -I > ship.lonlatgravsat
It is recommended to use the above method of projecting and unprojecting the data in such
an application, because then there is only one interpolation step (in grdtrack). If one
first tries to convert the grid file to lon,lat and then sample it, there are two
interpolation steps (in conversion and in sampling).
To make a lon,lat grid from the above grid we can use
gmt grdproject merc_grav.nc -R-40/40/-70.0004681551/-29.9945810754 -Jm1i -I -D2m -Ggrav.nc
In some cases this will not be easy as the -R in the two coordinate systems may not align
well. When this happens, we can also use (in fact, it may be always better to use)
gmt grd2xyz merc_grav.nc | gmt mapproject \
-R-40/40/-70.0004681551/-29.994581075 -Jm1i -I | \
gmt surface -R-40/40/-70/70 -I2m -Ggrav.nc
To make a Mercator map of the above region, suppose our gmt.conf value for
PROJ_LENGTH_UNIT is inch. Then since the above merc_grav.nc file is projected with -Jm1i
it is 80 inches wide. We can make a map 8 inches wide by using -Jx0.1i on any map programs
applied to this grid (e.g., grdcontour, grdimage, grdview), and then for overlays which
work in lon,lat (e.g., psxy, pscoast) we can use the above adjusted -R and -Jm0.1 to get
the two systems to match up.
However, we can be smarter than this. Realizing that the input img file had pixels 2.0
minutes wide (or checking the nx and ny with grdinfo merc_grav.nc) we realize that
merc_grav.nc used the full resolution of the img file and it has 2400 by 2039 pixels, and
at 8 inches wide this is 300 pixels per inch. We decide we do not need that many and we
will be satisfied with 100 pixels per inch, so we want to average the data into 3 by 3
squares. (If we want a contour plot we will probably choose to average the data much more
(e.g., 6 by 6) to get smooth contours.) Since 2039 isn't divisible by 3 we will get a
different adjusted -R this time:
gmt img2grd -M world_grav.img.7.2 -Gmerc_grav_2.nc -R-40/40/-70/-30 -N3 -V
This time we find the adjusted region is -R-40/40/-70.023256525/-29.9368261101 and the
output is 800 by 601 pixels, a better size for us. Now we can create an artificial
illumination file for this using grdgradient:
gmt grdgradient merc_grav_2.nc -Gillum.nc -A0/270 -Ne0.6
and if we also have a CPT file called "grav.cpt" we can create a color shaded relief map
like this:
gmt grdimage merc_grav_2.nc -Iillum.nc -Cgrav.cpt -Jx0.1i -K > map.ps
gmt psbasemap -R-40/40/-70.023256525/-29.9368261101 -Jm0.1i -Ba10 -O >> map.ps
Suppose you want to obtain only the constrained data values from an img file, in lat/lon
coordinates. Then run img2grd with the -T2 option, use grd2xyz to dump the values, pipe
through grep -v NaN to eliminate NaNs, and pipe through mapproject with the inverse
projection as above.
SEE ALSO
gmt
COPYRIGHT
2015, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe