6.5. Scripting the Java viewer

In the Free Edition scripting functions are not available. You need to upgrade to the full version to use viewer scripting.

Experienced users can control the behaviour of the 3DSOM Pro Java Viewer using a simple scripting language. This capability allows buttons on the web page to control the appearance of the 3D model - for example smoothly rotating the object to a particular viewpoint, zooming in to a specific feature, fading up the lighting, or playing a repeated fly-through sequence. You could even create your own graphical user interface to replace the default mouse controls.

A script file can be used or JavaScript commands or a combination of the two. Script execution is interrupted if the user clicks or drags within the applet window.

Scripting the viewer applet

A script is a set of instructions that are processed in order by the viewer. By convention each line in the script text file contains a single command...

    function_name1([parameter1[,parameter2]...]);
    function_name2([parameter1[,parameter2]...]);

The "script" applet parameter contains the name of the script file to be used or alternatively contains the actual script with each line separated by a newline character (there must be more than one line). For example the following script displays the 3D model over a flashing background image...

<applet code="javaRenderer/JavaRenderer.class"
        archive="viewerb.jar, model.jar" id="myapplet" scriptable=1
        width=200 height=200>
        <param name="model" value="model.123">
        <param name="script" value="\
          setAppletParameter('bgImage','background.jpg');\n\ 
          sleep(1000);\n\ 
          setAppletParameter('bgImage','');\n\
          sleep(1000);\n\
          startScript();">
        ...
        </applet>

The applet can be directly controlled using JavaScript calls of the form appref.function_name1([parameter1[,parameter2]...]); where appref is a reference to the applet object obtained using the JavaScript DOM. For example the following JavaScript function has the same effect as the previous example...

var flag=true;
function flashBackground()
{
   // get a reference to the applet from the DOM
   var appref = document.getElementById("myapplet");

   // modify the bgImage applet parameter
   if (flag) appref.setAppletParameter("bgImage","background.jpg");
   else appref.setAppletParameter("bgImage","");

   // switch flag
   flag = !flag;
   
   // change state again in one second
   setTimeout("flashBackground();", 1000);
}

Note that certain functions (sleep, synch) suspend execution for a significant time period and should not be called directly from JavaScript - use a script file in these cases.

TIP:	You should not attempt to script the applet using JavaScript until after the applet has been initialised i.e. after the onInit JavaScript handler code has been executed.

Script functions

Here are all the available function calls...

animateAppletParameter(name,value,timeperiod)

name (string) - an applet parameter name (must be a parameter with a numerical value).

value (real number) - final numerical value of parameter

timeperiod (integer) - time in milliseconds over which to perform this animation

This command is used to smoothly change any numerical applet parameter (e.g. "diffuseLight") from the current value to the desired final value over a time period. Execution proceeds immediately to the next line in the script. Use the synch() command to wait until all queued animations are finished.

animateObjectTransform(ox,oy,oz,px,py,pz,t)

ox (real number) - final orientationX value.

oy (real number) - final orientationY value.

oz (real number) - final orientationZ value.

px (real number) - final positionX value.

py (real number) - final positionY value.

pz (real number) - final positionZ value.

t (integer) - time in milliseconds over which to perform this animation.

This command is used to smoothly change the object orientation and position parameters to the desired final values over a time period. Execution proceeds immediately to the next line in the script. Use the synch() command to wait until all queued animations are finished.

setAppletParameter(name,value)

name (string) - the name of an applet parameter

value (string or number) - new value of paremeter

This command immediately changes an applet parameter and updates the viewer display. Currently, changing the "model" parameter has no effect.

sleep(timeperiod)

timeperiod (integer) - time period in milliseconds.

This command suspends execution for the given time period. If called within a script, the thread that is processing the script will pause but the main viewer thread continues to show the 3d model.

Note - do not use this command within a JavaScript function! Either use a "setTimeout" call or use a script.

synch()

This command suspends execution until all queued up animations (created using animateAppletParameter or animateObjectTransform) have finished playing. If called within a script, the thread that is processing the script will pause but the main viewer thread continues to show the 3d model.

Note - do not use this command within a JavaScript function! Either use a "setTimeout" call or use a script.

startScript()

This commands starts the current script as defined by the "script" applet parameter (which may or may not be the current script being executed). Adding this command to the end of a script allows the script to loop indefinitely.

TIP:	You can interactively obtain the 6 parameters used by animateObjectTransform using the 3DSOM Pro hotspot editor. Open your 3D model with the hotspot editor and the 'Object Transform' field will display the current parameters.