How To


Note: a WebGL-enabled browser is needed to run the demos presented below. Please refer to this page for a quick HOWTO or click here to test your browser.


Trackball setting

Description

This page describes how to chose and configure which trackball is used by 3DHOP to manage the scene.

Featured Scene Elements:

  • Trackball


3DHOP uses the "object in hand" metaphor: the camera framing the scene is fixed in front of the object and the user, with the mouse, moves the object in front of the camera.
The way the mouse controls are mapped on the object is determined by an entity called Trackball; a trackball is a description of how the object moves/rotates/zoom depending on the mouse buttons, motions and keyboard press. As different shapes of objects would work better with a different mapping of movements, 3DHOP does offer different trackballs, each one with a specific behaviour. Additionally, each of the trackball may be configured, setting up motion limits and starting parameters.
When declaring the 3DHOP scene, if nothing is explicitly specified, the viewer will use the default trackball, created with its default values. The default trackball is the TurnTable trackball.

If we want to explicitly ask for a specific trackball, or to configure its parameters, it is necessary to add a trackball entity while declaring the scene in the "setScene" function, and specify the type of trackball we want. Each trackball has a unique name to be used in the type field (see further down).
In the following example we just asked to 3DHOP to use the TurnTable trackball.

var presenter = null;

function setup3dhop() {
  presenter = new Presenter("draw-canvas");

  presenter.setScene({
    ...
    trackball: {
      type: TurnTableTrackball
    }
  });
}  

Once we have declared the trackball we want to use, it is then possible to configure its parameters, by adding a "trackOptions" and specifying a value for all the parameters we want to change. Each trackball type has its own set of parameters (see further down). It is not mandatory to always specify all parameters; if a parameter is not included in the trackOptions declaration, its default value will be applied.
In the following example, we configure all the parameters of the TurnTable trackball.

var presenter = null;

function setup3dhop() {
  presenter = new Presenter("draw-canvas");

  presenter.setScene({
    ...
    trackball: {
      type: TurnTableTrackball,
      trackOptions: {
        startPhi: 0.0,
        startTheta: 0.0,
        startDistance: 2.5,
        minMaxPhi: [-180, 180],
        minMaxTheta: [-10.0, 50.0],
        minMaxDist: [0.5, 3.0]
      }
    }
  });
}  

Each trackball definition is in a separate file in the distribution. In this way it is possible to add new trackball, or modify existing ones. The files containing the trackball code are included in the header of the HTML file. Be sure the trackball you want to use is among the included files.


<script type="text/javascript" src="js/trackball_sphere.js"></script>
<script type="text/javascript" src="js/trackball_turntable.js"></script>
<script type="text/javascript" src="js/trackball_turntable_pan.js"></script>
<script type="text/javascript" src="js/trackball_pantilt.js"></script>

We will now describe each of the trackball included in the 3DHOP distribution.


TurnTable Trackball

Click to run live demo
The 3DHOP object in-hand metaphor: the TurnTable Trackball

The TurnTable trackball is a very simple manipulation paradigm. Basically, left mouse button + horizontal mouse movement rotates the object around its vertical axis, and left mouse button + vertical mouse movement tilts the view direction up or down; mouse wheel zooms in and out.
By always preserving the vertical axis, it is an extremely versatile and easy-to-use trackball for many categories of objects. This trackball is very simple, controlled by a "phi" angle of rotation around the vertical axis, a "theta" angle of view tilt, and a view "distance" acting like a zoom.
Since it is very simple but still versatile, this is the default trackball used by 3DHOP.

Set Up

If we want to explicitly ask for a TurnTable trackball, or to configure its parameters, it is necessary to add a trackball entity while declaring the scene in the "setScene" function, and specify TurnTableTrackball as type, like in this example. As the TurnTable trackball is the default one, this step is only required if we want to configure the trackball parameters.

var presenter = null;

function setup3dhop() {
  presenter = new Presenter("draw-canvas");

  presenter.setScene({
    ...
    trackball: {
      type: TurnTableTrackball
    }
  });
}  

Configuration

Once we have declared the TurnTable trackball, it is then possible to configure its parameters, by adding a "trackOptions" and specifying a value for all the parameters we want to change. It is not mandatory to always specify all parameters; if a parameter is not included in the declaration, its default value will be applied.
In the following example, we configure all the parameters of the TurnTable trackball.

var presenter = null;

function setup3dhop() {
  presenter = new Presenter("draw-canvas");

  presenter.setScene({
    ...
    trackball: {
      type: TurnTableTrackball,
      trackOptions: {
        startPhi: 0.0,
        startTheta: 0.0,
        startDistance: 2.5,
        minMaxPhi: [-180, 180],
        minMaxTheta: [-10.0, 50.0],
        minMaxDist: [0.5, 3.0]
      }
    }
  });
}  

Here is a description of the different parameters which can be configured in the "trackOptions" declaration and their default value:

startPhi-starting value for the rotation around the vertical axis. Default value: 0.0, that means front view
startTheta-starting value for view tilt. Default value: 0.0, that means straight view
startDistance-starting view distance from the object. Default value: 2.0
minMaxPhi-limits for the rotation around the vertical axis, with respect to the frontal view; if [-180.0, 180.0], the object can rotate continuously without limits. Default value: [-180.0, 180.0], which is equal to continuous rotation
minMaxTheta-upper and lower limit for the view tilt. Default value: [-80.0, 80.0]
minMaxDist-upper and lower limit for the view distance. Default value: [0.2, 4.0]

This trackball can also be animated, as detailed in this HOWTO.



TurnTable Pan Trackball

Click to run live demo
The 3DHOP object in-hand metaphor: the TurnTable Trackball

The TurnTable Pan trackball is an extension of the TurnTable trackball just presented, that also allow the user to pan across the object, changing the center of rotation. Still very simple to use, it gives more freedom to explore the objects, especially when zooming close to the surface. Left mouse button + horizontal mouse movement rotates the object around its vertical axis, and left mouse button + vertical mouse movement tilts the view direction up or down; mouse wheel zooms in and out; CTRL + left mouse button + mouse movements (or middle mouse button + mouse movements) pans across the object. Double-click on a 3D model, and 3DHOP will re-center the trackball on the clicked point and zoom in a little (using a smooth animation).
This trackball is controlled by a "phi" angle of rotation around the vertical axis, a "theta" angle of view tilt, a view "distance" acting like a zoom, plus the "panX" "panY" "panZ" panning parameters.

Set Up

If we want to explicitly ask for a TurnTable Pan trackball, or to configure its parameters, it is necessary to add a trackball entity while declaring the scene in the "setScene" function, and specify TurntablePanTrackball as type, like in this example. As the TurnTable Pan trackball is the default one, this step is only required if we want to configure the trackball parameters.

var presenter = null;

function setup3dhop() {
  presenter = new Presenter("draw-canvas");

  presenter.setScene({
    ...
    trackball: {
      type: TurntablePanTrackball
    }
  });
}  

Configuration

Once we have declared the TurnTable Pan trackball, it is then possible to configure its parameters, by adding a "trackOptions" and specifying a value for all the parameters we want to change. It is not mandatory to always specify all parameters; if a parameter is not included in the declaration, its default value will be applied.
In the following example, we configure all the parameters of the TurnTable Pan trackball.

var presenter = null;

function setup3dhop() {
  presenter = new Presenter("draw-canvas");

  presenter.setScene({
    ...
    trackball: {
      type: TurntablePanTrackball,
      trackOptions: {
		startPhi      : 0.0,
		startTheta    : 0.0,
		startDistance : 2.5,
		startPanX     : 0.0,
		startPanY     : 0.0,
		startPanZ     : 0.0,
		minMaxPhi     : [-180, 180],
		minMaxTheta   : [-10.0, 50.0],
		minMaxDist    : [0.5, 3.0],
		minMaxPanX    : [-0.5, 0.5],
		minMaxPanY    : [-0.6, 0.6],
		minMaxPanZ    : [-0.3, 0.3],
      }
    }
  });
}  

Here is a description of the different parameters which can be configured in the "trackOptions" declaration and their default value:

startPhi-starting value for the rotation around the vertical axis. Default value: 0.0, that means front view
startTheta-starting value for view tilt. Default value: 0.0, that means straight view
startDistance-starting view distance from the object. Default value: 2.0
minMaxPhi-limits for the rotation around the vertical axis, with respect to the frontal view; if [-180.0, 180.0], the object can rotate continuously without limits. Default value: [-180.0, 180.0], which is equal to continuous rotation
minMaxTheta-upper and lower limit for the view tilt. Default value: [-80.0, 80.0]
minMaxDist-upper and lower limit for the view distance. Default value: [0.2, 4.0]

This trackball can also be animated, as detailed in this HOWTO.



PanTilt Trackball

Click to run live demo
The 3DHOP object in-hand metaphor: the PanTilt Trackball

The PanTilt trackball is especially suited to manage mostly-flat, vertically-mounted objects like bas-reliefs or wall panels, with an interesting front side, but nothing to see on the other sides. It is possible to pan across the object horizontally and vertically using CTRL + left mouse button + mouse movements (or middle mouse button + mouse movements), tilt the view direction horizontally and vertically using left mouse button + mouse movements, and zoom in and out using mouse wheel. Double-click on a 3D model, and 3DHOP will re-center the trackball on the clicked point and zoom in a little (using a smooth animation).
This trackball is controlled by a "panX" and "panY" offset parameters, "tiltX" "tiltY" view tilt angles, and a view "distance" acting like a zoom.

Set Up

If we want to explicitly ask for a PanTilt trackball, or to configure its parameters, it is necessary to add a trackball entity while declaring the scene in the "setScene" function, and specify PanTiltTrackball as type, like in this example.

var presenter = null;

function setup3dhop() {
  presenter = new Presenter("draw-canvas");

  presenter.setScene({
    ...
    trackball: {
      type: PanTiltTrackball
    }
  });
}  

Configuration

Once we have declared the PanTilt trackball, it is then possible to configure its parameters, by adding a "trackOptions" and specifying a value for all the parameters we want to change. It is not mandatory to always specify all parameters; if a parameter is not included in the declaration, its default value will be applied.
In the following example, we configure all the parameters of the PanTilt trackball.

var presenter = null;

function setup3dhop() {
  presenter = new Presenter("draw-canvas");

  presenter.setScene({
    ...
    trackball: {
      type: PanTiltTrackball,
      trackOptions: {
        startPanX: 0.0,
        startPanY: 0.0,
        startAngleX: 0.0,
        startAngleY: 0.0,
        startDistance: 2.5,
        minMaxPanX: [-0.7, 0.7],
        minMaxPanY: [-0.7, 0.7],
        minMaxAngleX: [-70.0, 70.0],
        minMaxAngleY: [-70.0, 70.0],
        minMaxDist: [0.5, 3.0]
      }
    }
  });
}  

Here is a description of the different parameters which can be configured in the "trackOptions" declaration and their default value:

startPanX-starting value for horizontal pan, with respect to scene center. Default value: 0.0, that means scene center
startPanY-starting value for vertical pan, with respect to scene center. Default value: 0.0, that means scene center
startAngleX-starting value for horizontal tilt. Default value: 0.0, that means straight view
startAngleY-starting value for vertical tilt. Default value: 0.0, that means straight view
startDistance-starting view distance from the object. Default value: 2.0
minMaxPanX-upper and lower limit for horizontal pan. Default value: [-0.7, 0.7]
minMaxPanY-upper and lower limit for vertical pan. Default value: [-0.7, 0.7]
minMaxAngleX-upper and lower limit for horizontal tilt. Default value: [-70.0, 70.0]
minMaxAngleY-upper and lower limit for vertical tilt. Default value: [-70.0, 70.0]
minMaxDist-upper and lower limit for the view distance. Default value: [0.2, 4.0]

This trackball can also be animated, as detailed in this HOWTO.



Sphere Trackball

Click to run live demo
The 3DHOP object in-hand metaphor: the Sphere Trackball

The Sphere trackball is the generic, sphere-like interaction paradigm used in many 3D software tools. It enables full and free rotation and panning on all axes, making it possible to reach every possible view direction. However, due to its freedom of movement can be be more difficult to be used by non-experts.
Horizontal and vertical mouse movement rotate the object as it were enclosed in a sphere, rolling under the mouse; CTRL + left mouse button + mouse movements (or middle mouse button + mouse movements) pans the object, changing the center of rotation; mouse wheel zooms in and out. Double-click on a 3D model, and 3DHOP will re-center the trackball on the clicked point and zoom in a little.

Set Up

If we want to explicitly ask for a Sphere trackball, or to configure its parameters, it is necessary to add a trackball entity while declaring the scene in the "setScene" function, and specify SphereTrackball as type, like in this example.

var presenter = null;

function setup3dhop() {
  presenter = new Presenter("draw-canvas");

  presenter.setScene({
    ...
    trackball: {
      type: SphereTrackball
    }
  });
}  

Configuration

Once we have declared the Sphere trackball, it is then possible to configure its parameters, by adding a "trackOptions" and specifying a value for all the parameters we want to change. It is not mandatory to always specify all parameters; if a parameter is not included in the declaration, its default value will be applied.
In the following example, we configure all the parameters of the Sphere trackball.

var presenter = null;

function setup3dhop() {
  presenter = new Presenter("draw-canvas");

  presenter.setScene({
    ...
    trackball: {
      type: SphereTrackball,
      trackOptions : {
        startDistance : 2.5,
        minMaxDist: [0.5, 3.0]
      }
    }
  });
} 

Here is a description of the different parameters which can be configured in the "trackOptions" declaration and their default value:

startDistance-starting view distance from the object. Default value: 2.0
minMaxDist-upper and lower limit for the view distance. Default value: [0.2, 4.0]

As shown above the only configurable parameters for this trackball are "startingDistance" and "minMaxDist", that control the starting view distance from the object and specific the view distance limits. Moreover at the moment this trackball can't be animated (these limitations may be lifted in the next update).



The complete sources of these examples are provided together the 3DHOP code in the download section.

If you want instead to learn more about how to define a complex scene into 3DHOP click here and go to the next HOWTO.