Skip to main content
Version: 4.x

HTML overlays

A common requirement for a 3D application is to add information overlays hovering over 3D objects to provide details or draw the attention to a given point. This can be done by placing HTML elements over the 3D canvas that follows the object it's attached to. HtmlOverlayTool is a convinience tool to manage overlays. The tool also supports "clustering", i.e. that overlapping elements are combined into a single element to avoid clustering.

Note that these overlays always will be placed on top of the 3D viewer, they will not be hidden when the object is obscured by other objects. To achieve this it's necessary to use custom 3D objects.

Attaching HTML elements to 3D objects/positions requires the following operations:

  1. Create an HTML element and apply style position: absolute to the element. There also some other recommended styles that should be applied (see below).
  2. Determine 3D world coordinate of the pivot point (e.g. using intersection when user clicks an object)
  3. Attach overlay using HtmlOverlayTool.add.

This will attach the overlay to the 2D position corresponding to the 3D coordinate, then it will provide the updated coordinate whenever navigating the viewer.

note

The following CSS style is recommended for overlays:

position: absolute; /* Required */

/* Anchor to the center of the element and ignore events */
transform: translate(-50%, -50%);
pointer-events: none;
touch-action: none;
user-select: none;
Live Editor

It's also possible to apply styling based on the position of the overlay, e.g. to vary the opacity of the overlay based on distance from the camera. To do this, provide an options-argument with a positionUpdatedCallback to HtmlOverlayTool.add. This callback is triggered every time the HTML overlay is updated.

Live Editor

As shown above, overlays can be removed using remove(). It is also possible to remove all overlays by calling clear() or by disposing the tool using dispose(). The tool cannot be used after calling dispose().

Overlays can change visibility of elements with visible(true/false), which will unhide/hide all the elements in the overlay.

Clustering overlays​

The overlay tool also support clustering of elements. When enabled, the tool will detect overlapping HTML elements and combine them into a single element by invoking a callback factory for creating a "composite" element. This is useful to avoid cluttering when theres a high number of overlays in the view.

Clustering is enabled by providing an options-argument to the constructor or HtmlOverlayTool and provide a cluster mode and a callback for creating a "composite element" based on a set a set of clustered overlay elements. Currently the only mode supported is overlapByScreenSpace which causes overlay elements that overlap on screen to be replaced with a composite element.

Each overlay added to HtmlOverlayTool may have assosciated, custom userData. This data can be used to create custom labels for composite elements.

In the following example, overlays are added on click in the model. When overlays overlap they are replaced with composite elements. userData is used to display a value range of the underlying overlay elements.

Live Editor