Difference between revisions of "File formats/Export"

From Jmol
Jump to navigation Jump to search
(→‎MOL format)
(Exporting for augmented reality)
 
(12 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
== Exporting or saving molecular model files from Jmol ==
 
== Exporting or saving molecular model files from Jmol ==
−
Although Jmol is basically a viewer, it has some limited capabilities to save files for the displayed molecular model (or a subset of it).
+
Although Jmol was designed as a viewer, it has now capabilities to save files for the displayed molecular model (or a subset of it).
  
−
* <code>write</code> command
+
=== <code>write</code> command ===
−
* Pop-up menu
+
Jmol can export ''the currently selected set of atoms'' to a file in
−
* <code>save isosurface</code> command
+
* XYZ format
−
 
+
* PDB format
−
=== MOL format ===
 
−
Jmol can export the currently selected set of atoms to a file in
 
 
* MOL v2000 format (single model)
 
* MOL v2000 format (single model)
 
* MOL v3000 format (single model)
 
* MOL v3000 format (single model)
 
* SDF v2000 format (single or multiple models)
 
* SDF v2000 format (single or multiple models)
−
according to the [http://www.symyx.com/downloads/public/ctfile/ctfile.pdf official format specification from MDL-Symyx-Accelrys].
+
The last 3 are according to the [http://accelrys.com/products/informatics/cheminformatics/ctfile-formats/no-fee.php official format specification from MDL-Accelrys-Symyx].
 +
 
 +
The syntax (see
 +
[{{ScriptingDoc}}#writemodel reference documentation]) is like this:
 +
 
 +
{| class="wikitable"
 +
|-
 +
! commands (synonymous)
 +
! export the currently selected set of atoms,
 +
with original coordinates, using this format:
 +
|-
 +
| <pre>write myFile.xyz
 +
write xyz myFile.myExt
 +
write myFile.myExt as xyz</pre>
 +
| {{file|xyz}} format
 +
|-
 +
| <pre>write myFile.pdb
 +
write pdb myFile.myExt
 +
write myFile.myExt as pdb</pre>
 +
| {{file|pdb}} format
 +
|-
 +
| <pre>write myFile.mol
 +
write mol myFile.myExt
 +
write v2000 myFile.myExt
 +
write myFile.myExt as mol
 +
write&nbsp;myFile.myExt&nbsp;as&nbsp;v2000</pre>
 +
| {{file|mol-v2000}}  format
 +
|-
 +
| <pre>write v3000 myFile.myExt
 +
write&nbsp;myFile.myExt&nbsp;as&nbsp;v3000</pre>
 +
| {{file|mol-v3000}}  format
 +
|-
 +
| <pre>write myFile.sdf
 +
write sdf myFile.myExt
 +
write myFile.myExt as sdf</pre>
 +
| {{file|sdf-v2000}}  format
 +
|-
 +
| <pre>write myFile.jmol
 +
write jmol myFile.myExt
 +
write myFile.myExt as jmol</pre>
 +
| writes a single file that packs the original model file, the state as a Jmol script, and a snapshot ({{file|png}} image) of the current display; this file may be loaded back into Jmol and will reproduce the state
 +
|-
 +
| <pre>write image pngj myFile.png
 +
write myFile.png as pngj</pre>
 +
| functionally equivalent to the previous one, but produces a {{file|png}} file that is displayed as a regular image in any software; when loaded into Jmol it will read the model and its state
 +
|}
 +
 +
All of the above commands will save the original cooordinates of each atom as they were in the input file.
 +
 
 +
There is also the choice (only in MOL format) of saving the '''transformed coordinates''' as they are in the current state of the model:
 +
{| class="wikitable"
 +
|-
 +
! commands (synonymous)
 +
! export the currently selected set of atoms,
 +
with transformed coordinates, using this format:
 +
|-
 +
| <pre>write coord myFile.mol
 +
write coord mol myFile.myExt</pre>
 +
| {{file|mol-v2000}}  format
 +
|-
 +
| <pre>write&nbsp;coord&nbsp;v3000&nbsp;myFile.myExt</pre>
 +
| {{file|mol-v3000}}  format
 +
|}
 +
 
 +
=== <code>write()</code> function ===
 +
This function in the Jmol Scripting Language allows to place the output of the write command into a variable, rather than saving to a file. The data can later be loaded using <code>load var a</code>.
 +
See also <code>show()</code> below, as an alternative.
 +
 
 +
First parameter in the function is the format, second if needed is some qualifier, both matching what would be used in the command.
 +
 
 +
Common examples:
 +
{| class="wikitable"
 +
|-
 +
! commands
 +
!
 +
|-
 +
| <pre>a = write("xyz")</pre>
 +
| exports to {{file|xyz}} format
 +
|-
 +
| <pre>a = write("pdb")</pre>
 +
| exports to {{file|pdb}} format; note that Jmol will read back this format, but it is not compliant with the official PDB standard
 +
|-
 +
| <pre>a = write("mol")
 +
a = write("v3000")</pre>
 +
| exports to {{file|mol-v2000}} or {{file|mol-v3000}} format, respectively
 +
|-
 +
| <pre>a = write("coord")</pre>
 +
| exports to {{file|xyz}} format, original untransformed coordinates
 +
|-
 +
| <pre>a&nbsp;=&nbsp;write("coord","mol")</pre>
 +
| exports transformed coordinates to {{file|mol-v2000}} or {{file|mol-v3000}} format, respectively
 +
|-
 +
| <pre>a = write("jmol")</pre>
 +
| exports a packed file that contains the model and the state (but not the snapshot)
 +
''(only available since Jmol 14.27)''
 +
|}
 +
 
 +
=== <code>show() chemical</code> function ===
 +
The same information that would be exported to a file may be put into a variable using this function. It uses the NCI CACTVS Resolver web service for format conversion, and hence it needs a live internet connection to work.
 +
:''Available since Jmol version 14.6.0''
 +
:Note: ''If only a subset of the full model has been selected, only that subset will be included in the exported model. Since the procedure involves a query to the Resolver, and their server tries to interpret it as a full molecule, the result may then not be what you expect. Example: <code>select _N; show("chemical mol")</code> returns mol-formatted data for ammonia, no matter which was the original molecule containing several N atoms.''
 +
 
 +
Formats available are:
 +
{| class="wikitable"
 +
|-
 +
! <code>[[File_formats/Coordinates#Alchemy_.28Tripos.29|alc]]</code>
 +
| Alchemy (Tripos)
 +
! <code>[https://www.cambridgesoft.com/services/documentation/sdk/chemdraw/cdx/IntroCDXML.htm cdxml]</code>
 +
| XML-compliant version of ChemDraw's native file format
 +
! <code>cerius</code>
 +
| Cerius II from Accelrys/MSI
 +
|-
 +
! <code>[https://www.charmmtutorial.org/index.php/CHARMM:The_Basics#Molecule_Metadata charmm]</code>
 +
| CHARMM (Chemistry at HARvard Macromolecular Mechanics)
 +
! <code>[[File_formats/Coordinates#CIF|cif]]</code>
 +
| Crystallographic Information File
 +
! <code>cml</code>
 +
| Chemical Markup Language
 +
|-
 +
! <code>ctx</code>
 +
| Gasteiger group
 +
! <code>gjf</code>
 +
| Gaussian input
 +
! <code>[[File_formats/Coordinates#GROMACS|gromacs]]</code>
 +
| GROMACS
 +
|-
 +
! <code>hyperchem</code>
 +
| HIV / HIN format from Hyperchem
 +
! <code>[[File_formats/Chemical_Structure#JME|jme]]</code>
 +
| from the JME/JSME Molecular Editor
 +
! <code>[https://sites.google.com/a/srscicomp.com/maestro/data-analysis/data-file-format maestro]</code>
 +
| from Schrödinger
 +
|-
 +
! <code>[[File_formats/Coordinates#MOL_and_SD_.28Symyx_MDL.29|mol]]</code>
 +
| Symyx MDL
 +
! <code>mol2</code>
 +
| Sybyl, Tripos
 +
! <code>sybyl2</code>
 +
| Sybyl, Tripos
 +
|-
 +
! <code>[http://onlinelibrarystatic.wiley.com/marvin/help/formats/mrv-doc.html mrv]</code>
 +
| Marvin format, from ChemAxon
 +
! <code>pdb</code>
 +
| from Protein DataBank, but nonstandard
 +
! <code>[[File_formats/Coordinates#MOL_and_SD_.28Symyx_MDL.29|sdf]]</code>
 +
| Symyx MDL
 +
|-
 +
! <code>[[File_formats/Coordinates#MOL_and_SD_.28Symyx_MDL.29|sdf3000]]</code>
 +
| Symyx MDL, V3000
 +
! <code>[https://pubs.acs.org/doi/abs/10.1021/ci7004687 sln]</code>
 +
| SYBYL Line Notation
 +
! <code>[[File_formats/Chemical_Structure#SMILES|smiles]]</code>
 +
| SMILES string
 +
|-
 +
! <code>[[File_formats/Coordinates#XYZ|xyz]]</code>
 +
| the traditional XYZ format
 +
|
 +
|
 +
|
 +
|
 +
|}
 +
 
 +
The syntax is like this:
 +
d = show("chemical xyz")
 +
d = show("chemical mol")
 +
d = show("chemical hyperchem")
 +
etc.
 +
 
 +
The result (text string as the value of the variable) may then be displayed, processed, or even may be written to a file using
 +
<code> write var d myFile.hin</code>. In this way, Jmol is in fact exporting file formats that it cannot export natively, by using the format conversion server at NCI.
 +
 
 +
=== Pop-up menu ===
 +
These are available:
 +
 
 +
File > Save > Save a copy of file
 +
 
 +
File > Save > Save as PNG/JMOL (image+zip)
 +
 
 +
File > Save > Save JVXL isosurface
 +
 
 +
File > Export > Export PNG+JMOL image
 +
 
 +
The 2nd and 4th are equivalent and contain, packed in a single file, a snapshot PNG image, the coordinates file and the state script file.
  
−
''(Jmol version 12.1.26 has this full set of options; former versions export only MOL v2000 and match the specification only partially.)''
+
=== Save isosurface ===
 +
The pop-up menu entry will svae the last isosurface selected or generated. More flexibility is allowed by using the [{{ScriptingDoc}}#writeobject <code>write isosurface</code>] command.
  
−
The syntax (see  
+
== Saving Jmol-specific files ==
−
[{{ScriptingDoc}}#writemodel reference documentation]) is
+
 
−
write myFile.mol #exports to MOL v2000
+
=== Special image files PNGJ ===
−
write v3000 myFile.mol #exports to MOL v3000
+
 
−
  write myFile.sdf #exports to SDF v2000
+
Jmol can export to a PNG file that, in addition of a snapshot of the current molecular rendering, includes the state with all the information of rendering style (PNG) and, optionally, the data of the molecular model (PNGJ).
 +
These files appear as regular image files to any software but, when loaded back in Jmol (or drag-and-dropped) will reproduce the exact state of the 3D molecular model.
 +
 
 +
(The extra non-image information is included in a metadata area allowed by the png format)
 +
 
 +
Here are the basic commands; for additional options, see the [{{ScriptingDoc}}#writeimagesandframes documentation]  
 +
 
 +
{| class="wikitable"
 +
|-
 +
! commands
 +
!
 +
|-
 +
| <pre>write image png "myFileName"</pre>
 +
| saves to disk a snapshot image of the current display, including also the state (''notes 1, 2 and 3'')
 +
|-
 +
| <pre>write "myFileName" as png</pre>
 +
| does the same as the above one
 +
|-
 +
| <pre>set imageState off;
 +
write image png "myFileName"</pre>
 +
| saves to disk a snapshot image of the current display, without the state (''note 2'')
 +
|-
 +
| <pre>write image pngj "myFileName"</pre>
 +
| saves to disk a snapshot image of the current display, including also the model, state and any files involved in the rendering (''note 1'')
 +
|-
 +
| <pre>write "myFileName" as pngj</pre>
 +
| does the same as the above one
 +
|}
 +
 
 +
:(*) Note 1: if the specified file extension is not png, the file will still be a valid png image file, but it may or not be recognized by any software and may not be recognized by Jmol.
 +
:Note 2: by default, molecular state is included in the file, unless <code>set imageState</code> has been previously set to <code>false</code> or <code>off</code>.
 +
:Note 3: in the case of png files (not pngj), the molecular model file and any isosurface files involved must be in the same folder as the png file in order for the state to be interpreted.
 +
 
 +
 
 +
''New feature:'' Allows replacement of PNG data in PNGJ
 +
(available since version 14.31.34)
 +
:<code>write "fileA.png" as pngj;</code> saves a file containing both the image, the model data and the state
 +
:<code>a = load("fileA.png",true);</code> loads the file contents into a (binary) variable
 +
:<code>b = load("fileB.png");</code> loads a regular image file into another (binary) variable
 +
:<code>a._IMAGE_ = b._DATA_;</code> puts the binary data making image "B" into the image section of data from file "A" (replacing the existing image data)
 +
:<code>write var a "fileC.png";</code> saves the new combination stored in variable "a", i.e. molecular data from file "A" and image from file "B", into a new PNGJ file
 +
 
 +
== Exporting for augmented reality software ==
 +
 
 +
Some users have produced models to be used in augmented reality (AR) software following one of these procedures using [https://www.blender.org/ Blender]:
 +
 
 +
* Open the model in Jmol, export as {{file|X3D}},<sup>1</sup> import into Blender, retouch aspect, texture... and export to an {{file|FBX}} file. This latter format may be input into some AR software.
 +
 
 +
* Import directly a {{file|PDB}} file into Blender. Sometimes this results in a model with atoms but no bonds (since the PDB format does not necessarily include bond information). In this case, you may open the {{file|PDB}} file into Jmol and export as PDB,<sup>2</sup> then load this new file into Blender.
 +
 
 +
* For models available in other file formats like {{file|SDF}}, open them in Jmol and export as {{file|PDB}},<sup>2</sup> then open in Blender.
 +
 
 +
Notes:
 +
 
 +
1. <code>write ? as x3d</code>
  
−
write mol myFile.myExt #exports to MOL v2000
+
2. <code>write ? as pdb</code>
−
write v2000 myFile.myExt #exports to MOL v2000
 
−
write v3000 myFile.myExt #exports to MOL v3000
 
−
write sdf myFile.myExt #exports to SDF v2000
 

Latest revision as of 16:34, 25 August 2023

Exporting or saving molecular model files from Jmol

Although Jmol was designed as a viewer, it has now capabilities to save files for the displayed molecular model (or a subset of it).

write command

Jmol can export the currently selected set of atoms to a file in

  • XYZ format
  • PDB format
  • MOL v2000 format (single model)
  • MOL v3000 format (single model)
  • SDF v2000 format (single or multiple models)

The last 3 are according to the official format specification from MDL-Accelrys-Symyx.

The syntax (see reference documentation) is like this:

commands (synonymous) export the currently selected set of atoms,

with original coordinates, using this format: 

write myFile.xyz
write xyz myFile.myExt
write myFile.myExt as xyz
 File icon.gifxyz format 
write myFile.pdb
write pdb myFile.myExt
write myFile.myExt as pdb
 File icon.gifpdb format 
write myFile.mol
write mol myFile.myExt
write v2000 myFile.myExt
write myFile.myExt as mol
write myFile.myExt as v2000
 File icon.gifmol-v2000 format 
write v3000 myFile.myExt
write myFile.myExt as v3000
 File icon.gifmol-v3000 format 
write myFile.sdf
write sdf myFile.myExt
write myFile.myExt as sdf
 File icon.gifsdf-v2000 format 
write myFile.jmol
write jmol myFile.myExt
write myFile.myExt as jmol
 writes a single file that packs the original model file, the state as a Jmol script, and a snapshot (File icon.gifpng image) of the current display; this file may be loaded back into Jmol and will reproduce the state 
write image pngj myFile.png
write myFile.png as pngj
 functionally equivalent to the previous one, but produces a File icon.gifpng file that is displayed as a regular image in any software; when loaded into Jmol it will read the model and its state

All of the above commands will save the original cooordinates of each atom as they were in the input file.

There is also the choice (only in MOL format) of saving the transformed coordinates as they are in the current state of the model:

commands (synonymous) export the currently selected set of atoms,

with transformed coordinates, using this format: 

write coord myFile.mol
write coord mol myFile.myExt
 File icon.gifmol-v2000 format 
write coord v3000 myFile.myExt
 File icon.gifmol-v3000 format

write() function

This function in the Jmol Scripting Language allows to place the output of the write command into a variable, rather than saving to a file. The data can later be loaded using load var a. See also show() below, as an alternative.

First parameter in the function is the format, second if needed is some qualifier, both matching what would be used in the command.

Common examples:

commands 
a = write("xyz")
 exports to File icon.gifxyz format 
a = write("pdb")
 exports to File icon.gifpdb format; note that Jmol will read back this format, but it is not compliant with the official PDB standard 
a = write("mol")
a = write("v3000")
 exports to File icon.gifmol-v2000 or File icon.gifmol-v3000 format, respectively 
a = write("coord")
 exports to File icon.gifxyz format, original untransformed coordinates 
a = write("coord","mol")
 exports transformed coordinates to File icon.gifmol-v2000 or File icon.gifmol-v3000 format, respectively 
a = write("jmol")
 exports a packed file that contains the model and the state (but not the snapshot)

(only available since Jmol 14.27)

show() chemical function

The same information that would be exported to a file may be put into a variable using this function. It uses the NCI CACTVS Resolver web service for format conversion, and hence it needs a live internet connection to work.

Available since Jmol version 14.6.0
Note: If only a subset of the full model has been selected, only that subset will be included in the exported model. Since the procedure involves a query to the Resolver, and their server tries to interpret it as a full molecule, the result may then not be what you expect. Example: select _N; show("chemical mol") returns mol-formatted data for ammonia, no matter which was the original molecule containing several N atoms.

Formats available are:

alc Alchemy (Tripos) cdxml XML-compliant version of ChemDraw's native file format cerius Cerius II from Accelrys/MSI
charmm CHARMM (Chemistry at HARvard Macromolecular Mechanics) cif Crystallographic Information File cml Chemical Markup Language
ctx Gasteiger group gjf Gaussian input gromacs GROMACS
hyperchem HIV / HIN format from Hyperchem jme from the JME/JSME Molecular Editor maestro from Schrödinger
mol Symyx MDL mol2 Sybyl, Tripos sybyl2 Sybyl, Tripos
mrv Marvin format, from ChemAxon pdb from Protein DataBank, but nonstandard sdf Symyx MDL
sdf3000 Symyx MDL, V3000 sln SYBYL Line Notation smiles SMILES string
xyz the traditional XYZ format

The syntax is like this: 

d = show("chemical xyz")
d = show("chemical mol")
d = show("chemical hyperchem")

etc.

The result (text string as the value of the variable) may then be displayed, processed, or even may be written to a file using write var d myFile.hin. In this way, Jmol is in fact exporting file formats that it cannot export natively, by using the format conversion server at NCI.

Pop-up menu

These are available: 

File > Save > Save a copy of file

File > Save > Save as PNG/JMOL (image+zip)

File > Save > Save JVXL isosurface

File > Export > Export PNG+JMOL image

The 2nd and 4th are equivalent and contain, packed in a single file, a snapshot PNG image, the coordinates file and the state script file.

Save isosurface

The pop-up menu entry will svae the last isosurface selected or generated. More flexibility is allowed by using the write isosurface command.

Saving Jmol-specific files

Special image files PNGJ

Jmol can export to a PNG file that, in addition of a snapshot of the current molecular rendering, includes the state with all the information of rendering style (PNG) and, optionally, the data of the molecular model (PNGJ). These files appear as regular image files to any software but, when loaded back in Jmol (or drag-and-dropped) will reproduce the exact state of the 3D molecular model.

(The extra non-image information is included in a metadata area allowed by the png format)

Here are the basic commands; for additional options, see the documentation

commands 
write image png "myFileName"
 saves to disk a snapshot image of the current display, including also the state (notes 1, 2 and 3) 
write "myFileName" as png
 does the same as the above one 
set imageState off;
write image png "myFileName"
 saves to disk a snapshot image of the current display, without the state (note 2) 
write image pngj "myFileName"
 saves to disk a snapshot image of the current display, including also the model, state and any files involved in the rendering (note 1) 
write "myFileName" as pngj
 does the same as the above one
(*) Note 1: if the specified file extension is not png, the file will still be a valid png image file, but it may or not be recognized by any software and may not be recognized by Jmol.
Note 2: by default, molecular state is included in the file, unless set imageState has been previously set to false or off.
Note 3: in the case of png files (not pngj), the molecular model file and any isosurface files involved must be in the same folder as the png file in order for the state to be interpreted.


New feature: Allows replacement of PNG data in PNGJ (available since version 14.31.34)

write "fileA.png" as pngj; saves a file containing both the image, the model data and the state
a = load("fileA.png",true); loads the file contents into a (binary) variable
b = load("fileB.png"); loads a regular image file into another (binary) variable
a._IMAGE_ = b._DATA_; puts the binary data making image "B" into the image section of data from file "A" (replacing the existing image data)
write var a "fileC.png"; saves the new combination stored in variable "a", i.e. molecular data from file "A" and image from file "B", into a new PNGJ file

Exporting for augmented reality software

Some users have produced models to be used in augmented reality (AR) software following one of these procedures using Blender:

  • Open the model in Jmol, export as File icon.gifX3D,1 import into Blender, retouch aspect, texture... and export to an File icon.gifFBX file. This latter format may be input into some AR software.
  • Import directly a File icon.gifPDB file into Blender. Sometimes this results in a model with atoms but no bonds (since the PDB format does not necessarily include bond information). In this case, you may open the File icon.gifPDB file into Jmol and export as PDB,2 then load this new file into Blender.
  • For models available in other file formats like File icon.gifSDF, open them in Jmol and export as File icon.gifPDB,2 then open in Blender.

Notes:

1. write ? as x3d

2. write ? as pdb

Contributors

AngelHerraez

Retrieved from "https://wiki.jmol.org/index.php?title=File_formats/Export&oldid=10196"