API Docs for:

Annotation

An Annotation is a labeled Pin that's attached to the surface of a Mesh.

Overview

Position

An Annotation is positioned within one of the triangles of its Mesh's Geometry. Wherever that triangle goes within the 3D view, the Annotation will automatically follow. An Annotation specifies its position with two properties:

  • primIndex, which indicates the index of the triangle within the Geometry indices, and
  • bary, the barycentric coordinates of the position within the triangle.

From these, an Annotation dynamically calculates its Cartesian coordinates, which it provides in each xeogl coordinate space:

An Annotation automatically recalculates these coordinates whenever its Mesh is replaced or transformed, the Geometry is replaced or modified, or the Camera is moved.

Appearance

As shown in the screen shot above, an Annotation is rendered as a dot with a label attached to it, using HTML elements.

  • glyph specifies a character to appear in the dot,
  • title and desc specify a title and description to appear in the label, and
  • pinShown and labelShown specify whether the pin and label are shown.

Use the stylesheet in annotation-style.css to set the default appearance for Annotations. Use that stylesheet as a guide for your own custom styles.

Visibility

  • occludable specifies whether the Annotation becomes invisible whenever its occluded by other objects in the 3D view, and
  • visible indicates if the Annotations is currently visible.

Vantage points

Each Annotation may be configured with a vantage point from which to view it, given as eye, look and up properties. To focus attention on an Annotation, you could set the Camera's Lookat to that vantage point, or even fly to the vantage point using a CameraFlightAnimation (which we'll demonstrate in the usage example below).

Interaction

An Annotation fires a "pinClicked" event whenever you click its dot. In the usage example, we make that event show the Annotation's label and set the Camera to the vantage point.

Examples

Usage

In the example below, we use a GLTFModel to load a glTF model of a reciprocating saw. Once the GLTFModel has loaded, we'll then create Annotations on three of its Meshes. Finally, we wire a callback to the "pinClicked" event from each Annotation, so that when you click its Pin, its label is shown and the Camera is positioned at its vantage point.

<script src="../build/xeogl.js"></script>
<script src="js/annotations/pin.js"></script>
<script src="js/annotations/annotation.js"></script>

<link href="js/annotations/annotation-style.css" rel="stylesheet"/>

<script>

var model = new xeogl.GLTFModel({
   src: "models/gltf/ReciprocatingSaw/PBR-SpecGloss/Reciprocating_Saw.gltf",
   transform: new xeogl.Rotate({
       xyz: [1, 0, 0],
       angle: 90
   })
});

model.on("loaded", function () {

   // Position the camera to look at the model

   var camera = model.scene.camera;
   camera.eye = [-110.89, -44.85, 276.65];
   camera.look = [-110.89, -44.85, -0.46];
   camera.up = [0, 1, 0];
   camera.zoom(20);

   // Create three annotations on meshes
   // within the model

   var a1 = new xeogl.Annotation({
       mesh: model.meshes[156], // Red handle
       primIndex: 125,
       bary: [0.3, 0.3, 0.3],
       occludable: true,
       glyph: "1",
       title: "Handle",
       desc: "This is the handle. It allows us to grab onto the saw so we can hold it and make things with it.",
       eye: [-355.481, -0.871, 116.711],
       look: [-227.456, -57.628, 5.428],
       up: [0.239, 0.948, -0.208],
       pinShown: true,
       labelShown: false
   });

   var a2 = new xeogl.Annotation({
       mesh: model.meshes[156], // Red handle and cover
       primIndex: 10260,
       bary: [0.333, 0.333, 0.333],
       occludable: true,
       glyph: "2",
       title: "Handle and cover",
       desc: "This is the handle and cover. It provides something grab the saw with, and covers the things inside.",
       eye: [-123.206, -4.094, 169.849],
       look: [-161.838, -37.875, 37.313],
       up: [-0.066, 0.971, -0.228],
       pinShown: true,
       labelShown: false
   });

   var a3 = new xeogl.Annotation({
       mesh: modelentities[796], // Barrel
       primIndex: 3783,
       bary: [0.3, 0.3, 0.3],
       occludable: true,
       glyph: "3",
       title: "Barrel",
       desc: "This is the barrel",
       eye: [80.0345, 38.255, 60.457],
       look: [35.023, -0.166, 8.679],
       up: [-0.320, 0.872, -0.368],
       pinShown: true,
       labelShown: false
   });

   // When each annotation's pin is clicked, we'll show the
   // annotation's label and fly the camera to the
   // annotation's vantage point

   var cameraFlight = new xeogl.CameraFlightAnimation();
   var lastAnnotation;

   function pinClicked(annotation) {
       if (lastAnnotation) {
           annotation.labelShown = false;
       }
       annotation.labelShown = true;
       cameraFlight.flyTo(annotation);
       lastAnnotation = annotation;
   }

   a1.on("pinClicked", pinClicked);
   a2.on("pinClicked", pinClicked);
   a3.on("pinClicked", pinClicked);

   // If desired, we can also dynamically track the Cartesian coordinates
   // of each annotation in Local and World coordinate spaces

   a1.on("localPos", function(localPos) {
       console.log("Local pos changed: " + JSON.stringify(localPos, null, "\t"));
   });

   a1.on("worldPos", function(worldPos) {
       console.log("World pos changed: " + JSON.stringify(worldPos, null, "\t"));
   });
});
</script>

Constructor

Annotation

(
  • [scene]
  • [cfg]
)

Parameters:

  • [scene] Scene optional

    Parent Scene - creates this Pin in the default Scene when omitted.

  • [cfg] optional

    Configs

    • [id] String optional

      Optional ID, unique among all components in the parent Scene, generated automatically when omitted.

    • [meta] String:Object optional

      Optional map of user-defined metadata to attach to the Annotation.

    • [mesh] Number | String | Mesh optional

      ID or instance of the Mesh the Annotation is attached to.

    • [bary=[0.3,0.3,0.3] Float32Array optional

      Barycentric coordinates of the Annotation within its triangle.

    • [primIndex=0] Number optional

      Index of the triangle containing the Annotation. Within the Mesh Geometry indices, this is the index of the first element for that triangle.

    • [offset=0.2] Number optional

      How far the Annotation is lifted out of its triangle, along the surface normal vector. This is used when occlusion culling, to ensure that the Annotation is not lost inside the surface it's attached to.

    • [occludable=true] Boolean optional

      Indicates whether occlusion testing is performed for the Annotation, where it will be flagged invisible whenever it's hidden by something else in the 3D camera.

    • [glyph=""] String optional

      Short piece of text to show inside the pin for the Annotation. Automatically truncated to 2 characters.

    • [title=""] String optional

      Title text for the Annotation's label. Automatically truncated to 64 characters.

    • [desc=""] String optional

      Description text for the Annotation's label. Automatically truncated to 1025 characters.

    • [eye=[0,0,-10] Float32Array optional

      Position of the eye when looking at the Annotation.

    • [look=[0,0,0] Float32Array optional

      Position of the look when looking at the Annotation.

    • [up=[0,1,0] Float32Array optional

      Direction of the "up" vector when looking at the Annotation.

    • [pinShown=true] Boolean optional

      Specifies whether a UI element is shown at the Annotation's pin position (typically a circle).

    • [labelShown=true] Boolean optional

      Specifies whether the Annotation's label is shown.

Methods

create

(
  • [cfg]
)

Convenience method for creating a Component within this Component's Scene.

The method is given a component configuration, like so:

var material = myComponent.create({
     type: "xeogl.PhongMaterial",
     diffuse: [1,0,0],
     specular: [1,1,0]
}, "myMaterial");

Parameters:

  • [cfg] optional

    Configuration for the component instance.

Returns:

:

destroy

()

Destroys this component.

Fires a destroyed event on this Component.

Automatically disassociates this component from other components, causing them to fall back on any defaults that this component overrode on them.

TODO: describe effect with respect to #create

error

(
  • message
)

Logs an error for this component to the JavaScript console.

The console message will have this format: [ERROR] [<component type> =<component id>: <message>

Also fires the message as an error event on the parent Scene.

Parameters:

  • message String

    The message to log

fire

(
  • event
  • value
  • [forget=false]
)

Fires an event on this component.

Notifies existing subscribers to the event, optionally retains the event to give to any subsequent notifications on the event as they are made.

Parameters:

  • event String

    The event type name

  • value Object

    The event parameters

  • [forget=false] Boolean optional

    When true, does not retain for subsequent subscribers

hasSubs

(
  • event
)
Boolean

Returns true if there are any subscribers to the given event on this component.

Parameters:

  • event String

    The event

Returns:

Boolean:

True if there are any subscribers to the given event on this component.

isType

(
  • type
)
Boolean

Tests if this component is of the given type, or is a subclass of the given type.

The type may be given as either a string or a component constructor.

This method works by walking up the inheritance type chain, which this component provides in property Component/superTypes:property, returning true as soon as one of the type strings in the chain matches the given type, of false if none match.

Examples:

var myRotate = new xeogl.Rotate({ ... });

myRotate.isType(xeogl.Component); // Returns true for all xeogl components
myRotate.isType("xeogl.Component"); // Returns true for all xeogl components
myRotate.isType(xeogl.Rotate); // Returns true
myRotate.isType(xeogl.Transform); // Returns true
myRotate.isType("xeogl.Transform"); // Returns true
myRotate.isType(xeogl.Mesh); // Returns false, because xeogl.Rotate does not (even indirectly) extend xeogl.Mesh

Parameters:

  • type String | Function

    Component type to compare with, eg "xeogl.PhongMaterial", or a xeogl component constructor.

Returns:

Boolean:

True if this component is of given type or is subclass of the given type.

log

(
  • message
)

Logs a console debugging message for this component.

The console message will have this format: [LOG] [<component type> <component id>: <message>

Also fires the message as a log event on the parent Scene.

Parameters:

  • message String

    The message to log

off

(
  • subId
)

Cancels an event subscription that was previously made with Component#on() or Component#once().

Parameters:

  • subId String

    Publication subId

on

(
  • event
  • callback
  • [scope=this]
)
String

Subscribes to an event on this component.

The callback is be called with this component as scope.

Parameters:

  • event String

    The event

  • callback Function

    Called fired on the event

  • [scope=this] Object optional

    Scope for the callback

Returns:

String:

Handle to the subscription, which may be used to unsubscribe with {@link #off}.

once

(
  • event
  • callback
  • [scope=this]
)

Subscribes to the next occurrence of the given event, then un-subscribes as soon as the event is subIdd.

This is equivalent to calling Component#on(), and then calling Component#off() inside the callback function.

Parameters:

  • event String

    Data event to listen to

  • callback Function(data)

    Called when fresh data is available at the event

  • [scope=this] Object optional

    Scope for the callback

warn

(
  • message
)

Logs a warning for this component to the JavaScript console.

The console message will have this format: [WARN] [<component type> =<component id>: <message>

Also fires the message as a warn event on the parent Scene.

Parameters:

  • message String

    The message to log

Properties

bary

Float32Array

Barycentric coordinates of this Pin within its triangle.

A value of [0.3, 0.3, 0.3] is the center of the triangle.

Fires a bary event on change.

Default: [0.3,0.3,0.3]

canvasPos

Float32Array final

Canvas-space 2D coordinates of this Pin.

This is read-only and is automatically calculated.

Default: [0,0]

desc

String

Description text for the Annotation's label.

Automatically truncated to 1025 characters.

Fires a desc event on change.

Default: ""

destroyed

Boolean

True as soon as this Component has been destroyed

eye

Float32Array

Position of the eye when looking at the Annotation.

Fires a eye event on change.

Default: [0,0,10]

glyph

String

Short piece of text to show inside the pin for the Annotation.

Usually this would be a single number or letter.

Automatically truncated to 2 characters.

Fires a glyph event on change.

Default: ""

id

String final

Unique ID for this Component within its parent Scene.

labelShown

Boolean

Specifies whether the label is shown for the Annotation.

Fires a labelShown event on change.

Default: true

localPos

Float32Array final

Local-space 3D coordinates of this Pin.

This is read-only and is automatically calculated.

Fires a localPos event on change.

Default: [0,0,0]

look

Float32Array

Point-of-interest when looking at the Annotation.

Fires a look event on change.

Default: [0,0,0]

mesh

Number | String | xeogl.Mesh

The Mesh this Pin is attached to.

You can attach a Pin to a different Mesh at any time.

Note that primIndex should always be within the indices of the Geometry belonging to the Mesh.

Fires an mesh event on change.

metadata

Object

Arbitrary, user-defined metadata on this component.

model

Model final

The Model which contains this Component, if any.

Will be null if this Component is not in a Model.

occludable

Float32Array

Indicates whether occlusion testing is performed for this Pin.

When this is true, then visible will be false whenever the Pin is hidden behind something else in the 3D view.

Set this false if the Pin is to remain visible when hidden behind things while being within the canvas.

Fires a occludable event on change.

Default: false

offset

Number

How far the Pin is lifted out of its triangle, along the surface normal vector.

This is used when occlusion culling, to ensure that the Pin is not lost inside the surface it's attached to.

Fires a offset event on change.

Default: 0.2

pinShown

Boolean

Specifies whether a UI element is shown at the Annotation's pin position (typically a circle).

Fires a pinShown event on change.

Default: true

primIndex

Number

Index of the triangle containing this pin.

Within the indices of the Geometry attached to the Mesh, this is the index of the first element for that triangle.

Fires a primIndex event on change.

Default: 0

scene

Scene final

The parent Scene that contains this Component.

title

String

Title text for the Annotation's label.

Automatically truncated to 64 characters.

Fires a title event on change.

Default: ""

type

String final

JavaScript class name for this Component.

For example: "xeogl.AmbientLight", "xeogl.ColorTarget", "xeogl.Lights" etc.

up

Float32Array

"Up" vector when looking at the Annotation.

Fires a up event on change.

Default: [0,1,0]

viewPos

Float32Array final

View-space 3D coordinates of this Pin.

This is read-only and is automatically calculated.

Default: [0,0,0]

visible

Boolean final

Indicates if this Pin is currently visible.

This is read-only and is automatically calculated.

The Pin is invisible whenever:

  • canvasPos is currently outside the canvas, or
  • occludable is true and the Pin is currently occluded by something in the 3D view.

Fires a visible event on change.

Default: true

worldNormal

Float32Array final

World-space normal vector of this Pin.

This is read-only and is automatically calculated.

Fires a worldNormal event on change.

Default: [0,0,1]

worldPos

Float32Array final

World-space 3D coordinates of this Pin.

This is read-only and is automatically calculated.

Fires a worldPos event on change.

Default: [0,0,0]

Events

bary

Fired whenever this Pin's bary property changes.

Event Payload:

  • value Object

    Float32Array The property's new value

desc

Fired whenever this Annotation's desc property changes.

Event Payload:

  • value Number

    The property's new value

destroyed

Fired when this Component is destroyed.

eye

Fired whenever this Annotation's eye property changes.

Event Payload:

  • value Number

    The property's new value

glyph

Fired whenever this Annotation's glyph property changes.

Event Payload:

  • value Number

    The property's new value

labelShown

Fired whenever this Annotation's labelShown property changes.

Event Payload:

  • value Number

    The property's new value

localPos

Fired whenever this Pin's localPos property changes.

look

Fired whenever this Annotation's look property changes.

Event Payload:

  • value Number

    The property's new value

mesh

Fired whenever this Pin's mesh property changes.

Event Payload:

  • value Object

    The property's new value

occludable

Fired whenever this Pin's occludable property changes.

Event Payload:

  • value Object

    Float32Array The property's new value

offset

Fired whenever this Pin's offset property changes.

Event Payload:

  • value Object

    Number The property's new value

pinClicked

Fired whenever the mouse is clicked on this Annotation's Annotation/pin:property.

pinShown

Fired whenever this Annotation's pinShown property changes.

Event Payload:

  • value Number

    The property's new value

primIndex

Fired whenever this Pin's primIndex property changes.

Event Payload:

  • value Object

    Number The property's new value

title

Fired whenever this Annotation's title property changes.

Event Payload:

  • value Number

    The property's new value

up

Fired whenever this Annotation's up property changes.

Event Payload:

  • value Number

    The property's new value

visible

Fired whenever this Pin's visible property changes.

Event Payload:

  • value Object

    Float32Array The property's new value

worldNormal

Fired whenever this Pin's worldNormal property changes.

worldPos

Fired whenever this Pin's worldPos property changes.