File formats/3D Objects

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 3D-world Objects Exported from Jmol

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 (3D-world or 3D-scenes).

VRML

Jmol can export most features of the model into Virtual Reality Modeling Language, VRML version 2, also known as VRML97. This can be done from script or from the pop-up menu.

The vrml or wrl file can then be opened using several programs and browser plugins, and manipulated in 3D using the mouse. It is also one of the common formats for sending to a 3D printer, in order to get a physical model in your hands.

Supported features

• Atoms (as spheres†), bonds (as cylinders†):
  • including atom size, bond thickness, color, translucency
  • double bonds (as parallel cylinders)
• Drawn objects (lines, arrows, triangles...).
• Isosurfaces (as IndexedFaceSets), even map-colored.
• Labels, 3D-positioned echo texts and measurement texts:
  • text, color, font family and font style
• Trace (but slightly irregular if its diameter is very small)
• Ribbons and cartoons (using hermiteLevel 1 automatically if necessary).
• Dots, halos, stars, polyhedra, vectors, dipoles, ellipsoids

† Note: Starting with 14.6.4, Jmol exports using only meshes (not spheres, cylinders or cones); this was done to improve compatibility with 3D printing software. As a result, atoms are not spheres, but polyhedra with many faces (visible when zooming in closely)

Unsupported features

• The orientation and zoom are not always kept.
• Labels, 3D-positioned echo texts and measurement texts:
  • font size and offset are fixed (but they follow zoom in the VRML viewer)
  • only 1st line is displayed, no multi-line texts
  • alignment is always left
  • no background labels
• Background image
• Ellipsoid quadrant cutouts

From Jmol to Blender

Blender is a free, open source, 3D content creation suite, available for all major operating systems under the GNU General Public License.

VRML files created by Jmol can be imported into Blender:

• Newer versions of Blender (e.g. 2.79) import VRML files directly.
• Older versions (2.42 or later) need to use the VRML97-Import-Script. One dependency you might need is SimpleParse.

Optimizing VRML files

VRML files of medium to large molecules tend to be huge. Some ways to reduce their size:

• Run them through an optimizer program (see refs. below)
• Compress them using the gzip algorithm, and maybe rename to .wrz which is the standard extension and should (hopefully) be recognized by viewers and browsers.

References

• The Annotated VRML 97 Reference, by Rikk Carey and Gavin Bell. Online documentation for the VRML format, including examples.
• A Guide to VRML 2.0 and an Evaluation of VRML Modelling Tools, by Neil Ashdown and Simon Forestiero. Online documentation for the VRML format.
• Chisel (HVRC Edition), a tool to optimize VRML files.
• Examples of VRML files produced by Jmol.

X3D

This is the Extensible 3D Graphics format, an XML successor of VRML.

Jmol (v.11.8) supports exporting to X3D. Features are nearly identical to those of VRML. (See VRML for details)

Note:

There are two X3D variants: one (.x3d) uses XML encoding, the other (.x3dv) uses Classic VRML encoding. Jmol produces the former.

There is a move to integrate X3D into (X)HTML 5. This would allow future web browsers to display 3D content natively, without any plugins or applets.

References

• X3D for Web Authors, by Don Brutzman and Leonard Daly. Examples.
• X3DOM is an experimental open source framework and runtime to support the ongoing discussion in the Web3D and W3C communities how an integration of HTML5 and declarative 3D content could look like. It tries to fulfill the current HTML5 specification for declarative 3D content and allows including X3D elements as part of any HTML5 DOM tree.
• InstantLabs X3D encoding converter, an online converter from X3D or VRML97 to X3D or (X)HTML5.
• Examples of X3D files produced by Jmol.

Maya

Jmol can export, with limited features, the current view of a model into Maya ascii format. This can be done from script or from the pop-up menu. Wikipedia info on Maya

References

• Overview and a description of the Maya ASCII file format

OBJ

Jmol (starting v. 12.1.33) can export files into the obj file format. This format is typically generated by Wavefront, Java3D and PyMOL.

This option is not available from either the top menu or the popup menu; it must be done from the console (command line) or from a script file. This syntax is enough:

write myMolecule.obj

Two files will be generated: obj and mtl with the same filename, which includes the needed materials information. The 2nd is referenced from the 1st, so you should keep them together for loading into any other software. (If the materials file is missing your model will be monochrome.)

Note that in these OBJ files, atoms are true spheres and not many-faced-polyhedra. This is different to what is obtained by converting other Jmol-exported formats (VRML, X3D, STL) to OBJ format in external software like Blender.

References

• Description of obj file format at EG-Models.de, an archive of electronic geometry models.
• Description of obj file format at FileFormat.info.
• Description of obj file format at The Graphics File Formats Page by Martin Reddy.
• Export of obj file format from PyMOL (molecular surfaces).

PDF

(Adobe's Portable Document Format)

Jmol can export an image of the model into a pdf document (single page, just the image in the center). Just use the methods for exporting images and choose pdf format in the drop-down list.

For producing pdf files with embedded 3D models, see instructions, but better read first about U3D and IDTF below.

U3D

Universal 3D format. ECMA-363 Standard.

Not yet supported directly by Jmol (but see IDTF below).

The most interesting feature of this format is that it can be embedded in pdf files, providing a 3D experience inside this well established standard for publication.

There are, however, some problems in implementing this format in Jmol and so in successfully producing PDF files more directly. The major limitations are related to the setting of a default view/orientation, or of alternative views, and of a rotation center. The documentation on the available IDTF and U3D formats is unsatisfactory, and the future stability of the 3D PDF standard is uncertain.

References

• Universal 3D Sample Software project at SourceForge.

A set of libraries to write, read, extend, render and interact with U3D-formatted data, as defined by standard ECMA-363. Intended as starting point for tools and applications to support U3D (exporters, importers, authoring packages and interactive viewers).

• MeshLab project at SourceForge.

MeshLab is the first open source tool to provide direct conversion of 3D meshes into the U3D format. Now you can create pdf with 3D objects with just MeshLab and LaTeX.

• This page holds a demo that generates a 3D model in PDF from the molecule's PubChem CID. It also allows to download the result in PDF, U3D and IDTF formats.
• Examples of U3D files, generated from IDTF produced by Jmol.

IDTF

Jmol (11.8) can export to the Intermediate Data Text Format, a human-readable format that can be transformed into the binary U3D format and hence be later inserted into pdf files.

A pair of files is produced by Jmol from any model:

• the .idtf file contains the 3D model data. This can be converted to .u3d format (read how)
• the .idtf.tex file contains the Jmol state (in a Tex comment) and a bit of TeX code that sets the zoom correctly. This may be used by some software while producing the .u3d or .pdf formats.

Some potential future improvements:

• Bypass IDTF completely and go straight to U3D export from Jmol. The compression algorithm must be understood first.
• Embed the Jmol state script in the U3D file, so one can load the pdf file itself (script "filename.pdf") or the U3D file itself (script "filename.u3d") back into Jmol.
• Embed a CML source file in the script too, and we would be a step further down semantic publishing.

Collada

Collada formats (KMZ/DAE) are Open Source arrangements that have been incorporated into many 3D packages and support textures/surfaces etc. They are a possible XML replacement to VRML and are the format apparently supported by the new Apple textbook authoring system iBooks author.

Not yet supported by Jmol. There is a feature request for this.

We would need:

• A description of how to specify a cylinder (position/translation, orientation/rotation, radius, length) but not using vertexes or meshes.
• A description of how to specify a sphere (position/translation, orientation/rotation, radius) but not using vertexes or meshes.

References

• General information about Collada.
• Format specification (Collada schema).

STL

Jmol (14.6.4) can export most features of the model into the STL (STereoLithography) format. This can be done from script or from the pop-up menu, only from the Jmol application and the JSmol-Java modality.

This is a popular format for sending to a 3D printer, in order to get a physical model in your hands. Note, however, that the STL format does not support colors, so the whole model will have a single color.

Jmol can export both the binary and text formats:

• binary STL is produced by default
• ASCII STL may be produced by first issuing set debug true; note that files will be very large in size

File Formats for 3D-world Objects Imported by Jmol

OBJ

Jmol (starting v. 11.7.28) can read files in the obj file format. This format is generated by Wavefront, Java3D and PyMOL. The described objects are handled as isosurfaces in Jmol, so

• OBJ files must be loaded using the isoSurface command and the OBJ flag, e.g. isoSurface OBJ "sample.obj";
• they can be mapped with other data;
• they can be saved in more compact JVXL format, if desired.

References

• Description of obj file format at EG-Models.de, an archive of electronic geometry models.
• Description of obj file format at FileFormat.info.
• Description of obj file format at The Graphics File Formats Page by Martin Reddy.
• Export of obj file format from PyMOL (molecular surfaces).

Troubleshooting

• Exporting from the Jmol script console may fail if your current path has spaces or non-English characters (executing the command reports nothing and does nothing). Move your files to a folder with a simple path before trying to export.

See also

File formats for ray tracing images.

3D printing.

Contributors

AngelHerraez, Michaelrandolph, NicolasVervelle, Kmcallenberg, Rzepa