S2PLOT:3dPDF

From S2PLOT

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
• A program for converting TGA image files to PNG image files
  • ImageMagick's convert is recommended
• 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)
• handles must be drawn with the function ds2ahx not s2handle
• 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

Texture conversion

S2PLOT writes textures in TGA image format, with the name convention vrml-texNNN.tga. It is necessary to convert these textures to PNG format prior to use of the S2PLOT-exported VRML. Textures are named in the output VRML file so that the necessary conversion is from vrml-texNNN.tga to vrml-texNNN.tga.png. This conversion can be accomplished with ImageMagick's convert program or almost any other image editor or converter.

Texture compression. For visualisations using lots of large textures, eg. volume rendering, it is well worth doing some extra work to compress the PNG textures. A substantial reduction in final PDF file size can be achieved simply by converting the PNG texture images to a 256-color indexed bitmap. This can be done with the ImageMagick convert tool:

convert -quality 0 +dither -colors 256 infile.png outfile.png

Further compression if desired can be achieved with tools such as OptiPNG and AdvancedComp. See this web page for more suggestions.

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.

1. 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.
2. 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. It will also be included with S2PLOT distributions after (not including) version 2.4.

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 current limitation is that billboards with a specific position angle (ie. created with ds2vbbr) are drawn with position angle 0 degrees in PDF at this stage.

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 decrease (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. If this is compiled with VRMLOUT defined, then three different volume renderings are created using the same input data and rendering parameters, and all three are drawn in the dynamic callback.

void callback(double *, int *);

int main(int argc, char **argv) {

  /* ... */

  if (!s2opend("/?", argc, argv)) {
    fprintf(stderr, "Failed to open S2PLOT device!\n");
    exit -1;
  }

  /* ... */

  /* create the volume rendering "object" */
  alphamin = 0.0;
  alphamax = 0.6;
  vrid = ns2cvr(grid, nx, ny, nz, 
		0, nx-1, 0, ny-1, 0, nz-1,
		tr, 's', 0.6, 9., alphamin, alphamax);
#if defined(VRMLOUT)
  vrid2 = ns2cvr(grid, nx, ny, nz, 
		 0, nx-1, 0, ny-1, 0, nz-1,
		 tr, 's', 0.6, 9., 0.0, 0.6);
  vrid3 = ns2cvr(grid, nx, ny, nz, 
		 0, nx-1, 0, ny-1, 0, nz-1,
		 tr, 's', 0.6, 9., 0.0, 0.6);
#endif
  
  /* ... */
  
  /* install the dynamic callback */
  cs2scb(callback);

  /* run the S2PLOT program */
  s2show(1);

  return 0;
}

void callback(double *time, int *keycount) {

  /* ... */

#if !defined(VRMLOUT) 
  /* draw the volume rendering */
  ds2dvr(vrid, 1);
#else
  pushVRMLname("VRSET1");
  ds2dvrXXX(vrid, 1, 1);
  pushVRMLname("VRSET2");
  ds2dvrXXX(vrid2, 1, 2);
  pushVRMLname("VRSET3");
  ds2dvrXXX(vrid3, 1, 3);
  pushVRMLname("ANON");
#endif

  /* ... */

}

If the above coding and naming convention is followed, and VRML is written from S2PLOT, then the provided s2plot.js Adobe 3D JavaScript will look after switching the axial views appropriately within a 3-d annotation in a PDF file.

Note. Volume rendering textures are exported to the VRML file with transparency set at 0.4. If your volume rendering comes out too faint in the PDF, you may like to globally search and replace the texture transparency settings with a lower transparency value, eg. 0.1. Note that VRML uses transparency, while S2PLOT uses opacity ... the two are related by:

transparency = 1 - opacity

Frame animation

Basic frame animation is enabled when the s2plot.js file is attached to a 3-d PDF annotation loaded from S2PLOT. To take advantage of this capability, an S2PLOT program need simply divide the displayed geometry into named sections of the VRML tree (using the pushVRMLname function) following the convention "FRAMEn".

As for volume rendering, the S2PLOT program will need to have a mode where it shows all the frames at once, so that the Shift-W keypress exports all of the geometry to a single VRML file.

If the s2plot.js Adobe 3D JavaScript is attached to a 3-d figure with parts of the tree following the "FRAMEn" convention, then a simple press of the spacebar while the 3-d mode is enabled will advance to the next frame, and loop back to the start when the final frame is reached.

Note that this implementation is presently quite slow. Substantial optimisation of the code in s2plot.js that controls animation is possible if you know in advance how many frames your VRML file contains.

Handles

This section will be written shortly. Further work is needed on the s2plot.js code before S2PLOT's handles work correctly in 3-d PDF files.

Going further

Integration with PDF forms

Adobe Acrobat provides support to place buttons, text fields, drop-down menus and other standard user interface (UI) elements within PDF documents. User input to these UI elements can be intercepted and processed by JavaScript attached to the document. Consequently, a button press for example can be programmed to execute a JavaScript function which modifies an embedded 3-d figure in some way. Refer to the Adobe Acrobat 3D and 3D JavaScript documentation for further information.

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.

To be continued...