Provided by: gmt_4.5.11-1build1_amd64 bug


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


       img2mercgrd imgfile -Ggrdfile -Rwest/east/south/north[r] -Ttype [ -C ] [ -D[minlat/maxlat]
       ] [ -Nnavg ] [ -Sscale ] [ -V ] [ -Wmaxlon ] [ -mminutes ]


       img2mercgrd reads an img format file and creates a  grid  file.   The  Spherical  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 grid 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 -Jm 1 and
       the  adjusted  -R.   By setting the default 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 grid file is pixel registered; it inherits this from the
       img file.

              An img format file such  as  the  marine  gravity  or  seafloor  topography  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 grid file.

       -R     west,  east,  south,  and north specify the Region of interest, and you may specify
              them in decimal degrees or in  [+-]dd:mm[][W|E|S|N]  format.   Append  r  if
              lower  left  and upper right map coordinates are given instead of w/e/s/n.  The two
              shorthands -Rg and -Rd stand for global domain (0/360 and  -180/+180  in  longitude
              respectively,  with  -90/+90  in  latitude).  Alternatively, specify the name of an
              existing grid file and the -R settings (and grid spacing, if applicable) are copied
              from the grid.

       -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 grid 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.


       -C     Set  the x and y Mercator coordinates relative to projection center (lon = lat = 0)
              [Default is relative to lower left corner of grid].

       -D     Use  the  extended   latitude   range   -80.738/+80.738.    Alternatively,   append
              minlat/maxlat  as  the  latitude  extent  of  the  input  img  file.   [Default  is

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

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


       To extract data in the region -R-40/40/-70/-30 from world_grav.img.7.2, run

       img2mercgrd world_grav.img.7.2 -G merc_grav.grd -R-40/40/-70/-30 -T 1 -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 grid
       file header shows its region to be -R 0/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
       -Jm 1.  Thus, to take ship.lonlatgrav and use it to sample the merc_grav.grd,  we  can  do

       gmtset ELLIPSOID Sphere
       mapproject  -R-40/40/-70.0004681551/-29.9945810754  -Jm  1  ship.lonlatgrav  | grdtrack -G
       merc_grav.grd   |   mapproject   -R-40/40/-70.0004681551/-29.9945810754   -Jm   1   -I   >

       It  is recommended to use the above method of projecting and unprojecting the data in such
       an application, because then there is only one interpolation step (in grdtrack).   If  one
       first  tries  to  convert  the  grid  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 -Jm  1  -I  -F  -D  2m  -G

       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  -Jm  1  -I  |
       surface -R-40/40/-70/70 -I 2m -G grav.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 projected with -Jm 1  it  is  80  inches
       wide.   We  can  make  a map 8 inches wide by using -Jx 0.1 on any map programs applied to
       this grid (e.g., grdcontour, grdimage, grdview), and  then  for  overlays  which  work  in
       lon,lat  (e.g., psxy, pscoast) we can use the above adjusted -R and -Jm 0.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 contours.)  Since 2039 isn't divisible by 3  we  will  get  a
       different adjusted OPT(R) this time:

       img2mercgrd world_grav.img.7.2 -G merc_grav_2.grd -R-40/40/-70/-30 -T 1 -N 3 -V

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

       grdgradient merc_grav_2.grd -G illum.grd -A 0/270 -N e0.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 -I illum.grd -C grav.cpt -Jx 0.1 -K >
       psbasemap -R-40/40/-70.023256525/-29.9368261101 -Jm 0.1 -B a10 -O >>

       Suppose you want to obtain only the constrained data values from an img file,  in  lat/lon
       coordinates.   Then  run img2mercgrd with the -T 2 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.


       GMT(1), grdproject(1), mapproject(1)