Reference Source
public class | source

Marker

Extends:

Component → Marker

Direct Subclass:

Annotation, SpriteMarker

Tracks the World, View and Canvas coordinates, and visibility, of a position within a Scene.

Position

A Marker holds its position in the World, View and Canvas coordinate systems in three properties:

  • Marker#worldPos holds the Marker's 3D World-space coordinates. This property can be dynamically updated. The Marker will fire a "worldPos" event whenever this property changes.
  • Marker#viewPos holds the Marker's 3D View-space coordinates. This property is read-only, and is automatically updated from Marker#worldPos and the current Camera position. The Marker will fire a "viewPos" event whenever this property changes.
  • Marker#canvasPos holds the Marker's 2D Canvas-space coordinates. This property is read-only, and is automatically updated from Marker#canvasPos and the current Camera position and projection. The Marker will fire a "canvasPos" event whenever this property changes.

Visibility

Marker#visible indicates if the Marker is currently visible. The Marker will fire a "visible" event whenever Marker#visible changes.

This property will be false when:

Usage

In the example below, we'll create a Marker that's associated with a Mesh (which a type of Entity).

We'll configure our Marker to become invisible whenever it's occluded by any Entities in the canvas.

We'll also demonstrate how to query the Marker's visibility status and position (in the World, View and Canvas coordinate systems), and how to subscribe to change events on those properties.

[Run this example]

import {Viewer, GLTFLoaderPlugin, Marker} from "xeokit-sdk.es.js";

const viewer = new Viewer({
    canvasId: "myCanvas"
});

// Create the torus Mesh
// Recall that a Mesh is an Entity
new Mesh(viewer.scene, {
    geometry: new ReadableGeometry(viewer.scene, buildTorusGeometry({
        center: [0,0,0],
        radius: 1.0,
        tube: 0.5,
        radialSegments: 32,
        tubeSegments: 24,
        arc: Math.PI * 2.0
    }),
    material: new PhongMaterial(viewer.scene, {
        diffuseMap: new Texture(viewer.scene, {
            src: "textures/diffuse/uvGrid2.jpg"
        }),
        backfaces: true
    })
});

// Create the Marker, associated with our Mesh Entity
const myMarker = new Marker({
     entity: entity,
     worldPos: [10,0,0],
     occludable: true
});

// Get the Marker's current World, View and Canvas coordinates
const worldPos   = myMarker.worldPos;     // 3D World-space position
const viewPos    = myMarker.viewPos;      // 3D View-space position
const canvasPos  = myMarker.canvasPos;    // 2D Canvas-space position

const visible = myMarker.visible;

// Listen for change of the Marker's 3D World-space position
myMarker.on("worldPos", function(worldPos) {
   //...
});

// Listen for change of the Marker's 3D View-space position, which happens
// when either worldPos was updated or the Camera was moved
myMarker.on("viewPos", function(viewPos) {
   //...
});

// Listen for change of the Marker's 2D Canvas-space position, which happens
// when worldPos or viewPos was updated, or Camera's projection was updated
myMarker.on("canvasPos", function(canvasPos) {
   //...
});

// Listen for change of Marker visibility. The Marker becomes invisible when it falls outside the canvas,
// has an Entity that is also invisible, or when an Entity occludes the Marker's position in the 3D view.
myMarker.on("visible", function(visible) { // Marker visibility has changed
   if (visible) {
       this.log("Marker is visible");
   } else {
       this.log("Marker is invisible");
   }
});

// Listen for destruction of Marker
myMarker.on("destroyed", () => {
     //...
});

Constructor Summary

Public Constructor
public

constructor(owner: Component, cfg: *)

Member Summary

Public Members
public get

Canvas-space 2D coordinates of this Marker.

public set

Sets the Entity this Marker is associated with.

public get

Gets the Entity this Marker is associated with.

public set

Sets whether occlusion testing is performed for this Marker.

public get

Gets whether occlusion testing is performed for this Marker.

public get

Gets the RTC center of this Marker.

public get

Gets the RTC position of this Marker.

public get

View-space 3D coordinates of this Marker.

public get

Indicates if this Marker is currently visible.

public set

Sets the World-space 3D position of this Marker.

public get

Gets the World-space 3D position of this Marker.

Method Summary

Public Methods
public

Destroys this Marker.

Inherited Summary

From class Component
public get

The Component that owns the lifecycle of this Component, if any.

public

True as soon as this Component has been destroyed

public

ID of this Component, unique within the Scene.

public

meta: *

Arbitrary, user-defined metadata on this component.

public

The parent Scene that contains this Component.

public

The viewer that contains this Scene.

public

clear()

Destroys all Components that are owned by this.

public

Destroys this component.

public

error(message: String)

Logs an error for this component to the JavaScript console.

public

fire(event: String, value: Object, forget: Boolean)

Fires an event on this component.

public

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

public

isType(type: *): *: Boolean

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

public

log(message: String)

Logs a console debugging message for this component.

public

off(subId: String)

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

public

on(event: String, callback: Function, scope: Object): String

Subscribes to an event on this component.

public

once(event: String, callback: Function, scope: Object)

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

public

scheduleTask(task: *)

Schedule a task to perform on the next browser interval

public

warn(message: String)

Logs a warning for this component to the JavaScript console.

Public Constructors

public constructor(owner: Component, cfg: *) source

Override:

Component#constructor

Params:

NameTypeAttributeDescription
owner Component
  • optional

Owner component. When destroyed, the owner will destroy this Marker as well.

cfg *
  • optional

Marker configuration

cfg.id String
  • optional

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

cfg.entity Entity
  • optional

Entity to associate this Marker with. When the Marker has an Entity, then Marker#visible will always be false if Entity#visible is false.

cfg.occludable Boolean
  • optional
  • default: false

Indicates whether or not this Marker is hidden (ie. Marker#visible is false whenever occluded by Entitys in the Scene.

cfg.worldPos Number[]
  • optional
  • default: [0,0,0]

World-space 3D Marker position.

Public Members

public get canvasPos: Number[] source

Canvas-space 2D coordinates of this Marker.

This property is read-only and is automatically calculated from Marker#worldPos and the current Camera position and projection.

The Marker fires a "canvasPos" event whenever this property changes.

public set entity: Entity source

Sets the Entity this Marker is associated with.

An Entity is optional. When the Marker has an Entity, then Marker#visible will always be false if Entity#visible is false.

public get entity: Entity source

Gets the Entity this Marker is associated with.

public set occludable: Boolean source

Sets whether occlusion testing is performed for this Marker.

When this is true, then Marker#visible will be false whenever the Marker is occluded by an Entity in the 3D view.

The Scene periodically occlusion-tests all Markers on every 20th "tick" (which represents a rendered frame). We can adjust that frequency via property Scene#ticksPerOcclusionTest.

public get occludable: Boolean source

Gets whether occlusion testing is performed for this Marker.

When this is true, then Marker#visible will be false whenever the Marker is occluded by an Entity in the 3D view.

public get origin: Number[] source

Gets the RTC center of this Marker.

This is automatically calculated from Marker#worldPos.

public get rtcPos: Number[] source

Gets the RTC position of this Marker.

This is automatically calculated from Marker#worldPos.

public get viewPos: Number[] source

View-space 3D coordinates of this Marker.

This property is read-only and is automatically calculated from Marker#worldPos and the current Camera position.

The Marker fires a "viewPos" event whenever this property changes.

public get visible: Boolean source

Indicates if this Marker is currently visible.

This is read-only and is automatically calculated.

The Marker is invisible whenever:

The Marker fires a "visible" event whenever this property changes.

public set worldPos: Number[] source

Sets the World-space 3D position of this Marker.

Fires a "worldPos" event with new World position.

public get worldPos: Number[] source

Gets the World-space 3D position of this Marker.

Public Methods

public destroy() source

Destroys this Marker.

Override:

Component#destroy