S2PLOT:3dPDF

From S2PLOT

(Difference between revisions)

Revision as of 04:12, 13 October 2008

1 3d-PDF: Embedding S2PLOT Content in PDF Documents

3d-PDF: Embedding S2PLOT Content in PDF Documents

Since version 2.02, S2PLOT has been able to write the displayed geometry to a VRML 97 format file. This format was selected as it can be read in by Adobe Acrobat 3D and embedded in Portable Document Format (PDF) files. Modern versions of Adobe Reader can then render the 3-d model interactively, allowing the reader to view the 3-d scene from any angle or distance. Individual parts of the model can be turned on and off by explicit user control (eg. toggling the display of axis labels) or by implicit programmatic control (eg. toggling the selected set of slices for display as a volume rendering).

The 3-d PDF capabilities of S2PLOT are documented in the following papers. If you embed S2PLOT content in a formally published article, please cite at least one of these sources:

Barnes, D.G., Fluke, C.J., 2008, Incorporating interactive 3-dimensional graphics in astronomy research papers, New Astronomy, 13, 599. For interactive figures, please download paper from here. (ADS) - arXiv:0709.2734.
Fluke, C.J., Barnes, D.G., 2008, The Interactive Astronomy Textbook, Astronomy Education Review, 7(1). For interactive figures, please download paper from here. (AER).

Requirements

S2PLOT version 2.02 or higher
- version 2.4 or higher recommended
- S2PLOT is freely available for non-commercial and educational use
Adobe Acrobat 3D version 8.1.2
- Adobe Acrobat Pro 9 Extended expected to work but not yet tested and interface may be different to that described below
- Acrobat 3D and Acrobat Pro 9 Extended are commercial software but frequently are available at special academic and education prices

VRML export from S2PLOT

Most S2PLOT geometry can be written to VRML format. While running an S2PLOT program, simply press Shift-W and a file called "test.wrl" will be written. It will overwrite any pre-existing "test.wrl" file in the current working directory.

When writing an S2PLOT program whose output may be captured to VRML, keep the following points in mind:

screen-coordinate geometry is not saved to VRML
line thickness is not properly supported in VRML
textured spheres are not presently written to VRML (next version of S2PLOT)
transparent dots are not presently written to VRML (next version of S2PLOT)
disks are not presently written to VRML (next version of S2PLOT)
both static and dynamic S2PLOT geometry is saved to the VRML file
you can organise parts of your geometry into named sections of the VRML file (model tree) by using the S2PLOT function pushVRMLname
correct volume rendering requires special attention (see below)
frame animation is possible (see below)
billboards can be used but require special attention (see below)
handles are written and can be used for particular types of interaction (see below)
Acrobat Reader generally struggles with more than say 5000 pieces of geometry (whether points, lines or facets)
you can programmatically export the VRML file by declaring the function "void writeVRML20(void)" and calling it from a dynamic S2PLOT callback function

VRML import to Acrobat 3D

You can either create a new document in Acrobat 3D based on a VRML file, or you can embed a 3-d figure in an existing document.

To create a new document, simply select "Create PDF: From File ..." from the "File" menu or the main toolbar. "Control-N" should also accomplish the same result. Choose your VRML file ("test.wrl" unless you have renamed it) and then press "Open". Continue below.
To embed a 3-d figure in an existing document, select "Open ..." from the "File" menu ("Control-O" is the usual shortcut). Select the PDF file into which you will embed the figure, and press "Open". From the "Tools" menu go to "Advanced Editing" and choose "3D Tool". Drag out the area on the document where you wish to place the 3-d figure. In the resulting "Add 3D Content" window, click on the "Browse" button next to the "3D Model" field, and choose your VRML file and press "Open", then click "OK"

You should now see the "Acrobat 3D Conversion" dialog on-screen. This dialog is slightly different depending on which path you took above, however at this point, many of the defaults will suffice. Just make sure that the "3D Format in PDF" setting in the "Import" tab is "PRC Tessellation (Faceted)", and click "OK".

Import of the 3-d VRML model will now proceed, and can take from seconds to minutes depending on the complexity of the scene. On completion, click the "Hand" icon on the toolbar, click on the figure, and you will enter "3D mode". In this mode by default you can:

drag with the left button to modify the viewing angle
scroll the mouse wheel to zoom in and out
drag up and down with the right button (or shift-left button) to zoom in and out
drag with control-left button to "strafe" the camera
drag with control-right button to select a rectangular zoom area

The 3D toolbar (usually showing above the figure) provides control of:

lighting
perspective versus orthographic rendering
background colour
rendering mode (wireframe, shaded, et cetera)
the model tree

At this stage, you might like to save your existing or new PDF file, and view it in Acrobat Reader. You might be happy with this result already, however some tips now follow on improving the visual appearance and viewing options.

View and Display Options

Global viewing options are set in the Acrobat Reader software by the end-user, and typically at a minimum the following settings are recommended:

enable double-sided rendering
disable 3D selection for the Hand tool
enable Acrobat JavaScript

Figure-specific options can be set and controlled in the Acrobat 3D application itself, and the ability of an end-user to access to modify these options in the Reader can be limited if required. Most options are accessed by selecting the "3D Tool" and double-clicking on the 3-d figure.

Background colour, lighting and rendering mode

In the "3D Properties" dialog, click the "Edit Content..." button to access settings for background colour, lighting and rendering mode. You can change these in the 3D Toolbar, but these changes will not be saved in the output PDF file. You must make changes in the "Edit Content..." pane for the changes to be saved with the PDF file.

Managing views and the poster image

To provide a range of different views, or to set a default view for creation of the "poster" image (see below), you will need to create a list of views for your figure. To do this, view the model in 3D mode (ie. click on the figure with the "Hand" tool), and select "Manage Views" from the "Views" drop-down in the 3D toolbar. The resultant dialog allows you to rename views, reorder views, and set the default view.

To create a new view, position the camera as you like (by dragging the mouse) before entering the "Manage Views" dialog. Then click "New View", enter a suitable name for it, click "Rename", and optionally make it the default view and/or change the view ordering.

The "poster" image is the image that is displayed before the user enters 3D mode. One option is to make the poster image look very like the initial view that will be presented when 3D mode is activated. To do this, you must set the default view (possible to a view you have created) and then in the "Edit Content" pane select the option to "Retrieve poster from default view".

Alternatively you can create a poster from a file. This is a nice option if you wish to present a 2-d specific figure that is illustrative and instructional, and will suffice if the user is unable to view 3-d figures, or wishes to print the document or export it to another medium.

We recommend the following article and in particular Figures 4 & 5 as an excellent example of using multiple views, as well as 2-d figures as poster images:

Ruthensteiner, B., 2008, Soft part 3D visualization by serial sectioning and computer reconstruction, Zoosymposia 1: 63. For interactive figures, please download paper from here. (Zoosymposia, Volume 1).

3D JavaScript and enabling standard S2PLOT interaction

One of our key goals is to provide a common interface for interaction with 3-d content across multiple media; for further details see our s2web publication:

Fluke, C.J., Barnes, D.G., Jones, N.T., 2008, "Interchanging Interactive 3-d graphics for Cosmology", submitted to PASA, Oct 2008

Adobe Acrobat 3D and the most recent Acrobat Reader include support for JavaScript, and a specific extension, Adobe 3D JavaScript. Relatively simple JavaScript code can be used to intercept key presses, mouse actions, and changes to the 3-d scene. A JavaScript source file can be attached to a 3-d figure by browsing for a ".js" script from the "Edit Content..." / "Add 3D Content" dialog. The selected JavaScript is executed once when a 3-d annotation is enabled: therefore, after attaching a JavaScript or updating and re-attaching a JavaScript, make sure you click on the 3-d figure with the "Hand" tool so that your new or changed script is re-executed.

Typically a 3D JavaScript file will start out by analysing the model tree (perhaps looking for special branch names in the mode tree - see below), and then install a number of event handlers. These event handlers enable functions in your script to be called when particular things happen, for example when the camera is moved, or when a key is pressed.

We provide a standard 3D JavaScript that is useful for all 3-d figures generated from S2PLOT VRML files. This script - "s2plot.js" - implements the standard S2PLOT interaction controls, viz.

left mouse drag to control camera
cursor keys to control camera
+,- to zoom in and out
[,] to roll left and right
<,> to change camera movement amount
/,* to change autospin speed
a,A to toggle autospin

and so on. It also includes code for controlling billboards, volume rendering, and frame-based animation where these are present in the input VRML file. Handles will likely be supported soon (see below).

The standard script "s2plot.js" is available from the peripheral downloads section of the S2PLOT website.

Billboards

Billboards are (mostly) handled correctly by the provided "s2plot.js" script. On every redisplay, the script applies transformations to each billboard to ensure they face the camera. This process is reasonably efficient and it is practical to display upto a few thousand billboards at once this way.

The rotational orientation of billboards on the screen may not be correct at this point, but will be addressed in the near future.

Volume rendering

Standard volume rendering in S2PLOT creates three sets of textures from the volume, one orthogonal to each axis of the data cube. During display, the set of textures most orthogonal to the current viewing direction is chosen for display; the remaining two sets are not drawn. As the camera is moved around the scene, the choice of texture set changes and S2PLOT handles this automatically.

Because the Shift-W keypress only saves the displayed geometry in the scene, some minor additional work is needed if you intend to transfer a volume rendering to PDF format.

S2PLOT's standard volume rendering function is ds2dvr. For export to VRML, a subsidiary function is provided and should be used in place of ds2dvr. This special function has the interface:

void ds2dvrXXX(int vrid, int force, int axis);

This function enables the caller to explicitly set which axial view is drawn. By the appropriate construction of three different volume renderings from the one data volume, and subsequent drawing of all three axial slices, the programmer can ensure that when VRML is exported, all three texture sets are written to the VRML file. The downside is that interactive frame rate in S2PLOT will deteriorate (as three sets of textures are drawn each cycle instead of one) and the visual appearance in S2PLOT will not be ideal. The programmer must also name the three different axial slices (using the pushVRMLname function) according to the convention:

VRSET1 for slices orthogonal to the S2PLOT X axis (axis = 0)
VRSET2 for slices orthogonal to the S2PLOT Y axis (axis = 1)
VRSET3 for slices orthogonal to the S2PLOT Z axis (axis = 2)

An example code fragment follows:

Frame animation

Handles

Going further

Working with LaTeX

The "movie15" package for LaTeX, written by Alexander Grahn, provides a nice way to handle the embedding of 3-d figures in LaTeX-generated PDF files. It does not remove the need for Adobe Acrobat 3D, but it does improve workflow when creating professional articles.

This package has traditionally been used to embed basic 2-d animations and movies in PDF documents using LaTeX. Some introductory material on movie15 for this purpose can be found [here.]

Retrieved from "https://astronomy.swin.edu.au/s2plot/index.php?title=S2PLOT:3dPDF"