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:
- Create an HTML element and apply style
position: absoluteto the element. There also some other recommended styles that should be applied (see below).
- Determine 3D world coordinate of the pivot point (e.g. using intersection when user clicks an object)
- Attach overlay using
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.
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%);
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
callback is triggered every time the HTML overlay is updated.
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
Overlays can change visibility of elements with
visible(true/false), which will unhide/hide all the elements in the overlay.
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
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
which causes overlay elements that overlap on screen to be replaced with a composite
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.