TSPACKGUI: Tension Spline Package Graphical User Interface
Table of Contents
- Display Derivatives
- Display Axes
- Display Box
- Display Grid Lines
- Display Control Points
- Freeze Axis Limits
- Standard 3D View
- Display Curvature
- Display First Derivative Curve
- Display Second Derivative Curve
- Function Graph
- Parametric Planar Curve
- Parametric Space Curve
- C2 Derivatives
- C1 Automatic Derivatives
- C1 User-specified Derivatives
- Shape-preserving Tension
- Bounds-constrained Tension
- User-specified Tension
- Closed Curve
- Automatic End Conditions
- User-specified End Conditions
- Interpolatory Curve
- Approximating/Smoothing Curve
- Append Control Point
- Drag Control Point
- Insert Control Point
- Remove Control Point
- Alter Derivative
- Alter Tension Factor
- Alter Smoothing Weight
- Alter Bounds
- Undo Last Operation
- Toggle Snap to Grid Option
This document describes the user interface to TSPACK, but the program
should be usable without any of the information provided here. See
the references in the next section for technical details. Also, the
header comments in the source code (help text) describe options for
starting TSPACKGUI with optional inputs. More than one instance may
be run concurrently.
A tension spline curve is either the graph of a function y = f(x) or
a parametric curve (x,y,z) = (f(t),g(t),h(t)) for real-valued functions
f, g, and h. It is defined by a sequence of n discrete knots x or t
(where t may be computed as cumulative chord length), control points,
also referred to as data points, y, (x,y), or (x,y,z), knot derivatives
yp or (xp,yp), or (xp,yp,zp), and a nonnegative tension factor sigma
associated with each of the n-1 knot intervals. The curve may be
interpolatory with one or two continuous derivatives, in which case knot
function values coincide with control points, or it may be a C2
smoothing curve or B-spline (approximating) curve in the parametric case.
The functions defining the curve segments are either cubic polynomials
or exponential functions. For example, the restriction of f to knot
interval [x1,x2] satisfies the fourth-order ordinary differential
f''''(x) - s2 f''(x) = 0 for all x in [x1,x2],
where s = sigma/(x2-x1). The solution is uniquely defined by endpoint
values and first derivatives. If sigma = 0, f is cubic. Otherwise it
is a linear combination of functions 1, x, exp(s*x), and exp(-s*x).
As the tension factor sigma is increased, f uniformly converges to the
linear interpolant of the endpoint values. Refer to the following
papers for further detail.
R. J. Renka, 1987, Interpolatory Tension Splines with Automatic
Selection of Tension Factors, SIAM J. Sci. Stat. Comp., 8,
No. 3, (May), pp. 393-415.
R. J. Renka, 1993, ALGORITHM 716. TSPACK: Tension Spline Curve
Fitting Package, ACM Trans. Math. Software, 19, No. 1, (March),
The curve type is specified by five parameters:
- number of degrees of freedom in each control point,
or number of dependent variables:
- ndof = 1 for a univariate function y = f(x).
- ndof = 2 for a parametric planar curve (x,y) = (f(t),g(t)).
- ndof = 3 for a parametric space curve (x,y,z) = (f(t),g(t),h(t)).
- string variable specifying the method for selecting
knot derivatives (first derivatives at knots):
- deriv = 'c2' if derivatives are chosen (by a global method) for
continuity of second derivatives.
- deriv = 'c1' if each derivative is approximated by a local fit to
three control points in an interpolatory curve.
- deriv = 'user' if derivatives are user-specified.
- string variable specifying the method for choosing
tension factors sigma:
- tension = 'shape' if tension factors are chosen to be just large
enough to preserve local monotonicity and convexity of
the data (ndof = 1) or direction of curvature (ndof > 1).
- tension = 'bounds' if tension factors in an interpolatory curve
are chosen to be just large enough to satisfy user-
specified bounds on values and derivatives (ndof = 1)
or on distance from the control polygon (ndof = 2).
- tension = 'user' if tension factors are user-specified.
- string variable specifying end conditions:
- endcond = 'periodic' specifies a closed parametric curve.
- endcond = 'auto' if end conditions in an open curve are
- endcond = 'user' if endpoint derivatives in an open
curve are user-specified
- logical variable:
- interpolate = true if the curve interpolates the
- interpolate = false specifies a smoothing curve
(ndof = 1) or a B-spline curve (ndof > 1).
Not all possible combinations of the above parameter values are legal
curve types. In particular, the following combinations are not legal:
- ndof = 1 & interpolate = false & endcond = 'user'
- ndof = 1 & endcond = 'periodic'
- ndof = 3 & tension = 'bounds'
- interpolate = false & tension = 'bounds'
- interpolate = false & (deriv = 'c1' or deriv = 'user')
- deriv = 'c1' & endcond = 'user'
- deriv = 'user' & endcond = 'auto'
- interpolate = false & ndof > 1 & tension = 'shape'
Many of the menu entries have associated accelerator keys (control
keys). Note that these keys may not be active until the menu has been
selected by a mouse click at least once.
The file format for storing a curve consists of the following sequence
of records. Comment lines with # in the first column are ignored.
- The number of knots and control points n and the five curve-type
parameter values ndof, deriv, tension, endcond, and interpolate,
in that order, each on a separate line.
- The sequence of n pairs (x,y), triples (t,x,y), or quadruples (t,x,y,z),
depending on ndof, defining the knots and control points with one
control point per line.
- The sequence of n knot derivatives (each with ndof components)
unless the curve is a B-spline (ndof > 1 and interpolate = false).
- The n-1 tension factors, one per line.
- The n smoothing weights, one per line, if ndof = 1 and interpolate
- A sequence of n-1 bounds records if tension = 'bounds', where a
bounds record associated with a knot interval is a sequence of
five values, [upper bound on f, lower bound on f, upper bound on f',
lower bound on f', sign of f''], for a function f (ndof = 1), or
an ordered pair [upper, lower] defining bounds on signed distance
(positive to the left) from an interpolatory parametric planar
curve to the line segment joining the endpoints.
Entries in the File menu are simple operations.
- 1. Open
Displays a dialog box allowing selection of a file name for data
- 2. Save
Saves the current curve as a data set using the current file name
and path: the name and path selected by execution of Saveas, or
that of the most recently opened file or, by default when no name
and path have been selected, tspgui_data.tsp in the working
- 3. Saveas
Displays a dialog box allowing selection of a file name and path,
and saves the current curve as a data set in that file.
- 4. Exit
Closes all windows and terminates execution of the program.
Entries in this menu are state-changing options which, with the
exception of Display Control Points (which has three options), are
toggled on or off and check-marked when on.
- 1. Display Derivatives
A tangent vector represented by an arrow is anchored at each data
point (control point) or knot function value in the case of an
approximating curve. For parametric curves, the arrow length is
proportional to the magnitude of the derivative vector. This
option is automatically toggled on by selection of 'Alter
Derivative' in the Operations menu.
- 2. Display Axes
This option toggles display of the axes and all associated marks:
axis tick marks and tick mark lables, axis labels, title, box,
and grid lines.
- 3. Display Box
A two or three-dimensional wireframe box may be drawn around the
- 4. Display Grid Lines
A two or three-dimensional coarse grid with grey dotted lines may
be drawn over the axes. By default, the grid lines coincide with
axis tick marks which are chosen so that labels require a small
number of decimal digits. Refer to the Snap to Grid option in
the operations menu.
- 5. Display Control Points
Control points (data points) are depicted by markers (large dots)
in figure 1 and, in the case of an approximating curve, these are
connected by dashed line segments (the control polygon). Also,
knot derivative values (ndof = 1) or curvature values (ndof > 1)
in figure 2, and second derivative values (ndof = 1) or torsion
(ndof = 3) in figure 3 have markers consisting of small dots. Marker
display may be turned off but is automatically turned on when required
by a selection from the Operations menu. Selection of Display
Control Points cycles through three states: no control point
markers, unannotated control point markers, and markers
annotated with control point indices. A check mark appears next
to the menu item in the latter two cases.
- 6. Freeze Axis Limits
This option prevents the axis limits (range of displayable data)
from changing. The axis limits define a three-dimensional view
volume (box) against which the curve is clipped. Anything that
changes the axis limits, such as dragging a control point or
arrow, or changing the camera position, results in a change in
the appearance of the curve associated with the rescaling of the
data. This rescaling can be distracting, but may be suppressed
in order to focus on the effect of the operation, or to smoothly
animate the display. The option can be toggled off to restore
the default stretch-to-fill behavior in which the view volume is
just large enough to contain the data. An additional effect of
toggling this option on is to increase the axis lengths by 2%.
This is often necessary to enable the selection of a control point
on the boundary of the view volume. An alternative is to zoom
out with the 'z' key. Refer also to the Toggle Snap to Grid Option
in the operations menu.
- 7. Standard 3D View
This option toggles between the standard two-dimensional view
(az = 0, el = 90) and the standard three-dimensional view
(az = -37.5, el = 30), where az and el are azimuth and elevation
in degrees. The camera position may also be changed with arrow
keypresses or with a toolbar button.
- 8. Display Curvature
For each of a set of discrete points on the curve, the curvature
vector at the point is depicted as a line segment directed from
the point toward the center of curvature and having magnitude
proportional to the curvature, but clamped to a restricted range
(0,crvmax]. This is referred to as a porcupine plot. Note that,
where values are clamped to the constant value crvmax, the plot
conveys an illusion of smoothness that may not exist.
- 9. Plot 1st Derivative or Curvature
This option displays the first derivative (ndof = 1) or
signed curvature (ndof = 2) or curvature (ndof = 3) in a separate
window. Curvature or signed curvature is plotted as a function
of arc length. The knot values are depicted with small dots, but
neither the knot values nor the curve segments are selectable by
the mouse. The display options that affect axes properties
(2, 3, ..., 6) apply to this window as well as the main figure.
- 10. Plot 2nd Derivative or Torsion
This option displays the second derivative (ndof = 1) or
signed curvature (ndof = 2) or torsion (ndof = 3) in its own
window. Knot values are depicted with small dots, but cannot
be selected. Note that torsion has discontinuities at the knots.
Display options 2, 3, ..., 6 also affect this window.
These menu entries correspond to the 14 curve-type parameter values
displayed as five sets of options with horizontal lines
between the sets. The currently selected option in each set is
indicated by a checkmark.
- 1. Function Graph (ndof = 1)
This option specifies a curve defined by the graph of a function
y = f(x). The abscissae (knots) x must be strictly increasing.
- 2. Parametric Planar Curve (ndof = 2)
The curve is defined by a pair of functions x = f(t), y = g(t).
- 3. Parametric Space Curve (ndof = 3)
The curve is defined by three functions x = f(t), y = g(t), and
z = h(t).
- 4. C2 Derivatives (deriv = 'c2')
Knot derivatives are computed by solving a linear system
associated with continuity of second derivatives at the knots
resulting in continuous second derivatives everywhere.
- 5. C1 Automatic Derivatives (deriv = 'c1')
Each knot derivative is obtained by a local fit to three control
points: a monotonicity-constrained parabolic fit if ndof = 1, or
an inverse chord-length weighted average of adjacent edge
directions (defining a unit tangent vector) if ndof > 1.
This option requires endcond = 'auto', and selection of this
option automatically changes endcond from 'user' to 'auto' if the
previous value of deriv was 'user'.
- 6. C1 User-specified Derivatives (deriv = 'user')
With this option, a derivative may be altered by dragging the tip
of the arrow with which it is depicted (refer to the Display
Options menu). Selection of this option automatically changes
endcond from 'auto' to 'user' if necessary.
- 7. Shape-preserving Tension (tension = 'shape')
Tension factors are automatically chosen to be just large enough
to preserve the shape properties of the data (local monotonicity
and convexity if ndof = 1, sign of curvature if ndof = 2, or
direction of projected curvature vector if ndof = 3).
- 8. Bounds-constrained Tension (tension = 'bounds')
With ndof = 1 and interpolate = true, function values and
derivative values may be bounded above and/or below, and the sign
of the second derivative may be restricted, in each interval. If
the bounds can be satisfied by the interpolant, the tension factor
is chosen just large enough to satisfy them. Otherwise, the
tension factor is zero. If ndof = 2 and interpolate = true, the
signed distance (positive to the left, negative to the right)
between each curve segment and the corresponding control polygon
chord may be bounded above by a positive value and/or below by
a negative value.
- 9. User-specified Tension (tension = 'user')
With this option, tension factors may be altered directly.
Clicking on a curve segment brings up a selection window.
- 10. Closed Curve (endcond = 'periodic')
A parametric curve (ndof > 1) may be open or closed. Selecting
this option adds a new last control point coincident with the
first, and enforces periodic end conditions (identical
derivatives) at the first and last points. The last control
point and curve segment are removed if endcond is changed to
'auto' or 'user'.
- 11. Automatic End Conditions (endcond = 'auto')
End conditions in an open curve are defined by endpoint knot
derivatives. These may be computed by a local fit to two or
three control points. Selection of this option is disallowed
if deriv = 'user'.
- 12. User-specified End Conditions (endcond = 'user')
With this option, endpoint derivatives may be altered by
dragging an arrow tip. Selection of this option is disallowed
if deriv = 'c1'.
- 13. Interpolatory Curve (interpolate = true)
An interpolatory curve goes through its control points so that
knot function values coincide with control points.
- 14. Approximating/Smoothing Curve (interpolate = false)
With this option, if ndof = 1, the knot function values and
derivative values are chosen to minimize the total linearized
curvature (a measure of smoothness) subject to a bound on a
weighted sum of deviations from the control points (data points).
Refer to the Operations menu for a means of altering smoothing
weights. A smoothing curve requires deriv = 'c2', and endcond
is automatically changed from 'user' to 'auto' if necessary.
If ndof > 1 this option specifies a generalization of a
cubic B-spline curve. In the case of an open B-spline curve,
end conditions must be user-specified: an endpoint derivative
vector determines the direction and distance from the endpoint
of the curve to the first or last control point. The value of
endcond is automatically changed from 'auto' to 'user' if
necessary. The locations of the knot function values in a
smoothing curve or B-spline can be discerned by setting the
current operation to Alter Tension Factor, and changing the color
of a curve segments by selecting it with the mouse.
With the exception of the last two options,
selection of one of these menu entries alters the current operation
(which is displayed in a text string at the bottom of the main plot
figure). An operation is actually initiated by selecting a control
point or curve segment with a left mouse button click. Selection with
the right mouse button displays information about the control point or
curve segment. Selectability of control points is suppressed by
operations that require selection of curve segments, and curve
segments cannot be selected when control point operations are in
- 1. Append Control Point
A control point may be appended to an open curve by left clicking
the first or last control point. The appended point may be dragged
to a new location by holding down the mouse button.
- 2. Drag Control Point
A control point is dragged by holding down the left mouse button.
Only the y-component may be changed if ndof = 1.
- 3. Insert Control Point
For an interpolatory curve, insertion is performed by left clicking
on a curve segment. For a smoothing or approximating curve, click
on a segment of the control polygon. The inserted control point may
be dragged to a new location by holding down the mouse button.
- 4. Remove Control Point
When this option is in effect, control points are deleted by simply
clicking on them.
- 5. Alter Derivative
Selection of this option automatically toggles on display of arrows
representing derivatives as tangent vectors anchored at knot function
values. Clicking on a control point allows the arrow tip to be dragged.
The arrow length is proportional to the magnitude of the derivative
vector in the case of a parametric curve, but is ignored in the case
of a function. Also, arrow directions with nonpositive x-components
are ignored in the latter case.
- 6. Alter Tension Factor
With this option in effect, selection of a curve segment brings up a
figure window with a text-entry box and a slider, either of which may
be used to alter the tension factor associated with the curve segment.
If the checkbox is selected, the tension factor is used for all curve
segments. The tension factor is restricted to the interval [0,100].
A cubic spline is constructed by using uniform zero tension with
deriv = 'c2'.
- 7. Alter Smoothing Weight
A smoothing curve (ndof = 1 and interpolate = false) requires a weight
to be associated with each data point. This should be the reciprocal
of the variance in a set of measurements for which the data value is
the mean. Selection of a control point raises a window containing a
text-entry box and slider, either of which may be used to enter a
variance for the control point. A checkbox may be selected to make
the weight common to all control points. The maximum allowable
variance is chosen to be large enough that a linear fitting function
satisfies the constraint. The smallest selectable value results in
a very small deviation from the data point.
- 8. Alter Bounds
An interpolatory function or planar curve may have tension factors
automatically selected to satisfy user-specified bounds. The
default values result in null constraints and zero tension. Selection
of this option raises a window with text-entry boxes for altering
- 9. Undo Last Operation
This menu entry reverses the previous operation or curve-type change
unless a maximum number of levels was exceeded or the required data
was not saved. User-specified derivatives and tension factors are
not saved for restoration by subsequent executions of the undo option.
However, a warning is issued before information is lost.
- 10. Toggle Snap to Grid Option
A dragged control point may be automatically moved to
the nearest point of a grid defined by subdividing each coarse
grid interval into gridsize subintervals, where gridsize is
1, 2, 5, or 10 (initially 1, and altered by the Alt-g key), and the
coarse grid is the figure 1 grid computed automatically by
MATLAB and chosen so that tick marks have short labels (decimal
numbers). Visibility of the grid can be toggled on or off by a
display_options menu selection, and tick mark labels are
suppressed if gridsize > 1. When the Snap to Grid option is
on (checkmarked), selection of Append Control Point, Insert
Control Point, or Drag Control Point automatically turns on the
Freeze Axis Limits display option.
Selection of this menu displays this text in the MATLAB browser.
Menu selection: control keys
Some of the menu entries can be selected by control keys. These are
displayed in the menus as in, for example, Ctrl+A, meaning control-a
(no shift key). Note that the corresponding menu must be selected by
a mouse click at least once before the control key becomes effective.
The command key, rather than the control key, is used on the Macintosh.
Camera position: arrow keys
The left and right arrow keys alter azimuth, and the up and down arrow
keys alter elevation in whichever window has the keyboard focus. The
increments are 1 degree, or 10 degrees with the shift key held down.
Zoom in/out: 'z'/'Z'
These keypresses expand or contract the axis limits by 10% (without
altering the center), effectively zooming in or out, respectively.
The escape key restores the default axis limits.
Pan: 'h', 'j', 'k', 'l'
These keypresses shift the camera target (center of axis limits)
left, down, up, and right, respectively. This is necessary to zoom
in on a particular portion of a curve. Holding down the shift key
moves the camera target faster. The escape key restores the default
Alter grid size: Alt-g
This option cycles through gridsize values 1, 2, 5, and 10 as
described in the Snap to Grid Option of the operations menu.
Cancel operation: Escape
The escape key cancels the current operation. This is useful to
restore right-click selectability of both control points and curve
segments. It also restores the axis limits to their defaults (just
large enough to contain the data, or slightly larger if the display
option Freeze Axis Limits has been selected). This is useful when
the curve disappears due to panning too far.
Enter debug mode: Alt-d
This option returns control to the MATLAB command window (and editor)
but with read access to TSPACKGUI's workspace. Use Alt-D on
The standard MATLAB toolbar appears below the menu list at the top of
the main figure window and below the title in figures 2 and 3 (first
and second derivative or curvature and torsion plots). These tools provide
mouse-motion alternatives to the keypress rotate, pan, and zoom capabilities,
although they don't always work properly (3D panning, in particular, is
defective). There are also toolbar functions for annotating
and printing the figure. Following the use of one of these tools,
control is returned to TSPACKGUI by unselecting the tool and/or
selecting a TSPACKGUI menu entry.