Difference between revisions of "File formats/Scripting"

From Jmol
Jump to navigation Jump to search
(for splitting the contents of File formats page)
 
(Script inline within a molecular coordinates file)
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
for splitting the contents of [[File formats]] page
+
{{File_Formats}}
--to be done
+
= File Formats for Scripting Jmol =
 +
 
 +
== Script input ==
 +
Jmol reads script files, using not the <code>load</code> command, but the <code>script</code> 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 {{file|.spt}} is the acknowledged standard).
 +
 
 +
For details on the scripting language, visit the [{{ScriptingDoc}} Interactive Scripting Documentation].
 +
 
 +
In the Jmol application, you can also read a script file using the top menu, <code>File > Open</code>.
 +
In both the application and the signed applet, the pop-up menu <code>Load > Script</code>.
 +
 
 +
 
 +
== 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:
 +
<code>File > Export > Write State</code>
 +
write a filename and click on <code>Save</code>.
 +
Or you can use the button in the toolbar.
 +
:''In older versions of Jmol:''
 +
:<code>File > Export > Export Image or Script</code>
 +
:and in the <code>Image Type</code> drop-down list, choose <code>SPT</code>, write a filename and click on <code>Save</code>.
 +
 
 +
Using the pop-up menu:
 +
<code>Save > Script with state</code>
 +
 
 +
or <code>Show > Current state</code>
 +
 
 +
 
 +
== Inline formats ==
 +
Molecular data are usually contained in an external file and loaded into Jmol using the <code>load</code> 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: <code>[http://jmol.org/jslibrary/#jmolAppletInline jmolAppletInline], [http://jmol.org/jslibrary/#jmolLoadInline jmolLoadInline], [http://jmol.org/jslibrary/#jmolLoadInlineScript jmolLoadInlineScript]</code>.
 +
 
 +
 
 +
=== Molecular coordinates inline within a script or script file ===
 +
Can be done using the <code>[{{ScriptingDoc}}#data data "model"]</code> command.
 +
 
 +
 
 +
=== Script inline within a molecular coordinates file ===
 +
Scripts can be included, in a single line, after a <code>jmolscript:</code> 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 <code>REMARK jmolscript:</code> in any line, followed by the script commands in the same line.
 +
:(Several <code>REMARK jmolscript:</code> lines are also supported.)
 +
* In a '''MOL''' file (both v2000 and v3000), use <code>jmolscript:</code> in the '''third line''', followed by the script commands in the same line.
 +
* In a '''MOL2''' file, use <code>jmolscript:</code> 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 <code>@<TRIPOS>MOLECULE</code> line), as a general comment, so the line must start with <code>#</code>. (Several <code>jmolscript:</code> lines are also supported.)
 +
** In the comments line for each model, that is, the sixth line after the <code>@<TRIPOS>MOLECULE</code> line. (The <code>#</code> 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 <code>jmolscript:</code> part.
 +
:: Note that, for a multimodel file, although you may include scripts within each of the <code>@<TRIPOS>MOLECULE</code> 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 <code>jmolscript:</code> in the '''second line''', followed by the script commands in the same line.
 +
* In a '''CIF''' file or a '''Z-matrix''' file, use <code>#jmolscript:</code> 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 <code>jmolscript:</code> 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 <code>set defaultLoadScript</code>.

Latest revision as of 20:11, 7 January 2015

File Formats

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 File icon.gif.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