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 2 quaternion @q # go back to stored orientation gradually (2 sec)

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 xyz by tilt degrees
tilted = r * s # rotate the starting orientation to get the tilted orientation
moveto @time quaternion @tilted # tilt the view, taking some time to do so.

Choosing x = 1, y = 0.5, z = 0 and tilt = 10, the buttons illustrate the commands.

Choosing x = 1, y = -0.5, z = 0 and tilt = 10, the buttons illustrate tilting in a different direction.

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}, 180) #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.

After pressing the button above, rotate the model a bit or a lot. Now will will go back the first orientation, with a nice speed no matter how different they are:

Here are the relevant Jmol commands:

q1 = quaternion() #Store first orientation
q2 = quaternion() #Store second orientation
rotation = q2 / q1 #rotation to get from q1 to q2 
rotangle = rotation%"theta" #Extract the rotation angle from the quaternion
rotangle = 2 * acos(rotation.w) #Alternative way to get the angle, avoids percent sign
duration = angle/45 + 0.1 #take one second per 45 degrees rotation, plus 0.1 sec 
moveto @duration quaternion @q1 # reorient the view back to q1 in duration seconds

Moveto vs Rotate command

The rotate command only rotates (no zoom or translation), and always at the same speed. If you want to have control over the rotation speed, you have to use moveto instead. Moveto takes the final orientation as a parameter, and moves to it from whatever the current orientation is. On the other hand, the rotate command is relative to the starting orientation. If you want to turn a rotate command into a moveto command, you have to calculate the final orientation in the following way:

start = quaternion();
final = rotation * start; #equation 1

Then, you can use the moveto command.

On the flip side, if you have the final and start orientations, and need the rotation, you use quaternion division:

rotation = final / start; #equation 2

Equation 2 is derived by right-dividing equation 1 by start to isolate rotation on the right hand side

Moving atoms

some other time...