API Docs for: 1.0.0

Annotation

Extends Pin
Module: annotations
Parent Module: xeogl

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

Overview

Position

An Annotation is positioned within one of the triangles of its Entity'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 Entity 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 Entities. 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.min.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/2.0/Reciprocating_Saw/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 view = model.scene.camera.view;
   view.eye = [-110.89, -44.85, 276.65];
   view.look = [-110.89, -44.85, -0.46];
   view.up = [0, 1, 0];
   view.zoom(20);

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

   var a1 = new xeogl.Annotation({
       entity: model.entities[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({
       entity: model.entities[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({
       entity: 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.

    • [entity] Number | String | Entity optional

      ID or instance of the Entity 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 Entity 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 view.

    • [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]
  • [instanceId]
)

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

You would typically use this method to conveniently instantiate components that you'd want to share (ie. "instance") among your Entities.

The method is given a component type, configuration and optional instance ID, like so:

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

The first time you call this method for the given type and instanceId, this method will create the PhongMaterial, passing the given attributes to the component's constructor.

If you call this method again, specifying the same type and instanceId, the method will return the same component instance that it returned the first time, and will ignore the configuration:

var material2 = component.create(xeogl.PhongMaterial, { specular: [1,1,0] }, "myMaterial");

So in this example, our PhongMaterial will continue to have the red specular and diffuse color that we specified the first time.

Each time you call this method with the same type and instanceId, the Scene will internally increment a reference count for the component instance. You can release the shared component instance with a call to Scene/putSharedComponent:method, and once you have released it as many times as you got it, the Scene will destroy the component.

Parameters:

  • [cfg] optional

    Configuration for the component instance - only used if this is the first time you are getting the component, ignored when reusing an existing instance.

  • [instanceId] String | Number optional

    Identifies the shared component instance. Note that this is not used as the ID of the component - you can specify the component ID in the cfg parameter.

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

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 superTypes, 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.Entity); // Returns false, because xeogl.Rotate does not (even indirectly) extend xeogl.Entity

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

(
  • handle
)

Cancels an event subscription that was previously made with on or once.

Parameters:

  • handle String

    Publication handle

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 handled.

This is equivalent to calling on, and then calling 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

entity

Number | String | xeogl.Entity

The Entity this Pin is attached to.

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

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

Fires an entity event on change.

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.

isDefault

Boolean

Indicates whether this is one of the Scene's built-in Components.

json

JSON final

JSON object containing the state of this Component.

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]

metadata

Object

Arbitrary, user-defined metadata on this component.

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: true

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 Entity, 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.

string

String final

Inherited from Component but overwritten in src/component.js:1056

String containing the serialized JSON state of this Component.

superTypes

Array of String final

An array of strings that indicates the chain of super-types within this component's inheritance hierarchy.

For example, if this component is a Rotate, which extends Transform, which in turn extends Component, then this property will have the value:

["xeogl.Component", "xeogl.Transform"]
                    

Note that the chain is ordered downwards in the hierarchy, ie. from super-class down towards sub-class.

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.

This is used when loading Scenes from JSON, and is included in the JSON representation of this Component, so that this class may be instantiated when loading it from the JSON representation.

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]

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

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.

entity

Fired whenever this Pin's entity property changes.

Event Payload:

  • value Object

    The property's new value

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

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 look 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

worldPos

Fired whenever this Pin's worldPos property changes.