.TH GREENSPLINE 1gmt "15 Jul 2011" "GMT 4.5.7" "Generic Mapping Tools"
.SH NAME
greenspline \- Interpolate 1-D, 2-D, 3-D Cartesian or spherical surface data using Green's function splines.
.SH SYNOPSIS
\fBgreenspline\fP [ \fIdatafile(s)\fP ] 
[ \fB\-A\fP[\fB1\fP|\fB2\fP|\fB3\fP|\fB4\fP|\fB5\fP,]\fIgradfile\fP ] [ \fB\-C\fP\fIcut\fP[/\fIfile\fP] ] 
[ \fB\-D\fP\fImode\fP ] [ \fB\-F\fP ] [ \fB\-G\fP\fIgrdfile\fP ] [ \fB\-H\fP[\fBi\fP][\fInrec\fP] ] 
[ \fB\-I\fP\fIxinc\fP[\fIyinc\fP[\fIzinc\fP]] ] [ \fB\-L\fP ] [ \fB\-N\fP\fInodefile\fP ] [ \fB\-Q\fP\fIaz\fP|\fIx/y/z\fP ] 
[ \fB\-R\fP\fIxmin\fP/\fIxmax\fP[/\fIymin\fP/\fIymax\fP[/\fIzmin\fP\fIzmax\fP]] ] 
[ \fB\-S\fP\fBc|t|g|p|q\fP[\fIpars\fP] ] [ \fB\-T\fP\fImaskgrid\fP ] [ \fB\-V\fP ] [ \fB\-:\fP[\fBi\fP|\fBo\fP] ] [ \fB\-bi\fP[\fBs\fP|\fBS\fP|\fBd\fP|\fBD\fP[\fIncol\fP]|\fBc\fP[\fIvar1\fP\fB/\fP\fI...\fP]] ] [ \fB\-bo\fP[\fBs\fP|\fBS\fP|\fBd\fP|\fBD\fP[\fIncol\fP]|\fBc\fP[\fIvar1\fP\fB/\fP\fI...\fP]] ]
.SH DESCRIPTION
\fBgreenspline\fP uses the Green's function G(\fBx\fP; \fBx'\fP) for the chosen spline and geometry to interpolate data
at regular [or arbitrary] output locations.  Mathematically, the solution is composed as
\fIw\fP(\fBx\fP) = sum {\fIc\fP(\fIi\fP) G(\fBx\fP; \fBx\fP(\fIi\fP))}, for \fIi\fP = 1, \fIn\fP, the number
of data points {\fBx\fP(\fIi\fP), \fIw\fP(\fIi\fP)}.  Once the \fIn\fP coefficients \fIc\fP(\fIi\fP)
have been found then the sum can be evaluated at any output point \fBx\fP.
Choose between ten minimum curvature, regularized, or continuous curvature splines in tension for
either 1-D, 2-D, or 3-D Cartesian coordinates or spherical surface coordinates. After first removing a linear or planar trend
(Cartesian geometries) or mean value (spherical surface) and normalizing these residuals,
the least-squares matrix solution for the spline coefficients \fIc\fP(\fIi\fP) is found by
solving the \fIn\fP by \fIn\fP linear system \fIw\fP(\fIj\fP) = sum-over-\fIi\fP {\fIc\fP(\fIi\fP) G(\fBx\fP(\fIj\fP); \fBx\fP(\fIi\fP))},
for \fIj\fP = 1, \fIn\fP; this
solution yields an exact interpolation of the supplied data points.  Alternatively, you may
choose to perform a singular value decomposition (SVD) and eliminate the contribution from the
smallest eigenvalues; this approach yields an approximate solution.  Trends and scales are
restored when evaluating the output.
.SH OPTIONS
.TP
\fIdatafile(s)\fP
The name of one or more ASCII [or binary, see \fB\-bi\fP] files holding the \fBx\fP, \fIw\fP
data points.  If no file is given then we read standard input instead.
.TP
\fB\-A\fP
The solution will partly be constrained by surface gradients \fBv\fP = \fIv\fP*\fBn\fP, where \fIv\fP is the
gradient magnitude and \fBn\fP its unit vector direction.  The gradient direction may be specified either by
Cartesian components (either unit vector \fBn\fP and magnitude \fIv\fP separately or gradient components \fBv\fP directly)
or angles w.r.t. the coordinate axes.  Specify one of five input formats:
\fB0\fP: For 1-D data there is no direction, just gradient magnitude (slope) so the input format is
\fIx, gradient\fP.  Options 1-2 are for 2-D data sets:
\fB1\fP: records contain \fIx, y, azimuth, gradient\fP (\fIazimuth\fP in degrees is measured
clockwise from the vertical (north) [Default]).
\fB2\fP: records contain \fIx, y, gradient, azimuth\fP (\fIazimuth\fP in degrees is measured
clockwise from the vertical (north)).  Options 3-5 are for either 2-D or 3-D data:
\fB3\fP: records contain \fBx\fP, \fIdirection(s), v\fP (\fIdirection(s)\fP in degrees are measured
counter-clockwise from the horizontal (and for 3-D the vertical axis). 
\fB4\fP: records contain \fBx\fP, \fBv\fP.
\fB5\fP: records contain \fBx\fP, \fBn\fP, \fIv\fP.
Append name of ASCII file with the surface gradients (following a comma if a format is specified).  
.TP
\fB\-C\fP
Find an approximate surface fit: Solve the linear system for the spline coefficients by SVD and eliminate the contribution
from all eigenvalues whose ratio to the largest
eigenvalue is less than \fIcut\fP [Default uses Gauss-Jordan elimination to solve the
linear system and fit the data exactly].  Optionally, append /\fIfile\fP to
save the eigenvalue ratios to the specified file for further analysis.
Finally, if a negative \fIcut\fP is given then /\fIfile\fP is required and execution
will stop after saving the eigenvalues, i.e., no surface output is produced.
.TP
\fB\-D\fP
Sets the distance flag that determines how we calculate distances between data points.  
Select \fImode\fP 0 for Cartesian 1-D spline interpolation:
\fB\-D\fP0 means (\fIx\fP) in user units, Cartesian distances,
Select \fImode\fP 1-3 for Cartesian 2-D surface spline interpolation:
\fB\-D\fP1 means (\fIx,y\fP) in user units, Cartesian distances,
\fB\-D\fP2 for (\fIx,y\fP) in degrees, flat Earth distances, and
\fB\-D\fP3 for (\fIx,y\fP) in degrees, spherical distances in km.
Then, if \fBELLIPSOID\fP is spherical, we compute great circle arcs, otherwise geodesics.
Option \fImode\fP = 4 applies to spherical surface spline interpolation only:
\fB\-D\fP4 for (\fIx,y\fP) in degrees, use cosine of great circle (or geodesic) arcs.
Select \fImode\fP 5 for Cartesian 3-D surface spline interpolation:
\fB\-D\fP5 means (\fIx,y,z\fP) in user units, Cartesian distances.
.TP
\fB\-F\fP
Force pixel registration.  [Default is gridline registration].
.TP
\fB\-G\fP
Name of resulting output file.  (1) If options \fB\-R\fP, \fB\-I\fP, and possibly \fB\-F\fP are set we produce
an equidistant output table.  This will be written to stdout unless \fB\-G\fP is specified.  Note: for 2-D
grids the \fB\-G\fP option is required.  (2) If option \fB\-T\fP is selected then \fB\-G\fP is required and the
output file is a 2-D binary grid file.  Applies to 2-D interpolation only.
(3) If \fB\-N\fP is selected then the output is an ASCII (or binary; see \fB\-bo\fP) table;
if \fB\-G\fP is not given then this table is written to standard output.  Ignored if \fB\-C\fP or \fB\-C\fP0
is given.
.TP
\fB\-H\fP
Input file(s) has header record(s).  If used, the default number of header records is \fBN_HEADER_RECS\fP.
Use \fB\-Hi\fP if only input data should have header records [Default will write out header records if the
input data have them]. Blank lines and lines starting with # are always skipped.
.TP
\fB\-I\fP
Specify equidistant sampling intervals, on for each dimension, separated by slashes.
.TP
\fB\-L\fP
Do \fInot\fP remove a linear (1-D) or planer (2-D) trend when \fB\-D\fP selects mode 0-3 [For those Cartesian cases a least-squares
line or plane is modeled and removed, then restored after fitting a spline to the residuals].  However, in mixed
cases with both data values and gradients, or for spherical surface data, only the mean data value is removed
(and later and restored).
.TP
\fB\-N\fP
ASCII file with coordinates of desired output locations \fBx\fP in the first column(s).  The resulting
\fIw\fP values are appended to each record and written to the file given in \fB\-G\fP [or stdout if not specified];
see \fB\-bo\fP for binary output instead.  This option eliminates the need to
specify options \fB\-R\fP, \fB\-I\fP, and \fB\-F\fP.
.TP
\fB\-Q\fP
Rather than evaluate the surface, take the directional derivative in the \fIaz\fP azimuth and return the magnitude of this
derivative instead.  For 3-D interpolation, specify the three components of the desired vector direction (the vector will
be normalized before use).
.TP
\fB\-R\fP
Specify the domain for an equidistant lattice where output predictions are required.  Requires \fB\-I\fP and optionally \fB\-F\fP.
.br
\fI1-D:\fP  Give \fIxmin/xmax\fP, the minimum and maximum \fIx\fP coordinates.
.br
\fI2-D:\fP  Give \fIxmin/xmax/ymin/ymax\fP, the minimum and maximum \fIx\fP and \fIy\fP coordinates.
These may be Cartesian or geographical.  If geographical, then
\fIwest, east, south,\fP and \fInorth\fP specify the Region of interest, and you may specify them
in decimal degrees or in [+-]dd:mm[:ss.xxx][W|E|S|N] format.  The two shorthands \fB\-Rg\fP and \fB\-Rd\fP stand for global domain
(0/360 and -180/+180 in longitude respectively, with -90/+90 in latitude).
.br
\fI3-D:\fP  Give \fIxmin/xmax/ymin/ymax/zmin/zmax\fP, the minimum and maximum \fIx\fP, \fIy\fP and \fIz\fP coordinates.
See the 2-D section if your horizontal coordinates are geographical; note the shorthands \fB\-Rg\fP and \fB\-Rd\fP cannot
be used if a 3-D domain is specified.
.TP
\fB\-S\fP
Select one of five different splines.  The first two are used for 1-D, 2-D, or 3-D Cartesian splines (see \fB\-D\fP for discussion).
Note that all tension values are expected to be normalized tension in the range 0 < \fIt\fP < 1:
(\fBc\fP) Minimum curvature spline [\fISandwell\fP, 1987],
(\fBt\fP) Continuous curvature spline in tension [\fIWessel and Bercovici\fP, 1998]; append
\fItension\fP[/\fIscale\fP] with \fItension\fP in the 0\-1 range and optionally supply a length scale [Default is the average grid spacing].
The next is a 2-D or 3-D spline:
(\fBr\fP) Regularized spline in tension [\fIMitasova and Mitas\fP, 1993]; again, append \fItension\fP and optional \fIscale\fP.
The last two are spherical surface splines and both imply \fB\-D\fP4 \fB\-fg\fP:
(\fBp\fP) Minimum curvature spline [\fIParker\fP, 1994],
(\fBq\fP) Continuous curvature spline in tension [\fIWessel and Becker\fP, 2008]; append \fItension\fP.
The G(\fBx\fP; \fBx'\fP) for the last method is slower to compute; by specifying OPT(SQ) you can speed up calculations
by first pre-calculating G(\fBx\fP; \fBx'\fP) for a dense set of \fBx\fP values (e.g., 100,001 nodes between -1 to +1)
and store them in look-up tables.  Optionally append /\fIN\fP (an odd integer) to specify how many points in the spline to set [100001]
.TP
\fB\-T\fP
For 2-D interpolation only.  Only evaluate the solution at the nodes in the \fImaskgrid\fP that are not equal to NaN. This option eliminates the need to
specify options \fB\-R\fP, \fB\-I\fP, and \fB\-F\fP.
.TP
\fB\-V\fP
Selects verbose mode, which will send progress reports to stderr [Default runs "silently"].
.TP
\fB\-bi\fP
Selects binary input.
Append \fBs\fP for single precision [Default is \fBd\fP (double)].
Uppercase \fBS\fP or \fBD\fP will force byte-swapping.
Optionally, append \fIncol\fP, the number of columns in your binary input file
if it exceeds the columns needed by the program.
Or append \fBc\fP if the input file is netCDF. Optionally, append \fIvar1\fP\fB/\fP\fIvar2\fP\fB/\fP\fI...\fP to
specify the variables to be read.
[Default is 2-4 input columns (\fBx\fP,\fIw\fP); the number depends on the chosen dimension].
.TP
\fB\-bo\fP
Selects binary output.
Append \fBs\fP for single precision [Default is \fBd\fP (double)].
Uppercase \fBS\fP or \fBD\fP will force byte-swapping.
Optionally, append \fIncol\fP, the number of desired columns in your binary output file.
.SH 1-D EXAMPLES
To resample the \fIx,y\fP Gaussian random data created by \fBgmtmath\fP and stored in 1D.txt, requesting output
every 0.1 step from 0 to 10, and using a minimum cubic spline, try
.br
.sp
\fBgmtmath\fP \fB\-T\fP0/10/1 0 1 \fBNRAND\fP = 1D.txt
.br
\fBpsxy \-R\fP0/10/-5/5 \fB\-JX\fP6i/3i \fB\-B\fP2f1/1 \fB\-Sc\fP0.1 \fB\-G\fPblack 1D.txt \fB\-K\fP > 1D.ps
.br
\fBgreenspline\fP 1D.txt \fB\-R\fP0/10 \fB\-I\fP0.1 \fB\-Sc\fP \fB\-V\fP | \fBpsxy\fP \fB\-R\fP \fB\-J\fP \fB\-O\fP \fB\-W\fPthin >> 1D.ps
.br
.sp
To apply a spline in tension instead, using a tension of 0.7, try
.br
.sp
\fBpsxy \-R\fP0/10/-5/5 \fB\-JX\fP6i/3i \fB\-B\fP2f1/1 \fB\-Sc\fP0.1 \fB\-G\fPblack 1D.txt \fB\-K\fP > 1Dt.ps
.br
\fBgreenspline\fP 1D.txt \fB\-R\fP0/10 \fB\-I\fP0.1 \fB\-St\fP0.7 \fB\-V\fP | \fBpsxy\fP \fB\-R\fP \fB\-J\fP \fB\-O\fP \fB\-W\fPthin >> 1Dt.ps
.SH 2-D EXAMPLES
To make a uniform grid using the minimum curvature spline for the same Cartesian data set from Davis (1986) that is
used in the GMT Cookbook example 16, try
.sp
\fBgreenspline\fP table_5.11 \fB\-R\fP0/6.5/-0.2/6.5 \fB\-I\fP0.1 \fB\-Sc\fP \fB\-V\fP \fB\-D\fP1 \fB\-G\fPS1987.grd
.br
\fBpsxy \-R\fP0/6.5/-0.2/6.5 \fB\-JX\fP6i \fB\-B\fP2f1 \fB\-Sc\fP0.1 \fB\-G\fPblack table_5.11 \fB\-K\fP > 2D.ps
.br
\fBgrdcontour \-JX\fP6i \fB\-B\fP2f1 \fB\-O\fP \fB\-C\fP25 \fB\-A\fP50 S1987.grd >> 2D.ps
.br
.sp
To use Cartesian splines in tension but only evaluate the solution where the input mask grid is not NaN, try
.br
.sp
\fBgreenspline\fP table_5.11 \fB\-T\fPmask.grd \fB\-St\fP0.5 \fB\-V\fP \fB\-D\fP1 \fB\-G\fPWB1998.grd
.br
.sp
To use Cartesian generalized splines in tension and return the magnitude of the surface slope in
the NW direction, try
.br
.sp
\fBgreenspline\fP table_5.11 \fB\-R\fP0/6.5/-0.2/6.5 \fB\-I\fP0.1 \fB\-Sr\fP0.95 \fB\-V\fP \fB\-D\fP1 \fB\-Q\fP-45 \fB\-G\fPslopes.grd
Finally, to use Cartesian minimum curvature splines in recovering a surface where the input data is a single surface
value (pt.d) and the remaining constraints specify only the surface slope and direction (slopes.d), use
.br
.sp
\fBgreenspline\fP pt.d \fB\-R\fP-3.2/3.2/-3.2/3.2 \fB\-I\fP0.1 \fB\-Sc\fP \fB\-V\fP \fB\-D\fP1 \fB\-A\fP1,slopes.d \fB\-G\fPslopes.grd
.SH 3-D EXAMPLES
To create a uniform 3-D Cartesian grid table based on the data in table_5.23 in Davis (1986) that contains \fIx,y,z\fP locations and
a measure of uranium oxide concentrations (in percent), try
.br
.sp
\fBgreenspline\fP table_5.23 \fB\-R\fP5/40/-5/10/5/16 \fB\-I\fP0.25 \fB\-Sr\fP0.85 \fB\-V\fP \fB\-D\fP5 \fB\-G\fP3D_UO2.txt
.SH 2-D SPHERICAL SURFACE EXAMPLES
To recreate Parker's [1994] example on a global 1x1 degree grid, assuming the data are in file mag_obs_1990.d, try
.sp
greenspline \fB\-V\fP \fB\-Rg\fP \fB\-fg\fP \fB\-Sp\fP \fB\-D\fP3 \fB\-I\fP1 \fB\-G\fPP1994.grd mag_obs_1990.d
.sp
To do the same problem but applying tension and use pre-calculated Green functions, use
.sp
greenspline \fB\-V\fP \fB\-Rg\fP \fB\-fg\fP \fB\-SQ\fP0.85 \fB\-D\fP3 \fB\-I\fP1 \fB\-G\fPWB2008.grd mag_obs_1990.d
.SH CONSIDERATIONS
(1) For the Cartesian cases we use the free-space Green functions, hence no boundary conditions are
applied at the edges of the specified domain.  For most applications this is fine as the region typically
is arbitrarily set to reflect the extent of your data.  However, if your application requires
particular boundary conditions then you may consider using \fBsurface\fP instead.
.br
(2) In all cases, the solution is obtained by inverting a \fIn\fP x \fIn\fP double precision matrix for the Green
function coefficients, where \fIn\fP
is the number of data constraints.  Hence, your computer's memory may place restrictions on how large data
sets you can process with \fBgreenspline\fP.  Pre-processing your data with \fBblockmean\fP, \fBblockmedian\fP,
or \fBblockmode\fP is recommended to avoid aliasing and may also control the size of \fIn\fP. For information,
if \fIn\fP = 1024 then only 8 Mb memory is needed, but for \fIn\fP = 10240 we need 800 Mb. Note that
\fBgreenspline\fP is fully 64-bit compliant if compiled as such.
.br
(3) The inversion for coefficients can become numerically unstable when data neighbors are very close
compared to the overall span of the data.  You can remedy this by pre-processing the data, e.g., by
averaging closely spaced neighbors.  Alternatively, you can improve stability by using the SVD solution and
discard information associated with the smallest eigenvalues (see \fB\-C\fP).
.SH TENSION
Tension is generally used to suppress spurious oscillations caused by the minimum curvature requirement, in particular
when rapid gradient changes are present in the data.  The proper amount of tension can only be determined by experimentation.
Generally, very smooth data (such as potential fields) do not require much, if any tension, while rougher data (such
as topography) will typically interpolate better with moderate tension.  Make sure you try a range of values before
choosing your final result.  Note: the regularized spline in tension is only stable for a finite range of \fIscale\fP values;
you must experiment to find the valid range and a useful setting.  For more information on tension see the references below.
.SH "REFERENCES"
Davis, J. C., 1986, \fIStatistics and Data Analysis in Geology\fP, 2nd Edition, 646 pp., Wiley, New York, 
.br
Mitasova, H., and L. Mitas, 1993, Interpolation by regularized spline with tension: I. Theory and implementation, \fIMath. Geol., 25\fP, 641\-655.
.br
Parker, R. L., 1994, \fIGeophysical Inverse Theory\fP, 386 pp., Princeton Univ. Press, Princeton, N.J.
.br
Sandwell, D. T., 1987, Biharmonic spline interpolation of Geos-3 and Seasat altimeter data, \fIGeophys. Res. Lett., 14\fP, 139\-142.
.br
Wessel, P., and D. Bercovici, 1998, Interpolation with splines in tension: a Green's function approach, \fIMath. Geol., 30\fP, 77\-93.
.br
Wessel, P., and J. M. Becker, 2008, Interpolation using a generalized Green's function for a spherical surface spline in tension, \fIGeophys. J. Int, 174\fP, 21\-28.
.br
Wessel, P., 2009, A general-purpose Green's function interpolator, \fIComputers & Geosciences, 35\fP, 1247\-1254, doi:10.1016/j.cageo.2008.08.012.
.SH "SEE ALSO"
.IR GMT (1),
.IR gmtmath (1),
.IR nearneighbor (1),
.IR psxy (1),
.IR surface (1),
.IR triangulate (1),
.IR xyz2grd (1)