[Jmol-developers] 10.x.04 new features -- rotation and spinning

[Bob H. <ha...@st...>]

Jmol users and developers:

What a fun week this has been, especially with the CONFCHEM focus on 
Jmol. I have made a few simple but relatively substantial feature 
additions to the Jmol prototype, now versioned 10.x.04.

Especially new is the complete integration of "spin" and "rotate". While 
still compatible with previous versions ("spin x;spin y; spin z;rotate x 
10;" etc.), 10.x.04 basically removes the distinction between these two 
commands. (They are processed by the exact same code.) Improvements include:

-full noninteger specifications for both spin and rotate
-animated rotation (limited spinning through a specified number of 
degrees, see below)
-internal-frame as well as fixed-frame rotation/spinning
-rotation/spinning about unit cell (fractional) coordinates

The new syntax is simply:

[rotate/spin] [axis-specifier] [total-number-of-degrees] 
[degrees-per-second]

The only distinction between rotate and spin is in the default actions. 
If one of those degree-values is left out, then the default is:

rotate [axis-specifier] [total-number-of-degrees]

spin [axis-specifier] [degrees-per-second]

These simpler forms, then, are consistent with Chime and previous 
versions of Jmol.
Note that there are several new options for [axis-specifier]:

 x, y, z, -x, -y, -z
$draw_object  (a predefined line, typically)
{1,1,1} {2,3,3} (a pair of cartesian coordinates)
{1,1,1/} {1/2,0,1/2} (a pair of fractional coordinates)
(atom expression) (atom expression)   (a pair of atom expression center 
points)

Of course, any mix of draw objects, cartesian coordinates, fractional 
coordinates, and atom expressions can be used.

A keyword "MOLECULAR" is optional in cases where "x", "y", or "z" are 
used. That's because there are two sets of x,y,z axes. The standard 
"fixed frame" set is what you are used to rotating about. As you know, 
when the user tweaks the molecule will it is spinning around one of 
these axes, the molecule goes into a tumble --- continues to rotate 
about that FIXED axis, but now with some completely other orientation. 
By specifying MOLECULAR, you are saying that you want the molecule to 
rotate or spin about the internal *molecular* frame -- the x,y,z, of the 
molecule, and have it keep spinning about that axis even if the user 
manipulates the model with the mouse. I think this is a very natural 
sort of motion. Actually, it's quite intriguing to work on the model 
with the mouse while it is spinning this way. Try it -- it will be a new 
experience.
So, for example, we have:

rotate molecular x 20
spin molecular y

(This is only for "x" "y" "z" "-x" "-y" and "-z".
Any other axis specifier is already molecular.)

You can see this molecular axis set using

set axesMolecular
set axes on

other possibilities include:

set axesMolecular OFF  # the standard fixed-frame axes
set axesUnitCell ON  # the unit cell axes.

In addition, I have now completed the integration of the rotation/spin 
system with atom picking. So you can now do:

set picking spin 30
[user selects two atoms -- molecule starts spinning at 30 degrees per 
second]

and you can also use

set windowCentered false
set picking center

to then start picking points that you want to rotate the molecule around 
without having that point jump to the center.

This pretty much completes the work I started in February along these 
lines.

See http://www.stolaf.edu/people/hansonr/jmol/test/proto/new.htm
and especially
http://www.stolaf.edu/people/hansonr/jmol/test/proto/fraction.htm
for a summary of new features in 10.x.04. JAR files are available in 
that directory:
http://www.stolaf.edu/people/hansonr/jmol/test/proto
along with the recommended Jmol-new.js that takes advantage of these 
features.
Note that to use the prototype, you need only two files: 
JmolAppletProto.jar and Jmol-new.js.
If your files are in the directory of the HTML file itself, you no 
longer need jmolInitialize(), because Jmol-new.js auto-initializes to 
use the prototype. But if your files are elsewhere, then you need to use:

jmolInitialize("../....whatever","JmolAppletProto.jar")

I'll start working on documenting this as a separate documentation 
document and will notify all when that is accomplished. For now, if you 
are interested in these features, you will have to work by examples 
shown in these demo files and whatever help this list can provide.

Comments/suggestions are welcome.

Bob Hanson
St. Olaf College