xenial (1) sph2grd.1gmt.gz

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

NAME

       sph2grd - Compute grid from spherical harmonic coefficients

SYNOPSIS

       sph2grd  [  table  ]  grdfile increment region [ [g|n] ] [  ] [ [k]filter ] [ [norm] ] [  ] [ [level] ] [
       -bi<binary> ] [ -h<headers> ] [ -i<flags> ] [ -r ] [ -x[[-]n] ]

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

DESCRIPTION

       sph2grd reads a spherical harmonics coefficient table with records of L, M, C[L,M], S[L,M] and  evaluates
       the spherical harmonic model on the specified grid.

REQUIRED ARGUMENTS

       -Ggrdfile
              grdfile is the name of the binary output grid file. (See GRID FILE FORMAT below.)

       -Ixinc[unit][=|+][/yinc[unit][=|+]]
              x_inc  [and  optionally  y_inc]  is  the  grid  spacing.  Optionally,  append  a  suffix modifier.
              Geographical (degrees) coordinates: Append m to indicate arc minutes or s to indicate arc seconds.
              If  one  of the units e, f, k, M, n or u is appended instead, the increment is assumed to be given
              in meter, foot, km, Mile, nautical mile or US survey foot, respectively, and will be converted  to
              the  equivalent  degrees longitude at the middle latitude of the region (the conversion depends on
              PROJ_ELLIPSOID). If /y_inc is given but set to 0 it will be reset equal  to  x_inc;  otherwise  it
              will  be  converted  to degrees latitude. All coordinates: If = is appended then the corresponding
              max x (east) or y (north) may be slightly adjusted to fit exactly the given increment [by  default
              the  increment  may  be  adjusted slightly to fit the given domain]. Finally, instead of giving an
              increment you may specify the number of nodes desired by  appending  +  to  the  supplied  integer
              argument;  the  increment  is  then  recalculated  from  the  number  of nodes and the domain. The
              resulting  increment  value  depends  on  whether  you  have  selected  a  gridline-registered  or
              pixel-registered  grid; see App-file-formats for details. Note: if -Rgrdfile is used then the grid
              spacing has already been initialized; use -I to override the values.

       -R[unit]xmin/xmax/ymin/ymax[r] (more ...)
              Specify the region of interest.

OPTIONAL ARGUMENTS

       table  One or more ASCII [or binary, see -bi] files  holding  the  spherical  harmonic  coefficients.  We
              expect  the  first four columns to hold the degree L, the order M, followed by the cosine and sine
              coefficients.

       -D[g|n]
              Will evaluate a derived field from a geopotential model.  Choose between Dg which will compute the
              gravitational field or Dn to compute the geoid [Add -E for anomalies on the ellipsoid].

       -E     Evaluate expansion on the current ellipsoid [Default is sphere].

       -F[d]filter
              Filter coefficients according to one of two kinds of filter specifications:.  Select -Fk if values
              are given in km [Default is coefficient harmonic degree  L].  a)  Cosine  band-pass:  Append  four
              wavelengths lc/lp/hp/hc.  Coefficients outside lc/hc are cut; those inside lp/hp are passed, while
              the rest are tapered.  Replace wavelength by - to skip, e.g., -F-/-/50/75 is  a  low-pass  filter.
              b)  Gaussian  band-pass:  Append  two  wavelengths  lo/hi  where filter amplitudes = 0.5.  Replace
              wavelength by - to skip, e.g., -F70/- is a high-pass Gaussian filter.

       -N[norm]
              Normalization used for coefficients.  Choose among m: Mathematical normalization - inner  products
              summed  over  surface  equal  1  [Default].   g Geodesy normalization - inner products summed over
              surface equal 4pi. s: Schmidt normalization - as used in geomagnetism.

       -V[level] (more ...)
              Select verbosity level [c].

       -bi[ncols][t] (more ...)
              Select native binary input. [Default is 4 input columns].

       -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
              Skip or produce header record(s). Not used with binary data.

       -icols[l][sscale][ooffset][,...] (more ...)
              Select input columns (0 is first column).

       -r (more ...)
              Set pixel node registration [gridline].

       -x[[-]n] (more ...)
              Limit number of cores used in multi-threaded algorithms (OpenMP required).

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

GRID VALUES PRECISION

       Regardless  of  the precision of the input data, GMT programs that create grid files will internally hold
       the grids in 4-byte floating point arrays. This is done to conserve memory and furthermore  most  if  not
       all  real data can be stored using 4-byte floating point values. Data with higher precision (i.e., double
       precision values) will lose that precision once GMT operates on the grid or  writes  out  new  grids.  To
       limit  loss  of  precision  when processing data you should always consider normalizing the data prior to
       processing.

GRID FILE FORMATS

       By default GMT writes out grid as single precision floats  in  a  COARDS-complaint  netCDF  file  format.
       However,  GMT  is  able  to  produce  grid  files  in many other commonly used grid file formats and also
       facilitates so called "packing" of grids, writing out floating point data as 1- or  2-byte  integers.  To
       specify  the  precision, scale and offset, the user should add the suffix =id[/scale/offset[/nan]], where
       id is a two-letter identifier of the grid type and precision, and scale and  offset  are  optional  scale
       factor  and  offset to be applied to all grid values, and nan is the value used to indicate missing data.
       See grdconvert and Section grid-file-format  of  the  GMT  Technical  Reference  and  Cookbook  for  more
       information.

       When  writing a netCDF file, the grid is stored by default with the variable name "z". To specify another
       variable name varname, append ?varname to the file name. Note that you may need  to  escape  the  special
       meaning  of ? in your shell program by putting a backslash in front of it, or by placing the filename and
       suffix between quotes or double quotes.

GEOGRAPHICAL AND TIME COORDINATES

       When the output grid type is netCDF, the coordinates will be labeled "longitude", "latitude",  or  "time"
       based  on the attributes of the input data or grid (if any) or on the -f or -R options. For example, both
       -f0x -f1t and -R90w/90e/0t/3t will result in a longitude/time grid. When the x, y,  or  z  coordinate  is
       time, it will be stored in the grid as relative time since epoch as specified by TIME_UNIT and TIME_EPOCH
       in the gmt.conf file or on the command line. In addition, the unit attribute of the  time  variable  will
       indicate both this unit and epoch.

EXAMPLES

       To create a 1 x 1 degree global grid file from the ASCII coefficients in EGM96_to_360.txt, use

              gmt sph2grd EGM96_to_360.txt -GEGM96_to_360.nc -Rg -I1 -V

REFERENCE

       Holmes,  S.  A.,  and  Featherstone,  W.  E.,  2002, A unified approach to the Clenshaw summation and the
       recursive computation of very high degree and order normalized associated Legendre functions: J. Geodesy,
       v. 76, p. 279-299.

SEE ALSO

       gmt, grdfft, grdmath

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