Class: HtmlOverlayTool

@cognite/reveal/tools.HtmlOverlayTool

Manages HTMLoverlays for @see {@link Cognite3DViewer}. Attaches HTML elements to a 3D position and updates its position/visibility as user moves the camera. This is useful to create HTML overlays to highlight information about key positions in the 3D model.

Attached elements must have CSS style 'position: absolute'. It's also recommended in most cases to have styles 'pointer-events: none' and 'touch-action: none' to avoid interfering with 3D navigation. Consider also applying 'transform: translate(-50%, -50%)' to anchor the center of the element rather than the top-left corner. In some cases the zIndex-attribute is necessary for the element to appear on top of the viewer.

example

const el = document.createElement('div');
el.style.position = 'absolute'; // Required!
// Anchor to center of element
el.style.transform = 'translate(-50%, -50%)';
// Avoid being target for events
el.style.pointerEvents = 'none;
el.style.touchAction = 'none';
// Render in front of other elements
el.style.zIndex = 10;

el.style.color = 'red';
el.innerHtml = '<h1>Overlay</h1>';

const overlayTool = new HtmlOverlayTool(viewer);
overlayTool.add(el, new THREE.Vector3(10, 10, 10));
// ...
overlayTool.remove(el);
// or, to remove all attached elements
overlayTool.clear();

// detach the tool from the viewer
overlayTool.dispose();

Hierarchy

• Cognite3DViewerToolBase

  ↳ HtmlOverlayTool

Constructors

constructor

• new HtmlOverlayTool(viewer, options?)

Parameters

Name	Type
viewer	Cognite3DViewer
options?	HtmlOverlayToolOptions

Overrides

Cognite3DViewerToolBase.constructor

Defined in

packages/tools/src/HtmlOverlay/HtmlOverlayTool.ts:166

Accessors

elements

• get elements(): { element: HTMLElement ; position3D: Vector3 }[]

Returns all added HTML elements along with their 3D positions.

Returns

{ element: HTMLElement ; position3D: Vector3 }[]

Defined in

packages/tools/src/HtmlOverlay/HtmlOverlayTool.ts:186

Methods

add

▸ add(htmlElement, position3D, options?): void

Registers a HTML overlay that will be updated on rendering.

Parameters

Name	Type
htmlElement	HTMLElement
position3D	Vector3
options	HtmlOverlayOptions

Returns

void

Defined in

packages/tools/src/HtmlOverlay/HtmlOverlayTool.ts:210

---

clear

▸ clear(): void

Removes all attached HTML overlay elements.

Returns

void

Defined in

packages/tools/src/HtmlOverlay/HtmlOverlayTool.ts:258

---

dispose

▸ dispose(): void

Removes all elements and detaches from the viewer.

override

Returns

void

Overrides

Cognite3DViewerToolBase.dispose

Defined in

packages/tools/src/HtmlOverlay/HtmlOverlayTool.ts:196

---

forceUpdate

▸ forceUpdate(): void

Updates positions of all overlays. This is automatically managed and there shouldn't be any reason to trigger this unless the attached elements are modified externally.

Calling this function often might cause degraded performance.

Returns

void

Defined in

packages/tools/src/HtmlOverlay/HtmlOverlayTool.ts:292

---

off

▸ off(event, handler): void

Unregisters an event handler for the 'disposed'-event.

Parameters

Name	Type
event	"disposed"
handler	() => void

Returns

void

Inherited from

Cognite3DViewerToolBase.off

Defined in

packages/tools/src/Cognite3DViewerToolBase.ts:37

---

remove

▸ remove(htmlElement): void

Removes a overlay and removes it from the DOM.

Parameters

Name	Type
htmlElement	HTMLElement

Returns

void

Defined in

packages/tools/src/HtmlOverlay/HtmlOverlayTool.ts:246

---

visible

▸ visible(enable): void

Hide/unhide all HTML overlay elements.

Parameters

Name	Type
enable	boolean

Returns

void

Defined in

packages/tools/src/HtmlOverlay/HtmlOverlayTool.ts:270