How To


This page introduces the trackball animation feature offers by 3DHOP, showing the simple steps needed to change the current point of view over the scene using JavaScript functions.

Featured Scene Elements

  • Trackball


Click to run live demo
A bit of action: the 3DHOP view animation system

Set Up

While it is important to give to the user the possibility of freely exploring the scene, it can also be useful to set the point of view in a specific point, to focus the attention of the user on a detail of the 3D models or to implement a sort of "guided tour" of the scene.
3DHOP offers a way to control the trackball using some JavaScript functions. By calling these function from the HTML elements of the page (e.g. by selecting a link, or clicking a button), it is possible to move (instantaneously or using a smooth animation) the position of the camera framing the scene.
As described in this how-to, the view over the scene is controlled by a trackball entity. The position of the trackball is controlled by a series of parameters; by changing these parameters, you can control the point of view. 3DHOP provides three different methods: one is used to retrieve the current set of parameters, the other two to set the view.

getTrackballPosition-returns the trackball position parameters;
setTrackballPosition-performs a jump-to camera movement;
animateToTrackballPosition-performs an animate-to camera movement;

The getTrackballPosition returns a vector containing the trackball parameters, while setTrackballPosition and animateToTrackballPosition wants as a parameter a vector containing the trackball parameters. Each trackball is defined by a different set of parameters, as described in this how-to; so, for each different kind of trackball, you will receive an array with a specific number of parameters, with a specific semantics. For example, the TurnTable trackball uses three parameters ("phi", "theta" and "distance"), TurnTable Pan trackball uses six ("phi", "theta", "panX", "panY", "panZ", and "distance"), and the PanTilt five ("panX", "panY", "angleX" "angleY" and "distance"), while Sphere works with five (the whole 4x4 transformation matrix array, plus "panX", "panY", "panZ", and "distance").
The difference between setTrackballPosition and animateToTrackballPosition is that the first one performs an instantaneous change of the point of view, while the second start a smooth animation that bring the view in the chosen position. Both the instantaneous jump and the animation are available for all the provided trackballs.

Obviously, these methods can be used everywhere in the HTML page: they can be invoked when the user clicks on a link, or when to user clicks on a button, or by a timed JavaScript function. In this way it is possible to implement an arbitrary interface for the visualization using HTML components and JavaScript functions, as in the standard webpage development, and integrate the 3DHOP viewer in already existing webpages.
In the example at the begin of the page, we used standard clickable links to get the current parameters of the TurnTable trackball, and to set the trackball in various positions all around the object. In the code snippet here below, we read the current state of the trackball with the "getTrackballPosition()" method and print the returned vector in an HTML text box (through the simple JavaScript "log()" function).
In the next snippet, we animate the trackball to a position on the left (phi 90.0 degrees), slightly above (theta 40.0 degrees) and far from the object (distance 3.0) by calling presenter.animateToTrackballPosition([ 90.0, 40.0, 3.0]);.

  <a onclick="log(presenter.getTrackballPosition());">Get Trackball Position </a>
  <a onclick="presenter.animateToTrackballPosition([ 90.0, 40.0, 3.0]);">Left</a>

Finally we used the "setTrackballPosition()" method to reset the trackball position when the toolbar "home" button has been pressed, simply by calling presenter.setTrackballPosition([ 0.0, 0.0, 3.0]); when handling the "home" button event (in place of the usual "presenter.resetTrackball()" function), as shown in the block of code below:

function actionsToolbar(action) {
    presenter.setTrackballPosition([ 0.0, 0.0, 3.0]);  
  else if(action=='zoomin') 
  else if(action=='zoomout') 
  else if(action=='light' || action=='light_on') { 
    presenter.enableLightTrackball(!presenter.isLightTrackballEnabled()); lightSwitch(); } 
  else if(action=='full'  || action=='full_on') 

This is only a simple example of the use of the trackball animation system. By using these functions is possible to create more complex interactive visualizations:

  • bookmarks: with a button, get the current trackball position; the obtained position parameters can be stored in memory (for a one-time use), on a cookie (to save them on the local machine for a later use) or sent to a remote server; then, a series of buttons will bring the user to the saved bookmarks
  • guided tour: after setting up the scene and the trackball, find the positions for the animated tour by moving the trackball manually, then getting the current parameters and write them down, then create a JavaScript function that invokes animateToTrackballPosition on all positions, one after another, waiting few seconds between each movement.

The complete sources of this example are provided together the 3DHOP code in the download section.

If you want instead to learn more about how to place an hotspot in the scene and how to link it to the 3DHOP event listeners click here and go to the next HOWTO.