Difference between revisions of "File formats/3D Objects"

From Jmol
Jump to navigation Jump to search
(some details on X3D format)
(IDTF)
 
(33 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
{{File_Formats}}
 
{{File_Formats}}
= File Formats for 3D Objects Exported from Jmol =
+
= 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, either raytracing or 3D-world.
+
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).
 
 
 
 
== POV-Ray ==
 
Jmol can export, with limited features, the current view of a model into POV-Ray format. This can be done from script or from the pop-up menu, but is better controled using the top menu in the Jmol application, which opens a dialog with options. See [[File_formats/Images#Saving_images_from_Jmol_application | File formats/Images]] for more details.
 
  
  
Line 14: Line 10:
  
 
The {{file|vrml}} or {{file|wrl}} file can then be opened using several programs and browser plugins, and manipulated in 3D using the mouse.
 
The {{file|vrml}} or {{file|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 printing|3D printer]], in order to get a physical model in your hands.
  
 
=== Supported features ===
 
=== Supported features ===
* Atoms (as spheres), bonds (as cylinders):
+
* Atoms (as spheres†), bonds (as cylinders†):
 
** including atom size, bond thickness, color, translucency
 
** including atom size, bond thickness, color, translucency
 
** double bonds (as parallel cylinders)
 
** double bonds (as parallel cylinders)
Line 26: Line 23:
 
* Ribbons and cartoons (using hermiteLevel 1 automatically if necessary).
 
* Ribbons and cartoons (using hermiteLevel 1 automatically if necessary).
 
* Dots, halos, stars, polyhedra, vectors, dipoles, ellipsoids
 
* 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 ===
 
=== Unsupported features ===
Line 40: Line 38:
 
[http://www.blender.org/ Blender] is a free, open source, 3D content creation suite, available for all major operating systems under the GNU General Public License.
 
[http://www.blender.org/ 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 (v. 2.42 or later) using the [http://sourceforge.net/projects/vrml97import/ VRML97-Import-Script].  
+
VRML files created by Jmol can be imported into Blender:
One dependency you might need is [http://simpleparse.sourceforge.net/ SimpleParse].
+
* Newer versions of Blender (e.g. 2.79) import VRML files directly.
 +
* Older versions (2.42 or later) need to use the [http://sourceforge.net/projects/vrml97import/ VRML97-Import-Script]. One dependency you might need is [http://simpleparse.sourceforge.net/ SimpleParse].
  
 
=== Optimizing VRML files ===
 
=== Optimizing VRML files ===
Line 53: Line 52:
 
* [http://www.agocg.ac.uk/train/vrml2rep/contents.htm 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.
 
* [http://www.agocg.ac.uk/train/vrml2rep/contents.htm 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.
 
* [http://www2.hrp.no/vr/tools/chisel/ Chisel (HVRC Edition)], a tool to optimize VRML files.
 
* [http://www2.hrp.no/vr/tools/chisel/ Chisel (HVRC Edition)], a tool to optimize VRML files.
 +
* [http://jmol.org/demo/3dscenes/ Examples] of VRML files produced by Jmol.
  
  
Line 61: Line 61:
 
:''Note:  
 
:''Note:  
 
:There are two X3D variants: one (<code>.x3d</code>) uses [http://www.web3d.org/x3d/specifications/ISO-IEC-19776-X3DEncodings-All-Edition-1/ISO-IEC-19776-1-X3DEncodings-XML/Part01/X3D_XML.html XML encoding], the other (<code>.x3dv</code>) uses [http://www.web3d.org/x3d/specifications/ISO-IEC-19776-X3DEncodings-All-Edition-1/ISO-IEC-19776-2-X3DEncodings-ClassicVRML/Part02/X3D_ClassicVRML.html Classic VRML encoding]. Jmol produces the former.''
 
:There are two X3D variants: one (<code>.x3d</code>) uses [http://www.web3d.org/x3d/specifications/ISO-IEC-19776-X3DEncodings-All-Edition-1/ISO-IEC-19776-1-X3DEncodings-XML/Part01/X3D_XML.html XML encoding], the other (<code>.x3dv</code>) uses [http://www.web3d.org/x3d/specifications/ISO-IEC-19776-X3DEncodings-All-Edition-1/ISO-IEC-19776-2-X3DEncodings-ClassicVRML/Part02/X3D_ClassicVRML.html 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 ===
 
=== References ===
 
* [http://x3dgraphics.com/examples/X3dForWebAuthors/ X3D for Web Authors], by Don Brutzman and Leonard Daly. Examples.
 
* [http://x3dgraphics.com/examples/X3dForWebAuthors/ X3D for Web Authors], by Don Brutzman and Leonard Daly. Examples.
 +
* [http://www.x3dom.org/ 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.
 +
* [http://www.instantreality.org/tools/x3d_encoding_converter/ InstantLabs X3D encoding converter], an online converter from X3D or VRML97 to X3D or (X)HTML5.
 +
* [http://jmol.org/demo/3dscenes/ Examples] of X3D files produced by Jmol.
  
  
Line 71: Line 76:
  
 
=== References ===
 
=== References ===
*[http://download.novedge.com/Brands/Alias/Helps/Maya6.5/en_US/FileFormats/overviewofmayaasciifileformat.html Overview of Maya ASCII file format]
+
*[[File formats/3D Objects/Maya‎|Overview and a description of the Maya ASCII file format]]
*[http://caad.arch.ethz.ch/info/maya/manual/FileFormats/index.html A desciption of the Maya Ascii format]
 
  
 +
== OBJ ==
 +
Jmol (starting v. 12.1.33) can export files into the <code>obj</code> file format. This format is typically generated by [[wikipedia:Wavefront_Technologies|Wavefront]], [https://java3d.dev.java.net/ Java3D] and [http://pymol.sourceforge.net PyMOL].
  
== OBJ ==
+
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:
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 also can be mapped with other data.
+
write myMolecule.obj
 +
 
 +
Two files will be generated: {{file|obj}} and {{file|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 [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 [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.fileformat.info/format/wavefrontobj/egff.htm <code>obj</code> file format] at ''FileFormat.info''.
 
* Description of [http://www.martinreddy.net/gfx/3d/OBJ.spec <code>obj</code> file format] at ''The Graphics File Formats Page'' by Martin Reddy.
 
* 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).
 
* Export of [http://www.pymolwiki.org/index.php/Surface#Exporting_Surface.2FMesh_Coordinates_to_File <code>obj</code> 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 [[File_formats/Images|exporting images]] and choose pdf format in the drop-down list.
 +
 +
For producing pdf files with embedded 3D models, see [[File_formats/3D_PDF|instructions]], but better read first about [[#U3D|U3D]] and [[#IDTF|IDTF]] below.
  
  
Line 87: Line 106:
 
Universal 3D format. ECMA-363 Standard.
 
Universal 3D format. ECMA-363 Standard.
  
'''Not yet supported by Jmol'''.
+
'''Not yet supported directly by Jmol''' (but see [[#IDTF|IDTF]] below).
 +
 
 +
The most interesting feature of this format is that it can be [[File_formats/3D_PDF|embedded in pdf files]], providing a 3D experience inside this well established standard for publication.
  
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|IDTF]] and U3D formats is unsatisfactory, and the future stability of the 3D PDF standard is uncertain.
  
 
=== References ===
 
=== References ===
Line 97: Line 118:
 
: 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.
 
: 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.
 
* [http://85.214.71.72/pdf3d/ 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.
 
* [http://85.214.71.72/pdf3d/ 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.
 +
* [http://jmol.org/demo/3dscenes/ 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|U3D]] format and hence be later [[File_formats/3D_PDF|inserted into pdf files]].
 +
 +
A pair of files is produced by Jmol from any model:
 +
* the {{file|.idtf}} file contains the 3D model data. This can be converted to {{file|.u3d}} format ([[File_formats/3D_PDF#IDTF_to_U3D|read how]])
 +
* the {{file|.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  {{file|.u3d}} or  {{file|.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 (<code>script "filename.pdf"</code>) or the U3D file itself (<code>script "filename.u3d"</code>) back into Jmol.
 +
* Embed a CML source file in the script too, and we would be a step further down semantic publishing.
  
 
== Collada ==
 
== Collada ==
 
Collada formats (KMZ/DAE) are Open Source arrangements that have been
 
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.
+
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.
 
'''Not yet supported by Jmol'''. There is a feature request for this.
Line 112: Line 146:
 
* [http://www.collada.org General information about Collada].
 
* [http://www.collada.org General information about Collada].
 
* [http://www.khronos.org/files/collada_spec_1_5.pdf#page=21 Format specification] (Collada schema).
 
* [http://www.khronos.org/files/collada_spec_1_5.pdf#page=21 Format specification] (Collada schema).
 +
 +
 +
== STL ==
 +
Jmol (14.6.4) can export most features of the model into the '''''[http://en.wikipedia.org/wiki/STL_(file_format) 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 printing|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 <code>set debug true</code>; 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 <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
 +
* OBJ files must be loaded using the <code>isoSurface</code> command and the <code>OBJ</code> flag, e.g. <code>isoSurface OBJ &quot;sample.obj&quot;</code>;
 +
* they can be mapped with other data;
 +
* they can be saved in more compact [[File_formats#JVXL_.28Jmol_Voxel.29 | JVXL format]], if desired.
 +
 +
=== References ===
 +
* 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 [http://www.fileformat.info/format/wavefrontobj/egff.htm <code>obj</code> file format] at ''FileFormat.info''.
 +
* 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).
 +
 +
 +
= 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/Ray_Tracing|File formats for ray tracing images]].
 +
 +
[[3D printing]].

Latest revision as of 23:34, 7 February 2024

File Formats

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 File icon.gifvrml or File icon.gifwrl 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


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

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: File icon.gifobj and File icon.gifmtl 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


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

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 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 File icon.gif.idtf file contains the 3D model data. This can be converted to File icon.gif.u3d format (read how)
  • the File icon.gif.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 File icon.gif.u3d or File icon.gif.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


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


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.