How to Adjust Advanced Parameters - Using PDF3DSettings Files

This section covers Advanced techniques to adjust additional parameters, which are not shown in the normal ReportGen user interface.

Set up a basic conversion operation within the ReportGen user interface with your specified input and output files. Once you are satisifed that you have choosen the correct options for your conversion, click Export State and save to an external .pdf3dsettings state file.

.pdf3dsettings files are XML based, this is a simple text based format for representing structured information. You may open these files using a text editor such as NotePad, Notepad++, Visual Studio Code or many other text editors.

Once the xml based .pdf3dsettings file has been modified, the Import State button will reload the modified state, clicking Convert will now make the conversion.

1. Adjusting Normalization

When using the exploded parts option, all assemblies are automatically normalized by default. In case this is not appropriate, this can be disabled to avoid unwanted normalization. To adjust this, add <Scale autoScale="false" generalScale="1.0"/> as a new sub-tag into <DefaultAssemblyProperties>.

Note for sequence animated mode such normalization is automatically disabled by default to this technique is not needed.

2. Animation initially paused, speed adjustment

Save conversion parameters in .pdf3dsettings (XML) state file (by using PDF3DReportGen "Export to .XML state file" from the tool bar). Open saved .pdf3dsettings file at any text editor and add the following:

<InsertAnimationControls animationName="Sequence_Animation_From_Assemblies" delayMultiplierByDefault="20" initiallyPlaying="true" />

This special addition sets several properties. The initiallyPlaying parameter means that the animation will play initially. If changed to 0, the animation will be paused initially, users will first need to push the play button. Animation speed may be controlled by using delayMultiplierByDefault parameter, where higher values mean a slower speed. Please do not modify the animationName attribute.

3. Metadata Selection, Display, Descriptive Elements

By saving state file, editing and reloading, additional metadata tags may be inserted which will be reported when each of the identified model nodes are selected, and the Metadata Control is enabled. An example of such a tag is shown below.

<Metadata nodeName="some_node_name">

<MetadataItem key="Part" value="This Part Description Here"/>

<MetadataItem key="ID" value="P-001234"/>

</Metadata>

The nodeName must exactly match an existing node. Any number of items may be added with arbitrary key/value pairs.

For users to access and display metadata, left-mouse selection on parts in the 3D view can be used, where parts are highlighted. By enabling the Add Metadata Control option, and extra display box is added to the 2D PDF page below the 3D view, where key/value pairs are displayed for the selected part. As an alternative, this extra box can remain disabled, and the model-tree panel exposed to the left of the PDF page view. If the conversion encoding mode is set to U3D or U3D-RHC, then the key/value pairs will be displayed in the attribute list in the bottom left corner of the model tree panel.

4. Part Name Substitution

When files are added into the input file list, normally the 3D PDF model tree part names are derived directly from the input file-name stems. Within the assembly tag specifying each input file, normally there is simply an input filename specified. By inserting a new NodeName tag inside the assembly, it may be re-named from the default to any user-defined part name. An example of part name substitution is shown below. In this example "P23472972-B" is changed to "NewPartName".

<Assembly>

<InputFileName value="C:\Data\ZZZ\P23472972-B.stl"/>

<NodeName value="NewPartName"/>

</Assembly>

5. JavaScript

User-written custom javascript can be attached to 3D views by adding code as-is inside of a JavaScript tag block in the XML state file. This should be outside of assembly, as a sub-tag to input parameters. An example of a simple script which changes the background view color and enables a grid is shown below:

<Javascript>

myRenderHandler = new RenderEventHandler();

myRenderHandler.onEvent = function(event)

{

scene.gridMode = "wire";

scene.showGrid = true;

var topColor = new Color(1, 0.6, 0.6);

var bottomColor = new Color(0.6, 0.6, 1);

event.canvas.background.setColor(topColor, bottomColor);

runtime.removeEventHandler(myRenderHandler);

}

runtime.addEventHandler(myRenderHandler);

</Javascript>

6. Draping Vector Features

Conforming and draping vector shapes onto terrains. It is possible to drape images, lines, polygons onto CAD format terrain surfaces as well as the more traditional terrain grid formats (.asc, .grd). This requires adding additional elements into the XML Settings file to specify a "TerrainMode" tag. A simple example is shown below, where a 3D DXF file defining an elevation mesh is marked as the "Terrain", and other files such as 2D shape, kml or other objects are then marked as "LiesOn".

<Assembly>

<InputFileName value="Surface.dxf"/>

<AssemblyProperties colorArrayIndex="0"colorArrayName=""/>

<TerrainMode mode="Terrain"/>

</Assembly>

...

<Assembly>

<TerrainMode mode="LiesOn"/>

</Assembly>

7. Sphere Tessellation

A special Pentaki Dodecahedron sphere representation is available using 60 equal area equilateral triangles, rather than the default polar latitude-longitude spherical subdivision. To enable this special representation, add the following XML tag:

<PentakiMode enabled="true" splitMin="1"splitMax="1"/>

8. Custom Camera Views

Each custom view can have a new unique name, with a camera look vector, up vector and switch for perspective or orthographic projection. For renaming views you should first change:

<DefaultViewScheme value="none"/>

which turns off current default views and then add the following:

<DefaultView>

<CameraName value="Modified Front(+Z)"/>

<Camera x="0"y="0"z="-1"/>

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

<IsPerspective value="true"/>

</DefaultView>

<DefaultView>

<CameraName value="Modified Back(-Z)"/>

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

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

<IsPerspective value="true"/>

</DefaultView>

<DefaultView>

<CameraName value="Modified Top(+Y)"/>

<Camera x="0"y="-1"z="0"/>

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

<IsPerspective value="true"/>

</DefaultView>

<DefaultView>

<CameraName value="Front View (renamed Bottom(-Y))"/>

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

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

<IsPerspective value="true"/>

</DefaultView>

<DefaultView>

<CameraName value="Modified Left(+X)"/>

<Camera x="-1"y="0"z="0"/>

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

<IsPerspective value="true"/>

</DefaultView>

<DefaultView>

<CameraName value="Modified Right (+X)"/>

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

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

<IsPerspective value="true"/>

</DefaultView>

<DefaultView>

<CameraName value="Modified IsoCorner"/>

<Camera x="-1"y="-1"z="-1"/>

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

<IsPerspective value="false"/>

</DefaultView>

<InitialView index="3"/>

9. Mixed Static and Dynamic Sequence Animation

Sequence Animation with some parts changing while other parts remain static. It is possible by using <SequenceAnimation> tag.

Explanation of steps:

  1. Manually created three sample files: tetrahedron1.wrl, tetrahedron2.wrl, tetrahedron3.wrl. These files contain the basic tetrahedron shape in different 3D positions and transformed shapes.
  2. Add all these files into PDF3D ReportGen and enable the [x] Sequence Animation check box. Result 3D PDF shows animation of all assemblies (tetrahedrons).
  3. Save parameters to XML .pdf3dsettings state file and manually edited this to change some tags. Load it again.

The result of this new conversion shows 2x animated tetrahedrons and one static (not moving) tetrahedron.

The modifications used in this example are:

<SequenceAnimation animateAssemblies="false" exposeScripts="false" supressAnimation="false">

<Node value="node1"/>

<Node value="node2"/>

</SequenceAnimation>

The "animateAssemblies" attribute means to animate ALL assemblies. In our case we want to animation only some subset, this is because we changed this parameter to false. The <Node> tags inside the animation block defines the list of nodes which should be animated. Also, note tags are edited:

<Assembly>

<InputFileName value="W:\ctest\tetrahedron1.wrl"/>

<NodeName value="0"node1""/>

</Assembly>

<Assembly>

<InputFileName value="W:\ctest\tetrahedron2.wrl"/>

<NodeName value="0"node2""/>

</Assembly>

<Assembly>

<InputFileName value="W:\ctest\tetrahedron3.wrl"/>

</Assembly>

<Assembly>

In the above example, there is an added <NodeName> tag which defines new node name which will be used in 3D scene.

10. Position and Orientation of Multiple Parts

It is possible to set up any arbitrary 3D position, size and orientation of parts in an exploded view. The following shows how to use the manual position, scale and rotate controls on the Interface Settings Common parameters tab:

  1. Add 2 teapot.stl files (from samples/stl, same model file loaded twice). Each one is only 1/2 model.
  2. Go to Interface Settings and turn ON Object Scale and Object Position. (as default selection mode)
  3. For both teapot.stl files "create options"
  4. For first teapot.stl set Scale Z to -1
  5. Set diffuse color selection, different for each model.
  6. Turn ON "Exploded" Mode on Animation tab and push Convert.

After these 5 steps, a whole teapot model is produced. This technique does not require any hand-editing of XML.

11. Camera Animation

It is possible to create camera animation using XML tags and scripting. For advanced uses, we would reccomend pdf3d.io, however for casual interest we describe a small example here for illustration. First, add the animation control on the PDF page. Then specify a Rigid Body Keyframe Animation mode, and specify camera positions and timing. For each camera keyframe, insert a timing delay, and geometric camera parameters. There is limited support in PDF3DReportGen for camera animation, and this is the only documentation available at this time.

<InsertAnimationControls animationName="" currTextFieldVisible="true" delayMultiplierByDefault="1.0" directionCheckBoxVisible="true" fastButtonVisible="true" forwardDirectionByDefault="true" initiallyPlaying="true" nextButtonVisible="true" normalRepeatCheckBoxVisible="true" pauseButtonVisible="true" pingpongRepeatCheckBoxVisible="true" playButtonVisible="true" prevButtonVisible="true" repeatByDefault="true" repeatCheckBoxVisible="true" repeatModeByDefault="Normal" slowButtonVisible="true" smoothRepeatCheckBoxVisible="false" stopButtonVisible="true" stretchToRect="false" timeTagTextFieldVisible="false">

<RigidAnimation animationName="" delayMultiplierByDefault="1.0" forwardDirectionByDefault="true" fps="20" hardTiming="false" initiallyPlaying="false" repeatByDefault="true" repeatModeByDefault="Normal" useInterpolation="true">

<CameraMovement localRepeatMode="Normal">

<TargetedCameraFrame>

<Delay value="9"/>

<CameraUp x="0.0" y="1.0" z="0.0"/>

<Near autoRecalculate="false" value="0.1"/>

<Far autoRecalculate="false" value="600"/>

<CoordinateSpace value="EarthMoonSystem"/>

<Rotation angle="0.0" x="-1" y="0.0" z="0.0"/>

<CameraDistance value="30"/>

</TargetedCameraFrame>

<TargetedCameraFrame>

<Delay value="1"/>

<CameraUp x="0.0" y="1.0" z="0.0"/>

<Near autoRecalculate="false" value="0.1"/>

<Far autoRecalculate="false" value="600"/>

<CoordinateSpace value="EarthMoonSystem"/>

<Rotation angle="0.0" x="-1" y="0.0" z="0.6"/>

<CameraDistance value="10"/>

</TargetedCameraFrame>

<TargetedCameraFrame>

<Delay value="4"/>

<CameraUp x="0.0" y="1.0" z="0.0"/>

<Near autoRecalculate="false" value="0.1"/>

<Far autoRecalculate="false" value="600"/>

<CoordinateSpace value="Earth"/>

<Rotation angle="0.0" x="-1" y="0.0" z="0.6"/>

<CameraDistance value="10"/>

</TargetedCameraFrame>

</CameraMovement>

12. Adding a Custom Caption Box

Using the standard caption option on the Annotation tab provides a simple way to specify a short paragraph of text to describe the scene above. However, it is always at a fixed location, size, font and color. Using the technique of saving the .pdf3dsettings file, editing and reloading, additional custom unique text boxes can be added. These provide complete freedom of placement at visual style. As an example, add the following block of XML into the saved .pdf3dsettings file:

<DrawTextRect alignment="HVCenter" bottom="20" drawBox="false" height="80" left="20" rotation="0.0" rotationAlignment="Left Top" value="This is a Test of a Custom Caption Box" width="600" wordWrap="true">

<Color alpha="255" blue="0" green="0" red="0">

<Font bold="false" family="Times New Roman" file="" italic="false" size="14.0" underline="false">

</DrawTextRect>

13. Poster Image - Click to Activate

The default mode is for 3D views to become active as soon as they are visible, so mouse interaction can commence immediately for users. However, by adding the following two tags, this can be disabled so a preview poster image is presented first, then on mouse hover a "Click to Activate" message is displayed to allow users to launch the 3D content. This also means that users see something helpful in the case the PDF viewer does not support 3D. For instance, in .pdf3dsettings you can write:

<Annotation3DActivation activationMode="Manual" deactivationMode="Manual"/>

<PosterImage value="my_poster_image.png"/>

14. Automatic Cycle through View List

Using the custom javascript method, a method can be added to cycle through all available 3D views with short delay at each view. This example also allows for a patience period on interactive moves, suspending animation until quiet again for 10 seconds. As an example, add the following block of XML+JS into the saved .pdf3dsettings file:

<Javascript>

var interval = 2.5;

var patience = 10;

var local_clock = 0;

var current_view=0;

var cycle_view_timer = new TimeEventHandler();

var mouseHandler = new MouseEventHandler();

mouseHandler.onEvent = function(event) { local_clock = 0; }

cycle_view_timer.onEvent = function(event)

{

local_clock += event.deltaTime;

if (local_clock > interval + patience )

{

runtime.setView(current_view,true);

if (runtime.viewCount > current_view +1)

current_view +=1;

else

current_view=0;

local_clock = patience;

}

}

runtime.addEventHandler(cycle_view_timer);

runtime.addEventHandler(mouseHandler);

</Javascript>

15. Defining Product Markup Information

Product manufacturing information (PMI) is design, manufacturing, quality, and other data which is often included in CAD files. PMI information may also be included within 3D PDFs and may be used to aid downstream interoperability. PMI may be included through the use of the <PMIMarkup> tag within the pdf3dsettings file.

<PMIMarkup name="">

<PMILabel textOnly="false">

<Anchor x="0.0" y="0.0" z="0.0"/>

<Opposite x="0.0" y="0.0" z="0.0"/>

<HSegmentLength value="0"/>

<Text height="0.0" left="0.0" overrideText2DSize="false" sizeType="markupZoomable" top="0.0" value="" width="0.0"/>

<LineColor alpha="255" blue="255" green="255" red="255"/>

<TextColor alpha="255" blue="255" green="255" red="255"/>

<Font bold="false" family="Times New Roman" file="" italic="false" size="14.0" underline="false"><Font bold="false" family="Times New Roman" file="" italic="false" size="14.0" underline="false"/>

</PMILabel>

</PMIMarkup>

16. Defining view-dependent node visibility

The <ViewDependent> tag may be used to define view-dependent node visibility and opacity block.

17. Defining Custom Clipping Plane Objects

The <ClippingPlaneObject> tag may be used to define a custom clipping plane object in world-coordinates at an arbitrary angle.

<ClippingPlaneObject >

<Position x="0.0" y="0.0" z="0.0"/>

<Rotation angle="0.0" x="0.0" y="0.0" z="0.0"/>

<RotationCenter x="0.0" y="0.0" z="0.0"/>

<GeneralScale value="1.0" />

<ScalePerComponent x="0.0" y="0.0" z="0.0"/>

</ClippingPlaneObject>

18. Defining Sequence Animation by loading Collection of Input Files

The <AnimationFromFolder> tag allows users to define a 3D sequence animation by loading a collection of input files from a specified folder.

Additional Command Line Tools

14 additional command line tools are packaged with ReportGen and are included in the installation directory. These command line tools are for standalone usage (i.e. cannot be used with additional RG functionality) and do not include any user graphical interface. Each utility corresponds to one of the interfaces loaded within ReportGen, for a description of interfaces and compatible formats, please click the 'About' button in the top toolbar within ReportGen. For a description of included options, please simply run the tool from command line (with no additional arguments). Excluding additional options, these utilities follow a calling sequence of "[utility.exe] /I [path to input file] /O [path to output file]". Included are:

  1. STL_2_PDF3D.exe
  2. Prc_2_PDF3D.exee
  3. COIN3D_2_PDF3D.exe
  4. GDAL_2_PDF3D.exe
  5. gLTF_2_PDF3D.exe
  6. OSG_2_PDF3D.exe
  7. GRD_2_PDF3D.exe
  8. Teigha_2_PDF3D.exe
  9. DCC_2_PDF3D.exe
  10. XGL_2_PDF3D.exe
  11. Oc_2_PDF3D.exe
  12. Pdf_2_PDF3D.exe
  13. X3D_2_PDF3D.exe
  14. VTK_2_PDF3D.exe