Jmol/Quaternions

Examples of how quaterions are used

http://proteopedia.org/wiki/images/7/76/Wobble.spt

jmol script to move molecule around a given orientation in a precession movement.

Preliminary definitions

A quaternion q is an mathematical object (like a matrix or a complex number) with four parameters x y z w. It is useful to express orientations and rotations, and to do calculations (combining, interpolating, dissecting) on them.

Orientation refers to from which side we are looking at an object (or how we a orienting the object in front of the camera or viewport). Rotation refers to changing either the orientation, or turning a selected object while keeping the view.

Coordinate systems

Jmol shows structures (e.g. atomic positions) on a display and allows the view to be rotated and individual atomic positions to be manipulated. The display has Cartesion coordinates (the x-axis goes right, the y-axis goes up, and the z-axis points at the viewer). The atoms have Cartesian coordinates x, y, z. The meaning of the axes is sometimes arbitrary (NMR structures) or along certain crystallographic directions (X-ray structures). When you rotate the model, the coordinate system of the model is rotated (same coordinates x, y, z, but axes of coordinate system point in different directions) with respect to the display coordinate system.

When a new structure is loaded, the model axes point left, up, and out of the screen. The Jmol command "reset" puts that coordinate system back into that initial orientation.

Changing orientations using quaternions

The Jmol command "q = quaternion()" assigns the current orientation to q.

So, again, how is an orientation different from a rotation? An orientation is the rotation necessary to get the coordinate system from the "reset" orientation to the current orientation. The quaternion q0 for the initial orientation corresponds to no rotation, i.e. {0 0 1 0}. To get back to an orientation q after rotating, use "moveto 0 quaternion q". After you saved an orientation, click the reset button above and then go back to the saved orientation with the button below.

Relevant Jmol command examples:

q = quaternion() # store current orientation
moveto 0 quaternion @q # go back to stored orientation instantly
moveto 1 quaternion @q # go back to stored orientation gradually

Combining two rotations

For the wobble script, I want to change the orientation a little bit, rotating about an axis in the plane of the display. The effect is that parts of the structure the the center foreground move around in a circle, tilting the view a bit in different directions. Distinct from the spin command, the view does not change much. Distinct from a rocking motion, the structure gets tilted over time in all directions, giving a better spatial view.

In order to achieve this effect, we have to apply a rotation r on the starting orientation s. This is done by quaternion multiplication. The order matters: the right-most rotation is applied first. Here, we first want to rotate the structure from the initial orientation to the current orientation, and then apply the tilting rotation, so the overall orientation becomes r * s.

Relevant Jmol command examples:

r = quaternion({@x @y @z},@tilt) # rotation about an axis in direction xyz by tilt degrees
tilted = r * s # apply the rotation to the starting orientation to get the tilted orientation
moveto @time quaternion @tilted # tilt the view, taking some time to do so.

Interpolating between orientations

If you have a quaternion that defines a rotation, and you want to rotate in a stepwise fashion, this is very easy. You just divide the quaternion by the number of steps, and apply that rotation.

Here is an example:

Relevant Jmol command examples:

qr = quaternion({1 1 0}, 90) #define the overall rotation
q10 = @qr / 10 #q10 is rotating only one tenth of the way
rotate @q10 # rotate the view by the given amount

Interpreting a rotation

For the second example script, I wanted to rotate the view back to the initial orientation. For small adjustments, I wanted it to take a small time, while for larger adjustment, I wanted to spend enough time that you can easily follow. The Jmol moveto command takes a duration for the entire rotation as a parameter. If I set this to a fixed value, it would be too slow for small adjustments or too fast for large rotations. So I had to figure out by how many degrees I would rotate first, and then decide on the timing accordingly.

Here are the relevant Jmol commands:

q0 = quaternion
angle = rotation%"theta" #Extract the rotation angle from the quaternion
angle = 2 * acos(rotation.w) #Alternative way to get the angle, avoids percent sign that gave me trouble
duration = angle/45 + 0.1 #take one second per 45 degrees rotation, plus 0.1 sec 
qnew = rotation * q0 #figure out the new orientation
moveto @duration quaternion @qnew # reorient the view to qnew in duration seconds