Difference between revisions of "Scripting"

From Jmol
Jump to navigation Jump to search
(Bob's new URL)
(RasMol commands not accepted by Jmol)
 
(17 intermediate revisions by 5 users not shown)
Line 1: Line 1:
== Jmol Scripting ==
+
{{Jmol_Documentation_Sections}}
 +
__TOC__
 +
 
 +
The Jmol [[Jmol_Application|Application]] and [[Jmol_Applet|Applet]] have a '''command language''' that grew on the base of the [http://www.mdl.com/support/developer/chime/developer_tools.jsp command language] of [http://www.umass.edu/microbio/rasmol/index2.htm RasMol] and its browser plugin [http://www.mdl.com/ MDL Chime]. A set of commands is called a '''''command script''''', and writing such sets of commands or scripts is called '''''scripting'''''. This is the major way of controlling the display of molecules in Jmol.
 +
 
 +
= Documentation links =
  
 
'''Documentation of Jmol's scripting language can be found here:'''
 
'''Documentation of Jmol's scripting language can be found here:'''
* http://www.stolaf.edu/academics/chemapps/jmol/
+
* {{ScriptingDoc}}
 +
This is the official document. The style is encyclopedic, explaining each command in turn, as usual in reference manuals.
 +
In addition to this primary site, with latest updates, there are some mirror sites (see links at right).
  
 
'''An introduction to Jmol scripting is available here:'''
 
'''An introduction to Jmol scripting is available here:'''
* http://www.clunet.edu/BioDev/omm/scripting/molmast.htm
+
* http://www.callutheran.edu/Academic_Programs/Departments/BioDev/omm/scripting/molmast.htm
 
+
A more user-friendly, but less thorough, basic guide by Nathan Silva and David Marcey; part of the Online Macromolecular Museum at California Lutheran University.
The following pages are read only versions of the online documentation webpage. Don't edit them; they are autogenerated. But comments are welcomed:
 
* JmolScriptHelp
 
* ScriptAnimationoranim
 
 
 
The Jmol [[Jmol_Application|Application]] and [[Jmol_Applet|Applet]] have a command language that closely resembles the [http://www.mdl.com/support/developer/chime/developer_tools.jsp command language] of the browser plugin [http://www.mdl.com/ MDL Chime]. A set of commands is called a ''command script'', and writing such sets of commands or scripts is called ''scripting''.
 
 
 
Chime's command language (see "About Chime" at http://molviz.org) is a superset of the [http://www.umass.edu/microbio/rasmol/getras.htm#rasmanual command language] of Roger Sayle's public domain application [http://www.umass.edu/microbio/rasmol/index2.htm RasMol]. (The command language of [http://www.rasmol.org/ open-source RasMol] has diverged somewhat from that in RasMol and Chime).
 
 
 
== CONNECT implementation ==
 
 
 
10.00.49 will have the following implementation: (Bob Hanson [mailto:hansonr@stolaf.edu hansonr@stolaf.edu])
 
 
 
select (atom expression)
 
connect <min distance> <max distance> <option STATIC> <bond type> (target atom expression)
 
 
where <bond type> includes SINGLE, DOUBLE, TRIPLE, AROMATIC, HBOND, DELETE
 
 
 
properties:
 
* Bonds that are already made are revised.
 
* Bonds are introduced exactly as desired, not just as single bonds.
 
* Actions are independent of the setting of BONDMODE
 
 
 
rationale/comments:
 
# You can be as specific as you want in selecting the atom sets and now the distance range, so that suggests to me that there should be no surprises. The command does just what it says and not "connect-unless-not-already-connected."
 
# It needs no dependency upon BONDMODE because the distance ranges -- that typically really do define bond order -- are the determining factors.
 
# It is also more flexible than using BONDMODE, because now we have a specific starting set and a target set between which bonds will be built or removed.
 
# The STATIC parameter indicates to only operate on atoms that are already connected.
 
 
 
examples:
 
  
select (carbon)
+
'''Other'''
connect 1.3 1.5 DOUBLE (oxygen)
+
* Scripts can be included inside the molecular model file. See [[File_formats/Scripting#Script_inline_within_a_molecular_coordinates_file|how to do it]].
connect 1.5 1.7 SINGLE (oxygen)
+
* Jmol scripting language has grown, among other features, by adding mathematical operators (''JmolMath''), control structures (loops, conditionals, etc.). You may be interested in this [[Scripting/Programming_Language|programming language]] approach.
connect 1.7 1.9 DELETE (oxygen)
 
 
connect STATIC DOUBLE (oxygen)
 
  
SEE THE EXAMPLE AT http://www.stolaf.edu/people/hansonr/jmol/test/json/connect.htm
+
= Similar but different scripting languages =
  
== BONDORDER implementation ==
+
Chime's command language (see "About Chime" at http://molviz.org) is a superset of the [http://www.umass.edu/microbio/rasmol/getras.htm#rasmanual command language] of Roger Sayle's public domain application [http://www.umass.edu/microbio/rasmol/index2.htm RasMol]. (The command language of [http://www.rasmol.org/ open-source RasMol] has diverged somewhat from that in RasMol and Chime). The command language used by Jmol started with most of the Chime commands, but has outgrown it in a notable extent, allowing for many new capabilities.
 +
<pre>
 +
*-RasMol (v&le;2.6)
 +
  |
 +
  |----Chime                Takes nearly all RasMol 2.6 commands and adds a few.
 +
  |    |
 +
  |    ----Jmol (v&ge;10)    Takes many RasMol 2.6 and Chime 2.6 commands and adds a few.
 +
  |          |
 +
  |          ---Jmol (v&ge;11) Adds many new commands.
 +
  |
 +
  -----OpenRasMol (v&ge;2.7)  Takes all RasMol 2.6 commands and adds a few.
 +
</pre>
  
An earlier implementation of something like this, "bondorder", created or removed bonds based on the setting of BONDMODE. The difference between bondorder and connect is that bondorder only acts on bonds ALREADY defined. While this could be useful, a simple parameter "STATIC" to the connect command does the same thing. We are thus planning to remove the BONDORDER command. (It was never documented, anyway.)
+
== RasMol commands not accepted by Jmol ==
 +
These are some RasMol / OpenRasMol commands that are not accepted by Jmol (they will raise an error and will stop further execution of the script):
 +
* <code>set cartoon on</code> defines that cartoon display should use arrowheads -- not needed in Jmol, since that is the default (and not changeable).
 +
* <code>set cartoon N</code> defines the "depth" (i.e. thickness) of the ribbons; more or less similar to Jmol's <code>cartoon N</code>.
 +
* <code>color atom cpknew</code> "cpkNew" is a color scheme for elements slightly diferent than the old default "cpk"; not available as such in Jmol. See [http://jmol.sourceforge.net/jscolors/index.en.html#Atoms%20(%27CPK%27%20colors,%20default%20element%20colors) Jmol Colors] for a comparison.
  
-Bob Hanson
+
= Transversal documentation =
 +
Covering specific aspects or applications (not by command, and usually not exhaustive):
 +
* [http://jmol.sourceforge.net/docs/surface/ Surfaces]. Jmol can calculate and render surfaces around a molecule, or part of it, representing its "true" shape and volume. Moreover, isosurfaces, atomic and molecular orbitals, and mathematically defined surfaces can also be rendered. An ''introductory'' tutorial on creating macromolecular Jmol surfaces is available: [http://www.callutheran.edu/Academic_Programs/Departments/BioDev/omm/surfaces/surfaces/surfaces.htm An Introduction to Jmol Surface Displays], part of the Online Macromolecular Museum at California Lutheran University.
 +
* [[Persistent Parameters|Persistent and nonpersistent "set" parameters]]. Some parameters defined using the "set" command are associated to the app/applet and hence maintained when a new molecule is loaded, while others are reset when the model is removed.

Latest revision as of 13:05, 11 July 2016

Jmol + JSmol Documentation

The Jmol Application and Applet have a command language that grew on the base of the command language of RasMol and its browser plugin MDL Chime. A set of commands is called a command script, and writing such sets of commands or scripts is called scripting. This is the major way of controlling the display of molecules in Jmol.

Documentation links

Documentation of Jmol's scripting language can be found here:

This is the official document. The style is encyclopedic, explaining each command in turn, as usual in reference manuals. In addition to this primary site, with latest updates, there are some mirror sites (see links at right).

An introduction to Jmol scripting is available here:

A more user-friendly, but less thorough, basic guide by Nathan Silva and David Marcey; part of the Online Macromolecular Museum at California Lutheran University.

Other

  • Scripts can be included inside the molecular model file. See how to do it.
  • Jmol scripting language has grown, among other features, by adding mathematical operators (JmolMath), control structures (loops, conditionals, etc.). You may be interested in this programming language approach.

Similar but different scripting languages

Chime's command language (see "About Chime" at http://molviz.org) is a superset of the command language of Roger Sayle's public domain application RasMol. (The command language of open-source RasMol has diverged somewhat from that in RasMol and Chime). The command language used by Jmol started with most of the Chime commands, but has outgrown it in a notable extent, allowing for many new capabilities.

*-RasMol (v≤2.6)
   |
   |----Chime                Takes nearly all RasMol 2.6 commands and adds a few.
   |     |
   |     ----Jmol (v≥10)     Takes many RasMol 2.6 and Chime 2.6 commands and adds a few.
   |          |
   |          ---Jmol (v≥11) Adds many new commands.
   |
   -----OpenRasMol (v≥2.7)   Takes all RasMol 2.6 commands and adds a few.

RasMol commands not accepted by Jmol

These are some RasMol / OpenRasMol commands that are not accepted by Jmol (they will raise an error and will stop further execution of the script):

  • set cartoon on defines that cartoon display should use arrowheads -- not needed in Jmol, since that is the default (and not changeable).
  • set cartoon N defines the "depth" (i.e. thickness) of the ribbons; more or less similar to Jmol's cartoon N.
  • color atom cpknew "cpkNew" is a color scheme for elements slightly diferent than the old default "cpk"; not available as such in Jmol. See Jmol Colors for a comparison.

Transversal documentation

Covering specific aspects or applications (not by command, and usually not exhaustive):

  • Surfaces. Jmol can calculate and render surfaces around a molecule, or part of it, representing its "true" shape and volume. Moreover, isosurfaces, atomic and molecular orbitals, and mathematically defined surfaces can also be rendered. An introductory tutorial on creating macromolecular Jmol surfaces is available: An Introduction to Jmol Surface Displays, part of the Online Macromolecular Museum at California Lutheran University.
  • Persistent and nonpersistent "set" parameters. Some parameters defined using the "set" command are associated to the app/applet and hence maintained when a new molecule is loaded, while others are reset when the model is removed.