Provided by: gmt-common_5.2.1+dfsg-3build1_all bug

NAME

       img2grd - Extract subset of img file in Mercator or Geographic format

SYNOPSIS

       img2grd  imgfile grdfile region type [  ] [ [minlat/maxlat] ] [  ] [ minutes ] [  ] [ navg
       ] [ [scale] ] [ [level] ] [ maxlon ] [ -n<flags> ]

       Note: No space is allowed between the option flag and the associated arguments.

DESCRIPTION

       img2grd reads an img format file, extracts a subset, and writes it to a grid file. The  -M
       option  dictates  whether  or  not  the  Spherical  Mercator projection of the img file is
       preserved or if a Geographic grid should be written by undoing the Mercator projection. If
       geographic grid is selected you can also request a resampling onto the exact -R given.

REQUIRED ARGUMENTS

       imgfile
              A Mercator 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_DATADIR,  then  img2grd will try to find imgfile in
              $GMT_DATADIR; else it will try to open imgfile directly.

       -Ggrdfile
              grdfile is the name of the output grid file.

       -R[unit]west/east/south/north[/zmin/zmax][r]
              west, east, south, and north specify the region of interest, and  you  may  specify
              them in decimal degrees or in [+-]dd:mm[:ss.xxx][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  for  grid  creation,  give
              Rcodelon/lat/nx/ny,  where  code is a 2-character combination of L, C, R (for left,
              center, or right) and T, M, B for top, middle, or bottom. e.g., BL for lower  left.
              This  indicates  which  point on a rectangular region the lon/lat coordinate refers
              to, and the grid dimensions nx and ny with grid spacings via -I is used  to  create
              the corresponding region.  Alternatively, specify the name of an existing grid file
              and the -R settings (and grid spacing, if applicable) are  copied  from  the  grid.
              Using  -Runit  expects  projected (Cartesian) coordinates compatible with chosen -J
              and we inversely project to determine actual rectangular  geographic  region.   For
              perspective  view  (-p), optionally append /zmin/zmax.  In case of perspective view
              (-p), a z-range (zmin, zmax) can be appended to indicate the third dimension.  This
              needs to be done only when using the -Jz option, not when using only the -p option.
              In the latter case a perspective view of  the  plane  is  plotted,  with  no  third
              dimension.

OPTIONAL ARGUMENTS

       -C     Set  the  x  and  y  Mercator coordinates relative to projection center [Default is
              relative to lower left corner of grid]. Requires -M.

       -D[minlat/maxlat]
              Use  the   extended   latitude   range   -80.738/+80.738.   Alternatively,   append
              minlat/maxlat  as  the  latitude  extent  of  the  input  img  file.   [Default  is
              -72.006/72.006]. Not usually required  since  we  can  determine  the  extent  from
              inspection of the file size.

       -E     Can  be  used  when  -M  is  not set to force the final grid to have the exact same
              region as requested with -R. By default, the final region is a direct projection of
              the  original  Mercator  region  and  will  typically  extend  slightly  beyond the
              requested latitude range, and furthermore the grid increment in latitude  does  not
              match  the  longitude  increment.  However,  the  extra resampling introduces small
              interpolation errors and should only be used if the  output  grid  must  match  the
              requested  region and have x_inc = y_inc. In this case the region set by -R must be
              given in multiples of the increment (.e.g, -R0/45/45/72).

       -I     Indicate minutes as the width of an  input  img  pixel  in  minutes  of  longitude.
              [Default  is  2.0]. Not usually required since we can determine the pixel size from
              inspection of the size.

       -M     Output a Spherical Mercator grid  [Default  is  a  geographic  lon/lat  grid].  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  -Jm1 and the adjusted -R. By setting the
              default PROJ_ 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 grid
              header remark, so it can be found later. See -C  to  set  coordinates  relative  to
              projection center.

       -Nnavg 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[scale]
              Multiply  the  img  file  values by scale before storing in grid file.  [Default is
              1.0]. For recent img files: img topo files are stored in (corrected) meters  [-S1];
              free-air gravity files in mGal*10 [-S0.1 to get mGal]; vertical deflection files in
              micro-radians*10 [-S0.1 to get micro-radians], vertical gravity gradient  files  in
              Eotvos*50  [-S0.02 to get Eotvos, or -S0.002 to get mGal/km]). If no scale is given
              we try to determine the scale by examining the file name for clues.

       -Ttype 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) 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 [Default is 1].

       -V[level] (more ...)
              Select verbosity level [c]. Particularly recommended here, as it is helpful to  see
              how the coordinates are adjusted.

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

       -^ or just -
              Print a short message about the syntax of the command, then exits (NOTE: on Windows
              use just -).

       -+ or just +
              Print  an  extensive  usage  (help)  message,  including  the  explanation  of  any
              module-specific option (but not the GMT common options), then exits.

       -? or no arguments
              Print  a  complete usage (help) message, including the explanation of options, then
              exits.

       --version
              Print GMT version and exit.

       --show-datadir
              Print full path to GMT share directory and exit.

GEOGRAPHIC EXAMPLES

       The -M option should be excluded  if  you  need  the  output  grid  to  be  in  geographic
       coordinates.  To  extract  data in the region -R-40/40/-70/-30 from world_grav.img.7.2 and
       reproject to yield geographic coordinates, you can try

              img2grd world_grav.img.16.1 -Gmerc_grav.nc -R-40/40/-70/-30 -V

       Because the latitude spacing in the  img  file  is  equidistant  in  Mercator  units,  the
       resulting  grid will not match the specified -R exactly, and the latitude spacing will not
       equal the longitude spacing. If you need an exact match with your -R and the same  spacing
       in longitude and latitude, use the -E option:

              img2grd world_grav.img.16.1 -Gmerc_grav.nc -R-40/40/-70/-30 -E -V

MERCATOR EXAMPLES

       Since the img files are in a Mercator projection, you should NOT extract a geographic grid
       if your plan is to make a Mercator map.  If  you  did  that  you  end  of  projecting  and
       reprojection the grid, loosing short-wavelength detail. Better to use -M and plot the grid
       using a linear projection with the same scale as the desired Mercator projection (see  GMT
       Example 29).  To extract data in the region -R-40/40/-70/-30 from world_grav.img.7.2, run

              gmt img2grd -M world_grav.img.7.2 -Gmerc_grav.nc -R-40/40/-70/-30 -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 -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.nc, we can do this:

              gmt set PROJ_ELLIPSOID Sphere

              gmt mapproject -R-40/40/-70.0004681551/-29.9945810754 -Jm1i ship.lonlatgrav | \
                        gmt grdtrack -Gmerc_grav.nc | gmt mapproject \
                        -R-40/40/-70.0004681551/-29.9945810754 -Jm1i -I > ship.lonlatgravsat

       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

              gmt grdproject merc_grav.nc -R-40/40/-70.0004681551/-29.9945810754 -Jm1i -I -D2m -Ggrav.nc

       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)

              gmt grd2xyz merc_grav.nc | gmt mapproject \
                  -R-40/40/-70.0004681551/-29.994581075 -Jm1i -I | \
                  gmt surface -R-40/40/-70/70 -I2m -Ggrav.nc

       To   make   a   Mercator  map  of  the  above  region,  suppose  our  gmt.conf  value  for
       PROJ_LENGTH_UNIT is inch. Then since the above merc_grav.nc file is projected  with  -Jm1i
       it is 80 inches wide. We can make a map 8 inches wide by using -Jx0.1i 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 -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.nc) we realize that
       merc_grav.nc 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 do not 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 -R this time:

              gmt img2grd -M world_grav.img.7.2 -Gmerc_grav_2.nc -R-40/40/-70/-30 -N3 -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:

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

              gmt grdimage merc_grav_2.nc -Iillum.nc -Cgrav.cpt -Jx0.1i -K > map.ps
              gmt psbasemap -R-40/40/-70.023256525/-29.9368261101 -Jm0.1i -Ba10 -O >> map.ps

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

COPYRIGHT

       2015, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe