NAME

       sph2grd - Compute grid from spherical harmonic coefficients

SYNOPSIS

       sph2grd [ table ]  -Ggrdfile
        -Iincrement
        -Rregion  [   -D[g|n]  ]  [   -E ] [  -F[k]filter ] [  -N[norm] ] [  -Q ] [  -V[level] ] [ -bibinary ] [
       -hheaders ] [ -iflags ] [ -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][+e|n][/yinc[unit][+e|n]]
              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 +e 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  +n  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.

       -Rxmin/xmax/ymin/ymax[+r][+uunit] (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 and transformations (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 just use -).

       -+ 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 all options, then exits.

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[+sscale][+ooffset][+ninvalid],  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  invalid
       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

COPYRIGHT

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

5.4.3                                             Jan 03, 2018                                     SPH2GRD(1gmt)