	$Id: README.imgsrc,v 1.9 2009/09/09 23:27:04 guru Exp $

Maintained by: W H F Smith
All code files are explicitly distributed under the
GNU Public License, see file LICENSE.TXT for more details.

==> 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 "makegmt.macros" in 
"makefile".

makefile uses "../makegmt.macros" 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.
