Table of Contents
The scripting engine has been completely rewritten for Jmol Release 6. As of this writing it should be considered *alpha test* code. Please supply feedback in case of bugs and/or unexpected behavior and/or with feature requests. You can do this through the jmol home page jmol.sourceforge.net
Jmol supports the RasMol scripting language defined by RasMol. Information about RasMol can be found at www.openrasmol.org The current URL for full RasMol documentation is: www.openrasmol.org/doc/rasmol.htm.
The Chime web browser plug-in was based upon the RasMol source code. Various extensions were added, including additional scripting commands. Information about Chime can be found at www.mdlchime.com The current URL for extended chime scripting commands is: www.mdlchime.com/chime/chimerasmol.html.
Jmol currently supports many of RasMol/Chime scripting commands. Our goal is to eventually provide full script support. This will provide a migration path for those who wish to move to an open source solution that supports a larger number of file formats on a wider variety of hardware platforms.
In this release most movement, selection, atom expression and color commands are operational.
Things that explicitly do *not* work are protein rendering formats such as ribbons, cartoons, strands, etc. Jmol does not perform lighting and surface rendering on the fly, so settings such as ambient, shadows, specular and specpower are not available. Finally, Jmol does not have a true 3D graphics engine, so renderings of intersecting surfaces are not handled properly. This occurs when Atoms are rendered with larger vanderWaals percentages (such as 50% or more).
Please give us feedback on what features you would use and would like to see. This will help us prioritize future development.
This is a Jmol specific command that is not available in RasMol/Chime.
The animate command provides basic control over files which contain multiple chemical frames. This mechanism can be used to play short movies of reactions, vibrations, etc.
The play and revplay commands will play all frames in the file, either in forward or reverse. The frame rate is currently limited by a) the rendering speed of the system, and b) with a maximum of 10 frames per second.
The next, prev, nextwrap, prevwrap and rewind commands allow one to step through a file frame by frame. nextwrap/prevwrap will wrap around to the first/last frame.
The frame command takes an integer argument which specifies the frame number to show.
Additional work will be done on this command for the next release of Jmol, allowing additional control over display frame rate, interpolated frames, etc.
Sets the center of rotation to be the center of the set of atoms defined by the expression. This is calculated as the mean value of the coordinates of the selected atoms along each of the respective axes. If no atoms are selected then the center is set to the center of the bounding box (the default).
Colors the object with the specified color. If no object is given then atom is assumed. Currently supported objects are atoms, bonds, labels and axes.
Renders selected atoms as shaded spheres.
A boolean value renders the spheres with the vanderWaals radius. The current jmol implementation does a poor job of rendering these because the renderer does nothandle intersecting objects.
A decimal value specifies sphere radius in Angstroms.
A positive integer specifies sphere radius in RasMol units, 1/250th of an Angstrom.
Jmol extension: A negative integer specifies sphere radius as a percentage of the vanderWaals radius. Thus, a value of -25 specifies that the selected atoms should be rendered with a sphere radius of 25% of the vanderWaals radius for that element.
cpk is synonymous with spacefill.
defines the specified variable to the the atoms selected by the expression;
Chime extended command.
Causes the screen to refresh and the script to stop executing for 'delaytime' seconds. Decimal values can be used to represent fractions of seconds. If 'delaytime' is not specified the default delay is 1 second.
Prints the specified string to the console. (We need to find a better place to send the output. Status line?)
Stops execution of the current script. In the case of a script which is being run as a child script, execution continues with the parent.
For programmers, this is a 'return' statement.
Allows you to specify a label to be shown with the selected atoms. %a Atom Name %b %t Protein B-Factor/Temperature %c %s Protein chain %e Element atomic symbol %i Atom serial number %m single letter amino acid code %n 3 letter residue name %r PDB residue number
Loads the specified file or URL.
Jmol automatically determines file type based upon the contents of the file. Therefore, the format parameter is ignored. It is allowed for backward compatibility with RasMol/Chime.
Chime extended command.
Causes the current script file to re-execute from the top after 'delaytime' seconds. Default value for 'delaytime' is 1 second.
Renders a measurement between the specified atoms.
Two atoms specify a distance measurement.
Jmol extension: Three atoms specify an angle measurement.
Jmol extension: Four atoms specify a dihedral angle measurement.
Chime extended command.
The move command provides powerful animation capabilities. It allows you to specify rotations, zooming, and translations to be performed in a specified period of time.
xRot, yRot, and zRot are rotations about the cartesian axes in degrees.
Zoom specifies a zoom factor (there is a good chance this is not currently implemented properly)
xTrans, yTrans, and zTrans are translations in the range -100 to 100.
If you don't know what slab is, just put in a zero. see the 'slab' command for more information.
'time' is the total time in seconds for the movement.
FPS and MaxAccel control the animation rate. The default values work fine, non-default values may not work at all. If you need and/or want these to work, send us an email and we will get it working.
In the current release of Jmol, quit is synonymous with exit.
This is inconsistent with RasMol, where quit means to exit the program.
Forces screen repaint during script execution. (Frankly, I am not sure under what circumstances this would be necessary?)
Selects the atoms identified by expression and hides all atoms and bonds which are outside the selection set.
Rotates the model the specified angle about the specified axis. Integer values specify degrees. Decimal values specify radians.
Loads and executes the specified script file/url. The hash/pound/sharp character (#) character marks a comment to the end of the line. The semicolon character (;) separates multiple statements on the same line. A script file may load another script file, up to 10 deep.
The command source is a synonym for script.
Selects the atoms identified by the expression.
If no expression is given then all atoms are selected.
RasMol does not hilite selections. To see selected atoms use the command set display selected
The handling of selection hilites is a problem for Jmol. We are torn between providing RasMol compatibility and useful visual feedback to the user.
If you have suggestions on how this can be improved please let us know.
Slab mode provides a z-clipping plane that allows you to specify the percentage of the molecule to be displayed.
A boolean parameter turns slabbing on or off.
A percentage from 0 to 100 controls the amount of the molecult to be shown. A value of 0 shows nothing. A value of 100 shows everything. A value of 50 shows the back 50% of the molecule. A value of 25 shows the back quarte of the molecule.
(I have never seen the term slab used in this way before. As far as I know, the term is only used in RasMol.)
Moves the molecule along the specified axes according to the amount specified by value. Value ranges from -100 to 100, and represents the percentage of the display window. Negative values move to the left (for the x axis) and down (for the y axis). A value of 100 will move the molecule completely out of the window. A value of 50 will move the center of the molecule to the edge of the window.
(A translation along the z axis is defined in the RasMol documentation. As far as I can tell, it does nothing. If anybody knows anything different, please let us know.)
In RasMol terminology, wireframe refers to the bonds drawn between the atoms. A boolean value of 'on' draws the selected bonds as lines. Alternatively, a numeric value may be used to specify the radius of the bonds. A decimal value specifies Angstroms. An integer value specifies RasMol units (1/250th Angstrom).
Clears the currently loaded molecule.
RasMol forces you to 'zap' prior to loading a new molecule. Jmol currently does not have this restriction and does not enforce it.
Allows you to enlarge (or shrink) the molecule.
A boolean value turns zooming on or off.
A percentage value specifies the zoom percentage. 100 is the default value. The smallest acceptable value is 10. The largest acceptable value is 500. (Note that these are arbitrary restrictions that were put in for RasMol compatiblity. If someone wants to lift these restrictions please let us know.)
The default size in Jmol is calculated so that all molecules are completely visible on the screen through all rotations using the default vanderWaals rendering percentage as defined in Edit->Preferences...