Provided by: gmt_4.5.11-1build1_amd64 
NAME
img2mercgrd - Extract region of img, preserving Mercator, save as grd
SYNOPSIS
img2mercgrd imgfile -Ggrdfile -Rwest/east/south/north[r] -Ttype [ -C ] [ -D[minlat/maxlat]
] [ -Nnavg ] [ -Sscale ] [ -V ] [ -Wmaxlon ] [ -mminutes ]
DESCRIPTION
img2mercgrd reads an img format file and creates a grid file. 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 -Jm 1 and
the adjusted -R. By setting the default 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 grdheader remark, so it can be found later. The -Ttype selects all data or
only data at constrained pixels, and can be used to create a grid of 1s and 0s indicating
constraint locations. The output grid file is pixel registered; it inherits this from the
img file.
imgfile
An 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_IMGDIR, then img2mercgrd will try to find imgfile in
$GMT_IMGDIR; else it will try to open imgfile directly.
-G grdfile is the name of the output grid file.
-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, specify the name of an
existing grid file and the -R settings (and grid spacing, if applicable) are copied
from the grid.
-T 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; all more recent files do not support this choice) 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.
OPTIONS
-C Set the x and y Mercator coordinates relative to projection center (lon = lat = 0)
[Default is relative to lower left corner of grid].
-D 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].
-N 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 Multiply the img file values by scale before storing in grid file. [Default is
1.0]. (img topo files are stored in (corrected) meters; gravity files in mGal*10;
vertical deflection files in microradians*10, vertical gravity gradient files in
Eotvos*10. Use -S 0.1 for those files.)
-V Selects verbose mode, which will send progress reports to stderr [Default runs
"silently"]. Particularly recommended here, as it is helpful to see how the
coordinates are adjusted.
-m Indicate minutes as the width of an input img pixel in minutes of longitude.
[Default is 2.0].
-W 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].
EXAMPLES
To extract data in the region -R-40/40/-70/-30 from world_grav.img.7.2, run
img2mercgrd world_grav.img.7.2 -G merc_grav.grd -R-40/40/-70/-30 -T 1 -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 -R 0/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
-Jm 1. Thus, to take ship.lonlatgrav and use it to sample the merc_grav.grd, we can do
this:
gmtset ELLIPSOID Sphere
mapproject -R-40/40/-70.0004681551/-29.9945810754 -Jm 1 ship.lonlatgrav | grdtrack -G
merc_grav.grd | mapproject -R-40/40/-70.0004681551/-29.9945810754 -Jm 1 -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
grdproject merc_grav.grd -R-40/40/-70.0004681551/-29.9945810754 -Jm 1 -I -F -D 2m -G
grav.grd
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)
grd2xyz merc_grav.grd | mapproject -R-40/40/-70.0004681551/-29.994581075 -Jm 1 -I |
surface -R-40/40/-70/70 -I 2m -G grav.grd
To make a Mercator map of the above region, suppose our .gmtdefaults4 MEASURE_UNIT is
inch. Then since the above merc_grav.grd file is projected with -Jm 1 it is 80 inches
wide. We can make a map 8 inches wide by using -Jx 0.1 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 -Jm 0.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.grd) we realize that
merc_grav.grd 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 don't 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 OPT(R) this time:
img2mercgrd world_grav.img.7.2 -G merc_grav_2.grd -R-40/40/-70/-30 -T 1 -N 3 -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:
grdgradient merc_grav_2.grd -G illum.grd -A 0/270 -N e0.6
and if we also have a cpt file called "grav.cpt" we can create a color shaded relief map
like this:
grdimage merc_grav_2.grd -I illum.grd -C grav.cpt -Jx 0.1 -K > map.ps
psbasemap -R-40/40/-70.023256525/-29.9368261101 -Jm 0.1 -B a10 -O >> map.ps
Suppose you want to obtain only the constrained data values from an img file, in lat/lon
coordinates. Then run img2mercgrd with the -T 2 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(1), grdproject(1), mapproject(1)