Hotspots & Annotations

The Dimensions 3D Viewer provides a client-side (JS) API to easily set up hotspots with annotations on the displayed 3D Model.

If you're not familiar yet with how to get started with the viewer go ahead and read this article first: Getting started with the Dimensions 3D Viewer.

Once you have the viewer set up on your page and loading a model, you can define the hotspots.

Example

Here's the basic code to get the model showing on your page with hotspots:

<body>
 <div id="three-d-viewer"
     style="height: 400px" 
     data-d8s-type="3d"
     data-d8s-id="prod-identifier"> 
 </div>


 <script>
  const d8sApi = initDimensions({
    account: "my-account-name", 
    viewers: ["3D"],
    threeDViewer: {
     viewer: {
       hotspots: {
	  enabled: true,
	  showLabels: true,
          size: "large",
          
          annotations: [
           {            
             mesh: "0.0",
             title: "Seat",
             text: "this is the seat area of the model",
             offset: [0.21, 0.5, -0.72],
           }
         ]
      }       
     }
    }
  });
 </script>
</body>

Mesh Assignment

Hotspots are assigned to objects (typically meshes) within the model. The mesh property of each annotation object is the hierarchal path to to the mesh inside the model.

The path can use either the name of the object or its index within its parent. It's also possible combine the the syntax like this: mesh: "0.frame001". This will target the mesh named "frame001" that is a child of the first object in the model's scene graph.

Reference

Hotspots

Below is the reference to all hotspots configuration properties:

hotspots: {
  //whether to show hotspots
  enabled: false,
  
  //whether to show all hotspots on load
  showOnLoad: true,

  //whether to expand hotspot annotation for mesh when its hovered  (showOnLoad must be false)
  showOnHover: false,

  //whether to always expand hotspots
  showExpanded: false,

  //whether to show labels on hotspots
  showLabels: false,

  //the size of the hotspots (small, medium, large), default: medium
  size: "medium",

  //by default expands on hover, if true, will wait for user to click
  expandOnClick: false,

  //whether to get annotation text from mesh's userData object
  contentFromUserData: false,

  //info of hotspots titles & texts
  annotations: [],
}

Annotation

Below is the reference to the annotation object that hotspots can have 1 or more of.

{
  //the path to the mesh inside the model (See Path Assignment above)
  mesh: String,

  //the text to show inside the hotspot. By default will the index of the annotation
  label: String,

  //the title to show in bold inside the annotation element
  title: String,

  //the text to show inside
  text: String, 

  //tuple array [x,y,z] of offset values to apply on the position 
  offset: Vector3,

  //the size of the hotspots (small, medium, large)
  size: "small" | "medium" | "large",

  //the color to use as the background of the hotspot/annotation
  background: String,

  //the color of the text for the hotspot/annotation
  color: String,
}

Offset

Hotspots are positioned using the mesh's position property (Vector3). The offset is applied on the position's property to make it possible to align the hotspot to the exact location you prefer. Typically a small change (<1) is enough. Using whole integers can cause the hotspot to disappear outside the view.

Title, Text, Label

Colors

By default, the background and text colors of the hotspots and annotations is determined by the theme (light, dark, custom). See reference here.

However, using the background & color properties of the annotation object, its possible to override.