util/src/TclTk/blt2.5/man/spline.mann

   1 '\"
   2 '\" Copyright 1991-1997 by Bell Labs Innovations for Lucent Technologies.
   3 '\"
   4 '\" Permission to use, copy, modify, and distribute this software and its
   5 '\" documentation for any purpose and without fee is hereby granted, provided
   6 '\" that the above copyright notice appear in all copies and that both that the
   7 '\" copyright notice and warranty disclaimer appear in supporting documentation,
   8 '\" and that the names of Lucent Technologies any of their entities not be used
   9 '\" in advertising or publicity pertaining to distribution of the software
  10 '\" without specific, written prior permission.
  11 '\"
  12 '\" Lucent Technologies disclaims all warranties with regard to this software,
  13 '\" including all implied warranties of merchantability and fitness.  In no event
  14 '\" shall Lucent Technologies be liable for any special, indirect or
  15 '\" consequential damages or any damages whatsoever resulting from loss of use,
  16 '\" data or profits, whether in an action of contract, negligence or other
  17 '\" tortuous action, arising out of or in connection with the use or performance
  18 '\" of this software.
  19 '\"
  20 '\" Spline command created by George Howlett.
  21 '\"
  22 .so man.macros
  23 .TH spline n BLT_VERSION BLT "BLT Built-In Commands"
  24 .BS
  25 '\" Note:  do not modify the .SH NAME line immediately below!
  26 .SH NAME
  27 spline \-  Fit curves with spline interpolation
  28 .SH SYNOPSIS
  29 .sp
  30 \fBspline natural \fIx y sx sy\fR
  31 .sp
  32 \fBspline quadratic \fIx y sx sy\fR
  33 .BE
  34 .SH DESCRIPTION
  35 The \fBspline\fR command computes a spline fitting a set of data
  36 points (x and y vectors) and produces a vector of the interpolated
  37 images (y-coordinates) at a given set of x-coordinates.
  38 .SH INTRODUCTION
  39 Curve fitting has many applications.  In graphs, curve fitting can
  40 be useful for displaying curves which are aesthetically pleasing to the
  41 eye.  Another advantage is that you can quickly generate arbitrary points
  42 on the curve from a small set of data points.
  43 .PP
  44 A spline is a device used in drafting to produce smoothed curves.  The
  45 points of the curve, known as \fIknots\fR, are fixed and the
  46 \fIspline\fR, typically a thin strip of wood or metal, is bent around
  47 the knots to create the smoothed curve.  Spline interpolation is the
  48 mathematical equivalent.  The curves between adjacent knots are
  49 piecewise functions such that the resulting spline runs exactly
  50 through all the knots.  The order and coefficients of the polynominal
  51 determine the "looseness" or "tightness" of the curve fit from the
  52 line segments formed by the knots.
  53 .PP
  54 The \fBspline\fR command performs spline interpolation using cubic
  55 ("natural") or quadratic polynomial functions.  It computes the spline
  56 based upon the knots, which are given as x and y vectors.  The
  57 interpolated new points are determined by another vector which
  58 represents the abscissas (x-coordinates) or the new points.  The
  59 ordinates (y-coordinates) are interpolated using the spline and
  60 written to another vector.
  61 .SH EXAMPLE
  62 Before we can use the \fBspline\fR command, we need to create two BLT
  63 vectors which will represent the knots (x and y coordinates) of the
  64 data that we're going to fit.  Obviously, both vectors must be the
  65 same length.
  66 .CS
  67 # Create sample data of ten points.
  68 vector x(10) y(10)
  69
  70 for {set i 10} {$i > 0} {incr i -1} {
  71     set x($i-1) [expr $i*$i]
  72     set y($i-1) [expr sin($i*$i*$i)]
  73 }
  74 .CE
  75 We now have two vectors \fBx\fR and \fBy\fR representing the ten data
  76 points we're trying to fit.  The order of the values of \fBx\fR must
  77 be monotonically increasing.  We can use the vector's \fBsort\fR operation
  78 to sort the vectors.
  79 .CS
  80 x sort y
  81 .CE
  82 The components of \fBx\fR are sorted in increasing order.  The
  83 components of \fBy\fR are rearranged so that the original x,y
  84 coordinate pairings are retained.
  85 .PP
  86 A third vector is needed to indicate the abscissas (x-coordinates) of
  87 the new points to be interpolated by the spline.  Like the x vector,
  88 the vector of abscissas must be monotonically increasing.  All the
  89 abscissas must lie between the first and last knots (x vector)
  90 forming the spline.
  91 .PP
  92 How the abscissas are picked is arbitrary.  But if we are going to
  93 plot the spline, we will want to include the knots too.  Since both
  94 the quadratic and natural splines preserve the knots (an abscissa from
  95 the x vector will always produce the corresponding ordinate from the y
  96 vector), we can simply make the new vector a superset of \fBx\fR.
  97 It will contain the same coordinates as \fBx\fR, but also the
  98 abscissas of the new points we want interpolated.  A simple way is to
  99 use the vector's \fBpopulate\fR operation.
 100 .CS
 101 x populate sx 10
 102 .CE
 103 This creates a new vector \fBsx\fR.  It contains the abscissas of
 104 \fBx\fR, but in addition \fBsx\fR will have ten evenly distributed
 105 values between each abscissa.  You can interpolate any points you
 106 wish, simply by setting the vector values.
 107 .PP
 108 Finally, we generate the ordinates (the images of the spline) using
 109 the \fBspline\fR command.  The ordinates are stored in a fourth
 110 vector.
 111 .CS
 112 spline natural x y sx sy
 113 .CE
 114 This creates a new vector \fBsy\fR.  It will have the same length as
 115 \fBsx\fR.  The vectors \fBsx\fR and \fBsy\fR represent the smoothed
 116 curve which we can now plot.
 117 .CS
 118 graph .graph
 119 \&.graph element create original -x x -y x -color blue
 120 \&.graph element create spline -x sx -y sy -color red
 121 table . .graph
 122 .CE
 123 The \fBnatural\fR operation employs a cubic interpolant when forming
 124 the spline.  In terms of the draftmen's spline, a \fInatural spline\fR
 125 requires the least amount of energy to bend the spline (strip of
 126 wood), while still passing through each knot.  In mathematical terms,
 127 the second derivatives of the first and last points are zero.
 128 .PP
 129 Alternatively, you can generate a spline using the \fBquadratic\fR
 130 operation.  Quadratic interpolation produces a spline which follows
 131 the line segments of the data points much more closely.
 132 .CS
 133 spline quadratic x y sx sy
 134 .CE
 135 .SH OPERATIONS
 136 .TP
 137 \fBspline natural \fIx y sx sy\fR
 138 Computes a cubic spline from the data points represented by the
 139 vectors \fIx\fR and \fIy\fR and interpolates new points using vector
 140 \fIsx\fR as the x-coordinates.  The resulting y-coordinates are
 141 written to a new vector \fIsy\fR. The vectors \fIx\fR and \fIy\fR must
 142 be the same length and contain at least three components.  The order
 143 of the components of \fIx\fR must be monotonically increasing.
 144 \fISx\fR is the vector containing the x-coordinates of the points to
 145 be interpolated.  No component of \fIsx\fR can be less than first
 146 component of \fIx\fR or greater than the last component.  The order
 147 of the components of \fIsx\fR must be monotonically increasing.
 148 \fISy\fR is the name of the vector where the calculated y-coordinates
 149 will be stored.  If \fIsy\fR does not already exist, a new vector will be
 150 created.
 151 .TP
 152 \fBspline quadratic \fIx y sx sy\fR
 153 Computes a quadratic spline from the data points represented by the
 154 vectors \fIx\fR and \fIy\fR and interpolates new points using vector
 155 \fIsx\fR as the x-coordinates.  The resulting y-coordinates are
 156 written to a new vector \fIsy\fR.  The vectors \fIx\fR and \fIy\fR must
 157 be the same length and contain at least three components.  The order
 158 of the components of \fIx\fR must be monotonically increasing.
 159 \fISx\fR is the vector containing the x-coordinates of the points to
 160 be interpolated. No component of \fIsx\fR can be less than first
 161 component of \fIx\fR or greater than the last component.  The order of
 162 the components of \fIsx\fR must be monotonically increasing.  \fISy\fR
 163 is the name of the vector where the calculated y-coordinates are
 164 stored.  If \fIsy\fR does not already exist, a new vector will be
 165 created.
 166 .SH REFERENCES
 167 .nf
 168 .sp
 169 Numerical Analysis
 170 by R. Burden, J. Faires and A. Reynolds.
 171 Prindle, Weber & Schmidt, 1981, pp. 112
 172 .sp
 173 Shape Preserving Quadratic Splines
 174 by D.F.Mcallister & J.A.Roulier
 175 Coded by S.L.Dodd & M.Roulier N.C.State University.
 176 .sp
 177 .fi
 178 The original code for the quadratric spline can be found in TOMS #574.
 179 .SH KEYWORDS
 180 spline, vector, graph
 181