How to set up a captioned view cycle?

PDF3D ReportGen and PDF3D.IO development SDK can be used to convert over 70 file formats to 2D or 3D PDF. In addition, these tools offer highly customisable viewpoints.

A simple 3D PDF with manual views is very common. When a user is faced with several views they can select each view using the selector menu. Easy enough. But what if you want to tell a story and show your user each view in a sequence or specific order with a beginning, middle and end, and with accompanying narration?

With the PDF3D system it’s easy and this article will show you how to generate interactive PDFs containing automated view transitions, captions per view, and object highlighting at each view. This technique uses additional XML tags and a small amount of JavaScript to add an extra layer of animation and interactive 3D PDF documents. The feature is used to give viewers a walk-through or guided tour, showing a scripted sequence of views, where each view highlights a specific part or area, with an explanation or guide comment from your own copy-paste content.

The Hard Way to Tell a Story

In a default PDF conversion, all parts are shown in normal state and views are set to various orientations around the whole model. Part selection and isolation is possible to force a sequential selection, however it requires navigation of the model tree menu and a setting of the rendering modes by hand, which isn’t very user-friendly.

For first-time viewers without such experience, a better way is needed to show a sequence of part views, where the orientation is modified to show a specific part at a time. In this instance, all other parts would appear in a neutral colour, while the selected part would be accompanied by a caption to explain that particular part in more detail.

In this article, we’d like to show you an easier way where the automatic cycling through of each part and stage of the model progression are added without requiring any user actions. If a user makes a 3D action to zoom, rotate, and explore the detail manually, the automatic cycle pauses until the scene is quiet again after a time-out period.

The Easy Way to Tell a Story

The Prerequisites

This process assumes as a starting point:

  • You have a PDF3D ReportGen program installed with valid license
  • Samples are installed with supporting tutorial files
  • You have access to a non-formatting text editor such as NotePad++, Visual Studio, Emacs, Vi, GEdit, or XMLSpy.
  • You have some basic introductory level knowledge of XML syntax and JavaScript.

Extending XML with new tags

The standard menus in PDF3D ReportGen offer basic functionality, however there are no menus to perform the actions explained in this guide.

  • First, the models and basic settings should be established and exported to the .pdf3dsettings state file.
  • Next open this file in an editor
  • extend it by adding additional tags
  • then reload it into ReportGen then convert.

A completed customised .pdf3dsettings file is provided as a working sample. Once developed the .pdf3dsettings file can be used by the XML Server for automated production and many more XML tag options.

Parts Names, Sizes and Locations

Next, you’ll need to enable 3D mouse probe temporarily, and convert and open the model tree. Write down a list of key model tree part names you want to automate, select them with the probe and note key locations and sizes in X,Y,Z coordinates.

That little annoying less-than (<) symbol

JavaScript, as a programming language, contains all the typical conditional test operators such as equal, non-equal, less-than, greater-than, &&, etc. As expected, the less-than symbol is “<”. However, there is a clash when JavaScript meets XML. XML uses “<” as the start of a new tag. So in your JavaScript there are two choices:

  1. Cleverly re-write conditional expressions to avoid less-than, double ampersands, or
  2. Replace < with <

The second is easiest to do, without changing the logic of the code, but is not so good for humans reading it. The first is best if you want the code to look the same and work the same both in and out of XML context.

Extending XML Tags

Add Custom Views

Views may be either those created automatically as DefaultViews (CAD, Geospatial, Anatomical schemes), or those which arrive from an external source such as one of the file loading or plug-in interfaces which may contain view information, or they can be added here by hand in XML.

First, you’ll need to disable all except our new custom ones with:

<DefaultViewScheme value="None"/>

Next, several new views area added with specific title names and orientations. Each view can be isometric (orthographic) or perspective, and the camera location is relative to the bounding box extend of the model (see below):

<DefaultView>

<CameraName value="**Overview**"/>

<Camera x="-0.7" y="-0.1" z="-0.7"/>

<CameraUp x="0" y="1" z="0"/>

<IsPerspective value="true"/>

</DefaultView>

<DefaultView>

<CameraName value="**Spring**"/>

<Camera x="0.2" y="-0.5" z="0"/>

<CameraUp x="0" y="1" z="0"/>

<IsPerspective value="true"/>

</DefaultView>

<DefaultView>

<CameraName value="**Shock**"/>

<Camera x="0.7" y="0" z="0"/>

<CameraUp x="0" y="1" z="0"/>

<IsPerspective value="true"/>

</DefaultView>

...

Add Text Forms

You’ll then be able to add some static labels and dynamic text-field areas for the view name and the caption text. The first one is for view name (single line):

<DrawText value="View" left="700" bottom="550"/>

<WidgetText name="WidgetTextField-001"/>

The second is for multi-line dynamic caption text box. These are much simplified for purposes of this article (see tutorial files for all the typical style attributes):

<DrawText value="Description" left="700" bottom="500"/>

<WidgetText isMultiLine="true" name="WidgetTextField-002"/>

Add JavaScript Tag

Add your own custom JavaScript inside

<JavaScript> ---- </JavaScript>

Start by adding the automatic timing period parameters:

var interval = 5;  // time interval between views

var patience = 10; // timeout after any mouse interaction stops

Now is the time to add the journey to define the view order and add narration prose. This is defined by a simple table. Paying attention to the names of views and the model tree name homework, add a small table, as in this example which shows 3 columns and 6 rows:

// part name, view name, caption description table

var caption_content = [

["nothing",  "Overview", "A-type Suspension, Structural Overview in 3D PDF, Part Descriptions"],

["3_Instance1_Resource", "Spring", "Compression Coil Spring over Shock, Stores and Releases Energy"],

["2_Instance2_Resource",  "Shock", "Shock Absorber Unit, Hydraulic Damper using Oil-Piston Improves Handling"],

["1_Instance2_Resource", "SteeringLink", "Control-arm for Azimuth Steering of Wheel Mount with inline damper"],

["7_Resource", "Wishbone", "A-type support structure for Lateral strength, with mirror part below"],

["nothing", "Next", "Next view description goes here"]

];

The rest of the JavaScript method can be copied from the tutorial files. The method implementations expect to find the view names and WidgeText names, etc.

A completed sample implementation is included in

states/captioned-view-cycle.pdf3dsettings

Further Extensions

This general method can be extended to use view-dependent visibility (hiding some objects on particular views, adding hyperlinks to additional areas of the document or external URLs, adding PMI or custom annotations into the 3D scene.

Storytelling Complete

And there you have it. We’d love to hear how easy you found it to add the order and narration. Get in touch to tell us how you got on.