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 Spher-
       ical  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
       grdfile header is set so that the x and y axis lengths  represent  dis-
       tance  from  the  west  and  south edges of the image, measured in user
       default units, with -Jm1 and the adjusted -R.  By  setting  the  gmtde-
       faults 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
       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             projection             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  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.

       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 res-
       olution 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  aver-
       age  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 dif-
       ferent 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 illumina-
       tion 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)



VERSION                              DATE           IMG2MERCGRD(GMTMANSECTION)

Man(1) output converted with man2html