TSPACKGUI: Tension Spline Package Graphical User Interface

Table of Contents

Overview

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.

Tension Splines

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 equation

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), pp. 81-94.

Curve-type Parameters

The curve type is specified by five parameters:

ndof
number of degrees of freedom in each control point, or number of dependent variables:
deriv
string variable specifying the method for selecting knot derivatives (first derivatives at knots):
tension
string variable specifying the method for choosing tension factors sigma:
endcond
string variable specifying end conditions:
interpolate
logical variable:

Not all possible combinations of the above parameter values are legal curve types. In particular, the following combinations are not legal:

Menu Descriptions

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.

File Menu

The file format for storing a curve consists of the following sequence of records. Comment lines with # in the first column are ignored.

  1. 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.
  2. 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.
  3. The sequence of n knot derivatives (each with ndof components) unless the curve is a B-spline (ndof > 1 and interpolate = false).
  4. The n-1 tension factors, one per line.
  5. The n smoothing weights, one per line, if ndof = 1 and interpolate = false.
  6. 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 input.
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 directory.
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.

Display_options Menu

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

Curve_type Menu

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

Operations Menu

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

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

Help Menu

Selection of this menu displays this text in the MATLAB browser.

Keypress Options

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 camera target.

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

Additional Controls

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.