## NAME

           img2mercgrd - Extract region of img, preserving Mercator, save as grd

## SYNOPSIS

           img2mercgrd imgfile -Ggrdfile -Rwest/east/south/north -Ttype [ -Nnavg ]
           [ -Sscale ] [ -V ] [ -mminutes ] [ -xmaxlon ] [ -yminlat/maxlat ]

## DESCRIPTION

           img2mercgrd reads an img format file and creates a grdfile. The Spheri-
           cal  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 grd-
           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 gmtdefaults ELLIP-
           SOID  = 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 grd file is pixel
           registered; it inherits this from the img file.

           imgfile
                  An img format file such as the marine gravity or seafloor topog-
                  raphy 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 grdfile.

           -R     west, east, south, and north specify the Region of interest.  To
                  specify boundaries in degrees and minutes, use the dd:mm format.

           -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
                  grd 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

           -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 grd

           -x     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].

           -y     Indicate minlat/maxlat as the latitude extent of the  input  img
                  file. All versions to date have used -72.006/72.006. [Default is
                  -72.006/72.006].

## 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 -Gmerc_grav.grd -R-40/40/-70/-30 -T1 -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  grd  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  projec-
           tion  using  -R-40/40/-70.0004681551/-29.9945810754  and -Jm1. 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 -Jm1 ship.lonlatgrav
           |         grdtrack         -Gmerc_grav.grd         |         mapproject
           -R-40/40/-70.0004681551/-29.9945810754 -Jm1 -I > ship.lonlatgravsat

           It  is recommended to use the above method of projecting and unproject-
           ing the data in such an application, because then  there  is  only  one
           interpolation step (in grdtrack). If one first tries to convert the grd
           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 -Jm1 -I
           -F -D2m -Ggrav.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 -Jm1 -I | surface -R-40/40/-70/70
           -I2m -Ggrav.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 pro-
           jected with -Jm1 it is 80 inches wide. We can make a map 8 inches  wide
           by using -Jx0.1 on any map programs applied to this grid (e.g., grdcon-
           tour, 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.

           img2mercgrd  world_grav.img.7.2  -Gmerc_grav_2.grd -R-40/40/-70/-30 -T1
           -N3 -V

           This     time     we     find     the      adjusted      region      is
           -R-40/40/-70.023256525/-29.9368261101 and the output is 800 by 601 pix-
           els, a better size for us. Now we can create an artificial illumination
           file for this using grdgradient:

           grdgradient merc_grav_2.grd -Gillum.grd -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:

           grdimage merc_grav_2.grd -Iillum.grd -Cgrav.cpt -Jx0.1 -K > map.ps
           psbasemap  -R-40/40/-70.023256525/-29.9368261101  -Jm0.1  -Ba10  -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  -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(GMTMANSECTION),   grdproject(GMTMANSECTION),  mapproject(GMTMANSEC-
           TION)

    GMT4.0                            1 Oct 2004        IMG2MERCGRD(GMTMANSECTION)