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

From Jmol
Jump to navigation Jump to search
(→‎LaTeX to PDF)
(→‎Sample documents)
 
(49 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
= PDF documents with integrated 3D interactive models =
 
= PDF documents with integrated 3D interactive models =
 +
== Easy procedure ==
 +
This is currently the easiest way to create a PDF document containing an interactive 3D molecular model, using only
 +
'''free software''' under '''Windows'''.
  
 +
(This is a brief description; if needed, extra information may be found in the next section below)
 +
 +
# Create a PDF document with the text and images from your preferred application (e.g. Word or Powerpoint), leaving enough blank spaces where you would position the 3D molecular models. If your application cannot export to PDF directly, you may use a virtual PDF printer like [https://www.pdfforge.org/ PDFforge PDF Creator] or [https://www.tracker-software.com/product/pdf-xchange-lite PDF-XChange Lite Printer] (both available for free).
 +
# Download and install '''IDTFConverter'''; create a {{file|u3d.bat}} file for convenience (see below for addresses and details).
 +
# Download and install [https://www.tracker-software.com/product/pdf-xchange-editor '''PDF-XChange Editor'''] (free version); you need 8.0.332 at least (26 Aug. 2019)
 +
# Get a current version of '''Jmol'''. Open your molecule; display it in the desired orientation and style.
 +
#* ''Suggestion: make the Jmol window square'', using <code>top menu > Display > Resize</code> and enterung two equal numbers.
 +
#* Export to an image file (that will be used as ''poster image'' to be displayed in the pdf until the 3D is enabled) using either
 +
#** <code>top menu > File > Export > Export image</code> and selecting <code>Image type: PNG > Save</code>
 +
#** or <code>pop-up menu > File > Export > Export PNG image > Save</code>
 +
#** ''Note:'' Make sure to include the <code>.png</code> file extension with the chosen filename (Jmol will not add it)
 +
#* Using the console, export the model to IDTF format: <code>write myMol.idtf</code>
 +
# Two files have been created: {{file|myMol.idtf}} and {{file|myMol.idtf.tex}}. Copy them to the folder where you have IDTFConverter, open the command line there and run the conversion: <code>u3d.bat myMol</code>.  That will create a {{file|myMol.u3d}}
 +
# Open the previous PDF file into PDF-XChange Editor. Find the place where your left blank space.  To insert a ''3D annotation'':
 +
#* If you are using the Ribbon interface: <code>Comment > Add 3D</code>
 +
#* If you are using the classical Toolbar interface: <code>Tools > Media tools > Add or edit 3D annotations</code>
 +
#: Draw the rectangle area with the mouse. ''Suggestion:'' draw a square by holding the Shift key while dragging to define the area.
 +
#* <code>3D Artwork</code>: select your {{file|myMol.u3d}} file.
 +
#* <code>Appearance > Poster > Create poster from file</code> and select the png file you previously saved from Jmol.
 +
#* Choose among any other options offered for display (like border and background color)
 +
#* Accept and save the file.
 +
# Check the 3D display in a PDF viewer application. Note that not all viewers support this kind of 3D content. At least, Adobe Reader and PDF-XChange Editor support 3D objects.
 +
 +
== Sample documents ==
 +
This has been created following the above procedure
 +
* [[:File:Cys_3D.pdf|Cysteine]]
 +
* [[:File:Ala_3D.pdf|Alanine]]
 +
 +
= Older reference =
 
== Installations ==
 
== Installations ==
 
=== Jmol ===
 
=== Jmol ===
Line 8: Line 40:
 
(See also descriptions and comments for Jmol output to [[File_formats/3D_Objects#IDTF|IDTF]] and [[File_formats/3D_Objects#U3D|U3D]] formats.)
 
(See also descriptions and comments for Jmol output to [[File_formats/3D_Objects#IDTF|IDTF]] and [[File_formats/3D_Objects#U3D|U3D]] formats.)
  
−
* ''Windows'' installation of IDTFConverter
+
Conversion from IDTF to U3D can be done using a simple command-line utility, IDTFConverter.
−
# Download and unzip http://www.iaas.msu.ru/tmp/u3d/u3dIntelWin.zip into, perhaps, {{file|c:\idtf\}}
+
 
−
# Create a simple command file {{file|u3d.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|u3d.bat}} file must contain this text:
+
* '''''Windows''''' installation of IDTFConverter
−
:: <code>c:\idtf\idtfconverter.exe -input %1.idtf -output %1.u3d</code>
+
# The converter is available from Universal 3D Sample Software [ref.1 below] and from Michail Vidiassov's site [ref.2 below]. Download the latest {{file|U3D_A_??.zip}} file. You only need a subset of the files in that package:
 +
#: Extract (unzip) the contents of {{folder|Bin/Win32/Release/}}  (that makes 4.46 MB out of the total 137 MB in the zipfile). From that,
 +
#: '''You need (minimal functional set of files)''': {{file|IDTFConverter.exe}}, {{file|IDTFExporter.dle}}, {{file|IFXCore.dll}} and the {{folder|Plugins}} folder
 +
#: '''You do not need''': {{file|HelloWorld.exe}}, {{file|SamplePlayer.exe}}, {{file|TrueType.exe}}
 +
#: A {{file|readme.txt}} file may be useful documentation, not essential.
 +
# Put those extracted files and folder in a location of your convenience, like {{file|c:\idtf\}}
 +
# In that location, create a simple command file {{file|u3d.bat}}. This plain text file must contain this text:
 +
#: <code>idtfconverter.exe -input %1.idtf -output %1.u3d</code>
 +
# Then put in that same location the <code>.idtf</code> and <code>.idtf.tex</code> files you want to convert (produced by Jmol), open the command line window (a.k.a. terminal) in that location and type
 +
#: <code>u3d ''yourFileName''</code>  (do not include the extension)
 +
# That will generate the corresponding <code>.u3d</code> file
  
−
* ''MacOS and Linux'' installation of IDTFConverter
+
* '''''MacOS and Linux''''' installation of IDTFConverter
−
# See [[File_formats/3D_Objects#IDTF|IDTF]] for instructions on getting the converter.
+
# You can get a port of IDTFConverter from Michail Vidiassov's site (ref.3 below).
 
# Create a command file similarly to the one described for Windows.
 
# Create a command file similarly to the one described for Windows.
 +
 +
==== References ====
 +
# ''Windows:'' [http://sourceforge.net/projects/u3d/ Universal 3D Sample Software] (at SourceForge). Go to 'View All Files' and download the latest {{file|U3D_A_??.zip}}
 +
# ''Windows:'' Alternatively, get just the necessary files from (''broken link'') http://www2.iaas.msu.ru/tmp/u3d/u3dIntelWin.zip (thanks to Michail Vidiassov).
 +
#: You need to extract the contents of {{file|u3dIntelWin/}}: several files and the {{file|Plugins}} folder; the {{file|doc/}} and {{file|samples/}} 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).
 +
# ''MacOS and Linux:'' A port of the software is available as {{file|u3d-1.2.852.tar.gz}} or, possibly, a newer version, at (''broken link'') http://www2.iaas.msu.ru/tmp/u3d/ (thanks to Michail Vidiassov).
  
 
=== LaTeX to PDF ===
 
=== LaTeX to PDF ===
−
There are several '''pdfLatex''' software, like '''[http://www.tug.org/tetex/ teTeX]''' (Unix; discontinued in 2006), '''MiKTeX''' (Windows), '''[http://www.tug.org/texlive/ TeX Live]''' (Unix, Linux, Windows)...
+
There are several '''pdfLatex''' software, like '''[http://www.tug.org/tetex/ teTeX]''' (Unix; discontinued in 2006), '''[http://miktex.org/ MiKTeX]''' (Windows), '''[http://www.tug.org/texlive/ TeX Live]''' (Unix, Linux, Windows), '''[http://www.tug.org/mactex/2009/ MacTeX]'''...
−
 
 
  
 
* Installation of MiKTeX (Windows)
 
* Installation of MiKTeX (Windows)
 
# Download and install '''MiKTeX "basic"''' from http://miktex.org/
 
# Download and install '''MiKTeX "basic"''' from http://miktex.org/
−
# Do an update (menu <code>Programs > MiKTeX > Maintenance > Update</code>)
+
# Do an update (menu <code>Programs > MiKTeX > Maintenance > Update</code>).
−
# Download the '''movie15''' package (menu <code>Programs > MikTex > Maintenance > Package Manager</code>)
+
# Download the '''movie15''' package (menu <code>Programs > MikTex > Maintenance > Package Manager</code>).
 +
 
 +
* You can avoid installing software and use instead an '''online service''' like '''[http://www.scribtex.com/ 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 ==
 
== Creating the document ==
 
1. Within Jmol script console: <code>write c:/temp/xxx.idtf</code>  
 
1. Within Jmol script console: <code>write c:/temp/xxx.idtf</code>  
−
: or from the application's pop-up menu: <code>File > Export IDTF 3D model</code> (a dialog prompts for destination folder and filename).
+
<!--: or from the application's pop-up menu: <code>File > Export IDTF 3D model</code> (a dialog prompts for destination folder and filename).
−
: Either of those will create two files: {{file|xxx.idtf}} and {{file|xxx.idtf.tex}}
+
: Either of those
 +
-->
 +
: This will create two files: {{file|xxx.idtf}} and {{file|xxx.idtf.tex}}
 +
 
 +
''Note'': by default, the final PDF will be a letter-sized page (215.9&times;279.4 mm, 8.5&times;11 inches). If you want instead an A4-sized page (210&times;297 mm), edit now the {{file|xxx.idtf.tex}} file, look for the line that says
 +
documentclass[12pt,letter]{article}
 +
and replace with
 +
documentclass[12pt,a4paper]{article}
  
 
2. At the system command line or terminal, call the {{file|u3d.bat}} file (Windows), or equivalent MacOS or Linux command file, to convert the {{file|.idtf}} to {{file|.u3d}} format:
 
2. At the system command line or terminal, call the {{file|u3d.bat}} file (Windows), or equivalent MacOS or Linux command file, to convert the {{file|.idtf}} to {{file|.u3d}} format:
 
: <code>u3d c:\temp\xxx</code>
 
: <code>u3d c:\temp\xxx</code>
  
−
3. Run the '''TeXworks''' program --included in MiKTeX-- and open in it your {{file|xxx.idtf.tex}}.
+
''If using MikTeX:''
 +
 
 +
:3.1. Run the '''TeXworks''' program --included in MiKTeX-- and open in it your {{file|xxx.idtf.tex}}.
  
−
4. Click menu item <code>Typeset > Typeset</code>, or click on the green 'play'-like button (leftmost in the toolbar).
+
:3.2. Click menu item <code>Typeset > Typeset</code>, 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|xxx.idtf.pdf}} should have been created.
 
: When processing ends, you will see a blank document in a new TeXworks window, because MiKTeX can't display the model, but {{file|xxx.idtf.pdf}} should have been created.
  
−
5. Open the {{file|.pdf}} file using Adobe Reader v. 7 or later.
+
''If using ScribTeX:''
 +
 
 +
:3.1. Go the [http://www.scribtex.com/ ScribTeX website], sign up or use the guest account.
 +
 
 +
:3.2. Click on [<code>Upload file</code>] and select in turn your {{file|xxx.idtf.tex}} and {{file|xxx.u3d}} files (or a {{file|.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|xxx.idtf.tex}} file to display it, then click on [<code>Compile</code>].
 +
 
 +
:3.4. When the {{file|.pdf}} file opens in the browser, click on the [<code>Save copy as</code>] button in your viewer's toolbar, to store it in your local disk.
 +
 
 +
4. Open the {{file|.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 <code>Partial options > Fit visible</code>
 
: If you don't see the model in its panel inside the document, right-click on it and choose <code>Partial options > Fit visible</code>
 +
 +
=== 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 [https://www.tracker-software.com/product/pdf-xchange-editor PDF-XChange Editor], 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 [http://bitbucket.org/rivanvx/beamer/wiki/Home Beamer package]. See the [http://en.wikipedia.org/wiki/Beamer_(LaTeX) Beamer wikipedia] page for more information about Beamer.
 +
 +
== Sample documents ==
 +
(Text in these documents has been added externally to the process described here.)
 +
 +
* 3D PDF with an [http://biomodel.uah.es/Jmol/3d-pdf/dan002.pdf organic molecule], ball and stick.
 +
: File sizes were: {{file|.hin}} 5 kB; {{file|.idtf}} 121 kB; {{file|.u3d}} 47 kB; {{file|.pdf}} 18 kB.
 +
* 3D PDF with a small protein, [http://chemapps.stolaf.edu/jmol/docs/examples-11/pdf/test1.idtf.pdf crambin] (1crn.pdb), in cartoon rendering.
 +
* 3D PDF with a polyhedra rendering of [http://chemapps.stolaf.edu/jmol/docs/examples-11/pdf/quartzPolyhedra.idtf.pdf quartz].
 +
* 3D PDF with a carbon [http://biomodel.uah.es/Jmol/3d-pdf/nanotube.pdf nanotube], ball and stick and molecular surface.
 +
: File sizes were: {{file|.hin}} 16 kB; {{file|.idtf}} 1800 kB; {{file|.u3d}} 182 kB; {{file|.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.
 +
: Display of 3D objects may be disabled by default. You may enable it either by '''trusting''' the document or by setting: ''Preferences > Multimedia & 3D > Enable Playing of Multimedia and 3D content''.
 +
* [https://www.pdf-xchange.com/product/pdf-xchange-editor PDF-XChange Editor] v.7.0.327 or later (from PDF-XChange Co. Ltd., formerly Tracker Software; proprietary, there is a free version). It can display 3D models embedded in the PDF if they were created in the [[File_formats/3D_Objects#U3D|U3D]] format (but currently not if created in the PRC format).
 +
* [https://www.foxit.com/pdf-reader/ Foxit PDF Reader] version 12 or later includes support for displaying embedded 3D models. For previous versions 9, 10, 11, you need to install the [https://www.foxitsoftware.com/pdf-editor/addons.php 3D plug-in]. ''Note:'' support and performance are poorer, in our hands, than with PDF-XChange.
 +
: Display of 3D objects may be disabled by default. You may enable it either by '''trusting''' the document or by setting: ''File > Preferences > 3D > Enable the playing of 3D content''.
 +
* Tech Soft 3D PDF Reader, for Android systems (supported on Android version 4 and up, but unsupported on version 9, maybe before)
 +
* Most other PDF viewers are not 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|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.
 +
* [https://www.pdf-xchange.com/product/pdf-xchange-editor PDF-XChange Editor] v.8.0.332 or later (from PDF-XChange Co. Ltd., formerly Tracker Software) can insert a 3D model from a [[File_formats/3D_Objects#U3D|U3D]] format file in an existing pdf document. This is possible both with the free and paid/licensed versions. If you have the licensed version, you can also do it with a newly created blank pdf document.
 +
* [https://www.foxit.com/pdf-editor/ Foxit PDF Editor Pro] (not free software) allows to insert a 3D model (in either {{file|u3d}} or {{file|prd}} formats) to a PDF page. Note that Jmol can only produce {{file|u3d}} files, not {{file|prd}} files.
 +
* [http://www.share3d.com/ Share3D PDF], by Quadrispace, looks like a promising solution to easily produce 3D-containing pdf documents at a reasonable price and with a nice set of features. Unfortunately, it doesn't seem to import any of the 3D formats that Jmol can produce.
 +
* [https://sourceforge.net/projects/u3d2pdf/ U3D-2-PDF] seems to be a user-friendly freeware tool that drives MeshLab and MiKTeX to facilitate the procedure from a {{file|wrl}} file to a {{file|pdf}} document. (Requires MiKTeX, MeshLab and .NET Framework 4 installed; all freeware)
 +
* Aspose offers a [https://products.aspose.app/3d/conversion free online converter] that will create a {{file|pdf}} document with the 3D model embedded, from an {{file|[[File_formats/3D_Objects#OBJ|obj+mtl]]}} pair of files generated by Jmol. The result is not very satisfactory: model is zoomed in far to much to be visible, with no hints for the user to zoom out. Choose PDF in the "save as" drop-down menu. The document will be of US-letter size.
 +
 +
= 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.
 +
: [http://dx.doi.org/10.1016/j.tibs.2008.06.004 doi:j.tibs.2008.06.004]
 +
: [http://www.sciencedirect.com/science/MiamiMultiMediaURL/B6TCV-4T3KP8R-1/B6TCV-4T3KP8R-1-6/5180/html/S0968000408001473/3435de14e2669d4c0f5671aae383fcdf/mmc2.pdf 3DPDF version of the article] (3.63 MB)
 +
: <cite>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.</cite>
 +
: 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.
 +
: [http://arxiv.org/abs/0709.2734 arXiv:0709.2734]; [https://dx.doi.org/10.1016/j.newast.2008.03.008 doi:10.1016/j.newast.2008.03.008].
 +
: related [http://astronomy.swin.edu.au/s2plot/index.php?title=S2PLOT:3dPDF wiki] article.
 +
: The authors use the three dimensional plotting library [http://astronomy.swin.edu.au/s2plot/index.php?title=S2PLOT S2PLOT] to write a 3D object to VRML97 format and use then Adobe Acrobat 3D to embed it in a pdf document.
 +
 +
4. '''Leaving the structural ivory tower, assisted by interactive 3D PDF'''.
 +
: (2010) P. Kumar, A. Ziegler, A. Grahn, C.S. Hee, A. Ziegler. ''Trends Biochem. Sci.'' '''35''':419-422 [https://doi.org/10.1016/j.tibs.2010.03.008 doi:10.1016/j.tibs.2010.03.008].
 +
 +
5. '''Embedding and publishing interactive, 3-dimensional, scientific figures in portable document format (PDF) files'''.
 +
: (2013) D. Barnes, M. Vidiassov, B. Ruthensteiner, C. Fluke, M. Quayle, C. Colin. ''PLOS One'' '''8''':e69446 [https://doi.org/10.1371/journal.pone.0069446 doi:10.1371/journal.pone.0069446].
 +
:: They do not use the U3D format, but PRC instead.
 +
 +
6. '''Towards an easier creation of three-dimensional data for embedding into scholarly 3D PDF (Portable Document Format) files'''.
 +
: (2015) A. Newe. ''PeerJ'' '''3''':e794 [https://doi.org/10.7717/peerj.794 doi:10.7717/peerj.794].
 +
 +
7. '''Enriching scientific publications with interactive 3D PDF: an integrated toolbox for creating ready-to-publish figures'''.
 +
: (2016) A. Newe. ''PeerJ Comput. Sci.'' '''2''':e64 [https://doi.org/10.7717/peerj-cs.64 doi:10.7717/peerj-cs.64].
 +
 +
8. '''On the use of PDF-3D to overcome spatial visualization difficulties linked with ternary
 +
phase diagrams'''.
 +
: (2019) D. Vergara, M. P. Rubio and M. Lorenzo. ''Education Sciences'' '''9''':67 [https://doi.org/10.3390/educsci9020067 doi:10.3390/educsci9020067].
 +
:: Reports on generating 3D-PDF via OBJ file to (Adobe Photoshop) U3D to (Adobe Acrobat) PDF. Note: Jmol can export models to the OBJ format.

Latest revision as of 15:31, 25 April 2024

PDF documents with integrated 3D interactive models

Easy procedure

This is currently the easiest way to create a PDF document containing an interactive 3D molecular model, using only free software under Windows.

(This is a brief description; if needed, extra information may be found in the next section below)

  1. Create a PDF document with the text and images from your preferred application (e.g. Word or Powerpoint), leaving enough blank spaces where you would position the 3D molecular models. If your application cannot export to PDF directly, you may use a virtual PDF printer like PDFforge PDF Creator or PDF-XChange Lite Printer (both available for free).
  2. Download and install IDTFConverter; create a File icon.gifu3d.bat file for convenience (see below for addresses and details).
  3. Download and install PDF-XChange Editor (free version); you need 8.0.332 at least (26 Aug. 2019)
  4. Get a current version of Jmol. Open your molecule; display it in the desired orientation and style.
    • Suggestion: make the Jmol window square, using top menu > Display > Resize and enterung two equal numbers.
    • Export to an image file (that will be used as poster image to be displayed in the pdf until the 3D is enabled) using either
      • top menu > File > Export > Export image and selecting Image type: PNG > Save
      • or pop-up menu > File > Export > Export PNG image > Save
      • Note: Make sure to include the .png file extension with the chosen filename (Jmol will not add it)
    • Using the console, export the model to IDTF format: write myMol.idtf
  5. Two files have been created: File icon.gifmyMol.idtf and File icon.gifmyMol.idtf.tex. Copy them to the folder where you have IDTFConverter, open the command line there and run the conversion: u3d.bat myMol. That will create a File icon.gifmyMol.u3d
  6. Open the previous PDF file into PDF-XChange Editor. Find the place where your left blank space. To insert a 3D annotation:
    • If you are using the Ribbon interface: Comment > Add 3D
    • If you are using the classical Toolbar interface: Tools > Media tools > Add or edit 3D annotations
    Draw the rectangle area with the mouse. Suggestion: draw a square by holding the Shift key while dragging to define the area.
    • 3D Artwork: select your File icon.gifmyMol.u3d file.
    • Appearance > Poster > Create poster from file and select the png file you previously saved from Jmol.
    • Choose among any other options offered for display (like border and background color)
    • Accept and save the file.
  7. Check the 3D display in a PDF viewer application. Note that not all viewers support this kind of 3D content. At least, Adobe Reader and PDF-XChange Editor support 3D objects.

Sample documents

This has been created following the above procedure

Older reference

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 [ref.1 below] and from Michail Vidiassov's site [ref.2 below]. Download the latest File icon.gifU3D_A_??.zip file. You only need a subset of the files in that package:
    Extract (unzip) the contents of Folder icon.gifBin/Win32/Release/ (that makes 4.46 MB out of the total 137 MB in the zipfile). From that,
    You need (minimal functional set of files): File icon.gifIDTFConverter.exe, File icon.gifIDTFExporter.dle, File icon.gifIFXCore.dll and the Folder icon.gifPlugins folder
    You do not need: File icon.gifHelloWorld.exe, File icon.gifSamplePlayer.exe, File icon.gifTrueType.exe
    A File icon.gifreadme.txt file may be useful documentation, not essential.
  2. Put those extracted files and folder in a location of your convenience, like File icon.gifc:\idtf\
  3. In that location, create a simple command file File icon.gifu3d.bat. This plain text file must contain this text:
    idtfconverter.exe -input %1.idtf -output %1.u3d
  4. Then put in that same location the .idtf and .idtf.tex files you want to convert (produced by Jmol), open the command line window (a.k.a. terminal) in that location and type
    u3d yourFileName (do not include the extension)
  5. That will generate the corresponding .u3d file
  • MacOS and Linux installation of IDTFConverter
  1. You can get a port of IDTFConverter from Michail Vidiassov's site (ref.3 below).
  2. Create a command file similarly to the one described for Windows.

References

  1. Windows: Universal 3D Sample Software (at SourceForge). Go to 'View All Files' and download the latest File icon.gifU3D_A_??.zip
  2. Windows: Alternatively, get just the necessary files from (broken link) http://www2.iaas.msu.ru/tmp/u3d/u3dIntelWin.zip (thanks to Michail Vidiassov).
    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).
  3. MacOS and Linux: A port of the software is available as File icon.gifu3d-1.2.852.tar.gz or, possibly, a newer version, at (broken link) http://www2.iaas.msu.ru/tmp/u3d/ (thanks to Michail Vidiassov).

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

This will create two files: File icon.gifxxx.idtf and File icon.gifxxx.idtf.tex

Note: by default, the final PDF will be a letter-sized page (215.9×279.4 mm, 8.5×11 inches). If you want instead an A4-sized page (210×297 mm), edit now the File icon.gifxxx.idtf.tex file, look for the line that says 

documentclass[12pt,letter]{article}

and replace with 

documentclass[12pt,a4paper]{article}

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 Editor, 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 described 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.
Display of 3D objects may be disabled by default. You may enable it either by trusting the document or by setting: Preferences > Multimedia & 3D > Enable Playing of Multimedia and 3D content.
  • PDF-XChange Editor v.7.0.327 or later (from PDF-XChange Co. Ltd., formerly Tracker Software; proprietary, there is a free version). It can display 3D models embedded in the PDF if they were created in the U3D format (but currently not if created in the PRC format).
  • Foxit PDF Reader version 12 or later includes support for displaying embedded 3D models. For previous versions 9, 10, 11, you need to install the 3D plug-in. Note: support and performance are poorer, in our hands, than with PDF-XChange.
Display of 3D objects may be disabled by default. You may enable it either by trusting the document or by setting: File > Preferences > 3D > Enable the playing of 3D content.
  • Tech Soft 3D PDF Reader, for Android systems (supported on Android version 4 and up, but unsupported on version 9, maybe before)
  • Most other PDF viewers are not 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.gifu3d 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.
  • PDF-XChange Editor v.8.0.332 or later (from PDF-XChange Co. Ltd., formerly Tracker Software) can insert a 3D model from a U3D format file in an existing pdf document. This is possible both with the free and paid/licensed versions. If you have the licensed version, you can also do it with a newly created blank pdf document.
  • Foxit PDF Editor Pro (not free software) allows to insert a 3D model (in either File icon.gifu3d or File icon.gifprd formats) to a PDF page. Note that Jmol can only produce File icon.gifu3d files, not File icon.gifprd files.
  • Share3D PDF, by Quadrispace, looks like a promising solution to easily produce 3D-containing pdf documents at a reasonable price and with a nice set of features. Unfortunately, it doesn't seem to import any of the 3D formats that Jmol can produce.
  • U3D-2-PDF seems to be a user-friendly freeware tool that drives MeshLab and MiKTeX to facilitate the procedure from a File icon.gifwrl file to a File icon.gifpdf document. (Requires MiKTeX, MeshLab and .NET Framework 4 installed; all freeware)
  • Aspose offers a free online converter that will create a File icon.gifpdf document with the 3D model embedded, from an File icon.gifobj+mtl pair of files generated by Jmol. The result is not very satisfactory: model is zoomed in far to much to be visible, with no hints for the user to zoom out. Choose PDF in the "save as" drop-down menu. The document will be of US-letter size.

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.

4. Leaving the structural ivory tower, assisted by interactive 3D PDF.

(2010) P. Kumar, A. Ziegler, A. Grahn, C.S. Hee, A. Ziegler. Trends Biochem. Sci. 35:419-422 doi:10.1016/j.tibs.2010.03.008.

5. Embedding and publishing interactive, 3-dimensional, scientific figures in portable document format (PDF) files.

(2013) D. Barnes, M. Vidiassov, B. Ruthensteiner, C. Fluke, M. Quayle, C. Colin. PLOS One 8:e69446 doi:10.1371/journal.pone.0069446.
They do not use the U3D format, but PRC instead.

6. Towards an easier creation of three-dimensional data for embedding into scholarly 3D PDF (Portable Document Format) files.

(2015) A. Newe. PeerJ 3:e794 doi:10.7717/peerj.794.

7. Enriching scientific publications with interactive 3D PDF: an integrated toolbox for creating ready-to-publish figures.

(2016) A. Newe. PeerJ Comput. Sci. 2:e64 doi:10.7717/peerj-cs.64.

8. On the use of PDF-3D to overcome spatial visualization difficulties linked with ternary phase diagrams.

(2019) D. Vergara, M. P. Rubio and M. Lorenzo. Education Sciences 9:67 doi:10.3390/educsci9020067.
Reports on generating 3D-PDF via OBJ file to (Adobe Photoshop) U3D to (Adobe Acrobat) PDF. Note: Jmol can export models to the OBJ format.

Contributors

AngelHerraez, Vdlee

Retrieved from "https://wiki.jmol.org/index.php?title=File_formats/3D_PDF&oldid=10266"