View source for File formats

{{Jmol_Documentation_Sections}}
(An attempt to compile information on file format specifications. It's not complete yet.)

Jmol [{{SVN Trunk}}Jmol-datafiles/ example/test data files] in all formats accepted.

[[:en:Chemical_file_format|Chemical file formats]] on Wikipedia.

[http://openbabel.sourceforge.net/wiki/Category:Formats File formats] on Open Babel.

Nice description of [http://reference.wolfram.com/mathematica/guide/3DGeometryAndModelingFormats.html 3D Geometry & Modeling Formats] by Wolfram Mathematica.


= Coordinates of molecule =

== MOL and SD (Symyx MDL) ==
MOL = MDL molfile

SD = SDF = Structure Data Format 

Jmol reads MOL and SD files (and can write MOL files under some circumstances).
Original from Molecular Design Limited, then Elsevier MDL, now Symyx Technologies, widely adopted by many other programs.
Contains atom coordinates and bonds. Limited to 1000 atoms.

MOL header lines:
* The first line is reserved for the molecule name and will be so used by Jmol in the popup menu.
* The second line is in principle reserved for information on the originating program, user, etc. (Jmol will ignore this line).
* The third line is for comments, and may contain an [[#Script_inline_within_a_molecular_coordinates_file | inline script]] starting with <code>jmolscript:</code>.

SD files share the MOL format but may contain several structures (separated by lines with $$$$), which will be read by Jmol as multiple models or frames.

Official document (PDF): http://www.mdl.com/downloads/public/ctfile/ctfile.pdf, copied [{{SVN Trunk}}Jmol-datafiles/mol/ctfile.pdf here].

[{{SVN Trunk}}Jmol-datafiles/mol/ Example files].

Some extra information on SD files at [http://www.epa.gov/ncct/dsstox/MoreonSDF.html US EPA DSSTox].

The newer format, '''V3000''' (extended molfile or extended connection table), applies to both MOL and SDF, hasn't got the 1000-atom limit and is also supported by Jmol.


== MOL2 (Sybyl, Tripos) ==
Jmol reads MOL2 files.
Original from Tripos.
Contains atom coordinates, bonds, partial charge, substructure information.

A single MOL2 file may contain several structures, which will be read by Jmol as multiple models or frames.

Official document: http://www.tripos.com/data/support/mol2.pdf

== PDB ==
Jmol reads PDB files.
Contains atom coordinates and information on biomolecular residues, sequence, chains, hydrogen and disulfide bonds, secondary structure, biologically relevant sites, cofactors. Can also contain temperature factor, formal charge, element symbol, alternate locations.

(Official Protein Data Bank document) Atomic Coordinate Entry Format.
Description:
http://www.wwpdb.org/documentation/format23/v2.3.html

[{{SVN Trunk}}Jmol-datafiles/pdb/ Example files].


== XYZ ==
Jmol reads XYZ files. Originally from XMol package, but has been widely adopted by many other programs. Contains only atom coordinates (no bonds) and, optionally, charges and vectors (e.g. for atom vibration). Supports multi-model data (multi-frame, animations).

XYZ header lines:
* The first line is reserved for the number of atoms.
* The second line is for comments, and may contain an [[#Script_inline_within_a_molecular_coordinates_file | inline script]]  starting with <code>jmolscript:</code>.

[http://local.wasp.uwa.edu.au/~pbourke/dataformats/xyz/ Example] by Paul Bourke.

[{{SVN Trunk}}Jmol-datafiles/xyz/ Example files].

Description:
:XYZ datafiles specify molecular geometries using a Cartesian coordinate system. This simple, stripped-down, ASCII-readable format is intended to serve as a "transition" format for the XMol series of applications. For example, suppose a molecular datafile was in a format not supported by XMol. In order to read the data into XMol, it would be possible to modify the datafile, perhaps by creating a shell script, so that it fit the relatively lenient requirements of the XYZ format specification. Once data is in XYZ format, it may be examined by XMol, or converted to yet another format. 
:The XYZ format supports '''multi-step datasets'''. '''Each step''' is represented by a two-line "header," followed by one line for each atom. The '''first line''' of a step's header is the number of atoms in that step. This  integer  may be preceded by whitespace; anything on the line after the integer is ignored.  The '''second line''' of the header leaves room for a descriptive string. This line may be blank, or it may contain some information pertinent to that particular step, but it must exist, and  it must be just one line long. '''Each line of text describing a single atom''' must  contain at least four fields of information, separated by whitespace: the atom's type (a short string of alphanumeric characters), and  its x-, y-, and z-positions. Optionally, extra fields may be used to specify a charge for the atom, and/or a vector associated with the atom. If an input line contains five or eight fields, the fifth field is interpreted as the atom's charge; otherwise, a charge of zero is assumed. If an input line contains seven or eight fields, the last three fields are interpreted as the components of a vector. These components should be specified in angstroms. 
:Note that the XYZ format doesn't contain '''connectivity''' information. This intentional omission allows for greater flexibility: to create an XYZ file, you don't need to know where a molecule's bonds are; you just need to know where its atoms are. Connectivity information is generated automatically for XYZ files as they are read into XMol-related applications. Briefly, if the distance between two atoms is less than the sum of their covalent radii, they are considered bonded.

:''Source: man page for XYZ (part of XMol), quoted at http://www.ccl.net/chemistry/resources/messages/1996/10/21.005-dir/index.html''

The XYZ reader in Jmol reads any of the following (updated for Jmol v. 11.4.5 and 11.5.41):
<pre>
Sym   x   y   z
Sym   x   y   z    vibX   vibY   vibZ
Sym   x   y   z    FormalCharge(integer)
Sym   x   y   z    FormalCharge(integer)    vibX   vibY   vibZ
Sym   x   y   z    PartialCharge(decimal)
Sym   x   y   z    PartialCharge(decimal)    vibX   vibY   vibZ
</pre>
:where <code>Sym</code> is either an element symbol (C, Fe, Si) or an element symbol preceded by an isotope number (2H, 13C, etc.)

== CIF ==
Jmol reads CIF files.
Crystallographic Information File, the official format from the International Union of Crystallography. [http://www.iucr.org/iucr-top/cif/standard/cifstd1.html Original documentation], Acta Cryst. (1991). A47, 655-685, and the [http://www.iucr.org/iucr-top/cif/spec/version1.1/ 2003 update].

CIF files may contain anywhere an [[#Script_inline_within_a_molecular_coordinates_file | inline script]] starting with <code>jmolscript:</code>.

== mmCIF ==
Jmol reads mmCIF files.
Macromolecular Crystallographic Information File, an expanded format to cope with macromolecules.
[http://www.pdb.org/robohelp/ftp/files_formats/structures/chemical_component_format/chemical_component_mmcif_format.htm Official documentation].


== Alchemy (Tripos) ==
Jmol does not (yet) support reading of Alchemy and Alchemy2000 files.
[http://local.wasp.uwa.edu.au/~pbourke/dataformats/alc/alc3/ Alchemy example] and [http://local.wasp.uwa.edu.au/~pbourke/dataformats/alc/ Alchemy2000 description] by Paul Bourke.

A simple Alchemy reader is implemented starting Jmol 11.7.18.

A complete specification of these formats is needed to fully implement the reader. If you have those details, please contact the developers team.


== GAMESS ==
Jmol reads GAMESS files (General Atomic and Molecular Electronic Structure System, by Gordon research group at Iowa State University).

[http://www.msg.ameslab.gov/GAMESS/doc.menu.html Official documentation].


== Gaussian ==
Jmol reads only the output format.
There are 
[{{SVN Trunk}}Jmol-datafiles/gaussian/ example files] 
of Gaussian input, output and log.

Recent versions of Jmol application can also export to files in Gaussian input format.


== Cube (Gaussian) ==
Jmol reads Cube files, original from Gaussian software ([http://www.gaussian.com/ Gaussian website]).

Description of Cube Input and Cube Output formats:
http://www.nersc.gov/nusers/resources/software/apps/chemistry/gaussian/g98/00000430.htm

[http://local.wasp.uwa.edu.au/~pbourke/dataformats/cube/ Description] by Paul Bourke.

[{{SVN Trunk}}Jmol-datafiles/cube/ Example files].


== GROMACS ==
''This is not read by Jmol, but might be supported in the future.''

File format is called '''gro''' or '''Gromos87'''. Usual extension is <code>.gro</code>

[http://www.gromacs.org/documentation/reference/online/gro.html Description] of the format.

You can convert from '''gro''' to '''pdb''' using the "editconf" program, which is a part of the GROMACS package that can be run from the command line:
 editconf -f whatever.gro -o whatever.pdb
[http://www.gromacs.org/documentation/reference/online/editconf.html Full syntax of editconf].


== HIV (Hyperchem) ==
Jmol reads HIV files, the native format of Hyperchem, a software sold by [http://www.hyper.com/ Hypercube Inc.].

[http://local.wasp.uwa.edu.au/~pbourke/dataformats/hyperchem/ Example] by Paul Bourke, and other [{{SVN Trunk}}Jmol-datafiles/hin/ example files].


== MOPAC ==
Jmol reads '''mopout''' output files from [http://openmopac.net/ MOPAC] 
and the new '''graphf''' output from MOPAC2007 (<code>.mgf</code> files), which 
contains coordinates, charges, and molecular orbitals.

openMOPAC, Molecular Orbital PACkage, public domain.


== PQR ==
Jmol (11.1.30 or later) reads '''pqr''' files.

PQR format is a format based on <code>[[#PDB|pdb]]</code>, where the ''occupancy'' is replaced with the atomic charge and the ''temperature'' (or ''B factor'') is replaced with atomic radius (however, the column positions in many pqr files do not match those of pdb files). This gives the acronym: '''P''' for pdb, '''Q''' for charge, '''R''' for radius. Jmol interprets the charge values (property ''partialcharge'') and the radii (property ''vanderwaals''), and can hence use them e.g. in <code>color atoms partialCharge</code> and <code>spacefill</code>.

The PQR format has somewhat uncertain origins, but is used by several computational biology packages, including MEAD, AutoDock and [http://apbs.sourceforge.net/ APBS], for which it is the primary input format.

[http://apbs.sourceforge.net/doc/user-guide/index.html#pqr-format PQR format description] within APBS documentation. ''Note that APBS reads PQR loosely, based only on white space delimiters, but Jmol may be more strict about column positions.''

PDB files can be converted to PQR by the [http://pdb2pqr.sourceforge.net/ PDB2PQR] software, which adds missing hydrogen atoms and calculates the charge and radius parameters from a variety of force fields.


== Amber ==
Jmol (11.7 or later) reads molecular dynamics output files from [http://ambermd.org/ '''Amber''']. The fileset must have have a structure like: 

1 (topology file) + n (coordinate files) 

The <code>filter</code> option of the <code>load</code> command can be used, as well as a new option to allow selective "first,last,step" loading of coordinate trajectories.

''(This is preliminary and needs testing)''


== V3000 (Symyx MDL) ==
See [[File_formats#MOL_and_SD_.28Symyx_MDL.29|MOL]].


== Q-Chem ==
Jmol reads files output from the computational chemistry package Q-Chem. See the [[Q-Chem|Q-Chem specific section]].

= Images =

== Saving images from Jmol application ==
Images (snapshots) of Jmol's viewport, including the model in the current rendering, can be saved by using the application's top menu bar:
<code>File > Export > Export Image</code>. A dialog will open to allow choosing the location and filename, as well as the format in the <code>Image Type</code> drop-down list; choose among <code>JPEG</code>, <code>PNG</code>, <code>PPM</code> or <code>GIF</code> formats. The menu also has <code>File > Export > Render in POV-Ray</code>, which produces images that can be displayed and edited in this raytracing program.
:''Note: GIF format is only available in recent versions of Jmol.''

Information on these [[:en:Graphics_file_format|image formats]] and [[:en:POV-Ray|POV-Ray]] on Wikipedia.

== Saving images from Jmol application and signed applet ==

The pop-up menu also allows in these cases (not in the normal, unsigned applet) to save a snapshot of the model, in <code>JPEG</code>, <code>PNG</code> or <code>POV-Ray</code> (raytracing) formats. Open the pop-up menu (right-click, or Ctrl+click, or click on Jmol frank) and choose <code>Save</code>. A dialog will open to choose the location and filename.

== Saving images from Jmol applet ==
''These methods work for both signed and unsigned applet, but for the first the method above is more convenient.''
=== Basic method ===
<i>Note:</i> This only works for certain browsers, so it is not a general solution for the general user. In particular, it does not work in MSIE. In Firefox, it may fail for large applet sizes.

The command from the console or via JavaScript is
<code>getProperty image</code>.

The result is a base-64 encoded JPEG image that looks like this:
<pre>/9j/4AAQSkZJRgABAAAAAQABAAD//gBBSl...</pre>

Pop that into an <code><img></code> tag using Firefox or Opera (not MSIE), and you have
an image that you can copy into your clipboard and do anything you would
do with a JPG. The JavaScript required to create the tag looks like this:
<pre>var myImage = jmolGetPropertyAsString("image")
document.getElementById("someDiv").innerHTML =
  '<img src="data:image/jpeg;base64,' + myImage + '">'</pre>

Example:
[http://www.stolaf.edu/academics/chemapps/jmol/docs/examples-11/new.htm Bob Hanson's examples page] (Just under the applet, click on the word "image".)

=== General method, using Perl ===
This works in any browser. The author must have access to the web server and be able to use a Perl script there.

It sends the "base64" encoded image (described above) to a perl
script on the server. This script uses the <code>MIME::Base64</code> package to decode the image (<code>MIME::Base64::decode($data)</code>) and sends it back to the browser, embedded in an HTML page.

'''Example code:'''

''HTML file and Javascript (client side)'':

<pre><html>
<head>
<script type="text/javascript">
  function get_snapshot()
  {
    var BI = document.getElementById("bounce_image");
    var BI_D = document.getElementById("IMAGE_DATA");
    var BASE64 = jmolGetPropertyAsString("image");
    BI_D.value = BASE64;
    BI.submit();
  }
</script>
</head>
<body>
<script type="text/javascript">
        jmolInitialize("jmol/");
        jmolApplet(350,"load something.pdb");
</script>
<input type="button" id="snapshot" value="snapshot"
onclick='get_snapshot()'>
<form id="bounce_image" 
     action="http://MY.SERVER.COM/cgi-bin/decode_snapshot.pl"
     method="post" target="_blank">
  <input type="hidden" id="IMAGE_DATA" name="IMAGE_DATA"
   value="empty">
</form>
</body>
</html></pre>

''PERL script (server side) file 'decode_snapshot.pl''':

<pre>#!/usr/bin/perl
use MIME::Base64;
print "Content-type: image/jpeg\n\n";
    %postFields = ();
    read( STDIN, $tmpStr, $ENV{ "CONTENT_LENGTH" } );
    @parts = split( /\&/, $tmpStr );
    foreach (@parts) {
        s/%([0-9A-F][0-9A-F])/pack("c",hex($1))/ge;
        ( $name, $value ) = split(/\=/);
        $postFields{ "$name" } = $value;
    }
    $decoded = decode_base64($postFields{"IMAGE_DATA"});
    open (MYFILE, '>path_to_file/jmol_snapshot.jpg');
    print MYFILE $decoded;
    close (MYFILE);
    print $decoded;
exit;</pre>
	
It is also possible to add additional information to the page containing the generated image 
(like in the example below).
  
Example: 
http://www.fli-leibniz.de/cgi-bin/3d_mapping.pl?CODE=1deh
(click on the "snapshot" button in the "Graphics Window" section).

=== General method, using just HTML, and PHP if necessary ===
This works in any browser. The server must support PHP, but no configuration is needed.

* No access to server configuration is needed (i.e., no need to install server-side scripts).
* If the browser is MS Internet Explorer, it needs online access to a PHP-enabled server that will return the image using a php page which is part of this package.
* If the browser is another, inline base64-encoded images will be used first (understood by Firefox and Opera, at least). This method works both online and off-line (e.g., from hard disk, USB disk or CDROM).

The image is opened in a new window, that fits the image size.
It can then be copied to clipboard using the browser's pop-up menu on it. Some browsers also allow to save the image to disk, from the same pop-up menu.

Example and downloadable kit: 
http://biomodel.uah.es/Jmol/export-image/

= Surfaces =

== JVXL (Jmol Voxel) ==
Jmol reads and writes JVXL files.

This format is unique to Jmol, stores isosurface data in a highly compressed format.

Documented at http://www.stolaf.edu/academics/chemapps/jmol/docs/misc/JVXL-format.pdf


== Pmesh ==
Jmol reads pmesh files for rendering pmesh surfaces, using not the <code>load</code> command, but the <code>pmesh</code> command.
[http://www.stolaf.edu/academics/chemapps/jmol/docs/#pmesh Description].

Example files [http://svn.sourceforge.net/viewvc/jmol/trunk/Jmol-datafiles/pmesh/ _1_] and [http://www.stolaf.edu/academics/chemapps/jmol/docs/misc/10x10pmesh.txt _2_].


== Cube (Gaussian) ==

See [[#(Gaussian)_Cube|above]].


== Open DX ==

Jmol (11.1.18 or later) reads DX files for rendering isosurfaces and color mapping.
DX contains three-dimensional scalar data; most frequently, isosurface and color by molecular electrostatic potential (MEP). 

(Not to be confused with JCAMP-DX format, used for spectral vibrational data, which can be shown 
using [http://jspecview.sourceforge.net/ JSpecView Applet] and [http://www.mdlchime.com MDL Chime].)

Open DX files are produced, among others, by [http://apbs.sourceforge.net/ APBS] (Adaptive Poisson-Boltzmann Solver).
APBS exists in standalone and web-server-based versions, and as a plug-in for [http://pymol.sourceforge.net/ PyMOL]. There is also an APBS web service integrated into [http://gemstone.mozdev.org Gemstone], which is a front-end GUI that facilitates the access to computational services run at dedicated web servers (follow the [http://gemstone.mozdev.org/usage-overview.html Gemstone tutorial]).

''Technical:''
: DX, as Cube, defines a three-dimensional grid of points in space. At each point is a number (a "scalar value"). This set of point values is then used by Jmol to define an "isosurface" -- the surface separating points having values greater than a given cutoff from those that have a value less than a certain cutoff. A typical application is molecular orbitals. The <code>phase</code> parameter of the <code>isosurface</code> command allows bicolor rendering: one color for "points greater than x" and another color for "points less than -x".
: Jmol can read DX files and re-export them to much smaller JVXL files.

Generally a MEP data set is not used for the isosurface itself. Rather, it is used to map color onto another isosurface, usually some representation of the "molecular surface".

Bottom line is that we can now take molecular electrostatic potential data that were generated in PyMOL (requires the APBS plugin for PyMOL) or in APBS or Gemstone, and use them to color a surface generated in Jmol. 

Documentation:
* [http://www.stolaf.edu/academics/chemapps/jmol/docs/misc/JVXL-format.pdf Jmol interpretation of DX files and re-exporting into much smaller JVXL files]
* [http://apbs.sourceforge.net/doc/user-guide/index.html#opendx-format DX generation of MEP data by APBS]
* [http://www.opendx.org OpenDX specification and software package]


== Efvet ==

Jmol (version 11.7.12 or later, support is preliminar) reads efvet files for rendering isosurfaces and color mapping.
Efvet is an XML file [http://ef-site.hgc.jp/eF-site/about.html format] used in [http://ef-site.hgc.jp/eF-site/ eF-site], a database for molecular surfaces colored by electrostatic potential, that covers the whole PDB.

The efvet file contains geometric information and coloring attributes of the molecular surface in the form of a set of polygons. Electrostatic potentials and hydrophobic properties are described together by the surface color: red --> blue colors correspond to negative --> positive electrostatic potentials, and yellow color indicates the surface of the hydrophobic residues.

= 3D objects =

Recent versions of Jmol application and signed applet can export models to several formats that specify three-dimensional objects and can be read by specialized software, either raytracing or 3D-world.

[[3D Formats | Documentation and plans for Jmol support of 3D object formats: VRML, X3D, U3D]].

== POV-Ray ==
Jmol can export, with limited features, the current view of a model into [[#Saving_images_from_Jmol_application | POV-Ray]] format.

== VRML ==
Jmol can export, with limited features, the model into Virtual Reality Modeling Language, [http://en.wikipedia.org/wiki/VRML VRML]. 
* Jmol exports only atoms (as spheres), bonds (as cylinders) and isosurfaces (as IndexedFaceSets, single color). Translucency will be supported soon. No dots, labels, cartoons... 
* The atom size and color, bond thickness and color, are preserved. The orientation and zoom are not always kept.
* Depending on your VRML viewer or plug-in, you may need to change the file to a {{file|.wrl}} extension. 

The {{file|vrml file}} can then be opened using several programs and browser plugins, and manipulated in 3D using the mouse.

== Maya ==
Jmol can export, with limited features, the current view of a model into [http://usa.autodesk.com/adsk/servlet/index?id=7635018&siteID=123112 Maya] format. 
[http://en.wikipedia.org/wiki/Maya_(software) Wikipedia info on Maya]

== OBJ ==
Jmol (starting v. 11.7.28) can read files in the <code>obj</code> file format. This format is generated by [[wikipedia:Wavefront_Technologies|Wavefront]], [https://java3d.dev.java.net/ Java3D] and [http://pymol.sourceforge.net PyMOL]. The described objects are handled as isosurfaces in Jmol, so they can  be saved in more compact [[File_formats#JVXL_.28Jmol_Voxel.29 | JVXL format]], if desired, and mapped with other data.

* Description of [http://www.eg-models.de/formats/Format_Obj.html <code>obj</code> file format] at ''EG-Models.de'', an archive of electronic geometry models.
* Description of <code>obj</code> file format at ''FileFormat.info'': <nowiki>www.fileformat.info/format/wavefrontobj/egff.htm</nowiki>
* Description of [http://www.martinreddy.net/gfx/3d/OBJ.spec <code>obj</code> file format] at ''The Graphics File Formats Page'' by Martin Reddy.
* Export of [http://www.pymolwiki.org/index.php/Surface#Exporting_Surface.2FMesh_Coordinates_to_File <code>obj</code> file format] from PyMOL (molecular surfaces).

= Scripting =

== 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.

For details on the scripting language, visit the [http://www.stolaf.edu/academics/chemapps/jmol/docs/ Interactive Scripting Documentation].


== Script output ==
Jmol application (not the applet) can write a script file that will restore the current appearance and state of the model. This functionality is still under improvement.

Use the application's top menu bar:
<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>.


== 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>[http://www.stolaf.edu/academics/chemapps/jmol/docs/#data data "model"]</code> command (Jmol 11 only).


=== 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.
* 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 an XYZ file, use <code>jmolscript:</code> in the '''second line''', followed by the script commands in the same line.
* In a CIF file, use <code>jmolscript:</code> in any line, followed by the script commands in the same line.

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>.