File formats/Scripting

File Formats

• General information
• Coordinates
• Chemical structure
• Compressed
• Converters
• Images
• Ray Tracing
• Surfaces
• 3D Objects
• Scripting
• Exporting / saving files
• Support for bond orders
• Support for isotopes
• Support for stereochemistry

File Formats for Scripting Jmol

Script input

Jmol reads script files, using not the load command, but the script command. These are plain-text files containing commands in the Jmol scripting language (in part common with Rasmol and Chime), that will modify the way the molecular model is shown. The file can have any extension (though .spt is the acknowledged standard).

For details on the scripting language, visit the Interactive Scripting Documentation.

In the Jmol application, you can also read a script file using the top menu, File > Open. In both the application and the signed applet, the pop-up menu Load > Script.

Script output

The Jmol application and the signed applet can write a script file that will restore the current appearance and state of the model. The unsigned applet cannot save files, but can output the data to the console, from where they can be copied and then pasted and saved to a file by the user.

Using the application's top menu bar: File > Export > Write State write a filename and click on Save. Or you can use the button in the toolbar.

In older versions of Jmol:

File > Export > Export Image or Script

and in the Image Type drop-down list, choose SPT, write a filename and click on Save.

Using the pop-up menu: Save > Script with state

or Show > Current state

Inline formats

Molecular data are usually contained in an external file and loaded into Jmol using the load command, but they can also be contained within the webpage (or fed into it using JavaScript or PHP, e.g. from a database).

In turn, script commands can also be contained in the molecular file.

To allow for this "inline" formats, several methods are implemented:

Please, note that these are advanced procedures. For normal needs, they can be avoided in favour of using normal scripting practices.

Molecular coordinates inline within a webpage

Can be done using direct instructions for the applet or, more easily, using functions in the Jmol.js library: jmolAppletInline, jmolLoadInline, jmolLoadInlineScript.

Molecular coordinates inline within a script or script file

Can be done using the data "model" command.

Script inline within a molecular coordinates file

Scripts can be included, in a single line, after a jmolscript: tag (case-sensitive; the final colon is needed). This must be taken as a comment by the molecular file parser, so its location depends on the file format:

• In a PDB file, use REMARK jmolscript: in any line, followed by the script commands in the same line.

(Several REMARK jmolscript: lines are also supported.)

• In a MOL file (both v2000 and v3000), use jmolscript: in the third line, followed by the script commands in the same line.
• In a MOL2 file, use jmolscript: followed by the script commands in the same line. There are two possible locations for this:
  • In the header section (i.e. before the first @<TRIPOS>MOLECULE line), as a general comment, so the line must start with #. (Several jmolscript: lines are also supported.)
  • In the comments line for each model, that is, the sixth line after the @<TRIPOS>MOLECULE line. (The # prefix is unneeded here, though it will be tolerated.) If you need to have a real comment in addition to the Jmol script, place it in the same line before the jmolscript: part.

Note that, for a multimodel file, although you may include scripts within each of the @<TRIPOS>MOLECULE sections, they will not be applied specifically to that model, but globally to the whole file. So, if the scripts are meant to be model-specific, you should make sure to reference the model in the script.

• In an XYZ file, use jmolscript: in the second line, followed by the script commands in the same line.
• In a CIF file or a Z-matrix file, use #jmolscript: followed by the script commands in the same line. It may be in any line as long as it does not interfere with the data structure, so it is better to put it either at the beginning or the end of the file.
• Other file formats where embedded scripts are supported (using jmolscript: in any line) are: Gromacs, Cube, JME, Wien2k.

In all cases, the script will be applied after the whole molecule has loaded and after whatever script commands may have been set using set defaultLoadScript.

Contributors

AngelHerraez, Bevmorguson