File formats/3D PDF

From Jmol
Revision as of 10:11, 12 June 2011 by AngelHerraez (talk | contribs) (Clarify that intermediate files are not available - file icons may create confusion)
Jump to navigation Jump to search

PDF documents with integrated 3D interactive models

Installations

Jmol

You need at least version 12.0.RC26 to do this.

IDTF to U3D

(See also descriptions and comments for Jmol output to IDTF and U3D formats.)

Conversion from IDTF to U3D can be done using a simple command-line utility, IDTFConverter.

  • Windows installation of IDTFConverter
  1. The converter is available from Universal 3D Sample Software and from Michail Vidiassov's site (see refs. below). Download and unzip into, perhaps, File icon.gifc:\idtf\
  2. Create a simple command file File icon.gifu3d.bat and place it in a folder where it is easily accessible (e.g. the Windows directory or a folder included in the system's path). This File icon.gifu3d.bat file must contain this text:
c:\idtf\idtfconverter.exe -input %1.idtf -output %1.u3d
  • MacOS and Linux installation of IDTFConverter
  1. You can get a port of IDTFConverter from Michail Vidiassov's site (see refs. below).
  2. Create a command file similarly to the one described for Windows.

References

You need to extract the contents of File icon.gifBin/Win32/Release/: several files and the File icon.gifPlugins folder (that makes 4.46 MB out of the total 137 MB in the zipfile; you may probably dispense with the HelloWorld.exe, SamplePlayer.exe, TrueType.exe files).
You need to extract the contents of File icon.gifu3dIntelWin/: several files and the File icon.gifPlugins folder; the File icon.gifdoc/ and File icon.gifsamples/ folders are not essential (that makes 4.46 MB out of the total 29 MB in the zipfile; you may probably dispense with the HelloWorld.exe, SamplePlayer.exe, TrueType.exe files).

LaTeX to PDF

There are several pdfLatex software, like teTeX (Unix; discontinued in 2006), MiKTeX (Windows), TeX Live (Unix, Linux, Windows), MacTeX...

  • Installation of MiKTeX (Windows)
  1. Download and install MiKTeX "basic" from http://miktex.org/
  2. Do an update (menu Programs > MiKTeX > Maintenance > Update).
  3. Download the movie15 package (menu Programs > MikTex > Maintenance > Package Manager).
  • You can avoid installing software and use instead an online service like ScribTeX (they have a Free Plan that gives you 50 MB storage space; you can even test-run it without signing up).

Creating the document

1. Within Jmol script console: write c:/temp/xxx.idtf

or from the application's pop-up menu: File > Export IDTF 3D model (a dialog prompts for destination folder and filename).
Either of those will create two files: File icon.gifxxx.idtf and File icon.gifxxx.idtf.tex

2. At the system command line or terminal, call the File icon.gifu3d.bat file (Windows), or equivalent MacOS or Linux command file, to convert the File icon.gif.idtf to File icon.gif.u3d format:

u3d c:\temp\xxx

If using MikTeX:

3.1. Run the TeXworks program --included in MiKTeX-- and open in it your File icon.gifxxx.idtf.tex.
3.2. Click menu item Typeset > Typeset, or click on the green 'play'-like button (leftmost in the toolbar).
When processing ends, you will see a blank document in a new TeXworks window, because MiKTeX can't display the model, but File icon.gifxxx.idtf.pdf should have been created.

If using ScribTeX:

3.1. Go the ScribTeX website, sign up or use the guest account.
3.2. Click on [Upload file] and select in turn your File icon.gifxxx.idtf.tex and File icon.gifxxx.u3d files (or a File icon.gif.zip file containing both, it will be automatically unzipped in the server).
3.3. In the file listing on the server, click on the File icon.gifxxx.idtf.tex file to display it, then click on [Compile].
3.4. When the File icon.gif.pdf file opens in the browser, click on the [Save copy as] button in your viewer's toolbar, to store it in your local disk.

4. Open the File icon.gif.pdf file using a reader/viewer that supports 3D PDF (see a list below).

If you don't see the model in its panel inside the document, right-click on it and choose Partial options > Fit visible

Caveats

  • If you move in Jmol the model rotation center away from screen center (as with CTRL-ALT-drag), the model in the 3D PDF will be a very close but not quite perfect reproduction. (The reason for this is that moving the center of perspective seems to be not supported in virtual reality formats like VRML and U3D.)
  • Lighting is not working properly: the light moves with the model. If someone knows how to do that, please let us know.
  • Perspective canot be orthographic from the beginning (Jmol uses this by default for crystal structures). Once in the 3D PDF, there is a right-mouse-button option to go into that mode. Please let us know if you know how to do that.
  • Don't expect rotation and translation using the mouse in the 3D PDF to be like in Jmol. It is harder to control, and you can even completely loose the rotation center.
  • For large models (big proteins, surfaces, electron density maps), files are quite big, and seeing and manipulating the model in the PDF will need substantial computer power. To alleviate this, you can try to set the image frequency to a lower value in the Reader's 3D options and/or to change the optimisation method for small frequency to 'Abandon'. Also, if you are using it in a presentation, it is a good idea to preload the PDF document in the Reader ahead of time.

Documents with text

In order to have text, images etc. alongside the 3D model, ideally you need a full PDF editor, which is normally commercial like Adobe Acrobat Pro.

As an alternative, some of the freeware PDF viewers, like PDF-XChange Viewer, allow you to add text and images onto the generated 3D PDF and save the modified document.

The best freeware way to create a full pdf-presentation including 3D objects, text and other images is by using pdflatex with the Beamer package. See the Beamer wikipedia page for more information about Beamer.

Sample documents

(Text in these documents has been added externally to the process descrbed here.)

File sizes were: File icon.gif.hin 5 kB; File icon.gif.idtf 121 kB; File icon.gif.u3d 47 kB; File icon.gif.pdf 18 kB.
  • 3D PDF with a small protein, crambin (1crn.pdb), in cartoon rendering.
  • 3D PDF with a polyhedra rendering of quartz.
  • 3D PDF with a carbon nanotube, ball and stick and molecular surface.
File sizes were: File icon.gif.hin 16 kB; File icon.gif.idtf 1800 kB; File icon.gif.u3d 182 kB; File icon.gif.pdf 113 kB.

Software for creating or viewing 3D PDF

(This aims to be a compilation of resources; if you know of another software, please add it here).

3D PDF Viewers

  • Adobe Reader v.7 or later (proprietary, freeware). Note that the latest Adobe Reader v.9 renders the 3D object more nicely than v.8 and v.7. In v.9 it is possible to remove the compass that appears by default in the lower left corner via the Reader's 3D content options. No other PDF viewers are known to be able to display interactive 3D data.

3D PDF Editors

  • Adobe Acrobat Pro Extended (proprietary, commercial).
Note that you do not create the 3D model using Adobe; you just insert or embed it from an available File icon.gif.u3d file that you have prepared with another software (like Jmol + IDTFConverter). The Adobe editor will mainly serve to position the 3D model within the page and to insert the other content of the document.

Bibliography

Related articles:

1. Grasping molecular structures through publication-integrated 3D models.

(2008) P. Kumar, A. Ziegler, J. Ziegler, B. Uchanska-Ziegler & A. Ziegler. Trends in Biochemical Sciences 33:408-412.
doi:j.tibs.2008.06.004
3DPDF version of the article (3.63 MB)
Here, we describe how an interactive 3D model of a molecular complex can be embedded directly into a PDF, thus providing readers with important and educational visual information that would otherwise be more difficult to disseminate.
They use Pymol + Adobe to produce the 3D PDF.

2. A step-by-step guide to creating PDF-integrated 3D models.

(Published online as Supplementary Material to #1)
Part 1: PyMOL ~ Part 2: Adobe 3D Reviewer ~ Part 3: PDF Export (Acrobat 9 Pro Extended)
http://www.charite.de/immungenetik/model3d.html
Pymol exports to VRML2; Adobe 3D Reviewer imports that and exports to U3D; Acrobat 9 Pro Extended is used to insert and finish off the 3D model in the PDF.

3. Incorporating interactive 3-dimensional graphics in astronomy research papers.

(2008) D. G. Barnes, C. J. Fluke. New Astronomy 13:599-605.
arXiv:0709.2734; doi:10.1016/j.newast.2008.03.008.
related wiki article.
The authors use the three dimensional plotting library S2PLOT to write a 3D object to VRML97 format and use then Adobe Acrobat 3D to embed it in a pdf document.

Contributors

AngelHerraez, Vdlee