Reference Source
public class | source

Scene

Extends:

Component → Scene

Contains the components that comprise a 3D scene.

Getting a Viewer's Scene

var scene = viewer.scene;

Creating and accessing Scene components

As a brief introduction to creating Scene components, we'll create a Mesh that has a uildTorusGeometry and a PhongMaterial:

var teapotMesh = new Mesh(scene, {
    id: "myMesh",                               // <<---------- ID automatically generated if not provided
    geometry: new TorusGeometry(scene),
    material: new PhongMaterial(scene, {
        id: "myMaterial",
        diffuse: [0.2, 0.2, 1.0]
    })
});

teapotMesh.scene.camera.eye = [45, 45, 45];

Find components by ID in their Scene's Scene#components map:

var teapotMesh = scene.components["myMesh"];
teapotMesh.visible = false;

var teapotMaterial = scene.components["myMaterial"];
teapotMaterial.diffuse = [1,0,0]; // Change to red

A Scene also has a map of component instances for each Component subtype:

var meshes = scene.types["Mesh"];
var teapotMesh = meshes["myMesh"];
teapotMesh.xrayed = true;

var phongMaterials = scene.types["PhongMaterial"];
var teapotMaterial = phongMaterials["myMaterial"];
teapotMaterial.diffuse = [0,1,0]; // Change to green

See Node, Node and Model for how to create and access more sophisticated content.

Controlling the camera

Use the Scene's Camera to control the current viewpoint and projection:

var camera = myScene.camera;

camera.eye = [-10,0,0];
camera.look = [-10,0,0];
camera.up = [0,1,0];

camera.projection = "perspective";
camera.perspective.fov = 45;
//...

Managing the canvas

The Scene's Canvas component provides various conveniences relevant to the WebGL canvas, such as firing resize events etc:

var canvas = scene.canvas;

canvas.on("boundary", function(boundary) {
    //...
});

Picking

Use Scene#pick to pick and raycast entites.

For example, to pick a point on the surface of the closest entity at the given canvas coordinates:

var hit = scene.pick({
     pickSurface: true,
     canvasPos: [23, 131]
});

if (hit) { // Picked an entity

    var entity = hit.entity;

    var primitive = hit.primitive; // Type of primitive that was picked, usually "triangles"
    var primIndex = hit.primIndex; // Position of triangle's first index in the picked Mesh's Geometry's indices array
    var indices = hit.indices; // UInt32Array containing the triangle's vertex indices
    var localPos = hit.localPos; // Float32Array containing the picked Local-space position on the triangle
    var worldPos = hit.worldPos; // Float32Array containing the picked World-space position on the triangle
    var viewPos = hit.viewPos; // Float32Array containing the picked View-space position on the triangle
    var bary = hit.bary; // Float32Array containing the picked barycentric position within the triangle
    var normal = hit.normal; // Float32Array containing the interpolated normal vector at the picked position on the triangle
    var uv = hit.uv; // Float32Array containing the interpolated UV coordinates at the picked position on the triangle
}

Pick masking

We can use Scene#pick's includeEntities and excludeEntities options to mask which Meshes we attempt to pick.

This is useful for picking through things, to pick only the Entities of interest.

To pick only Entities "gearbox#77.0" and "gearbox#79.0", picking through any other Entities that are in the way, as if they weren't there:

var hit = scene.pick({
     canvasPos: [23, 131],
     includeEntities: ["gearbox#77.0", "gearbox#79.0"]
});

if (hit) {
      // Entity will always be either "gearbox#77.0" or "gearbox#79.0"
      var entity = hit.entity;
}

To pick any pickable Entity, except for "gearbox#77.0" and "gearbox#79.0", picking through those Entities if they happen to be in the way:

var hit = scene.pick({
     canvasPos: [23, 131],
     excludeEntities: ["gearbox#77.0", "gearbox#79.0"]
});

if (hit) {
      // Entity will never be "gearbox#77.0" or "gearbox#79.0"
      var entity = hit.entity;
}

See Scene#pick for more info on picking.

Querying and tracking boundaries

Getting a Scene's World-space axis-aligned boundary (AABB):

var aabb = scene.aabb; // [xmin, ymin, zmin, xmax, ymax, zmax]

Subscribing to updates to the AABB, which occur whenever Entitys are transformed, their ReadableGeometrys have been updated, or the Camera has moved:

scene.on("boundary", function() {
     var aabb = scene.aabb;
});

Getting the AABB of the Entitys with the given IDs:

scene.getAABB(); // Gets collective boundary of all Entities in the scene
scene.getAABB("saw"); // Gets boundary of an Object
scene.getAABB(["saw", "gearbox"]); // Gets collective boundary of two Objects

See Scene#getAABB and Entity for more info on querying and tracking boundaries.

Managing the viewport

The Scene's Viewport component manages the WebGL viewport:

var viewport = scene.viewport
viewport.boundary = [0, 0, 500, 400];;

Controlling rendering

You can configure a Scene to perform multiple "passes" (renders) per frame. This is useful when we want to render the scene to multiple viewports, such as for stereo effects.

In the example, below, we'll configure the Scene to render twice on each frame, each time to different viewport. We'll do this with a callback that intercepts the Scene before each render and sets its Viewport to a different portion of the canvas. By default, the Scene will clear the canvas only before the first render, allowing the two views to be shown on the canvas at the same time.

var viewport = scene.viewport;

// Configure Scene to render twice for each frame
scene.passes = 2; // Default is 1
scene.clearEachPass = false; // Default is false

// Render to a separate viewport on each render

var viewport = scene.viewport;
viewport.autoBoundary = false;

scene.on("rendering", function (e) {
     switch (e.pass) {
         case 0:
             viewport.boundary = [0, 0, 200, 200]; // xmin, ymin, width, height
             break;

         case 1:
             viewport.boundary = [200, 0, 200, 200];
             break;
     }
});

// We can also intercept the Scene after each render,
// (though we're not using this for anything here)
scene.on("rendered", function (e) {
     switch (e.pass) {
         case 0:
             break;

         case 1:
             break;
     }
});

Gamma correction

Within its shaders, xeokit performs shading calculations in linear space.

By default, the Scene expects color textures (eg. PhongMaterial#diffuseMap, MetallicMaterial#baseColorMap and SpecularMaterial#diffuseMap) to be in pre-multipled gamma space, so will convert those to linear space before they are used in shaders. Other textures are always expected to be in linear space.

By default, the Scene will also gamma-correct its rendered output.

You can configure the Scene to expect all those color textures to be linear space, so that it does not gamma-correct them:

scene.gammaInput = false;

You would still need to gamma-correct the output, though, if it's going straight to the canvas, so normally we would leave that enabled:

scene.gammaOutput = true;

See Texture for more information on texture encoding and gamma.

Constructor Summary

Public Constructor
public

Member Summary

Public Members
public get

Gets the World-space axis-aligned 3D boundary (AABB) of this Scene.

public get

Gets the Camera for this Scene.

public

Manages the HTML5 canvas for this Scene.

public get

Gets the World-space 3D center of this Scene.

public set

When Scene#passes is greater than 1, indicates whether or not to clear the canvas before each pass (true) or just before the first pass (false).

public get

When Scene#passes is greater than 1, indicates whether or not to clear the canvas before each pass (true) or just before the first pass (false).

public

The Components within this Scene, each mapped to its Component#id.

public get

Gets the default EdgeMaterial for this Scene.

public get

Gets the gamma factor to use when Scene#gammaOutput is set true.

public set

Sets the gamma factor to use when Scene#gammaOutput is set true.

public set

Sets whether or not Scene should expect all Textures and colors to have pre-multiplied gamma.

public get

Gets whether or not Scene should expect all Textures and colors to have pre-multiplied gamma.

public get

Gets whether or not to render pixels with pre-multiplied gama.

public set

Sets whether or not to render pixels with pre-multiplied gama.

public get

Gets the default Geometry for this Scene, which is a ReadableGeometry with a unit-sized box shape.

public get

Gets the default highlight EmphasisMaterial for this Scene.

public get

Gets the IDs of the Entitys in Scene#highlightedObjects.

public

Map of currently highlighted Entitys that represent objects.

public

Publishes input events that occur on this Scene's canvas.

public

lightMaps: {String: LightMap}

The LightMaps in this Scene, each mapped to its LightMap#id.

public

lights: {String: Light}

The Lights in this Scene, each mapped to its Light#id.

public

The number of models currently loading.

public get

Gets the default Material for this Scene, which is a PhongMaterial.

public

Configures this Scene's units of measurement and coordinate mapping between Real-space and World-space 3D coordinate systems.

public get

Gets the IDs of the Entitys in Scene#models.

public

models: {String: Entity}

Map of Entitys that represent models.

public get

Gets the IDs of the Entitys in Scene#objects.

public

objects: {String: Entity}

Map of Entitys that represents objects.

public set

Sets the number of times this Scene renders per frame.

public get

Gets the number of times this Scene renders per frame.

public

The ReflectionMaps in this Scene, each mapped to its ReflectionMap#id.

public

The SectionPlanes in this Scene, each mapped to its SectionPlane#id.

public get

Gets the default selection EmphasisMaterial for this Scene.

public get

Gets the IDs of the Entitys in Scene#selectedObjects.

public

selectedObjects: {String: Object}

Map of currently selected Entitys that represent objects.

public

The epoch time (in milliseconds since 1970) when this Scene was instantiated.

public set

Sets the number of "ticks" that happen between occlusion testing for Markers.

public get

Gets the number of "ticks" that happen between each render of this Scene.

public get

Gets the number of "ticks" that happen between each render or this Scene.

public set

Sets the number of "ticks" that happen between each render or this Scene.

public

types: {String: {String: Component}}

For each Component type, a map of IDs to Component instances of that type.

public get

Gets the Viewport for this Scene.

public get

Gets the IDs of the Entitys in Scene#visibleObjects.

public

visibleObjects: {String: Object}

Map of currently visible Entitys that represent objects.

public get

Gets the default xraying EmphasisMaterial for this Scene.

public get

Gets the IDs of the Entitys in Scene#xrayedObjects.

public

xrayedObjects: {String: Object}

Map of currently xrayed Entitys that represent objects.

Method Summary

Public Methods
public

clear()

Destroys all non-default Components in this Scene.

public

Destroys all Lights in this Scene..

public

Destroys all SectionPlanes in this Scene.

public

Destroys this Scene.

public

Performs an occlusion test on all Markers in this Scene.

public

getAABB(ids: String[]): [Number, Number, Number, Number, Number, Number]

Gets the collective axis-aligned boundary (AABB) of a batch of Entitys that represent objects.

public

pick(params: *, pickResult: PickResult): PickResult

Attempts to pick an Entity in this Scene.

public

render(forceRender: Boolean)

Renders a single frame of this Scene.

public

setObjectsCollidable(ids: String[], collidable: Boolean): Boolean

Batch-updates Entity#collidable on Entitys that represent objects.

public

setObjectsColorized(ids: String[], colorize: Number[]): Boolean

Batch-updates Entity#colorize on Entitys that represent objects.

public

Batch-updates Entity#culled on Entitys that represent objects.

public

Batch-updates Entity#edges on Entitys that represent objects.

public

setObjectsHighlighted(ids: String[], highlighted: Boolean): Boolean

Batch-updates Entity#highlighted on Entitys that represent objects.

public

setObjectsOpacity(ids: String[], opacity: Number): Boolean

Batch-updates Entity#opacity on Entitys that represent objects.

public

Batch-updates Entity#pickable on Entitys that represent objects.

public

Batch-updates Entity#selected on Entitys that represent objects.

public

Batch-updates Entity#visible on Entitys that represent objects.

public

Batch-updates Entity#xrayed on Entitys that represent objects.

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

warn(message: String)

Logs a warning for this component to the JavaScript console.

Public Constructors

public constructor(cfg: Object) source

Override:

Component#constructor

Params:

NameTypeAttributeDescription
cfg Object

Scene configuration.

cfg.canvasId String
  • optional

ID of an existing HTML canvas for the Scene#canvas - either this or canvasElement is mandatory. When both values are given, the element reference is always preferred to the ID.

cfg.canvasElement HTMLCanvasElement
  • optional

Reference of an existing HTML canvas for the Scene#canvas - either this or canvasId is mandatory. When both values are given, the element reference is always preferred to the ID.

Throw:

String

Throws an exception when both canvasId or canvasElement are missing or they aren't pointing to a valid HTMLCanvasElement.

Public Members

public get aabb: Number[] source

Gets the World-space axis-aligned 3D boundary (AABB) of this Scene.

The AABB is represented by a six-element Float32Array containing the min/max extents of the axis-aligned volume, ie. [xmin, ymin,zmin,xmax,ymax, zmax].

public get camera: Camera source

Gets the Camera for this Scene.

public canvas: Canvas source

Manages the HTML5 canvas for this Scene.

public get center: Number[] source

Gets the World-space 3D center of this Scene.

public set clearEachPass: Boolean source

When Scene#passes is greater than 1, indicates whether or not to clear the canvas before each pass (true) or just before the first pass (false).

Default value is false.

public get clearEachPass: Boolean source

When Scene#passes is greater than 1, indicates whether or not to clear the canvas before each pass (true) or just before the first pass (false).

Default value is false.

public components: {} source

The Components within this Scene, each mapped to its Component#id.

*@type {{String:Component}}

public get edgeMaterial: EdgeMaterial source

Gets the default EdgeMaterial for this Scene.

Has EdgeMaterial#id set to "default.edgeMaterial".

Meshs in this Scene have Mesh#edgeMaterial set to this EdgeMaterial by default.

Meshs have their edges emphasized while Mesh#edges is true.

public get gammaFactor: Number source

Gets the gamma factor to use when Scene#gammaOutput is set true.

Default value is 2.2.

public set gammaFactor: Number source

Sets the gamma factor to use when Scene#gammaOutput is set true.

Default value is 2.2.

public set gammaInput: Boolean source

Sets whether or not Scene should expect all Textures and colors to have pre-multiplied gamma.

Default value is false.

public get gammaInput: Boolean source

Gets whether or not Scene should expect all Textures and colors to have pre-multiplied gamma.

Default value is false.

public get gammaOutput: Boolean source

Gets whether or not to render pixels with pre-multiplied gama.

Default value is true.

public set gammaOutput: Boolean source

Sets whether or not to render pixels with pre-multiplied gama.

Default value is true.

public get geometry: ReadableGeometry source

Gets the default Geometry for this Scene, which is a ReadableGeometry with a unit-sized box shape.

Has ReadableGeometry#id set to "default.geometry".

Meshs in this Scene have Mesh#geometry set to this ReadableGeometry by default.

public get highlightMaterial: EmphasisMaterial source

Gets the default highlight EmphasisMaterial for this Scene.

Has EmphasisMaterial#id set to "default.highlightMaterial".

Meshs in this Scene have Mesh#highlightMaterial set to this EmphasisMaterial by default.

Meshs are highlighted while Mesh#highlighted is true.

public get highlightedObjectIds: String[] source

Gets the IDs of the Entitys in Scene#highlightedObjects.

public highlightedObjects: {String: Object} source

Map of currently highlighted Entitys that represent objects.

An Entity represents an object if Entity#isObject is true is true, and is highlighted when Entity#highlighted is true.

Each Entity is mapped here by Entity#id.

Properties:

NameTypeAttributeDescription
highlightedObjects *

public input: Input source

Publishes input events that occur on this Scene's canvas.

Properties:

NameTypeAttributeDescription
input *

public lightMaps: {String: LightMap} source

The LightMaps in this Scene, each mapped to its LightMap#id.

public lights: {String: Light} source

The Lights in this Scene, each mapped to its Light#id.

public loading: Number source

The number of models currently loading.

Properties:

NameTypeAttributeDescription
loading *

public get material: PhongMaterial source

Gets the default Material for this Scene, which is a PhongMaterial.

Has PhongMaterial#id set to "default.material".

Meshs in this Scene have Mesh#material set to this PhongMaterial by default.

public metrics: Metrics source

Configures this Scene's units of measurement and coordinate mapping between Real-space and World-space 3D coordinate systems.

Properties:

NameTypeAttributeDescription
metrics *

public get modelIds: String[] source

Gets the IDs of the Entitys in Scene#models.

public models: {String: Entity} source

Map of Entitys that represent models.

Each Entity is mapped here by Entity#id when Entity#isModel is true.

Properties:

NameTypeAttributeDescription
models *

public get objectIds: String[] source

Gets the IDs of the Entitys in Scene#objects.

public objects: {String: Entity} source

Map of Entitys that represents objects.

Each Entity is mapped here by Entity#id when Entity#isObject is true.

Properties:

NameTypeAttributeDescription
objects *

public set passes: Number source

Sets the number of times this Scene renders per frame.

Default value is 1.

public get passes: Number source

Gets the number of times this Scene renders per frame.

Default value is 1.

public reflectionMaps: {String: ReflectionMap} source

The ReflectionMaps in this Scene, each mapped to its ReflectionMap#id.

public sectionPlanes: {String: SectionPlane} source

The SectionPlanes in this Scene, each mapped to its SectionPlane#id.

public get selectedMaterial: EmphasisMaterial source

Gets the default selection EmphasisMaterial for this Scene.

Has EmphasisMaterial#id set to "default.selectedMaterial".

Meshs in this Scene have Mesh#highlightMaterial set to this EmphasisMaterial by default.

Meshs are highlighted while Mesh#highlighted is true.

public get selectedObjectIds: String[] source

Gets the IDs of the Entitys in Scene#selectedObjects.

public selectedObjects: {String: Object} source

Map of currently selected Entitys that represent objects.

An Entity represents an object if Entity#isObject is true, and is selected while Entity#selected is true.

Each Entity is mapped here by Entity#id.

Properties:

NameTypeAttributeDescription
selectedObjects *

public startTime: Number source

The epoch time (in milliseconds since 1970) when this Scene was instantiated.

Properties:

NameTypeAttributeDescription
timeCreated *

public set ticksPerOcclusionTest: Number source

Sets the number of "ticks" that happen between occlusion testing for Markers.

Default value is 20.

public get ticksPerOcclusionTest: Number source

Gets the number of "ticks" that happen between each render of this Scene.

Default value is 1.

public get ticksPerRender: Number source

Gets the number of "ticks" that happen between each render or this Scene.

Default value is 1.

public set ticksPerRender: Number source

Sets the number of "ticks" that happen between each render or this Scene.

Default value is 1.

public types: {String: {String: Component}} source

For each Component type, a map of IDs to Component instances of that type.

public get viewport: * source

Gets the Viewport for this Scene.

public get visibleObjectIds: String[] source

Gets the IDs of the Entitys in Scene#visibleObjects.

public visibleObjects: {String: Object} source

Map of currently visible Entitys that represent objects.

An Entity represents an object if Entity#isObject is true, and is visible when Entity#visible is true.

Properties:

NameTypeAttributeDescription
visibleObjects *

public get xrayMaterial: EmphasisMaterial source

Gets the default xraying EmphasisMaterial for this Scene.

Has EmphasisMaterial#id set to "default.xrayMaterial".

Meshs in this Scene have Mesh#xrayMaterial set to this EmphasisMaterial by default.

Meshs are xrayed while Mesh#xrayed is true.

public get xrayedObjectIds: String[] source

Gets the IDs of the Entitys in Scene#xrayedObjects.

public xrayedObjects: {String: Object} source

Map of currently xrayed Entitys that represent objects.

An Entity represents an object if Entity#isObject is true, and is xrayed when Entity#xrayed is true.

Each Entity is mapped here by Entity#id.

Properties:

NameTypeAttributeDescription
xrayedObjects *

Public Methods

public clear() source

Destroys all non-default Components in this Scene.

Override:

Component#clear

public clearLights() source

Destroys all Lights in this Scene..

public clearSectionPlanes() source

Destroys all SectionPlanes in this Scene.

public destroy() source

Destroys this Scene.

Override:

Component#destroy

public doOcclusionTest() source

Performs an occlusion test on all Markers in this Scene.

Sets each Marker#visible true if the Marker is currently not occluded by any opaque Entitys in the Scene, or false if an Entity is occluding it.

public getAABB(ids: String[]): [Number, Number, Number, Number, Number, Number] source

Gets the collective axis-aligned boundary (AABB) of a batch of Entitys that represent objects.

An Entity represents an object when Entity#isObject is true.

Each Entity on which Entity#isObject is registered by Entity#id in Scene#visibleObjects.

Each Entity is only included in the AABB when Entity#collidable is true.

Returns the AABB of all Entitys in Scene#objects by default, or TODO

Params:

NameTypeAttributeDescription
ids String[]

Array of Entity#id values.

Return:

[Number, Number, Number, Number, Number, Number]

An axis-aligned World-space bounding box, given as elements [xmin, ymin, zmin, xmax, ymax, zmax].

public pick(params: *, pickResult: PickResult): PickResult source

Attempts to pick an Entity in this Scene.

Ignores Entitys with Entity#pickable set false.

When an Entity is picked, fires a "pick" event on the Entity with the pick result as parameters.

Picking the Entity at the given canvas coordinates:

var pickResult = scene.pick({
         canvasPos: [23, 131]
      });

if (pickResult) { // Picked an Entity
        var entity = pickResult.entity;
    }

Picking, with a ray cast through the canvas, hits an Entity:

var pickResult = scene.pick({
        pickSurface: true,
        canvasPos: [23, 131]
     });

if (pickResult) { // Picked an Entity

    var entity = pickResult.entity;

    if (pickResult.primitive === "triangle") {

        // Picked a triangle on the entity surface

        var primIndex = pickResult.primIndex; // Position of triangle's first index in the picked Entity's Geometry's indices array
        var indices = pickResult.indices; // UInt32Array containing the triangle's vertex indices
        var localPos = pickResult.localPos; // Float32Array containing the picked Local-space position on the triangle
        var worldPos = pickResult.worldPos; // Float32Array containing the picked World-space position on the triangle
        var viewPos = pickResult.viewPos; // Float32Array containing the picked View-space position on the triangle
        var bary = pickResult.bary; // Float32Array containing the picked barycentric position within the triangle
        var worldNormal = pickResult.worldNormal; // Float32Array containing the interpolated World-space normal vector at the picked position on the triangle
        var uv = pickResult.uv; // Float32Array containing the interpolated UV coordinates at the picked position on the triangle

    } else if (pickResult.worldPos) {

        // Picked a point and normal on the entity surface

        var worldPos = pickResult.worldPos; // Float32Array containing the picked World-space position on the Entity surface
        var worldNormal = pickResult.worldNormal; // Float32Array containing the picked World-space normal vector on the Entity Surface
    }
}

Picking the Entity that intersects an arbitrarily-aligned World-space ray:

var pickResult = scene.pick({
      pickSurface: true,   // Picking with arbitrarily-positioned ray
      origin: [0,0,-5],    // Ray origin
      direction: [0,0,1]   // Ray direction
});

if (pickResult) { // Picked an Entity with the ray

      var entity = pickResult.entity;

      if (pickResult.primitive == "triangle") {

         // Picked a triangle on the entity surface

          var primitive = pickResult.primitive; // Type of primitive that was picked, usually "triangles"
          var primIndex = pickResult.primIndex; // Position of triangle's first index in the picked Entity's Geometry's indices array
          var indices = pickResult.indices; // UInt32Array containing the triangle's vertex indices
          var localPos = pickResult.localPos; // Float32Array containing the picked Local-space position on the triangle
          var worldPos = pickResult.worldPos; // Float32Array containing the picked World-space position on the triangle
          var viewPos = pickResult.viewPos; // Float32Array containing the picked View-space position on the triangle
          var bary = pickResult.bary; // Float32Array containing the picked barycentric position within the triangle
          var worldNormal = pickResult.worldNormal; // Float32Array containing the interpolated World-space normal vector at the picked position on the triangle
          var uv = pickResult.uv; // Float32Array containing the interpolated UV coordinates at the picked position on the triangle
          var origin = pickResult.origin; // Float32Array containing the World-space ray origin
          var direction = pickResult.direction; // Float32Array containing the World-space ray direction

    } else if (pickResult.worldPos) {

        // Picked a point and normal on the entity surface

        var worldPos = pickResult.worldPos; // Float32Array containing the picked World-space position on the Entity surface
        var worldNormal = pickResult.worldNormal; // Float32Array containing the picked World-space normal vector on the Entity Surface
    }
}

Picking the Entity that intersects an arbitrarily-aligned World-space ray, implicitly given as a 4x4 matrix:

const matrix = math.lookAtMat4v([0,10,0], [0,-1,0], [0,0,-1]); // Eye, look and up vectors

const pickResult = scene.pick({
      pickSurface: true,   // Picking with arbitrarily-positioned ray
      matrix: matrix
});

if (pickResult) { // Picked an Entity with the ray
     ....
}

Params:

NameTypeAttributeDescription
params *

Picking parameters.

params.pickSurface Boolean
  • optional
  • default: false

Whether to find the picked position on the surface of the Entity.

params.canvasPos Number[]
  • optional

Canvas-space coordinates. When ray-picking, this will override the origin, direction and matrix parameters. Effectively fires a ray through the canvas at this position, directly along the negative View-space Z-axis.

params.origin Number[]
  • optional

World-space ray origin when ray-picking. Ignored when canvasPos given.

params.direction Number[]
  • optional

World-space ray direction when ray-picking. Ignored when canvasPos given.

params.matrix Number[]
  • optional

Alternative way to indicate ray origin and direction when ray-picking. Overrides origin and direction. Ignored when canvasPos given.

params.includeEntities String[]
  • optional

IDs of Entitys to restrict picking to. When given, ignores Entitys whose IDs are not in this list.

params.excludeEntities String[]
  • optional

IDs of Entitys to ignore. When given, will pick through these Entitys, as if they were not there.

params.pickInvisible Boolean
  • optional
  • default: false

When true, will pick all Entities, including those that are currently invisible.

pickResult PickResult
  • optional

Holds the results of the pick attempt. Will use the Scene's singleton PickResult if you don't supply your own.

Return:

PickResult

Holds results of the pick attempt, returned when an Entity is picked, else null. See method comments for description.

public render(forceRender: Boolean) source

Renders a single frame of this Scene.

The Scene will periodically render itself after any updates, but you can call this method to force a render if required.

Params:

NameTypeAttributeDescription
forceRender Boolean
  • optional
  • default: false

Forces a render when true, otherwise only renders if something has changed in this Scene since the last render.

public setObjectsCollidable(ids: String[], collidable: Boolean): Boolean source

Batch-updates Entity#collidable on Entitys that represent objects.

An Entity represents an object when Entity#isObject is true.

Params:

NameTypeAttributeDescription
ids String[]

Array of Entity#id values.

collidable Boolean

Whether or not to cull.

Return:

Boolean

True if any Entitys were updated, else false if all updates were redundant and not applied.

public setObjectsColorized(ids: String[], colorize: Number[]): Boolean source

Batch-updates Entity#colorize on Entitys that represent objects.

An Entity represents an object when Entity#isObject is true.

Params:

NameTypeAttributeDescription
ids String[]

Array of Entity#id values.

colorize Number[]
  • optional
  • default: (1,1,1)

RGB colorize factors, multiplied by the rendered pixel colors.

Return:

Boolean

True if any Entitys changed opacity, else false if all updates were redundant and not applied.

public setObjectsCulled(ids: String[], culled: Boolean): Boolean source

Batch-updates Entity#culled on Entitys that represent objects.

An Entity represents an object when Entity#isObject is true.

Params:

NameTypeAttributeDescription
ids String[]

Array of Entity#id values.

culled Boolean

Whether or not to cull.

Return:

Boolean

True if any Entitys were updated, else false if all updates were redundant and not applied.

public setObjectsEdges(ids: String[], edges: Boolean): Boolean source

Batch-updates Entity#edges on Entitys that represent objects.

An Entity represents an object when Entity#isObject is true.

Params:

NameTypeAttributeDescription
ids String[]

Array of Entity#id values.

edges Boolean

Whether or not to show edges.

Return:

Boolean

True if any Entitys were updated, else false if all updates were redundant and not applied.

public setObjectsHighlighted(ids: String[], highlighted: Boolean): Boolean source

Batch-updates Entity#highlighted on Entitys that represent objects.

An Entity represents an object when Entity#isObject is true.

Each Entity on which both Entity#isObject and Entity#highlighted are true is registered by Entity#id in Scene#highlightedObjects.

Params:

NameTypeAttributeDescription
ids String[]

Array of Entity#id values.

highlighted Boolean

Whether or not to highlight.

Return:

Boolean

True if any Entitys were updated, else false if all updates were redundant and not applied.

public setObjectsOpacity(ids: String[], opacity: Number): Boolean source

Batch-updates Entity#opacity on Entitys that represent objects.

An Entity represents an object when Entity#isObject is true.

Params:

NameTypeAttributeDescription
ids String[]

Array of Entity#id values.

opacity Number
  • optional
  • default: 1.0

Opacity factor, multiplied by the rendered pixel alphas.

Return:

Boolean

True if any Entitys changed opacity, else false if all updates were redundant and not applied.

public setObjectsPickable(ids: String[], pickable: Boolean): Boolean source

Batch-updates Entity#pickable on Entitys that represent objects.

An Entity represents an object when Entity#isObject is true.

Params:

NameTypeAttributeDescription
ids String[]

Array of Entity#id values.

pickable Boolean

Whether or not to enable picking.

Return:

Boolean

True if any Entitys were updated, else false if all updates were redundant and not applied.

public setObjectsSelected(ids: String[], selected: Boolean): Boolean source

Batch-updates Entity#selected on Entitys that represent objects.

An Entity represents an object when Entity#isObject is true.

Each Entity on which both Entity#isObject and Entity#selected are true is registered by Entity#id in Scene#selectedObjects.

Params:

NameTypeAttributeDescription
ids String[]

Array of Entity#id values.

selected Boolean

Whether or not to highlight.

Return:

Boolean

True if any Entitys were updated, else false if all updates were redundant and not applied.

public setObjectsVisible(ids: String[], visible: Boolean): Boolean source

Batch-updates Entity#visible on Entitys that represent objects.

An Entity represents an object when Entity#isObject is true.

Each Entity on which both Entity#isObject and Entity#visible are true is registered by Entity#id in Scene#visibleObjects.

Params:

NameTypeAttributeDescription
ids String[]

Array of Entity#id values.

visible Boolean

Whether or not to cull.

Return:

Boolean

True if any Entitys were updated, else false if all updates were redundant and not applied.

public setObjectsXRayed(ids: String[], xrayed: Boolean): Boolean source

Batch-updates Entity#xrayed on Entitys that represent objects.

An Entity represents an object when Entity#isObject is true.

Each Entity on which both Entity#isObject and Entity#xrayed are true is registered by Entity#id in Scene#xrayedObjects.

Params:

NameTypeAttributeDescription
ids String[]

Array of Entity#id values.

xrayed Boolean

Whether or not to xray.

Return:

Boolean

True if any Entitys were updated, else false if all updates were redundant and not applied.