Skip to content

270 Degrees Annotations Plugin

The 270 Degrees Annotations Plugin adds a flexible system for placing and managing interactive pins within the 3D Viewer.
These annotation pins can be used to highlight features, display contextual information, or provide guidance directly in the 3D scene.

270 Viewer Annotations

Overview

Key Features

  • Add Pins Anywhere: Position annotation pins in 3D space using precise coordinates.
  • Custom Labels: Display text, HTML, or custom elements as pin content.
  • Dynamic Visibility: Show or hide pins individually or in groups.
  • Occlusion Detection: Pins are marked as is-occluded when facing away from the camera.
  • Debug Tools: Visualize pin positions with optional debug markers.
  • Performance-Aware Rendering: Batch updates and manually control rendering when needed.

Installation

The Annotations Plugin is easy to integrate and provides a robust API for developers to easily add labels to their scene.

  1. Load the plugin script after you have loaded the Viewer script.

    <script src="https://api.270degrees.nl/api/script/latest/annotations.js"></script>
    import * as TSDAnnotations from 'https://api.270degrees.nl/api/script/latest/annotations.esm.js';

  2. Attach the plugin to your viewer automatically: 

    TSDViewer.create(element, {
    plugins: 'annotations'
})
    <div class="js-270viewer" data-270-plugins="annotations">

    Or attach it via javascript after TSDViewer.create():

    TSDAnnotations.attach(element, {
    onAttach: () => {
        // attached the plugin methods
    }
});

  3. Access methods
    Annotation methods are now available via the Annotations namespace, for example element.Annotations.getPins().
    Read more about the avaiable methods.

Usage notes

An Annotation consists of a Pin and a Label:

Pins are 3D Anchors

Each pin represents a point in 3D space, defined by x, y, and z coordinates.
When added, the plugin projects this point into screen space and attaches a DOM element (label) to it.

Labels are DOM Elements

The label content (e.g., text, HTML, or even a full HTMLElement) is injected into a div.TSD-pin-label, which is positioned over the 3D canvas using screen coordinates.

DOM Structure

Each pin creates the following structure in the DOM:

<div class="TSD-pin-container myPin">
  <div class="TSD-pin-label">Look at this</div>
</div>
  • .TSD-pin-container wraps each pin and includes the pin’s name as an additional class (e.g., myPin in this example).
  • .TSD-pin-label contains the label content, which can be plain text, HTML, or a full HTMLElement.

Occlusion

As the camera moves, the plugin automatically repositions labels to stay aligned with their corresponding 3D points.
If the pin is facing away from the camera, its container will get the is-occluded class: div.TSD-pin-container.is-occluded.
You can use this to adjust the styling accordingly, like (partially) hiding the label. 

.TSD-pin-container.is-occluded {
    opacity: 0.3;
}

Unattaching

You can unload the Annotations completely by calling TSDAnnotations.unattach(el).
This will remove all Annotations and associated methods and listeners from the Viewer.