xenial (1) img2grd.1gmt.gz

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

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