3DSOM Pro Hotspot Editor

On this page:
Installation
Editor Instructions
Technical Info

Experienced users can extend the interaction avaliable with the SOM java models by defining active regions ('hot-spots') on the 3D model. When the mouse cursor is left stationary over a hotspot region ('hovers') the java viewer will overlay a short text message in a box. When a hotspot region is clicked the web page is dynamically changed using JavaScript.

This page desribes how to use the 3DSOM Pro Hotspot Editor to automatically create a webpage containing a 3DSOM Pro model displayed using the 3DSOM Pro Java Viewer with a number of hotspots. Once created, an expert user can modify the page manually, or cut and paste parts into their own webpages.

Installation

To install the hotspot editor...

Using the Hotspot Editor

The default page created by the Hotspot Editor consists of two distinct areas. The left side displays the 3D model in an interactive applet. The right side displays a title and some text describing more information on the object. When the user clicks on a hotspot, the text on the right will dynamically change to display the desired context-sensitive information. (With some JavaScript expertise you can modify the behaviour to perform other actions.)

Choose the model

The first step is to select the required 3D model. Hit the "Browse..." button and select the ".htm" file associated with the model exported from 3DSOM. The model must have been exported from 3DSOM Pro in the 3DSOM Pro Viewer format.

Basic page content

Now enter the heading for the right hand area of the page in the box on the form next to "Page heading:". Typically this is a title for your 3D object.

To define the default information that will be displayed on the final page (when no hotspot is active) hit the "Set Initial Text" button and fill in the form. You can use any valid html fragment. For example, use tags such as "<b>...</b>" for bold or "<p>...</p>" to define a paragraph. If you wish, you can use a WYSIWIG html editor and then cut and paste the text inside the "<body>" section of your document into this form.

Name each hotspot and what it displays

Before you can define the hotspot regions, you need to give each hotspot an identifier (id). Hit the "New/Edit" button. Then type in the ID (e.g. "head" or "id1" ). The ID should be nice and short but is never seen by the end user.

A form will then be displayed to control what is displayed when this hotspot is active. Enter the "Mouse-over text" to be displayed when the mouse hovers over the hotspot. Then enter the text to be displayed on the right hand side when the user clicks the hotspot. (As before this can be formatted using html tags) and hit "done".

Once you have entered the hotspot IDs you can select one from the drop down menu. You can always add new hotspots or edit the information associated with the existing hotspots by selecting the desired ID from the drop-down list and then clicking on the "New/Edit" button.

Define hotspot regions on the model

For each hotspot you need to define a region on the model by interactively marking one or more reference points on the 3d model. The way these marked points define each region on the model is controlled by the two thresholds for the page.

Rough shapes can be defined by marking just a few reference points and setting a high value such as 1000 for the distance threshold and a low value such as 5 for the confidence. For more accurate regions, add lots of reference points, particularly where the regions are close together. Increasing the confidence threshold increases the separation between the regions and will also result in more areas of the model having no associated hotspot at all.

Note: The current mouse position (projected back onto a 3D position on the model) is compared to the labelled reference points. In order to activate a hotspot two constraints must be satisfied. The distance in 3D from the (back-projected) mouse position to the nearest labelled point must be less than the supplied "distance threshold". A confidence value calculated by looking at the relative distance to the next closest hotspot region must be greater than the supplied "confidence threshold". The reference points also include orientation information allowing the top and bottom sides of a very thin flat object to be associated with different hotspot regions.

To add a reference point for a hotspot region, select the hotspot ID from the drop-dpwn menu and left-click on the stationary 3D model in the desired location. If the model is spinning you can click once to stop it first. Remember to rotate the model and add reference points from all sides.

You will notice that the nearest hotspot is dynamically displayed along with the distance and confidence values as you hover over the model. If the hotspot would be active given the current threshold values, it is displayed against a green background. When the current mouse position is over a point on the model that should be part of the current region but the hotspot is not displayed as active then either add a reference point at that location or modify the thresholds appropriately.

Note: Avoid adding too many hotspots as this will increase the size of your page and decrease the speed of interaction for the end user.

Creating the page

When you are happy that your hotspot regions are correctly defined hit the "Create Page" button. A new window will appear containing the HTML text that defines the required interactive viewer. Select the text in the textbox (right_mouse_menu->Select_All then right_mouse_menu->Copy). Open a text editor with a blank document and paste in the selected text. Now save the file with an ".htm" extension in the same directory as the 3D model files.

You should now be able to launch the .htm file to see the interactive 3D viewer with hotspots. If you are happy upload the .htm and .jar files onto your web site!

If you are an expert web developer (JavaScript, DHTML), you can edit the file to customise the viewer (see technical info).

Technical info:

The hotspot functionality is implemented using JavaScript and Java technologies.

There are 3 applet parameters:

  • "onInit": the value of this parameter is a string. The string is sent to the JavaScript interpreter of the browser as soon as the Java applet is up and running. This can be used to hide the applet area (grey box) until the applet is fully loaded. See the trainer model on the examples page.
  • "mouseOverHandler": the value of this parameter is a JavaScript function name. This function will be called when the mouse is hovering over the model. The handler will be called with a single string parameter. The format of this string is "coords=x,y,z;look=u,v,w" where the 3d position of the mouse cursor projected onto the model is (x,y,z) and the direction of sight of the current viewpoint is (u,v,w) in world coordinates scaled by 1000 (so that x,y,z,u,v,w are all between 0 and 1000). The handler function should return the text popup string to be overlaid on the viewer window or a zero-length string if no hotspot is active. The handler function should also set the window status bar to reflect the text popup (e.g. window.status="axe"; ). This is required because the Microsoft JVM ignores the return value from the JavaScript handler function.
  • "mouseClickHandler": the value of this parameter is a JavaScript function name. This function will be called when the user clicks on the model. A single string parameter is used as for the mouseOverHandler.

If you wish to write your own JavaScript handler functions note that they are called from the applet and execution will return to the applet. If the applet is no longer there (e.g. the function opens a new URL on top of the existing page) the results may be unpredictable in some browsers. Use the setTimeout JavaScript function in these cases to avoid problems (see Knight example).

The output html code generated by the hotspot editor calls JavaScript functions from within Java. We have avoided Java applet calls from within JavaScript methods as this does not work well in Netscape due to a known bug (there is a substantial delay due to a DNS lookup).