Jmol/JSmol Interactive Script Documentation

Jmol/JSmol interactive scripting documentation

Search results for callback

[Jmol Math]	getProperty	select	set echo
audio	hover	set (callback)	set picking
echo	message	set (debugging)	show
frame	print	set (misc) **	throw
* indicates new or modified in version 16.03 ** indicates new or modified in version after 16.03

[Jmol Math]

   Jmol Variables
   Examples of Variable Use
   Indirect referencing and use of @
   Global and Local Scope
   Read-Only Variables
   Jmol Math Variable Types
   Differences Between Jmol Math and JavaScript
   Jmol Quaternion Math
   Operators and Operands
   Operation Rules

Jmol incorporates a rich JavaScript-like math environment including multiple variable types and a wide variety of functions. This section of the documentation details the use of variables and the sorts of operations that are allowed with them.

Jmol Variables    back

Variables may be assigned using standard mathematical expressions and used throughout Jmol in standard Java/JavaScirpt-like statements such as:

x = y + 3
for (var i = 1; i < 10; i++){...}
print x

In addition, the at-symbol, @, can be used in any Jmol-specific command (LOAD, SELECT, etc.) in order to switch into "math mode" temporarily to obtain a variable, as in

x = "ala or gly"; select @x
echo "@{'file=' + _modelFile}"
x = 0.2; wireframe @x
zoom @{x * 3}

Likewise, math expressions can temporarily switch into "atom select mode" using just { } without the @ sign:

x = {ala or cys}
print {*}.length
for(var i in {*}) { print i.label() }

Examples of Variable Use    back

Variables may be combined with settings to adjust parameters:

x = bondModeOR; set bondModeOr @{!x}
set showBoundBox @{!showBoundBox}

Variables may be used to extract information from a model:

x = {carbon}.bonds.length.min

Variables may be used to introduce atom-related property data from external files into the model:

x = load("chargeData.txt");select 2.1;data "property_charges @x";select 2.1 and property_charges < 0.5

Variables may be inspected using print x, show x, or message @x where x is a variable name. You can use message or echo to transmit this information to the user or to the web page via a JavaScript callback function or use the Jmol.js function jmolEvaluate(). If using the Jmol stand-alone application or the signed applet, you can write a variable to a file using the write command. Variables and math expressions can be checked using the print command.

Standard C++/Java in-place assignments such as x++, x--, ++x, --x are allowed, along with assignments +=, -=, *=, /=, \= (integer division), |=, and &=.

Indirect referencing and use of @    back

Jmol math allows for one variable referencing the value contained in another variable. This is accomplished using the @ sign in a math context rather than an atom selection context. Thus, if y = 3 and x = "y", then print @x prints "3" because @x means "the value of the variable named by x" which in this case is y. The use of @ is summarized below:

select @x In implicit atom expression commands such as select, display, and delete in which x must represent an atom expression, either in the form of a string, x = "ala or cys", or as an actual expression, x = {ala or cys}.
y = {@x} Similarly, within selection mode within a math expression, to have a variable atom expression.
select chain=@x In an atom expression comparison, @ substitutes a variable's value directly. For example, select chain=X selects for chain X; x="A";select chain=@x selects for chain A.
echo "model=@{_modelNumber}" Specifically for the commands echo and hover, if a math expression is present, the text will be dynamically generated every time the screen is refreshed, thus automatically updating when variables are changed.
load @x In all other commands that accept parameters as any sort of variable parameter.
y = @x when x is a string, an indirect reference, with @x representing the contents of the variable named by x; when x is an array or associative array, carries out a deep copy of all elements and elements of elements.
@36 @ sign followed by a number n is a shortcut in any context for {atomno=n}.
@@36 @@ sign followed by a number n is a shortcut in any context for {atomno=n and thisModel}, returning the subset of atoms with this atom number that are in the current frame set as determined using with the frame or animation frames command. For example, model 3;select @@2 would be the same as select atomno=2 and model=3.
@myGroups ala or cys @ sign followed by a name in the context of a command is a substitute for the define command, which is an early Jmol syntax. In this case, "myGroups" is defined as "ala or cys", so we can now say select myGroups in place of select ala or cys. A difference between this usage and @myGroups, where myGroups is a Jmol Math variable, is that all definitions created with the DEFINE command are temporary definitions that will be deleted when a new model is loaded or appended. Such is not the case for Jmol Math variables.

Users are cautioned to be careful using @, particularly because of indirect referencing and the need to switch into the proper mode before using a variable. The following statements probably will not do what you think they will do: select x; print @x; x = @y + 2.

The table below lists all JavaScript-like commands as well as the RasMol commands not requiring quotes.

These JavaScript-like commands do not require @ with expressions. CASE CATCH FOR IF/ELSEIF LOG PRINT PROMPT RETURN SWITCH THROW VAR WHILE
These commands, many of which predate Jmol math, accept exactly one string parameter. For these specific commands, quotes are optional. The distinction with and without quotes in these cases only has to do with simple variable substitution. echo @x will echo the contents of variable x; echo "@x" will echo @x. (However, variable expressions, such as @{x + 3}, are processed in these cases even if quoted. cd echo goto help hover javascript label message pause

Global and Local Scope    back

Variables in Jmol have one of two scopes -- global or local. Global variables hold values that need to persist across scripts or functions. Local variables override the values previously assigned to the same name for some limited extent. In general, variables defined in Jmol are global variables. Note that no variables are recorded in the state. It is good programming practice to define variables locally as much as possible, but there are times when global assignments are needed. Just be aware that any global variables created and not destroyed using the reset command consume memory and may slow script processing. The following rules govern the scope of local variables:
applet localization all variables in Jmol are localized to a specific applet. Note that this is not necessarily true for functions. Specifically, functions beginning with static_ are common to all non-Java applets. These static functions, though able to be used by any applet, will not share variables.
script localization

Variables defined using the keyword VAR within a script file that is read by the script command are localized to that script and scripts that that script calls. var x = 30
var d = {atomno=1}.xyz.distance({atomno=2}.xyz)
function localization

The parameters of a function and any variables defined within a function using VAR are local to that function. The Jmol script on the right will print

a=1 b=2
testing now a = "testing"; c = "now"
function checkX(a, b) {
   var c = 15;
   print "a="+a + " b=" + b
}
checkX(1,2)
print "" + a + " " + c
FOR/WHILE localization

Variables defined using VAR within the context of a FOR or WHILE loop will be local to that loop. The script on the right will print

5
6
7
3
x = 3
for (var x = 5; x < 8; x++) {
   print x
}
print x
{ ... } localization

Variables defined using VAR can be localized to a section of a script by bracketing that section of the script with { and }. This script will print

10
3
x = 3
{
   var x = 10;print x
}
print x

Read-Only Variables    back

fome variables have preset meanings, as shown in the table below. A subset of these variables can be used in math expressions. If you create your own variables, their names must not begin with an underscore. Variables starting with underscore are defined by Jmol and can be used but not set in a script. To check the settings of all available read-only variables, use show _?. Read-only variables include:

_animating whether or not Jmol is currently running through the frames as a result of animation on or animation play (true or false)
_animTimeSec The time in seconds required for an animation to complete one cycle.
_applet whether or not Jmol is running as an applet
_atomHovered the overall atom index of the atom that was most recently hovered over (or -1)
_atomPicked the overall atom index of the atom that was most recently picked (or -1). Can be used, for example, with select atomIndex = _atomPicked
_currentFileNumber the number of the currently displayed file, starting with 1 (value will be 0 if more than one file is displayed)
_currentModelNumberInFile the number of the currently displayed model in its file (or 0 if more than one model is displayed)
_depthPlane The plane defining the back limit of the model for the current orientation and slabbing. See also _slabPlane
_fileType The file type of the most recently loaded file
_firstFrame The first frame in the current animation frame range expressed in x.y notation
_frameID A numerical frame number equal to 1000000 times the file number plus the model index in the file
_height the height of the applet or application window in pixels
_lastFrame The last frame in the current animation frame range expressed in x.y notation.
_hoverLabel Gives the general hover label set by hover command.
_hoverEnabled Indicates if hover is enabled or not.
_loadPoint a number indicating the load status, usually 3 indicating successful load, possibly 0 indicating load failure.
_M a shortcut for getProperty("modelInfo").models[_modelindex+1], providing easy access to detailed information about just the current model
_memory the amount of memory allocated to the applet or application
_modelFile the filename of the model (or "" if more than one model is displayed)
_modelName the name of the model (or "" if more than one model is displayed)
_modelNumber the current model number as a string in file.model notation (or "file1.model1 - file2.model2" if more than one model is currently displayed)
_modelTitle information from the file reader interpreted as a title
_mouseAction a number associated with the current mouse/key state
_mouseModifiers a number associated with the current key combination associated with the mouse
_mouseX the current X-position of the mouse
_mouseY the current Y-position of the mouse
_multiTouchClient indicates if Jmol is operating as a Sparsh-UI client and has connected with the Sparsh-UI server (possibly itself).
_multiTouchServer indicates whether Jmol is functioning as a Sparsh-UI server. (Requires a specialized Jmol Sparsh-UI driver) and has successfully connected to a multi-touch device.
_navigating TRUE if navigation is on
_nProcessors the number of available processors
_picked The set of atoms most recently picked. This buffer is cleared when the user clicks twice off the molecule.
_pickedList The _picked atoms as an ordered array. Thus, _pickedList[0] is the last-picked atom; _pickedList[-1] is the second-to-last-picked atom; _pickedList[-2][0] are the three last-picked atoms.
_pickInfo information about the last atom picked, including a description of the atom, its atom number, and its x y z coordinates. For example:
[GLN]25:A.O/2.1 #175 40.271 8.524 2.615
_signedApplet whether or not Jmol is running as an signed applet
_slabPlane The plane defining the front limit of the model for the current orientation and slabbing. See also _depthPlane
_spinning whether or not the model is currently spinning (true or false). The _spinning variable can be used, for example, to toggle spinning on and off:
if (_spinning);spin off;else;spin on;endif;
_useCommandThread TRUE if Jmol is using an independent command thread.
_version the version of Jmol expressed as an integer: vvrrxxx for Jmol vv.rr.xxx. For example, for Jmol 11.2.38, _version = 1102038
_versionDate the version of Jmol expressed in the form of 14.5.4_2016.04.03 2016-04-03 14:35 .
_width the width of the applet or application window in pixels

Jmol Math Variable Types    back

Jmol math allows for several distinct variable types, some of which are common types (boolean, integer, decimal, string, serial array, byte array, associative array, binary associative arrays), and some of which are special types of particular use in molecular calculations (point, plane, quaternion, 3x3 matrix, 4x4 matrix, atom bitset, bond bitset). Variable types may be combined in mathematical expressions. Array types may include any number of any combination of these data types. Examples include:

array Standard arrays in Jmol are created using x = [...] or x = array(...). For example:

xlist = array(true,3,3.5,"testing",{2.3,3.4,4.5});
xlist = [true,3,3.5,"testing",{2.3, 3.4, 4.5}]
xlist = [3 -3 5 -5]

Note that arrays may contain a mix of any variable type. Commas between elements are not required. The two methods of defining an array are slightly different. The array() function always defines an array, regardless of its contents. The a = [....] notation, on the other hand, will define a matrix, not an array, if the elements are numerical and the array is of the correct form (3 rows and 3 columns, or 4 rows and 4 columns).

Arrays are stored, saved, and manipulable as objects, and all array assignments are by reference, as for JavaScript and Java, meaning that if x = ["a", "b", [3, 4, 5]], and we assign y = x[3], then y is x[3], not a copy of it, and if we later assign y[4] = "new", then at x[3] = ["a", "b", [3, 4, 5], "new"] as well. The functions x.push(y) and x.pop() can be used to add and remove elements from a Jmol array.

The notation a[2][3] generally refers to the subarray consisting of the second and third elements of a. However, in the assignment context a[2][3] = ..., these numbers refer to the third element of the second element of the multidimensional array.

To specify a specific element of a multidimensional array in other contexts, you can use parentheses: print (a[2])[3] or, starting in Jmol 14.3.13, you can use "." separation to indicate nested array elements: print a[2].[3].

byte array A byte array holds data in the form of 8-bit bytes. Starting with Jmol 14.2, byte arrays can be created from base64-encoded data using x = array(";base64,...") where "..." is base64-encoded data or loaded from a file using load(fileName, TRUE). When loaded from a file, the byte array takes the form of one or more entries in a "binary associative array" (below). A byte array x will give x.type = "byteArray".
associative array Associative arrays store information retrievable by string-based keys. The information may be any type, including another associative array. Empty associative arrays are created using x = {}. Reference or retrieval is accomplished one of three ways:

arrayName["keyName"] The guaranteed way to get a key is the same as JavaScript notation. If a key is absent, the empty string is returned.
arrayName..keyName Alternatively, wo consecutive periods can be used, provided the key is a simple alphanumeric quantity such as "key1" or "x". Keys can be chained: myData..atoms[1]..x
arrayName.keyName Finally, similarly to JavaScript and Java, one can use simple "dot" notation -- with just one caveate. In Jmol the three functions a.keys, a.size, and a.type return an array of keys, the number of keys, and the string "hash" for an associative array. If your array has those keys, you must use a..keys, a..size, or a..type, or a["keys"], a["size"], or a["type"], to access them.

Thus,

x = {}
x.atoms = {visible}
x["file"] = _modelFile. The functions x.push(key,value) and x.pop(key) can be used to add and remove elements from a Jmol associate array .

Jmol's associative arrays are, strictly speaking, a superset of JSON arrays, consisting of a bracketed comma-separated list of key-value pairs, involving a key, a colon, and an expression. The key does not have to be quoted if it is a simple alphanumeric key such as "x" or "x2" and square brackets [...] are used rather than braces {...}. For example:

b = [test : 34, "my test": "OK"]
b.test = 100
b.test3 =["one", 3, 4, 5]
print b["my test"] + " -- " + ++b.test +" -- "+b.test3[1]

OK -- 101 -- one

show b

b = [ "my test":"OK","test":101,"test3":[ "one",3,4,5 ] ]

b -= "test3"
show b

b = ["test" : 101, "my test" : "OK"]

The key can always be quoted, as in JSON, and, as noted, an alternative syntax involving braces insead of brackets, as in JavaScript, can be used, in which case the key must be quoted. Note that an empty associative array must be created using {}, not [ ].
binary associative array Jmol 14.2 introduces the binary associative array type. This data type is a form of associative array that allows data to be preserved as raw bytes. For example, image or zip file data can be saved in an array without need for translation to base64. Any associative array is a binary array if it contains the key "$_BINARY_$". The value of this key is never checked, but Jmol will then assume that all other values MAY be in byte form. (They can be any values, but if they are byte arrays, then they will be preserved as such.)

The three forms of binary associative arrays are given in the table below:
keys contents write VAR
$_BINARY_$, _DATA_ generic binary data as a single byte array binary file
$_BINARY_$, (filenames) byte arrays keyed by filename ZIP file; created by x = write("ZIP") or x = write("Jmol")
$_BINARY_$, _IMAGE_ , (filenames) PNG image with associated files PNGJ file, if created as such using x = write("PNGJ")

Combined with Jmol's capability to read and write ZIP files, the manipulation of associative arrays allows Jmol scripts to read or create, modify, append to, and save ZIP files and PNGJ images as well as any binary data format. For example, the following script creates a ZIP file relating to the currently loaded structure:

  a = {}
  a.push("file.dat",show("file"))
  a.push("state.spt",show("state"))
  a.push"image.png", getProperty("image"))
  a.push("$_BINARY_$",true)
  write var a myfile.zip
bitset x = {atomno < 30};
x = ({0:28 45 56:62})

Atom bitsets specify a group of atoms in the overall collection (not just one model). Numbers are atom indices, which start with 0 and run through all atoms in all models.
bondset x = {atomno < 30}.bonds;
x = [{0:4 6 9:12}]

Bondsets specify groups of bonds in the overall collection. Numbers are bond indices, which start with 0 and go through all bonds in all models. There are only a few contexts in which bond bitsets can be used. Examples include:

color @{ {ala}.bonds } green; select [{3:300}]; color BONDS white; connect @{ {dna}.bonds } radius 0.1;.
boolean Boolean values include TRUE and FALSE. Case is not sensitive, so TRUE == True == true:

isOK = TRUE; if(isOK) { print "all is good" }
decimal averX_nm = {atomno < 10}.x * 100.0;

Decimal numbers in Jmol are stored as 32-bit floating-point values, with critical calculations carried out as 64-bit double values.
integer for (var i = 1; i < 10; i = i + 1){ print i }

3x3 matrix Rotation matrices in Jmol are indicated either as a 3-row, 3-column array or by 9 numbers set off by double brackets.

m = [[1.0 2.0 3.0],[4.0 5.0 6.0],[7.0 8.0 9.0]];
m = [[0.57010806 -0.0516641 0.8199437 0 -0.5407497 0.72776425 0.42183995 -0.6185197 -0.68387866 0.3869669]]
m = axisAngle({1 0 0},30)%-9
rotate @m

Note that commas are required between rows, if they are indicated.
4x4 matrix Translation/rotation matrices in Jmol are indicated either as a 4-row, 4-column array or by 16 numbers set off by double brackets.

m = [[0.57010806 -0.0516641 0.8199437 0],[-0.5407497 0.72776425 0.42183995 0],[-0.6185197 -0.68387866 0.3869669 0][0 0 0 1]];
m =[[0.57010806 -0.0516641 0.8199437 0 -0.5407497 0.72776425 0.42183995 0 -0.6185197 -0.68387866 0.3869669 0 0 0 0 1]] ;
rotate @m

Commas are required between rows, but indicating rows is optional.
point pt = {3.2 3.3 3.4};

Commas are optional.
plane xyPlane = {0 0 1 0};

Planes are defined as {a b c d}, where the equation of the plane is ax + by + cz + d = 0.
quaternion q = quaternion({1 0 0}, 30);
q = {0.25881904 0.0 0.0 0.9659258};

(see next section) Quaternions are saved internally in Jmol using the same format as for planes, as single-precision floating point four-element vectors, with parameter order {x y z w} or {q1 q2 q3 q0}. Ordering the parameters in this way is consistent with Java Quat4f format and allows both quaternions and planes to contain axis information in the first three parameters. The common storage format for planes and quaternions works because typical quaternion operations are not common to operations involving planes.
string myLabel = "this is a test";

Strings may be enclosed in either single or double quotes.

Differences Between Jmol Math and JavaScript    back

Jmol Math is mostly an extension of JavaScript, with some differences, most notably:

Jmol JavaScript
String comparisons in Jmol are not case sensitive, so "test" == "TEST". (But see the "like" operator, where "test" like "TEST" evaluates to false.) Note that this means that cases "f" and "F" in switch both match "f" and "F". String comparisons are case sensitive; there is no "like" operator.
Variable and function names are not case sensitive. test == Test. Variable and function names are case sensitive.
Boolean values in Jmol are not case sensitive: TRUE == true. Booleans are specifically true and false.
Use of undefined variables in Jmol is not an error; undefined variables are simply returned as empty strings. Reference to undefined variables throws an error.
Integers are distinct from decimals in Jmol All numbers outside of specialized array buffers are double-precision 64-bit floating-point values.
Decimal values are 32-bit floating-point values in Jmol/Java and 64-bit floating-point values in JSmol. All numbers are double-precision 64-bit floating-point values.
Array indices are 1-based in Jmol; 0 is the last element of an array, -1 is the next-to-last element, etc. If a is an array, then a[1][2] generally represents the first two elements of a. To specify a specific element of a multidimensional array, use parenthesis: (a[1])[2]. However, in the assignment context a[1][2] = ..., this notation refers to the second element of the first element of the multidimensional array a. Array indices are 0-based; negative array indices are not meaningful.. If a is an array, then a[1][2] represents the third element of the second element of the multidimensional array a.
In Jmol, 3x3 and 4x4 matrices are distinct subsets of arrays. If m is a matrix, then m[1][2] addresses the matrix element in column 1, row 2. No distinction between arrays and matrices.
Associative arrays in Jmol are expressed as {"key":value} or [key:value]. The {} notation is compatible with JSON, so JSON object and array string data can be used directly as Jmol associative and serial arrays, respectively. Quotation marks, are required when braces { } are used (as in JSON), but are optional when brackets [ ] are used (as in JavaScript objects). Associative arrays are JavaScript Objects and as such are expressed as {key:value} only. Quotation marks around key are generally optional. [ ] notation is for serial arrays only.
Bitsets in Jmol serve as highly compressed boolean arrays, with logical operations AND, OR, and NOT. No equivalent data type.
Operations in Jmol such as a + b on variables of different types depend upon the types involved and the order used, with the one on the left of principal importance, coercing the result (see below). For example, 3 + "3" == 6; "3" + 3 = "33". Operations such as a + b on variables of different types depend upon the types involved, but do not depend upon order: 3 + "3" and "3" + 3 both equal "33".
Binary operations in Jmol include +, -, *, /, % (modulus), \ (integer division), ** (exponentiation), && (or AND or just &), || (or OR or just |), ! (or NOT), == (or just =), other standard comparison operators, and like. Jmol math does not support bitwise operations such as &, |, or ^, although bitwise and, or, and not are all used with bitsets. Operations include +, -, *, /, %, ++, --, && (logical AND), || (logical OR), == and === (strict equivalence, as distinct from == or the assignment operator, =), and bitwise operations &, | ^, ~, <<, >>, and >>>.
Inline assignment in Jmol, such as x = (y = 3), or just x = y = 3, is not supported. (In this case, x will end up true or false, depending upon the value of y. Inline assignment such as x = (y = 3),or just x = y = 3, is supported.

Jmol Quaternion Math    back

All quaternions in Jmol are unit quaternions, which are four-dimensional vectors that can be used to define the relative rotational aspects of a protein or nucleic acid structure as well as overall molecular orientation. This means that they can be used in a variety of commands, including navigate, moveto, and rotate to rotate the model or selected atoms of the model around specific axes and to specific orientations. Each quaternion can be thought of as representing a unique axis and angle which will transform a reference frame (either the molecular reference frame or the window reference plane to a given orientation. If n is the axis and theta is the angle (measured in a right-handed, counter-clockwise direction), then q(theta/2, n) = (cos(theta/2), n sin(theta/2)). For storage, the vector n is broken out into its x, y, z components, giving a total of four numbers, (q0, q1, q2, q3), where q0 = cos(theta/2), q1 = n_x sin(theta/2), q2 = n_y sin(theta/2), and q3 = n_z sin(theta/2). Jmol reports a quaternion as a four-vector with q0 listed last: {q1, q2, q3, q0} in order to be consistent with Java's {x, y, z, w} notation.

The quaternion() function constructs quaternions using a variety of starting points, including no parameters (the current model rotation), the four numbers q0-q3, quaternion(q0, q1, q2, q3), axis-angle information, quaternion({0 0 01}, 30), and 3x3 rotation matrices, quaternion(mat). The quaternion() function also can deliver the spherical mean rotation of a set of rotations, quaternion([qa, qb, qc, ....]), or its standard deviation, quaternion([qa, qb, qc, ....], TRUE) based on Samuel R. Buss and Jay Fillmore, "Spherical Averages and Applications to Spherical Splines and Interpolation", ACM Transactions on Graphics 20 (2001) 95-126.
In addition, quaternions representing the orientation of specific amino acid residues and nucleic acid bases can be constructed automatically based on the setting of the Jmol parameter quaternionFrame, and certain commands and functions such as show rotation and script("show rotation") deliver quaternions. These quaternion values can be depicted visually using the draw and plot commands and can be listed or saved to a file using the show and write commands, respectively.

An interesting feature of quaternions that makes them different from the more common 3x3 rotation matrices is that they can encode rotations up to 720 degrees. For example, quaternion({0 0 1}, 30) = {0.0 0.0 0.25881904 0.9659258} (a 30-degree CCW rotation around the Z axis), while quaternion({0 0 1}, 390) = {0.0 0.0 -0.25881904 -0.9659258} (because sin(195) and cos(195) are both negative). While rotations of 0 degrees, {0 0 1 1}, and 360 degrees, {0 0 -1 -1} represent the same final state, in certain cases they can represent different processes and can thus be significantly different. In addition, quaternion differences (or "derivatives") can be quantified in ways that cannot be done for 3x3 rotation matrices. For example, the mean and standard deviation of a set of quaternions can be determined: print [a,b,c,d,e].average, print [a,b,c,d,e].stddev, where a-e are quaternions, providing, for example, the average helical axis for a protein helix structure, or a measure of how "ideal" that helix is.

The quaternion q = quaternion() measures how much the model has been rotated from its reference position (with x to the right, y to the top, and z toward the user). It can be used to align any axis or plane with any other "window-frame" axis. For example, here is a quaternion recipe for the shortest rotation that takes atom "X" and puts it between the center of the model and the user, that is, "in the forefront:"

q = quaternion(script("show rotation"))
toAtom = {C1}.xyz - {*}.xyz
toUser = (!q)%{0 0 1}
axis = cross(toAtom, toUser)
a = angle(toAtom, {0 0 0}, axis, toUser)
rotate MOLECULAR {0 0 0} @axis @a

The idea here is to apply the reverse model rotation quaternion to the z axis, {0 0 1} to give a vector that is pointing straight at the user. Then we get an axis that is perpendicular to both that and the vector we want to assume this position. The directed angle around that axis is obtained as a dihedral angle relating our atom, the origin, that axis, and the point in space directed toward the user. Then we rotate in a MOLECULAR frame to get the desired effect.

For another example, let's line up the plane through atoms C1, C5, and C8 such that, relative to the user, C1 is directly to the right of C5, and C8 is in the plane of the screen, above the other two atoms. This is trivial using quaternions:

x = quaternion({c5}, {C1}, {c8})
q = quaternion(script("show rotation"))
rotate molecular quaternion @{(!q) * (!x)}

This basically says, "Move this plane into the position currently occupied by the xy plane (!x), then move that plane back to the original position of the xy plane (!q)."

Operators and Operands    back

Jmol expressions can include standard operators: +, -, *, /, \(integer division), **(exponentiation) %(modulus), and (&, &&, and), or (|, ||, or), not (!, not), and all standard comparison operators. The SQL-like operator LIKE can be used to compare strings in a case-sensitive manner. So, for example, while "a" == "A" is true, "a" LIKE "A" is false. (This design admittedly is a bit odd; it derives from legacy Jmol and SELECT expressions, where "=" has never been case-sensitive.) LIKE supports wildcards ("xxx*", "*xxx", and "*xxx*", for "starts with", "ends with", and "contains", respectively).

Also supported are the unary operators x++, x--, ++x, --x, which can stand alone or be part of an expression:

a = ++b
print "i=" + ++i
++a

In addition, assignments +=, -=, *=, /=, \=, |=, and &= are supported:

a += 2
b = {ala}; b |= {gly}

In general, expressions are evaluated from left to right using standard operator precedence (*,/,\ before +/-; +/- before AND/OR/NOT). For example:

twoPI = 3.14159 * 2;
minBondDistance = minBondDistance * 0.5 + 0.1;

In addition, you can set variables to be the number of atoms that match an atom expression. For example:

nNC = {_N and */1 and connected(_C)}.size
nAtoms = {*}.size;
nCH = {_H} + {_C};

Since Jmol math does not include strict typecasting, it uses a relatively complex set of rules to determine the result of operations on mixed variable types. When two different variables are operated upon, the resulting variable type depends upon the operator used, the order of the variables, and sometimes the value of the variables. See misc/operations.txt for details. In general, when conversion is required for a string, point, plane, bitset, or array, Jmol will attempt to convert it to a variable type compatible with the left-hand operand prior to operating. These conversions generally involve:

string to boolean The strings "", "FALSE", "0", and decimal strings such as "0E1" and "0.0" that equal 0 are converted to FALSE; all other strings are converted to TRUE.
string to integer A string evaluating to an integer is converted to that integer; all other strings are converted to 0.
string to decimal A string evaluating to a number is converted to that number; all other strings are converted to the decimal value "not a number", or "NaN".
string to other Jmol saves all states as simple strings, so certain character sequences are automatically turned back into other variable types when operated upon. Jmol automatically converts:

{x y z} to a point
{x y z w} to a plane or quaternion
({i j k l:m ... }) to an atom bitset
[{i j k l:m ... }] to a bond bitset
point to integer The distance from the point to {0 0 0} rounded DOWN to the nearest integer.
point to decimal The distance from the point to {0 0 0}; same as x.distance({0 0 0}). Note that this means that 0.0 + {3 4 0} or 1.0 * {3 4 0} both give 5.0, sqrt(3*3 + 4*4 + 0*0), because the point is first converted to a decimal, then operated upon by + or *.
plane to integer The distance from the plane to {0 0 0} rounded DOWN to the nearest integer
plane to decimal The distance from the plane to {0 0 0}; same as x.distance({0 0 0})
quaternion to decimal cotangent(abs(theta)/2), where theta is the angle of the rotation associated with this quaternion
bitset to decimal or integer The number of selected atoms or bonds in the bitset; same as x.size
array to decimal or integer The number of elements in the array; same as x.size

Operation Rules    back

Rules for operations with the given types include:

+ addition a + b produces a decimal number EXCEPT:

string + b string If b is not a string, the closest string representation will be used.
integer + b integer unless b is a decimal.
array + b array adds b (or all the elements of b, if b is also an array) to the end of the array to form a new array. Thus, to add a full array b as a single element to the array a, use a + [b], and to add an element b to the beginning of array a, use [b] + a.
associative array + associative array associative arrray creates a new array that has all of the keys of both associative arrays. (See also array.push(array).)
point + b point If b is another point then adds the two; if b is a quaternion or plane, extracts the {x y z} component of b and adds that; otherwise adds the decimal equivalent of b to all coordinates of the point.
matrix3x3 + matrix3x3 matrix3x3 sum of individual elements of the two matrices
matrix3x3 + point matrix4x4 adds a translation vector to a rotation matrix to give a 4x4 matrix
quaternion + b quaternion If b is a quaternion, generates the product of the two quaternion rotations; otherwise adds the decimal equivalent of x to the angle of rotation associated with this quaternion.

- subtraction a - b produces a decimal number EXCEPT:

string - b integer specifically when the string is not a string representation of a decimal, such as "3.5", and b is not a decimal itself.
integer - b integer unless b is a decimal.
point - b point subtraction of one point from another if both are points; subtraction of the {x y z} components of b if b is a quaternion or plane; otherwise subtaction of the decimal equivalent of b from each of the coordinates of the point.
associative array - x associative arrray creates a new array that is the same as the original but does not contain key x. (See also array.pop(x).)
matrix3x3 - matrix3x3 matrix3x3 difference of individual elements of the two matrices
matrix4x4 - matrix4x4 matrix4x4 difference of rotational parts of the two matrices, with no change in the translational component
quaternion - b quaternion If b is a quaternion, generates the divides b into the quaternion; otherwise subtracts the decimal equivalent of x from the angle of rotation associated with this quaternion

* multiplication a * b produces a decimal number EXCEPT:

string * integer integer when the string is the string representation of an integer
integer * b integer unless b is a decimal
point * b point producing the point scaled by the decimal equivalent of b, unless b is also a point, in which case the result is the dot product producing a decimal, or a matrix, in which case the result is the transform of the point
array * matrix3x3 array when the array has 3 elements; the transpose of the matrix is used for the transformation
array * matrix4x4 array when the array has 4 elements; the transpose of the matrix is used for the transformation
matrix3x3 * matrix3x3 matrix3x3 product of two matrices
matrix3x3 * b point if b is a representation of a point, the matrix transformation of that point.
matrix3x3 * array array if the array is a 3-element array; generates a 3-element array transformed by the matrix.
matrix4x4 * matrix4x4 matrix4x4 product of two 4x4 matrices
matrix4x4 * b point if b is a represenation of a point, the matrix transformation of that point.
matrix4x4 * array array if the array is a 4-element array; generates a 4-element array transformed by the matrix.
quaternion * quaternion quaternion quaternion multiplication q2 * q1 results in a composite rotation resulting from first rotating by q1, then by q2.
quaternion * (decimal)x quaternion multiplication of the angle associated with this quaternion by x
quaternion * matrix3x3 quaternion quaternion product

/ division a / b produces a decimal number EXCEPT:

integer / integer integer
point / b point if b is a point, then a is scaled by the magnitude of b; thus a/a when a is a point produces a normalized vector in the direction from {0 0 0} to point a
quaternion / (decimal)x quaternion division of the angle associated with this quaternion by x
quaternion / quaternion quaternion q2 / q1 = q2 * q1^-1 (absolute difference in rotation, in the molecular frame)

\ left division a \ b produces integer division EXCEPT:

quaternion \ quaternion quaternion q1 \ q2 = q1^-1 * q2 (relative difference in rotation, in the q1 frame)

** exponentiation a**b takes a to the power of b; if both a and b are integers, the result is an integer, otherwise the result is a decimal number.

% modulus a % b is fully defined only for integer b and produces an integer EXCEPT:

decimal % 0 integer decimal a rounded to nearest integer, with n.5 rounding to (n + 1) and -n.5 rounding to -(n + 1)
decimal % b string decimal a rounded to b digits after the decimal point when b > 0; decimal a rounded to b significant digits in scientific notation when b < 0
matrix4x4 % 1 matrix3x3 extract the 3x3 rotation matrix from a 4x4 rotation/translation matrix
matrix4x4 % 2 point extract the translational vector from a 4x4 rotation/translation matrix
quaternion %"w" decimal (also q.w or q%0) extract q0
quaternion %"x" decimal (also q.x or q%1) extract q1
quaternion %"y" decimal (also q.y or q%2) extract q2
quaternion %"z" decimal (also q.z or q%3) extract q3
quaternion (or plane) %"normal" point (also q%4) plane normal or quaternion axis; in the case of a plane, the vector from this point to {0 0 0} is directed toward the plane; for quaternions, the axis is defined such that the angle would be between -180 and 180 degrees.
quaternion %"eulerZXZ" point (also q%5) Euler Z-X-Z equivalent angles, as {z x z}.
quaternion %"eulerZYZ" point (also q%6) Euler Z-Y-Z equivalent angles, as {z y z}.
quaternion %"vector" point (also q%-1) extract the rotational axis ({q1 q2 q3} or {x y z}) as a point (vector from {0 0 0})
quaternion %"theta" decimal (also q%-2) extract the angle in degrees for the rotation associated with this quaternion
quaternion %"axisX" point (also q%-3) extract the first column of the rotation matrix associated with this quaternion (what {1 0 0} is transformed to)
quaternion %"axisY" point (also q%-4) extract the second column of the rotation matrix associated with this quaternion (what {0 1 0} is transformed to)
quaternion %"axisZ" point (also q%-5) extract the third column of the rotation matrix associated with this quaternion (what {0 0 1} is transformed to)
quaternion %"axisangle" point4 (also q%-6) extract the related axis-angle for this rotation as {x, y, z, theta(degrees)}
quaternion %"matrix" 3x3 matrix (also q%-9) rotation matrix equivalent.
quaternion % {x y z} point transform {x y z} by the rotation associated with this quaternion
string % b string when b > 0, right-justified in a field b characters wide; when b < 0, left-justified in a field b characters wide. Special values 9999 and -9999 return upper case and lower case, respectively. b = 0 trims the string of white space.
point % b point generates the unitcell coordinate corresponding to the point, offset from {0 0 0} by {b/1 b/1 b/1}.
bitset % b bitset a truncated to first b items; same as a[1][b]
array % b array each element treated as a string and justified individually

&& || ! AND/OR/NOT In a logical AND operation (as opposed to a bitset AND operation) if the operand on the left is FALSE, the operand on the right will not be evaluated; likewise for logical OR -- if the left operand evaluates to TRUE, then the right operand is not evaluated. This is the same as in most programming languages, including JavaScript and Java. The following are equivalent:
AND & &&
OR || |
NOT !

a AND/OR b as well as NOT b produce a boolean except for the following cases:

array OR x array adds the element x to the array. If x itself is an array, the operation appends the elements of x as individual elements, concatenating the two arrays. To append one array onto another as a single element, simply surround the array being added with brackets: a = [1,2,3]; a |= [4, 5 6] leaves a as [1,2,3,4,5,6]; a = [1,2,3]; a |= [ [4, 5 6] ] leaves a as [1,2,3,[4,5,6] ].
bitset AND bitset bitset the intersection of the two bitsets
bitset OR bitset bitset including all selections from both bitsets
NOT bitset bitest the inverse of the bitset, based on the total atom count for an atom bitset or the total bond count for a bond bitset
bitset OR integer bitset turns on the specified bit in the bitset. For example, ({2}) | 4 evaluates to ({2 4}).
bitset OR array bitset turns on the specified bits in the bitset. For example, ({2}) | [4,5,6] evaluates to ({2 4:6}).
!m matrix matrix inversion
!q quaternion quaternion inverse, {-x -y -z w}

==  != equal/not equal == (or just "=") and != test for equality based on the following rules:

string == string true if the strings are identical
array == array true if the two arrays (including associative arrays) are the same length and each of their elements are identical. (In this test numerical identity does not distinguish between integers and decimals, so, for example, [4 5 6] == [4.0 5.0 6.0].)
bitset == bitset true if their bits are identical
point == point true if the distance between the points is less than 1E-6.
plane == plane
quaternion == quaternion true if the four-vector distance between the quaternions or planes is less than 1E-6.
others all other comparisons are processed by first converting the two values to decimals and then testing to see if these values are within 1E-6 of each other. Note that this conversion follows the rules given in Operators and Operands. So, for example, 4.0 == 4, 5 == "5", 1.0000005 == 1, {1 1 1} == 1.7320508, [1 4 5] == 3, and ({9:12}) == 4. If a strict identity test is desired, use array notation: [5] != ["5"], since array equality does not use these conversions.

top

index

audio

Jmol can load and play audio clip files of standard types. JavaScript allows WAV, MP3, OGG; Java allows just WAV. AUDIOcallback can be used to monitor the state of the running audio clip. For example: audio "https://chemapps.stolaf.edu/jmol/jsmol/iucrdemo/Jeopardy-theme-song.mp3". Playing audio clips can be disabled with SET allowAudio FALSE.

audio ID id "filename" action

Load and play an audio file. An optional ID identifies the clip for referencing (default "audio1"). Any running clip with this ID is stopped before playing begins, but other running clips with other IDs may continue playing. And optional additional action (see below, default START) is allowed, most likely LOOP or PAUSE.

audio ID id action

Carries out an action on a running audio clip. ID is optional and defaults to "audio1". Actions include

START starts an audio clip from the beginning
LOOP starts an audio clip and restarts the clip when it is done playing
PAUSE pauses an audio clip
PLAY plays an audio clip wherever it was last stopped
STOP stops an audio clip and resets it to the starting point
CLOSE stops an audio clip and releases its resources, including its ID

audio OFF

Stops and closes all audio clips and releases their resources.

See also:

undefined

top

index

echo

In Jmol, models can be annotated in one of three ways. Text can be associated with a specific atom using a label, text can appear when the user hovers the mouse over an atom or other user-defined point in space for a designated period of time (hover), and text can be placed at a specified position on the window (2D echo) or at a point in space (3D echo). In addition, the text is echoed in the Java console, the Jmol console, and the set messageCallback or set echoCallback function, if defined. Multi-line text can be generated using a vertical bar as a line separator.

See also the message command for variable-displaying capabilities that send information to the consoles and callback functions without displaying text. One can also place JPEG, PNG, or GIF images at either a 2D screen position or a 3D molecular position. See set echo for details.

echo "%SCALE (units)"

Same as SCALE (units)

echo (string)

Sends text to the console, callbacks, and, depending upon the setting of set echo, to a position in the Jmol window. Echos can contain variables such as @x. If in an echo is one that is displayed and the string contains a variable expression in quotes, such as set echo top center; echo "@{_modelNumber}", the echo is updated dynamically every time the screen is refreshed. Variable substitution can be prevented using \@ instead of @.

Examples: in new window using caffeine.xyz

set echo top left;font echo 20 serif bolditalic;color echo green
echo "I am green top left|20 serif bolditalic"
set echo myecho 350 150
echo this is|myecho; set echo myecho center
echo this|is|a|test
set echo myecho right
set echo myecho left
set echo top center
set echo top right
set echo top 70 320

top

index

frame or frames

See animation.htm

Sets the current frame or frame set. Numbers refer to the physical position of the model in the file or set of files (1 being the first). Same as the animation frame command. See also model. Note that you can show specific pairs or sets of frames or models by using frame all followed by display (*/n,*/m,*/p), where n, m, and p are frame numbers. See also set backgroundModel. For the applet, if AnimFrameCallback is enabled, a message indicating the frame change is sent to the associated JavaScript function. The simple command frame has no observable effect but forces an animFrameCallback message to be sent, which also serves to update the pop-up context menu. This is sometimes useful if scripting has changed something in the structure such as the addition of vibration vectors that would alter menu options .

frame (integer >= 1)

Go to a specific model in the case of loading a single file with multiple models. The number used here is the sequential index of the model in the file, starting with 1. If more than one file is loaded, the number indicates the file, and all models in that file are overlaid.

frame (positive decimal)

Go to a specific model in a specific file when one or more files are loaded. The format for specifying which model to go to is the same as for select or display: file.model. For example, frame 2.3 goes to the third model in the second file listed in the most recent load command. Note that atoms in models chosen with the frame command must also be in the current display set in order to be visible. So, for example, display 2.1;frame 2.2 will display nothing; display connected(hbond);frame 2.2 will display only the hydrogen-bonded atoms in model 2.2.

frame (decimal) - (decimal)

Sets the animation range and displays a range of models, possibly spanning multiple files. The hyphen is optional. If the hyphen is present but the second model number is missing, then all models from the designated model forward are assumed.

frame (negative decimal)

Using a negative decimal indicates that one of the linear morphs between trajectory frames is to be shown. Files must have been loaded using the TRAJECTORY option.

frame 0

Overlay all frames of the current frame range set. Note that this may not be all the models if the frame range has been set to a subset of the models or if multiple files are loaded and only models within one file have been specified with a previous frame command.

frame 0.0

Same as frame ALL.

frame [ array of model numbers ]

Sets the current frame set; same as anim frames [ ... ] followed by frame *. Ranges of frames can be written with hyphenes: [ 1-5 7-11]. The atom selector thisModel selects for atoms in the current frame set. Note that these models can be in any order.

frame {atomSet}

This syntax allows setting of a model by an atom set. The first atom in the set determines which model is displayed. For example, model {within(smarts,"[r3]")} would bring into frame the first model with a 3-membered ring.

frame "id"

Recalls a frame with the given ID assigned with the frame ID command option.

frame ALIGN [atom-expression]

Provides a way to align structures across a set of frames. This is important for certain animations. The atom expression is evaluated per frame, and the resultant point is aligned in each case.

frame ALIGN [atom-expression] FIXED

Addition of FIXED ensures that atom alignment continues even when multiple models are showing. Note, however, that in this first implementation, objects such as isosurfaces and drawn objects are not shifted (as they would be when TRUE is not present).

frame modelID ALIGN {x y z}

aligns a model at a specific coordinate rather than at an atom. TRUE is assumed; the same issues as above involving objects are the case here.

frame ALL

Resets the frame range to all models and overlays them.

frame CREATE (integer)

Creates one or more "empty" models. If no parameter is given, 1 is assumed.

frame ID "id"

Assigns an ID to a frame that can later be used to recall the frame using FRAME "xxx" where xxx is a frame ID.

frame LAST

Go to the last frame in the frame range set.

frame MO

Go to the first frame with a molecular orbital.

frame NEXT

Go to next frame in the frame range set.

frame PAUSE

Pause animation at the current frame.

frame PLAY (starting frame)

Start playing at the specified frame number (current frame if number is omitted). Direction, speed of play, and mode of animation (ONCE, LOOP, or PALINDROME) are set using animation mode.

frame PLAYREV (starting frame)

Start playing at the specified frame number (current frame if number is omitted), reversing the direction.

frame PREVIOUS

Go to previous frame in the current frame set.

frame RANGE (starting frame) (ending frame)

Sets the range of frames to play as an animation and sets the current frame to the first number given. If the starting frame number is larger than the ending frame number, then play is in reverse. If only one number is given, then the range is set from that frame through the last frame in the file. If both numbers are omitted, then the range is set to include all frames in the file.

frame RESUME

Resume playing from the current frame. (Same as PLAY.)

frame REWIND

Return to the first frame in the frame range set.

frame TITLE "title"

Sets a title for all frames currently visible, which appears in the bottom left corner of the applet or application. If the title includes an expression such as "@{_modelName}", then that expression is evaluated whenever the model is rendered (for example, when the frame is changed). To set all titles at once, first make all frames visible. with frame all, then issue the frame title command.

frame TITLE (array)

Sets the title for all visible frames at once using an array of strings. For example, this sequence might give each frame title that shows the minimum energy for the files, converting energies to kJ/mol in the process:

x = getproperty("modelinfo.models.energy")
y = x.sub(x.min).mul(2625.5) # relative energies, in kJ
frame *;frame title @y

Examples: in new window using cyclohexane_movie.xyz

model 1
model NEXT
model PREVIOUS
model 0;select *;wireframe 0.1;spacefill 0.2
anim on
model 0;select *;wireframe off;spacefill off;
select 1.1 # in Jmol10 use */1
wireframe 0.1;spacefill 0.2;color atoms red;
select 1.35;wireframe 0.1;spacefill 0.2;color atoms blue

See animation.htm

top

index

getProperty

The getProperty command sends information to the Jmol console or message callback function defined for a Jmol applet using the jmolSetCallback("messageCallback", funcName) function in Jmol.js or via the set command. Either a simple text string in the case of a file property or a valid JSON (JavaScript Object Notation) string in the case of a molecular property is returned. Such callbacks are asynchronous, meaning they do not return a value immediately. An alternative synchronous method for the applet is to use one of the JSmol built-in JavaScript commands Jmol.getPropertyAsArray(), Jmol.getPropertyAsString(), Jmol.getPropertyAsJSON(), or Jmol.getPropertyAsJavaObject(), all of which take three parameters: applet, infoType, and params. For example, in JavaScript:
var modelInfo = Jmol.getPropertyAsArray(jmolApplet0, "modelInfo") alert(modelInfo.modelCount) for (int i = 0; i < modelInfo.modelCount; i++) alert(modelInfo.models[i].name)
.

In addition, when using the Jmol application, see the note at show regarding setting the output to go directly into a file on your system.

This information is also available using the Jmol math getProperty() function.

getProperty animationInfo

Structure describing the current state of animation. See animationInfo.txt.

getProperty appletInfo

Structure describing the applet, including, for example, the applet version, compile date, Java version, and name of the applet object. See appletInfo.txt.

getProperty atomInfo [atom-expression]

Structure describing the atoms in the model. A second (optional) parameter specifies a subset of the atoms. The default is (visible). Parentheses are required. See atomInfo.txt.

getProperty auxiliaryInfo

Structure describing auxiliary information that is in the loaded file. This information is file-dependent and might include, for example, symmetry information, molecular orbital coefficients, dipole moments, partial charges, and/or vibrational modes. See auxiliaryInfo.txt.

getProperty bondInfo [atom-expression]

Structure describing the bonds in the model. A second (optional) parameter specifies a subset of the atoms that are involved in the bonds. The default is (visible). Parentheses are required. See bondInfo.txt.

getProperty boundBoxInfo

A simple JSON array containing the coordinates of the center and corner of the volume containing the molecule. See bondBoxInfo.txt.

getProperty centerInfo

A single JSON array giving the current center coordinate. See centerInfo.txt.

getProperty chainInfo [atom-expression]

Structure describing the chains in a biomodel (PDB or mmCIF, for example). Information for each residue of the chain is provided. A second (optional) parameter specifies a subset of the atoms. The default is (visible). Parentheses are required. See chainInfo.txt.

getProperty cifInfo filepath

The contents of a CIF file (or for the current file if no filepath parameter is given) in a structured data format. The corresponding getProperty("cifinfo",filename) function produces this result in a Jmol structure. For example:
print getProperty("cifinfo", "=ams/quartz").keys.all

models
models..45.name
models..45["_atom_site_fract_x"]
models..45["_atom_site_fract_y"]
models..45["_atom_site_fract_z"]
models..45["_atom_site_label"]
models..45["_atom_site_u_iso_or_equiv"]
models..45["_cell_angle_alpha"]
models..45["_cell_angle_beta"]
models..45["_cell_angle_gamma"]
models..45["_cell_length_a"]
models..45["_cell_length_b"]
models..45["_cell_length_c"]
models..45["_cell_volume"]
models..45["_chemical_compound_source"]
models..45["_chemical_formula_sum"]
models..45["_chemical_name_mineral"]
models..45["_database_code_amcsd"]
models..45["_exptl_crystal_density_diffrn"]
models..45["_journal_name_full"]
models..45["_journal_page_first"]
models..45["_journal_page_last"]
models..45["_journal_volume"]
models..45["_journal_year"]
models..45["_publ_author_name"]
models..45["_publ_section_title"]
models..45["_space_group_symop_operation_xyz"]
models..45["_symmetry_space_group_name_h-m"]

getProperty dataInfo type

Returns an array having four or six elements, depending upon whether the data are to be saved in the state of whether they are from file loading and unchanged:
[1] the exact-case name of the property
[2] the array of values
[3] a bitset indicating the associated atoms
[4] an integer used internally related to array depth
[5] (reserved)
[6] if from a file and unchanged, so need not be saved in the state, a string with length > 0. getProperty data TYPES or print getProperty("dataInfo", "TYPES") returns an array for which the first element is the string "types" and the second element is a comma-separated list of the available data name.

getProperty extractModel [atom-expression]

The extractModel keyword delivers text in the form of a MOL file, allowing up to 999 atoms and 999 bonds to be "extracted" from the model as an independent structure.

getProperty fileContents

The contents of the currently loaded file.

getProperty fileContents filepath

The contents of ANY file on the web or, if operating locally, any file on the hard drive in the directory containing the JAR file or any directory below that.

getProperty fileHeader

The file header for the file. This will depend upon the file format; some file formats may not have file headers.

getProperty fileName

The file name of the currently loaded file.

getProperty fileInfo type

An associative array of file information. For most files this is simply the file header lines. In the case of PDB files, this array associates PDB header information with its resource name. For example, getProperty fileInfo.SHEET reports SHEET information from the PDB header. In the case of CIF files, this information is the entire contents of the file in array format. (See also the function getProperty("fileInfo"), which allows direct access to file information as a Jmol variable. For example, x = getProperty("fileInfo.REMARK800").

getProperty image

A base-64 encoded JPEG suitable for writing by the applet to an image tag using a dataURI. For example, in JavaScript on the page using JSmol.min.js, with an applet named jmolApplet0: var img = new Image(); img.src="data:image/jpeg;base64," + Jmol.getPropertyAsString(jmolApplet0,"image");$("body").append(img) .

getProperty isosurfaceData

Returns information about an isosurface of getProperty isosurfaceInfo along with vertices, vertex values, and polygons.

getProperty isosurfaceInfo

Returns information about an isosurface, including haveQuads, haveValues, id, polygonCount, and vertexCount.

getProperty ligandInfo

Structure indicating ligand information, including and array of "ligands", each containing items "reslist", "atoms", and "groupNames".

getProperty measurementInfo

Structure describing the currently-defined measurements for the model, including the atoms involved, the measurement type, and the value of the measurement in decimal and in string formats. See measurementInfo.txt.

getProperty menu

A tab-separated string defining the current Jmol menu, including what options are currently enabled. See, for example, misc/menu.tab. See also show MENU.

getProperty minimizationInfo

A summary of the minimization that was carried out. See minimizationInfo.txt.

getProperty modelInfo

Structure describing each model in the loaded model collection. See modelInfo.txt.

getProperty modelkitInfo

Structure listing current modelkit properties.

getProperty moleculeInfo [atom-expression]

Structure describing each molecule (covalent set of atoms) in the model, including the number of atoms, the number of elements, and the molecular formula. A second (optional) parameter specifies a subset of the atoms. The default is (visible). Parentheses are required. See moleculeInfo.txt.

getProperty nmrinfo

Structure describing NMR calculation data including (a) a table of isotope masses (negative if these are default parameters for a nucleus), gyromagnetic ratio, and quadrapolar coupling constant, and (b) assigned shift references in PPM. See nmrInfo.txt.

getProperty orientationInfo

Structure describing the moveTo command required to return to the currently displayed orientation. See orientationInfo.txt.

getProperty polymerInfo [atom-expression]

Structure similar to chainInfo describing the residues in a biomodel. A second (optional) parameter specifies a subset of the atoms. The default is (visible). Parentheses are required. See polymerInfo.txt.

getProperty shapeInfo

Structure listing a small amount of information relating to shapes displayed with the model (molecular orbitals, isosurfaces, cartoons, rockents, dipoles, etc.) See shapeInfo.txt.

getProperty stateInfo

The same report as SHOW STATE; useful especiall as x = getProperty("stateInfo").

getProperty transformInfo

Structure representing the current transformation matrix describinng the current orientation of the model. See transformInfo.txt.

getProperty variableInfo (math expression)

Evaluates a variable. This option is most likely used in association with JavaScript. The JSmol API includes Jmol.evaluateVar(app,expr) where app is an applet object and expr is a string containing a Jmol math expression (anything that work with the print command). For example, "{atomno < 3}" or "at.join(af)".

top

index

hover

Turns on and off pop-up labels that appear when the user "hovers" the mouse over the atom or a point associated with a draw object. hover off disables the hover message; hover on enables it again. Any other parameter or string is used as the label, which can contain atom property fields such as %a or %U and will apply to all atoms in the model. To set a specific hover label for one atom, select the atom(s) and then use set hoverLabel. To change the delay time prior to the label appearing, use set hoverDelay x.x where x.x is the delay time in seconds. Setting this time to 0.001 seconds effectively makes the hover label appear immediately. See also label. Multiple lines can be indicated using | (vertical bar). Even with hover OFF, the hover message can be sent to a JavaScript function on the applet's page using set hoverCallback.

top

index

message

Sends a string of text to the messageCallback function (for the applet). The set MessageCallback command can be used to set this JavaScript function. The message is also entered into the scriptStatus queue. Variable values and math expressions can be included in messages and echos. These use the following syntax: message my variable = @{variablename}, provided a variable with that name exits. Note that the braces are required -- message my variable = @x will simply deliver "my variable = @x". The @{...} syntax is also supported in this context: message the fraction 3 / 2 is @{ 3.0 / 2 }. Basically, any expression that can appear in a print command can appear in @{...} in a message or echo. For example: message @{ {_N and connected(2,_H)}.size } NH2 groups are present. Since the Jmol application can be run "headless" -- with no display -- using the -ions set of flags, you can use a designed message command to deliver model information to other programs, however the print command has a simpler syntax and is more flexible.

message (string)

top

index

PRINT

Note: The PRINT command does not require @{ ... } around Jmol math expressions.

Prints a Jmol math expression to the console window, status message callback function, and Jmol.scriptWait return value. By itself, print clears the JavaScript and Jmol consoles.

print {default: 1.1}.find(SMILES,MF)

Determines the molecular formula based on a SMILES string from the atomset.

print {default: 1.1}.find(SMILES,MF, true)

Determines the empirical formula based on a SMILES string from the atomset.

print CCCC.find(SMILES,MF)

Determines molecular formula of a SMILES string.

print CCCC.find(SMILES,MF, true)

Determines the empirical formula of a SMILES string.

top

index

select

Note: The select command does not require { ... } around Jmol atom expressions.

See select.htm

Selects the atoms identified by the expression. If no expression is given then all atoms are selected. The optional parameters ADD and REMOVE prior to the atom expression allow quick alternatives to "selected or..." and "selected and not...", respectively. In addition, the keyword GROUP prior to the atom expression provides a quick alternative to "within(group, ...)".

select (comma) ...

If the first parameter of a SELECT command is a comma and selectCallback has been set, fires selectCallback immediately rather than after script is completed.

Examples: in new window using 1a3n.pdb

select carbon;color white
select protein;ribbons on
select *:D;color blue
select [HIS]:D;spacefill 300
select [HIS]92:D.N;spacefill 600
select [HIS]92:D.C?;color orange
select [HIS]92.N;color [255,196,196]
select elemno<7;spacefill 200
select within(group, within(10.0, :a));color green;select :a;color red
select within(chain, [HIS]92);color white;
select within(chain, within(3.0,[HIS]92:D));color purple;
select within(chain,within(5.0,[HIS]92));color white
select 95^a:L # selects chain L, residue 95, insertion code a

See select.htm

See also:

display hide restrict subset undefined

top

index

set (callback)

Jmol allows for dynamic JavaScript callback function definition. You can specify the functions to receive callbacks, and you can change the functions at any time. Specific parameters sent to these functions are discussed more fully at http://jmol.sourceforge.net/jslibrary/#jmolSetCallback. To turn off callbacks of a given type, specify "NONE". The function name must be present in JavaScript on the page containing the applet. Specifying "alert" will send the message to the user via a JavaScript alert. Note that quotation marks are required around the function name. If the filename starts with "jmolscript:" then instead of JavaScript being run, Jmol executes the Jmol script that follows. For example, set hoverCallback "jmolscript:script hover.spt" executes the Jmol script "script hover.spt" when an atom is hovered over. The code in the file hover.spt can then respond to that hovering action without the need for JavaScript.

set AnimFrameCallback "function name"

Sends a message indicating a change of frame. For compatibility with Chime, the second parameter of this function returns a number ONE LESS than the actual frame number. This function returns nine parameters. The product of the last two parameters indicates the true direction of animation.

function animFrameCallback(app, frameNo, fileNo, modelNo, firstNo, lastNo, isAnimationRunning, animationDirection, currentDirection)

app String The name of the applet
frameNo int The current frame number (0-based)
fileNo int The current file number (1-based)
modelNo int The current model number within the current file (1-based)
firstNo int The first frame of the animation range, expressed as fileNo*1000000+modelNo
lastNo int The last frame of the animation range, expressed as fileNo*1000000+modelNo
isAnimationRunning int 0 (animation is off) or 1 (animation is on)
animationDirection int 1 (animation direction +1) or -1 (animation direction -1)
currentDirection int 1 (forward) or -1 (reverse)

set EchoCallback "function name"

Sends a message each time the echo command is executed. If an EchoCallback function is not defined, these messages go to the MessageCallback function.

set EvalCallback

Generally the Jmol applet is allowed to use the eval() function of the host page JavaScript using the javascript command (unless execution of JavaScript by the applet has been specifically disallowed by setting Info.allowJavaScript = false for the Info structure used when creating the applet). The setting of evalCallback function must be made prior to jmolAppletCall() using jmolSetCallback("evalCallback","someFunctionName"). It cannot be set using set evalCallback. The callback sends the JavaScript to be evaluated back to the web page for evaluation rather than initiating that evaluation within Jmol. This could be important for the signed applet in order to isolate threads or for debugging applet calls to eval(). It is used in http://chemapps.stolaf.edu/pe/protexpl.

set AtomMovedCallback "function name"

Sends a message indicating what atoms have been moved.

set AudioCallback "function name"

Called when an {#.audio} clip event occurs. The second parameter is a map containing information about the clip, including its id; the third parameter is its status as a single word. status firing depends upon various factors and may be unpredictable in indicating completion. (Java may report "pause" for both an actual pause and a termination, possibly not releasing resources)

set HoverCallback "function name"

Sends a message indicating what atoms is being hovered over, independently of whether hover is ON or OFF.

set LoadStructCallback "function name"

Sends a message each time a file is loaded.

set MeasureCallback "function name"

Sends a message indicating the status of measurements made by the user. If a MeasureCallback function is not defined, these messages go to the MessageCallback function.

set MessageCallback "function name"

Sends a wide variety of messages during script execution.

set MinimizationCallback "function name"

Sends a message that indicates the status of a currently running minimization.

set ModelkitCallback "function name"

Sends a message that indicates the status ("ON" or "OFF") of the model kit anytime that status is changed.

set PickCallback "function name"

Sends a message that depends upon the current status of set picking.

set ResizeCallback "function name"

Sends a message indicating changes of the window size.

set ScriptCallback "function name"

Sends messages indicating the status of script execution. Line-by-line script commands are sent if one has set debugScript TRUE. If a ScriptCallback function is not defined, these messages go to the MessageCallback function.

set SelectCallback "function name"

Sends a message indicating that a selection has been made.

set StructureModifiedCallback "function name"

Sends a message each time a structure is modified. Parameters include mode, atomIndex and modelIndex, where mode is one of:
1 assignAtom element/charge change start
-1 assignAtom element/charge change end
2 assignBond start
-2 assignBond end
3 assignAtom position start
-3 assignAtom position end
4 delete atom begin
-4 delete atom end
5 delete model begin
-5 delete model end

set SyncCallback "function name"

The SyncCallback method allows a JavaScript function to intercept and modify or cancel an applet-applet sync message. If the called function returns "" or 0, the synchronization is canceled; any other string is substituted for the script and sent to the other currently synchronized applets. For example, the following script sets atom color by proximity to the user:
set syncmouse sync on set synccallback "jmolscript:color atoms property sz"

See also:

getProperty javascript script undefined

variables

top

index

set (debugging)

set debugScript OFF

Turning this parameter ON enables debugging (going to a JavaScript message callback).

set scriptReportingLevel (integer)

Sets the maximum script depth (how many scripts have been called) for which certain messages should appear in the console and be reported back via callbacks. A value of 0 (default) displays messages only from the topmost level -- as, for example, commands entered from the console; a value of 1 displays messages from the top level and messages due to commands such as "script t.spt" but not from scripts that are called from t.spt; etc. A value of -1 turns off all reporting. Affected commands include connect, select (and related commands), and set. This parameter is particularly useful when scripts utilize message/goto to control program flow.

variables

top

index

set (misc)

In all cases below, "ON" and "TRUE" are equivalent, and "OFF" and "FALSE" are equivalent.

set bondPicking FALSE

Setting this parameter TRUE allows picking of bonds. If pickCallback is enabled, a message is sent to the callback function providing detailed information about the bond that was picked. See also set atomPicking and set drawPicking.

set drawPicking OFF

When ON, Jmol reports picking of points associated with draw objects to the console, the messageCallback function, and the pickCallback function. In addition, setting drawPicking true enables measurement of distances and angles involving drawn objects such as points, lines, arrows, and planes. Measurements of this type only appear transiently; they are not saved. See also set atomPicking and set bondPicking.

set messageStyleChime FALSE

Changes the style of message reporting by script callbacks to one similar to Chime.

set pickLabel (string)

Sets the format of the message sent to the console and callback functions when an atom is clicked.

variables

top

index

set echo

Sets positioning and visibility parameters associated with text written to the screen using the echo command. In all set echo commands, an optional id may be given. If this id is not given, the previously indicated id is assumed. set echo IMAGE allows images to be displayed instead of text. Characteristics of the text that are settable include:
background color Includes translucency. See background ECHO.
depth The default Z-position for echoed text and images is in front of the model. However, this can be set to any depth in relation to the model, from 0 (rear) to 100 (front). See below.
font color Includes translucency. See color ECHO.
font size, face, style, and scaling factor See font ECHO.
ID "xxx" The optional ID keyword introduces an echo ID that is in quotes or from evaluation, such as set echo ID @{"test" + i} in order to distinguish it from echo text, which would be indicated with set echo "text here". Three special echo IDs, TOP, MIDDLE, and BOTTOM are defined for quick placement of text. These three special echos are always defined along with one of three predefined positions and text alignments: LEFT, CENTER, or RIGHT. Thus we have set echo TOP LEFT, set echo TOP RIGHT, etc. Note that you cannot have two separate echos both with the ID TOP. Thus, after set echo top left;echo OK, if you issue set echo top right, the text "OK" originally in the top left corner will jump to the top right corner. Note that TOP is an echo label, not an echo position. If you need two echos, one on the top left and one on the top right, it is best to use your own label id -- set echo myTopLeft 0 100%; echo "on the left"; set echo myTopRight 100% 100%; echo "on the right". The difference in this case between set echo TOP RIGHT and set echo myTopRight 100% 100% is that in the latter case, if you want to right-align multi-line text, you also need to issue set echo myTopRight right. With set echo TOP RIGHT, the text is both positioned on the right and right-aligned.
IMAGE You can also place JPEG, PNG, or GIF images at either a 2D screen position or a 3D molecular position. See below.
model Echo text can be associated with a specific model, with visibility controlled by the frame command. See below.
scaling Using the command set fontScaling TRUE 3D-positioned images and text along with atom labels can be made to scale when zoom is applied. The current zoom setting is used to fix a "scaling factor" used for the font. However the font command can be used to set a different reference scaling factor. The absolute scale of an image independent of this 3D zoom scaling, can be set using set echo scale, below.
text alignment Text in echos is generally left-aligned. You can use set echo myecho CENTER to center text at the given position of that echo or set echo myecho RIGHT to have it right-aligned. Use set echo myecho LEFT to return the text to the default left alignment. Note that the special echo IDs TOP, MIDDLE, and BOTTOM are automatically text-aligned based on their required horizontal postion keyword -- LEFT, RIGHT, or CENTER. If you need center-aligned text that is positioned in the top right corner, for example, use your own ID: set echo myecho 100% 100%;set echo myecho CENTER. Set echo myecho CENTER also aligns multi-line text and images vertically.
visibility Echos are deleted using set echco off. However, you can selectively display or hide echos using either the set echo HIDDEN/DISPLAYED command or the hide and display commands with $name, where name is the name given an echo in the set echo command (including the special echos TOP, MIDDLE, and BOTTOM using $top, $middle, and $bottom, respectively).
x and y position within the window A "2D" echo. A block of text can be displayed anywhere within the applet or application window. An automatic adjustment is made to prevent text from going outside of the bounds of the window. See below.
x, y, and z position within the model itself A 3D echo. This position can be defined as a point in space, the coordinate of an atom, the average coordinate of a set of atoms, the position of a drawn point, or the average position of a drawn object. See below.

Default settings for font, color, and background can be set by first issuing set echo none, so that no real echo is set, and then issuing the desired font, color, and background commands. In addition, any changes to these settings for any specific echo text become the new default for future text echos that are created for the same model.

set echo NONE

Sets the current echo to be "none" -- The next echo command will be to the console/message callback only. After this command, set echo off will still delete all echos.

variables

top

index

set picking

The set picking command determines the response to clicking of atoms by the user. For those options for which they apply, the keywords MEASURE and SELECT are optional.

set picking ON

Setting this paramter OFF turns off the sending of picking information (atom identifier, atom number, and atomic position) to both to the status line and to the PickCallback function, if defined.

set picking DRAW

The vertices of all draw objects are highlighted. Holding the SHIFT key down while dragging moves the object to a new location ("shifts" the object); holding ALT down while dragging moves a single vertex to a new location ("alters" the shape of the object). The draw command required to reproduce the object can be seen immediately using the Java console. This new command can also be seen via message callback, or in the Jmol console using show DRAW.

set picking MEASURE DISTANCE

Turns picking on and returns atom identities and distance between two atoms. Three messages are sent to the MessageCallback function, if defined: Atom #1 (after the first click) and then Atom #2 and Distance (after the second click).

Examples:

(pdb data in this case)
Atom #1:[VAL]8.CA #49
Atom #2:[GLU]23.OE2 #169
Distance [VAL]8.CA #49 - [GLU]23.OE2 #19 : 16.765396

set picking MEASURE ANGLE

Turns picking on and returns atom identities and angle involving three atoms. Four messages are sent to the MessageCallback function, if defined: Atom #1 (after the first click), Atom #2 (after the second click), and then Atom #3 and Angle (after the third click).

Examples:

(xyz data in this case)
Atom #1:C 2 #2
Atom #2:C 3 #3
Atom #3:C 4 #4
Angle C 2 #2 - C 3 #3 - C 4 #4 : 122.3754

set picking MEASURE TORSION

Turns picking on and returns atom identities and torsion angle (dihedral angle) involving four atoms. Five messages are sent to the MessageCallback function, if defined: Atom #1 (after the first click), Atom #2 (after the second click), Atom #3 (after the third click), and then Atom#4 and Torsion (after the fourth click).

Examples:

(cml data in this case)
Atom #1:a7 #7
Atom #2:a3 #3
Atom #3:a1 #1
Atom #4:a2 #2
Torsion a7 #7 - a3 #3 - a1 #1 - a2 #2 : -4.15209

top

index

show

show sends information about the model to the MessageCallback function and to the Java or Jmol console. If using the application, using Jmol -ionx filename.spt modelfile.xyz > output.txt, you can put a show command in a script file (filename.spt), and have the output directed to output.txt. The command line options used in this example include -i (silent startup), -o (use standard output), -n (no display), -x (exit after running the specified script file). All of the parameters that can be set can be shown. They are not listed here. Adding "/xxxx" to the command, such as SHOW file/cell will filter the output only to lines containing the text after the slash character. Adding "/!xxxx" to the command, such as SHOW file/!cell will filter the output only to lines NOT containing the text after the slash character.

show ATOM

Lists the atom numbers that are currently selected in the order of atom index; duplicates are not listed twice.

show BEST ROTATION

Operates on the currently selected atoms, reporting a quarternion that would rotate them to their best orientation for viewing.

show BEST BOX

Operates on the currently selected atoms, reporting the volume and dimensions of the best box that would contain the selected atoms.

show BOUNDBOX

Delivers the coordinates of the center coordinate and a directional vector defining a box just perfectly enclosing the model. The vector is determined by taking the min and max values for the atom along each cartesian axis. The center is the geometric center of the model, not the default center of rotation (which is the mean atom position). The eight corners of the boundbox are found by adding the center point to the vector, with all possible combinations of +/- component cectors. The length of a side of the boundbox is determined by doubling the appropriate component of the vector. So, for example, the length of the boundbox along the x-axis is (2*vectorX). Units are in Angstroms. Output is in the form
boundbox: (centerX, centerY, centerZ) (vectorX, vectorY, vectorZ)

show CACHE

Lists the contents of the cache.

show CENTER

Delivers the coordinates of the center of the model. Units are in Angstroms. Output is in the form
center: (centerX, centerY, centerZ)

show CHAIN

Lists the chains (A, B, C, etc.) of the atoms that are currently selected in the order of atom index; duplicates are not listed twice.

show CHEMICAL [option]

Displays a property of the selected atoms depending upon the selected file type option obtained from the NIH Catus server. These include: alc ,cdxml, cerius, charmm, cif, cml, ctx, gjf, gromacs, hyperchem, jme, maestro, mol, mol2, sybyl2, mrv, pdb, sdf, sdf3000, sln, and xyz. In addition to these, the SHOW command also allows for show SMILES (created by Jmol) and show DRAWING (same as show CHEMICAL IMAGE).
cas CAS Registry Number
chemspider_id ChemSpider ID
ficts FICTS Identifier
ficus FICuS Identifier
formula Chemical Formula
effective_rotor_count Number of Effectively Rotatable Bonds
hashisy Cactvs HASHISY
h_bond_donor_count Number of Hydrogen Bond Donors
h_bond_acceptor_count Number of Hydrogen Bond Acceptors
h_bond_center_count Number of Hydrogen Bond Acceptors and Donors
image GIF Image
inchi standard InChI string
inchikey standard InChI key
iupac_name IUPAC Name
mw Molecular Weight
name the first name of the compound found in the NIH database
names list of known names of the compound, if found in the NIH database
ring_count Number of Rings
ringsys_count Number of Ring Systems
rotor_count Number of Freely Rotatable Bonds
rule_of_5_violation_count Number of Rule of 5 Violations
smiles SMILES
uuuuu uuuuu Identifier

show COLORSCHEME "name"

Displays the list of colors comprising a color scheme, where "name" is, for example, "roygb", "rwb", or "user", "byElement_Jmol", "byElement_Rasmol", "byResidue_Shapely" (cooresponding to color shapely), and "byResidue_Amino" (corresponding to color amino).

show DATA "type"

Displays the most recently read data of the given type. See also getProperty data.

show DOMAINS

Shows domain annotations that have been loaded from RCSB or PDBe with the /dom option. For example,

load =1crn/dom;show domains SCOP
1crn SCOP 57430 identifier=Crambin-like
1crn SCOP 57430 fold description=Crambin-like
1crn SCOP 57430 fold sunid=57428
1crn SCOP 57430 description=Crambin-like
1crn SCOP 57430 class description=Small proteins
1crn SCOP 57430 class sunid=56992
1crn SCOP 57430 superfamily description=Crambin-like
1crn SCOP 57430 superfamily sunid=57429

show DRAW

Displays the command required to generate the current draw object. Particularly useful after using set picking DRAW.

show DRAWING

Displays a drawing of the Jmol structure in a new browser window.

show DSSP

Displays a DSSP secondary structure analysis report, which includes regions of three kinds of helix (3/10, alpha, and pi), turns, sheets, and bridge groups (DSSP codes G, H, I, T, E, and B, respectively). Bends (DSSP "S") are not included. This report can be sent to a file using, for example: var x = script("show DSSP");write var x "dsspReport.txt".

show FILE

Delivers the entire contents of the file for the current model.

show FILE filepath

Delivers the entire contents of the specified file on the server from which the applet was loaded. The filename must be relative to the current page (not necessarily the directory containing the applet) and must be enclosed in quotation marks. If the file is in ZIP format -- JAR, ZIP, JMOL -- or contains ZIP data (PNGJ), only a directory of the contained files is reported.

show ISOSURFACE

Displays the JVXL file equivalent. (Not available for all object types.)

show FUNCTIONS

Lists all user-defined functions.

show GROUP

Lists the groups (ALA, VAL, etc.) of the atoms that are currently selected in the order of atom index; duplicates are not listed twice.

show HISTORY n

Shows n lines of command history. If no number is given, show history by itself shows the full set of recorded command lines (100 maximum by default, but this maximum can be changed using the set history command. History recording can be turned on and off using the history command.

show INCHI

Calculates the InChI for the currently selected atoms. For example:

load files "$caffeine" "$tylenol"
select 1.1; show inchi
InChI=1S/C8H10N4O2/c1-10-4-9-6-5(10)7(13)12(3)8(14)11(6)2/h4H,1-3H3

select 2.1; show inchi
InChI=1S/C8H9NO2/c1-6(10)9-7-2-4-8(11)5-3-7/h2-5,11H,1H3,(H,9,10)

show LIGHTING

Displays lighting details, including ambientPercent, diffusePercent, specular, specularPercent, specularPower, specularExponent, and zShade

show MEASUREMENTS

Displays a table of information relating to measurements that have been made.

show MENU

Displays the current Jmol menu in a format that can be loaded using load MENU.

show MINIMIZATION

Displays a detailed report regarding minimization parameters used for the most recent minimization.

show MO

Displays the JVXL file equivalent for the current molecular orbital. If no MO is currently shown, displays the JVXL equivalent for the entire set of molecular orbitals. (This can take some time to construct.)

show MODEL

Delivers properties associated with the currently loaded model. Output includes information about all of the models in the set. This command is still in development. The exact form and content of the output is subject to change (and suggestion).

show MOVETO

Same as show orientation moveto

show NMR

Links to http://www.nmrdb.org/predictor (or whatever URL is indicated in set nmrUrlFormat using the SMILES string of the selected atoms.

show ORIENTATION [optional type]

Delivers the orientation of the model. Output consists of both a "moveTo" command and an alternative sequence of "reset; rotate z; rotate y; rotate z" commands that would result in the current orientation. Thus, this command allows reading and restoring specific user-specified orientations. Optional types include:
moveto the moveto command leading to this orientation, with no comments
rotation the current rotation, as a quaternion
translation the current translation in percent X and percent Y from center of the window

show PDBHEADER

Delivers the PDB file header.

show POINTGROUP

Displays a table summarizing the point group of a symmetrical or nearly symmetrical model. See calculate pointgroup for details of this calculation.

show POINTGROUP POLYHEDRON

Displays a table summarizing the point group of a selected polyhedron. One atom (one polyhedron) should be selected prior to this command.

show PROPERTIES (list) FORMAT %s %i ...

Displays a list of up to three atom properties, optionally along with atom name and index. For example, show properties x y z tabulates just x, y, and z coordinate values. Adding a format allows rounding and formatting as for labels. Two special formats, %s and %i, add atom name and index, respectively. For example, show properties x y z FORMAT "%s %i %10.6f %10.6f %10.6f". The corresponding WRITE command puts these into a file.

show RESIDUES

Reports a listing of currently selected residues:
[GLY]1:A[ARG]2:A
[ARG]3:A
[ILE]4:A
[GLN]5:A
[GLY]6:A
[GLN]7:A
[ARG]8:A
[ARG]9:A
[GLY]10:A
[ARG]11:A
[GLY]12:A

show ROTATION

Same as show orientation rotation

show SELECTED

Lists the default label for all selected atoms, in the order of atom index.

show SEQUENCE

Reports the sequence of the currently selected residues in the following format:

Model 1
Chain A:
[GLY]1 [ARG]2 [ARG]3 [ILE]4 [GLN]5 
[GLY]6 [GLN]7 [ARG]8 [ARG]9 [GLY]10 
[ARG]11 [GLY]12 [THR]13 [SER]14 [THR]15 
[PHE]16 [ARG]17 [ALA]18 [PRO]19 [SER]20 
[HIS]21 [ARG]22 [TYR]23 [LYS]24 [ALA]25 
[ASP]26 [LEU]27 [GLU]28 [HIS]29 [ARG]30 
[LYS]31 [VAL]32 [GLU]33 [ASP]34 [GLY]35 
[ASP]36 [VAL]37

show SET

Delivers a list of all "set" commands that have been issued, with their values.

show SMILES /directive

Delivers a SMILES string for the selected atoms. Optional directives include /strict, /open, and /nci.

show SPACEGROUP "name"

Displays information relating to crystallographic space groups. If a file with crystallographic symmetry is loaded, show spacegroup by itself displays information for that spacegroup. Quotes are required around the space group name. If the name itself includes double quotes, use two single quotes instead. For example: P 32 2", not P 32 2" or surround the name with single quotes.

show SPACEGROUP TABLE

Displays space group tables from the Bilbao Crystallographic Server the user's browser. Optional group may be a space group name or number; default is to use the current space group; example: show spacegroup table; show spacegroup table 13; show spacegroup table P2/c.

show STATE [optional name]

Delivers a Jmol script that, when run, will regenerate the state of the Jmol applet or application. The following objects are not yet supported: dipole, isosurface, lcaoCartoon, mo. If a name is given, then the state saved with that name is used; if no name is given, the state described is the current state.

show STATE /xxx

Shows only the lines from the current state that contain the specified phrase "xxx"

show STATE FILE "fileName"

Delivers the Jmol state embedded in an image file of the format PNG or JPG created by Jmol (and thus containing the string "**** Jmol Embedded Script ****").

show SYMOP (integer)

Describes the specified symmetry operation. For example, show symop 3 might give "-y,x-y,z-1/3 3-fold screw axis|translation: 0 0 -1/3". If no integer is given, this command delivers the full list of symmetry operations for the current frame. Starting with Jmol 14.2, an optional additional flag "fmatrix" reports the symmetry operation as a matrix rather than in Jones-Faithful notation.

show SYMOP [atom-expression-or-coordinate] [atom-expression-or-coordinate]

Describes the symmetry operation relating the two specified points. (If an atom set is given, only the average position of the coordinates is used.) For example, show symop {molecule=1} {molecule=2} might give "3 -y,x-y,z-1/3 3-fold screw axis|translation: 0 0 -1/3". If more than one symmetry operation relates the positions, then all are described. Starting with Jmol 14.2, an optional additional flag "fmatrix" reports the symmetry operation as a matrix rather than in Jones-Faithful notation.

show SYMOP (integer) {atom expression} {atom expression}

Shows the symmetry relation associated with the specified symmetry operator between any two atoms or groups or any two positions in space. For example, load =ams/quartz 1 packed;show symop 2 @1 @3.

show SYMOP {atom expression} {atom expression} (integer)

Shows the nth symmetry operator for special positions, where multiple symmetry operations relate two positions in space. For example, load =ams/quartz 1 packed;show symop @1 @3 1.

show SYMOP [matrix]

Shows the symmetry operation associated with the given 4x4 matrix, which most likely comes from a variable, for example here the symmetry operation that is the product of two other symmetry operations: show SYMOP @{symop(11)*symop(14)}.

show SYMMETRY

Displays information relating to the crystallographic symmetry of the model, including space group name and symmetry operations. (Applicable file formats only.)

show TIMEOUT

Lists all pending timeouts.

show TRACE

Reports a trace of function and script calls leading to the current command.

show TRANSFORM

Delivers the current 3x3 transformation matrix (rotation only).

show TRANSLATION

Same as show orientation translation

show UNDO

Reports if undoAuto is true or false, and if it is false, reports the sizes of the user UNDO and REDO stacks.

show UNITCELL

Displays information relating to the crystallographic unit cell of the model. (Applicable file formats only.)

show URL

Opens the data file in a new browser window. (applet only)

show URL URL

Opens the specified URL in a new browser window. (applet only)

show VALIDATION

Shows validation annotations that are available as properties, having been loaded from RCSB or PDBe with the /val option. For example,

load *1crn/val; show validation
Validations loaded:
property_types_of_outliers (residues: 3)
property_bond_lengths (atoms: 2, max: 5.38)
property_bond_angles (atoms: 6, max: 7.83)

show VARIABLES

Reports a listing of all variables and their values.

show ZOOM

Delivers the current zoom setting. Output is in the form of the zoom command: "zoom n" where "n" is an integer percent of "normal" zoom.

show $objectID

For draw objects, displays the command that can be used to generate that object. For isosurface objects, displays the JVXL file equivalent. The $ is required. (Not available for all object types.)

top

index

THROW

Note: The THROW command does not require @{ ... } around Jmol math expressions.

The throw command initiates a user-defined error condition that either stops processsing or, when within a try/catch syntax, is caught and handled at another point in the script.

throw CONTEXT contextName

The throw CONTEXT form of the throw command allows an unusual form of asynchronous processing that is unlike anything in Java or JavaScript. The command replaces pause and resume, now deprecated. The command throws a catchable error, but in the process of doing so, creates a script context that allows RESUMING the process at the point of the throw. If within a try/catch phrase, throw CONTEXT contextName is handled by the catch, in which case the variable thrown_value is just the string contextName (and @thrown_value will be the context itself, in the form of an associative array).

More interesting, though, is when the throw is not within a try/catch phrase, in which case Jmol reports to the console:

  to restore the context, enter: &contextName

This essentially provides a callback into the running (though interrupted) script. So you could, for example, put a running script "on hold" while you load a file or check or modify variables, and then continue where it left off.

Resuming the process at the point of the throw is carried using restore CONTEXT contextName or just & followed by the name of the context:

  throw context test
  ...
  &test

The current context returns to the highest level, out of all for or while loops or function calls. However, the variables in the context that was thrown are accessible as though the contextName variable were an associative array. So, for example, if we have

  function f(a, b, c) {
    var x = 5
    throw context testing
    print "x=" + x
  }

  f(1,2,3)
  print "done"

The context will be saved as the variable "testing", which takes the form of an associative array with keys that are lower-case names of all variables defined for this context (using VAR). We can then test all the variables in that saved context and even change them before continuing:

  print testing["x"]

  5

  testing["x"]++
  print testing

  _path  :  [script] >> function f
  _retval  :  0
  a  :  2
  b  :  2
  c  :  3
  x  :  6

If we were then to issue

  &testing

we would get the report:

  x=6
  done

Note that contexts can be restored any number of times. The variables will be whatever values they were left at in the previous time through the process (not necessarily their original values.)

Note also that resuming contexts within functions that return a value, for example, in the function myfunc within

  x = a + myfunc(a,b,c) + c

will not return to complete the assignment. Instead, the process will continue at the next statement in the script, and the assignment will be ignored. If this sort of functionality is desired, it is recommended that arguments be passed by reference, as arrays:

  x = [ ]
  myfunc(a,b,c,x) // fills in x[1] rather than returning a value
  x = a + x[1] + c

then works as expected.