$Id: README.imgsrc,v 1.11 2011/03/04 06:47:15 guru Exp $
Maintained by: W H F Smith
Distributed under the GNU Public License (see file ../LICENSE.TXT)
==> CHANGES IN GMT 4.4.1 <==
Added img2google which creates Google Earth tiles from
the topo.11.1.img bathymetry grid.
==> CHANGES IN GMT 4.1.2 <==
Replaced -x -y options with -W and -D options to avoid conflict with GMT
initializations. -D with no arguments is shorthand for -D-80.738/+80.738.
==> CHANGES IN GMT 3.4 <==
For complete portability, it is understood that the Sandwell/Smith
*.img format is defined to be big-endian and thus the img2grd routines
have built-in automatic byte-swapping for little-endian systems. If
you have byte-swapped the data files to little-endian you may need to
revert to the original big-endian format.
==> CHANGES IN GMT 3.3.6 <==
Added the Bourne script img2grd to facilitate the
extraction of data with img2mercgrd. It takes the
same options plus an optional -M. Without -M it will
use grdproject to create a geographic grid, with -M it
will simply call img2mercgrd which results in a Mercatorized
grid.
==> CHANGES IN GMT 3.3 <==
The datasets used by img2mercgrd are native binary files
(short ints) and were created on workstations with big-endian
byte-order. If you install this supplement as part of the
main GMT installation using the install_gmt script it will
automatically determine if byte-order swapping should be
applied and compile that into the program. Should you want
to manually controll this (say, because you have already
swapped the data files) you can remote the $(GMTSWAP) macro
from the makefile.
Alternatively, if you with to swap the byte-order of the
*.img files, simply use
xyz2grd troublefile -Sgoodfile -V -Zh
where troublefile is the img-file with wrong byte-order
goodfile is the name of the fixed file
If goodfile is not given it will write to stdout. Note this
will not work under WIN32 since binary stdout is not supported.
==> CHANGES IN GMT 3.2 <==
11/28/1998 img2mercgrd.c: Fixed bug in -T0 that gave 0 data
==> CHANGES IN GMT 3.1 <==
W H F Smith, 14 October 1998, for GMT version 3.1
1. What is the imgsrc distribution?
imgsrc is a GMT supplement sub-directory which may be optionally
installed under the GMT src directory. It contains code to manipulate
"img" format files of marine gravity anomalies and estimated seafloor
depths produced from satellite altimeter data by D T Sandwell and W H F
Smith in several versions since the early 1990s. If you are not a user
of these files, you do not need to install the imgsrc supplement.
The imgsrc supplement distribution contains the following files:
README.imgsrc: this file.
gmt_imgsubs.c: source code for img subroutines.
gmt_imgsubs.h: header file for gmt_imgsubs.c and img2mercgrd.c
img2mercgrd.c: source code for a main program.
makefile: make file for these programs.
img2mercgrd.1: the img2mercgrd man page.
2. How do I make and install the imgsrc supplement?
These files are intended for installation in a sub-directory below the
primary GMT src directory. If the imgsrc files are placed somewhere
else, the user will have to change the paths to "gmt.h" in
"gmt_imgsubs.h" and to "-lgmt", "-lpsl", and "config.mk" in
"makefile".
makefile uses "../config.mk" which also control the "make" of
programs in the primary GMT src directory.
Assuming you have installed the imgsrc files in src/imgsrc within the
GMT src dir, and you have already compiled GMT successfully in the src
dir, then all you need to do is
"make install"
and this will create "img2mercgrd" and install it in your GMT bin directory.
"make install-man"
will install the man page in your man directory.
3. How do I use "img2mercgrd"?
img2mercgrd is used to extract data from an img file and store the
result in a GMT grd file. The usage message and man page give a terse
explanation and some examples. The feature that users need to study and
understand is the relationship between the img, lat/lon, and plot
coordinates and the -R and -J options, so I have given that a separate
section (#4) below.
To use img2mercgrd, you must specify the img file to read, the grd file
to write, the -R region to extract, and whether to extract data values
or information about how they are constrained (using -T). There are
options for averaging the data [-N], rescaling the data [-S], and for
verbose operation [-V]. There also are options [-m, -x, -y] which re-
define the img coordinate system (see #6 below) and which have their
default values set for the current img files (2-minute spherical
Mercator pixel files in -R0/360/-72.006/72.006).
Optional environment variable GMT_IMGDIR: At run time, img2mercgrd will
look to see if the user has set an environment variable GMT_IMGDIR. If
this is set, img2mercgrd will look for the img filename given on the
command line in the GMT_IMGDIR directory. If the environment variable
was not set, then img2mercgrd will simply try to open the file using the
name given on the command line.
4. The use of -R and -J in latitude and longitude coordinates and in
the spherical Mercator coordinates used by img2mercgrd.
GMT uses coordinate systems in various ways. When you use a GMT program
which processes data with reference to their coordinates but without
plotting (e.g. interpolating a grid to a list of data points with
"grdtrack") then the x,y values (which may be longitude, latitude) of
the various input files are assumed to be in the same coordinate system.
When you make a plot, the -R and -J options define a mapping between the
data coordinates and the plot coordinates (location on the page). If
you need to go between these two coordinate systems without plotting,
"mapproject" (for lists of data) and "grdproject" (for grd files)
provide both forward [default] and inverse [-I] transformations.
The "img" files use a spherical Mercator coordinate system (detailed
below in section #6), which is available in GMT using -Jm or -JM with
the .gmtdefaults4 parameter ELLIPSOID set to "Sphere". The img values
are given at locations corresponding to pixels in a spherical Mercator
map whose overall dimension (scale) is arbitrary. img2mercgrd extracts
pixels from this map and writes their values as a pixel-registered grd
file, preserving the Mercator projection and assigning it an arbitrary
scale of -Jm1.
When you give a -R<w>/<e>/<s>/<n> argument to img2mercgrd you are
indicating a desired region, just as with other GMT programs. However,
img2mercgrd will generally alter the latitudes and longitudes you give
with -R so that the altered values correspond to the edges of img pixels
(or n by n groups of img pixels if you use the -N averaging option).
These altered values will be written in the "Remark" section of the
header of the "grd" file (which you can view with "grdinfo") and may
also be written to standard error (if you use the -V option on
img2mercgrd). These altered values are reported as
-R<aw>/<ae>/<as>/<an>. You need these to make further use of the
img2mercgrd output grd file in GMT.
The grd file you obtain from img2mercgrd has a header which describes
the coordinates used in that grd file. These coordinates correspond to
the ones that you will get from other GMT programs using -Jm1
-R<aw>/<ae>/<as>/<an>, after setting ELLIPSOID = Sphere. The
coordinates will run from 0,0 in the lower left (southwest) corner to
x_max,y_max in the upper right (northeast) corner, where x_max,y_max
will be the values you would obtain by doing this:
Gmtset ELLIPSOID Sphere
Mapproject -Jm1 -R<aw>/<ae>/<as>/<an> << END
<ae> <an>
END
To go back and forth between longitude-latitude coordinates and the
projected coordinates in the grd file you get from img2mercgrd requires
forward or inverse projection using -Jm1 -R<aw>/<ae>/<as>/<an>. The man
page for img2mercgrd gives several examples.
The easiest thing to do, but the hardest for inexperienced GMT users to
understand, is to make a Mercator map which combines the img data with
other GMT plot operations referred to longitude-latitude coordinates
(such as psbasemap, pscoast, psxy, etc.). To make a map, note the
overall width of the mercatorized grd file obtained from img2mercgrd.
Since it was arbitrarily scaled with -Jm1 its width (in .gmtdefaults4
MEASURE_UNIT values) is simply the range of longitude from <aw> to <ae>.
Choose a map scale (in degrees of longitude per MEASURE_UNIT) so that
the desired map has the desired width. Any plot operations (such as
grdcontour, grdimage, grdview) on the grd file from img2mercgrd (call it
"merc.grd") should use a linear projection -Jx<scale>, since the
mercator projection is already accomplished. Any plot operations in
longitude-latitude coordinates should use -R<aw>/<ae>/<as>/<an>
-Jm<scale> to project these coordinates into a mercator map matching the
grd file to achieve correct overlay (with ELLIPSOID = Sphere). Examples
are given in the img2mercgrd man page. Note the use of the same scale
in both cases, but using -Jm or -Jx as needed. Also, you do not use -R
(or if you do use it, use -R0/0/x_max/y_max) on the operations on the
file from img2mercgrd, because you want the -Jx to be applied to the
already-mercatorized coordinate system, and not to the longitude-
latitude coordinate system.
If you create auxiliary grd files by operating on mymerc.grd (e.g. using
"grdgradient" to create a file for artificial illumination effects with
"grdimage") then the auxiliary grd will inherit the merc coordinate
system, and you will use -Jx with the auxiliary grid also. An example
is given in the img2mercgrd man page.
5. More info about the img files.
The img files have been produced in various versions and filenames since
the early 1990s by David T. Sandwell and Walter H. F. Smith. Each file
is a binary stream of two-byte signed integers (big-endian) representing
various aspects of the gravity field (gravity anomaly in mGal*10, north
and east deflections of the vertical in microradian*10, and vertical
gravity gradient in Eotvos*10) or elevation and depth (in corrected
meters). Published research articles cover the methods used to estimate
these quantities: Smith and Sandwell, J. Geophys. Res. vol. 99, #B11,
pp. 21803--21824, November 10, 1994; Sandwell and Smith, J. Geophys. Res.
vol. 102, #B5, pp. 10039--10054, May 10, 1997; Smith and Sandwell,
Science vol. 277, pp. 1956--1962, 26 September 1997; Smith, Ann. Rev.
Earth Planet. Sci. vol. 26, pp. 697--738, 1998.
At this writing the current versions of the gravity and topography are
"world_grav.img.7.2" and "topo_polish.6.2.img" and these are available
by ftp with some documentation at http://topex.ucsd.edu. A higher-
resolution gravity field has been promised (in an abstract submitted for
the December 1998 meeting of the American Geophysical Union). The U.S.
National Geophysical Data Center (http://www.ngdc.noaa.gov) has plans to
distribute some of this data and related products on CD-ROM, and my own
lab (http://ibis.grdl.noaa.gov/SAT) is working on a web site for
automatic generation of customized map views of these data.
6. More details of the img coordinate system; compatibility of the
current imgsrc with past, current, and future img files.
All of these files have used a spherical Mercator coordinate system in
which the following features have been true: the stream of bytes
represents a pixel-registered array written in scan-line order (loop
from W to E nested inside loop from N to S); the length of 360 degrees
of longitude is an integer number when measured in pixels; the pixels
are square; the vertical alignment of pixels is such that the Equator
falls on an edge between pixels; the horizontal alignment of the pixels
is such that the first pixel in each row has its left edge on the
Greenwich meridian. The present edition of the imgsrc supplement
assumes that these things will continue to be true in the future. These
features allow an analytic description of the transformations between
pixel row location in the array and latitude in terms of the forward and
inverse Gudermannian functions. Transformation between pixel column
location and longitude is by a trivial scale factor, since the west edge
of the array is at Greenwich; all that is required is to take care with
the periodicity in longitude. Coordinate transformation function source
code is in gmt_imgsubs.c.
Early (pre-1995; gravity only) versions of the img files covered a range
of longitude from 0 to 390 degrees (repeating 30 degrees for the sake of
some early map images) and had pixels 3 minutes of longitude in width.
Since 1995, files using ".2" in the version number have had pixels 2
minutes wide and have covered 360 degrees of longitude. Also in 1995
began the practice of using the least significant bit in each pixel to
indicate (True/False = 1/0) that the pixel value was constrained by one
or more types of information (satellite tracks in the case of gravity;
ship soundings, coastlines, or DEM information in the case of topography
and depth). To date, all files have covered a range of latitudes from
+/- 72.0059773539 (approximately).
img2mercgrd has options [-m<pixel_width_in_minutes>],
[-x<maximum_longitude>], and
[-y<minimum_latitude>/<maximum_latitude] which determine the mapping
between position in the file stream and position in the map array, and
between position in the map array and latitude and longitude. The
default values for these are set in gmt_imgsubs.h and (as currently
supplied) these are set for the current img files [-m2.0] [-x360.0]
[-y-72.0059773539 /72. 0059773539]. Old files may be read using -m3.0
-x390.0 (with -T0; see -T in man page) and future files may be readable
by other combinations of these options.
The user who wishes to check that the -m -x -y values correspond to an
img file may do the following:
Let <pixels_per_degree> = 60.0/<pixel_width_in_minutes> (the above [-m]
quantity).
Let <nxcol> = <maximum_longitude> * <pixels_per_degree>. This is the
number of columns in the img file array and it should be an integer.
Gmtset ELLIPSOID = Sphere
Mapproject -R0/360/<minimum_latitude>/<maximum_latitude> -Jm<
pixels_per_degree> << END
360.0 <maximum_latitude>
END
(answer:) <nx360> <nyrow>
These answers should be integers, and 2 * <nxcol> * <nyrow> should equal
the number of bytes in the img file. In practice, <nyrow> won't come
out to be exactly an integer, because the min and max latitude may not
have enough digits of accuracy to represent the values exactly hitting
an integer. But <nyrow> should be close to an integer, and rounding
<nyrow> to the nearest int should yield a calculation that makes sense.
7. Backward compatibility of the present imgsrc distribution with
previous GMT supplements.
"img2mercgrd" and another program "img2latlongrd" were previously (in
GMT version 3.0) supplied as a supplement under src/dbase/sio, a
supplement which also contained subroutines in imgsio.c and imgsio.h.
These versions were not ANSI and POSIX compliant and thus not compatible
with GMT 3.1.
The present distribution is fully compliant with ANSI, POSIX, and GMT
3.1. The location of this distribution and the file and subroutine
names have been changed to avoid confusion with old code. New features
(-N, -m, -x, -y) have been added to "img2mercgrd" to make it more
flexible in applications (-N) and in adapting to past and future
versions of img files (-m, -x, -y).
Two things are NOT backward-compatible with the old version of the
supplement:
First, the old [-v<version_number>] option has been replaced with the
new (-m, -x, -y) system for adapting the code to various img files.
Second, the old default scale value [-S0.1] has been replaced with a new
default value [-S1.0].
Both of these actions were taken because the old code was designed
around the gravity field files, before there were also topography/depth
files. Since these carry different version numbers and different scale
factors, and since the use of version numbers requires the code to be
modified every time a new version comes out, these features were
changed.
In addition, the former program "img2latlongrd" has been eliminated.
Users who wish to make a longitude-latitude grid from img data should
proceed as in the examples in #4 above. The reason for eliminating this
feature was that it became too hard to program while also supporting the
new -N option. It is better for users to use the new "img2mercgrd"
followed by a transformation, as this gives them the -N flexibility.
