NAME

       talwani3d - Compute free-air, geoid or vertical gravity gradients anomalies over 3-D bodies

SYNOPSIS

       talwani3d  [  modeltable  ] [  ] [ rho ] ] [ f|n|v ] [ grdfile ] [ increment ] [ [h][v] ] [ trackfile ] [
       region ] [ level|obsgrid ] [ [level] ] [ -bi<binary> ] [ -fg ] [ -i<flags> ] [  -o<flags>  ]  [  -r  ]  [
       -x[[-]n] ]

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

DESCRIPTION

       talwani3d  will  read  the  multi-segment  modeltable  from  file  or standard input.  This file contains
       contours of a 3-D body at different z-levels, with one contour per  segment.   The  segment  header  must
       contain  the  parameters  zlevel  rho,  which  states  the  z contour level and the density of this slice
       (individual slice densities may be overridden by a fixed density contrast given via -D).  We can  compute
       anomalies  on an equidistant grid (by specifying a new grid with -R and -I or provide an observation grid
       with elevations) or at arbitrary output points specified via -N.  Chose from free-air anomalies, vertical
       gravity gradient anomalies, or geoid  anomalies.   Options  are  available  to  control  axes  units  and
       direction.

REQUIRED ARGUMENTS

       modeltable
              The  file describing the horizontal contours of the bodies.  Contours will be automatically closed
              if not already closed, and repeated vertices will be eliminated.

       -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

       -A     The z-axis should be positive upwards [Default is down].

       -Dunit Sets fixed density contrast that overrides any setting in model file, in kg/m^3.

       -Ff|n|v
              Specify desired gravitational field component.  Choose between f (free-air anomaly)  [Default],  n
              (geoid) or v (vertical gravity gradient).

       -Ggrdfile
              Specify  the  name  of  the  output  grid  file;  see  GRID FILE FORMATS below).  Required when an
              equidistant grid is implied for output.  If -N is used then the output is written to stdout.

       -M[h][v]
              Sets units used.  Append h to indicate horizontal distances  are  in  km  [m],  and  append  z  to
              indicate vertical distances are in km [m].

       -Ntrackfile
              Specifies  locations where we wish to compute the predicted value.  When this option is used there
              are no grids and the output data records are written to stdout.

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

       -Zlevel|obsgrid
              Set observation level either as a constant or give the name of a grid with observation levels.  If
              the latter is used the the grid determines the output grid region [0].

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

       -fg    Geographic grids (dimensions of longitude, latitude) will be converted to km via  a  "Flat  Earth"
              approximation using the current ellipsoid parameters.

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

       -ocols[,...] (more ...)
              Select output 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).

       -:[i|o] (more ...)
              Swap 1st and 2nd column on input and/or output.

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

UNITS

       For map distance unit, append unit d for arc degree, m for arc minute, and s for arc  second,  or  e  for
       meter [Default], f for foot, k for km, M for statute mile, n for nautical mile, and u for US survey foot.
       By  default  we compute such distances using a spherical approximation with great circles. Prepend - to a
       distance (or the unit is no distance is given) to perform "Flat Earth"  calculations  (quicker  but  less
       accurate) or prepend + to perform exact geodesic calculations (slower but more accurate).

EXAMPLES

       To  compute  the  free-air  anomalies  on  a  grid  over  a 3-D body that has been contoured and saved to
       body.txt, using 1.7 g/cm^3 as the density contrast, try

          gmt talwani3d -R-200/200/-200/200 -I2 -G3dgrav.nc body.txt -D1700 -Fg

       To obtain the vertical gravity gradient anomaly along the track in crossing.txt for the same model, try

          gmt talwani3d -Ncrossing.txt body.txt -D1700 -Fv > vgg_crossing.txt

       Finally, the geoid anomaly along the same track in crossing.txt for the same model is returned by

          gmt talwani3d -Ncrossing.txt body.txt -D1700 -Fn > n_crossing.txt

REFERENCES

       Talwani, M., and M. Ewing (1960), Rapid computation  of  gravitational  attraction  of  three-dimensional
       bodies of arbitrary shape, Geophysics, 25(203-225).

SEE ALSO

       gmt.conf, gmt, grdmath, gravfft, gmtgravmag3d, grdgravmag3d, talwani2d

COPYRIGHT

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

5.2.1                                           January 28, 2016                                 TALWANI3D(1gmt)