Visualizing Quaternions: Quaternion-Map Documentation

Back to Home page.

Overview Description Download Using the Application
  • What are Quaternion maps?
  • About this demo
  • Snapshots of the application



  • Platforms supported
  • Download links for
    • License
    • Executables
    • Source Code


I. Overview

1. What are Quaternion Maps?

Quaternion Maps are plots of the quaternion values corresponding to 3D orientation frames attached to a curve, surface, or volume.

An orientation or orientation frame is characterized by a direction vector (n) and an angle of rotation (θ) around this direction.  The classical representation of a 3D orientation frame is a triad of three mutually-perpendicular vectors (fx, fy, fz), which is related to the identity frame by a rotation about a unique direction vector (n).

Quaternion maps plot the connected values of a set of unit quaternions, where quaternions are four-dimensional vectors, and unit-quaternions represent orientation-frames. This mapping provides interesting and elegant explanations for some intriguing phenomena described in the book Visualizing Quaternions.

2. About this Demonstration

This document describes an application for viewing and manipulating Quaternion maps of curves. There are several 'do it yourself' steps to explore the behavior of quaternion maps of curves. 

Maps of simple, closed curves like a knot or a circle can be highly instructive in understanding the nature of a sequence of orientation-frames. Such sequencea of frames arise while constructing tubes around curves or while describing navigational paths through space, such as camera-paths in an animation.  

3. Snapshots of the Application

The following images show some snapshots of the Quaternion-Map application.
Figure 1a: View of the interface showing the 2,3-Torus knot (Trefoil) in the main window Figure 1b: View of the Quaternion-map of the Trefoil shown in previous figure. The knot is shown in a smaller window on the right.



II. Description

1. Quaternions Describe Orientations in 3D:

Quaternions are vectors in four-dimensional Euclidean space (R4) and unit-quaternions represent orientations in three-dimensional space. An orientation can be thought of as a triad of three mutually perpendicular axes.

Quaternions are used in this manner to represent orientations as one sweeps along a curve in 3D. Since quaternions are four-dimensional vectors (think quaternion, q = (w, x, y, z), where w, x, y, z ε R, real-numbers), they are visualized by projecting the three out of the four components of each quaternion into the three-dimensional subspace. A visualization of these quaternions is called the quaternion-map

2. Quaternion Maps:

Quaternion maps are obtained by connecting a set of quaternions to form a smooth curve, surface, or volume. Quaternion curve maps can be open or closed curves. Since the configuration of the quaternion map signifies successive orientations of a frame in 3D space, a closed quaternion curve indicates that the starting and end frames have the same orientation in 3D. An open quaternion-curve may or may not imply the same. This is because the mapping between orientations in 3D and quaternions is a 1:2 mapping, which implies that each 3D orientation is represented by a pair of quaternions (with opposite sign). This property is referred to as the 'double cover'. If the end quaternions in an open quaternion-curve form such a pair, the orientations in 3D will be identical.

The application demonstrates orientations of frames that sweep closed, knotted curves such as torus knots. A highly interesting problem in itself is how the frames are assigned to a given curve. Three framing methods are exposed in this application, namely the Frenet-Serret, Parallel Transport, and Geodesic Reference framings.

The figure below shows quaternion maps corresponding to the three framing methods mentioned above:

Figure 2: Quaternion Maps for: Frenet-Serret (blue),
Parallel Transport (green) and Geodesic Reference (red).
The wire-frame sphere is the unit sphere in quaternion space.



III. Download Software

1. Platforms supported:

The following platforms are supported:

  • Windows - XP
  • Linux - Gentoo

System requirements:

2. Download Links:

The belt-trick is available in the form of a compressed archive. The archive contains:

  • Project Files (VC++6.0), Makefiles (Linux), Project Forms (Qt interface-designer)
  • Source Code
  • Executables
  • Libraries (Qt, GLUT)

To run the application: download and unzip onto the local computer.

The license for the software is available here: License for material on this website.

Follow the link below to download the compressed archive.



IV. Using the Application

The application demonstrates the quaternion-maps corresponding to different framing options. A snapshot of the application is shown in figure 3.

The main-window displays the curve, while the quaternion map appears in the smaller thumbnail view in the auxiliary window. The contents of the thumbnail window can be enlarged by double clicking inside the window area.

The control-panel holds several controls for manipulating the knot and quaternion-maps.

Try this: The application starts with a closed, knotted curve, i.e. the Trefoil or 2,3-knot. Try different knot configurations by dragging the sliders in the control panel located under tab: 'Object: Parameters'. See below for more options.

Figure 3: Application interface

1. Adjust Knot-Parameters -

Click to display the tab named 'Object: Parameters' in the panel on the right side of the application window. The following options are provided:

    • Knot constants m,n - set m and n to be mutually prime to generate a knotted curve. Otherwise, an 'Un-knot' or a loop is generated that is not a knotted curve, i.e. it is continuously deformable to a ring.
    • Constants a, b - control the major and minor radius of the torus on which the knotted curve resides.

    • Constant r - is similar to a scaling factor but also changes the shape of the knotted curve.
    • PT: Start angle - controls the angular orientation of the starting frame for the case of Parallel Transport (PT) frame. Change this along the slider to see the PT quaternion-curve move in quaternion space as the first frame and the subsequent frames change.

Figure : Tab to change knot-parameters

2. Frame Viewing Options -

Click to display the tab named 'Frames: Select Type' in the panel on the right side of the application window.

    • 3D-Curve Frame Options: are used to apply a framing method to the 3D curve (i.e. the knotted curve in 3D). The three options are as follows:
      • Frenet-Serret Frame
      • Parallel Transport Frame
      • Geodesic Reference


    • Quaternion-Map Frame Options: these options can be used to display the quaternion maps corresponding to the framing techniques. One or more quaternion curves can be displayed by selecting one or more check-boxes.

Figure 3: Tab to select frames

3. Quaternion Map Display -

The quaternion map is displayed in the a smaller window on the bottom right, below the controls panel. This screen also displays the full space of orientations around the tangents to the curve.

The full space of orientations is obtained as follows: First, quaternions corresponding to all possible orientations about a tangent vector are generated. These quaternions form a 'ring' in quaternion space. Second, such quaternion-rings are obtained for all the tangents. Lastly, adjoining rings are connected suitable with polygons to generate a surface object.

There are several modes of visualizing the full space of orientations for a given curve. The surface-view is shown in figure-4a. A corresponding see-through 'mesh' view can also be enabled. The quaternion-rings can be visualized by themselves by selecting the checkbox under the tab 'Quaternion Map Controls'.

The quaternion Ring structure is shown in figure-4b. Quaternion-Ring controls are provided under the tab 'Quaternion Rings' in the control panel. The number of visible rings can be adjusted by dragging the slider 'Number of Rings'. A duplicate slider is provided for start angle for the Parallel Transport frames.


Figure 4a: View of Auxiliary window showing the quaternion map and full space of orientations.

Figure 4b: Quaternion Ring structure for a 2,3-Torus Knot (or Trefoil). Yellow and Green rings correspond to the first and last tangents on the curve respectively.

4. Color and Texture Options -

Color and texture options are provided under the tabs: 'Color Code Controls' and 'Tube: Size, Texture'.

Color codes are provided to view properties of the curve like the Curvature and the Torsion experienced by the frames. The options are shown in the figure-5a. Several palettes can be chosen from the drop-down list box.

The figures below show a Trefoil knot with color-coding.

1. Curvature coded in color 2. Torsion coded in color 3. Palette used for the two figures (blue and red are extreme values)

 The properties of the tube applied to the curve can be adjusted in the 'Tube: Size, Texture' control group shown in figure-5b.

1. Stripped texture applied to the knot in the Frenet-Serret frame configuration. Notice the twists in the knot. 2. Same texture for a Parallel Transport frame configuration. The only frame mismatch (twist) is at where the knot closes on itself.


Figure 5a: Color coding options

Figure 5b: Tube properties options

V. Keyboard Shortcuts...

Global options
operation key
Help "h"
Reset View "r"
Swap Screens "q"
toggle feature key
Axes "a"
Curve "c"
Curve-tube Edges "c"
Curve-tube Faces "f"
Frames "Shift+f"
Gap "g"
Overall help "h"
Screen-help text "Shift+h"
Labels "l"
Palette "p"
Quaternion Map Color options
operation key
Reflect Frenet-Serret map "p"
Quaternion Rings "Shift+r"
Quaternion-map Mesh "m"
Quaternion-map Surface "Shift+m"
Unit sphere "s"
Quaternion Map options
operation key
Show component XYZ "w"
Show component WYZ "x"
Show component WXZ "y"
Show component WXY "z"



VI. Mouse Interface...

Operation Button + Action
Rotate Model Left + drag
Scale Model Right + drag vertically



Graphics and Visualization Lab,
Computer Science Department,
Indiana University Bloomington
Feb 2006