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
              file. [Default is 1.0].  (img topo files  are  stored  in  (cor-
              rected)  meters;  gravity  files in mGal*10; vertical deflection
              files in microradians*10, vertical  gravity  gradient  files  in
              Eotvos*10. Use -S0.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]

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

       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 won’t be easy as the -R in the two  coordinate  sys-
       tems won’t 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 gmtdefault MEA-
       SURE_UNIT is inch. Then since the above merc_grav.grd file is projected
       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.

       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 con-
       tours.)  Since 2039 isn’t divisible  by  3  we  will  get  a  different
       adjusted -R this time:’

       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)



                                  1 Jan 2004                    IMG2MERCGRD(l)

Man(1) output converted with man2html