scene

This module is a high level scene graph manipulation and query library.

  • Either id, name, or regex's can be used for node names.
  • All get functions return the value, or undefined if no match is found
  • All find functions return an id or a Path
  • All filter functions return an array of id or Path *

Methods

(static) addNode(node) → {Promise}

Add a node to the scene.

Parameters:
Name Type Description
node Node

The new node being added

Properties
Name Type Attributes Description
name String

The name of the new node
type String

The type of the new node
parent String

the id of the parent node for the new node
plugs Object <optional>

The plugs for the new node
Returns:
Type
Promise

(static) addOperator(id, plugType, operatorType, operatoropt, nameopt) → {Promise}

Add an operator to an existing node in the scene.

Parameters:
Name Type Attributes Description
id String

The id of the node receiving the operator
plugType String

The plug that is receiving the operator
operatorType string

The type of operator being added
operator Object <optional>

The details of the operator
name String <optional>

the name of the operator
Returns:
Type
Promise

(static) attachModel(anchorNode, model, modelAttachNode, withRotation)

Move a model so that the modelAttachNode is directly over and aligned with the anchorNode.

Parameters:
Name Type Description
anchorNode *

The node the model will be anchored to
model *

The model that will be moved
modelAttachNode *

The child of the model that will be aligned with the anchor node.
withRotation *

Default is false, when set to true, both position and rotation of anchorNode and modelAttachNode will be same after attach

(static) clone(query, optionsopt)

Given a query, clone these nodes. Without options, these nodes will be cloned in place

Parameters:
Name Type Attributes Description
query QueryObject | String | Array.<Path>

A list of nodes (from filter), or query that will find a list of nodes to clone
options Object <optional>
Properties
Name Type Attributes Description
to String <optional>

The scene being cloned to (default is the active scene)
withNull String <optional>

Add a null to clone the nodes to
includeDependencies Object <optional>

Clone dependencies (default true)
Example
// Clone all nodes from Objects on import scene into active scene
scene.clone({from: {id: importId, child: 'Objects'}});

// Clone children of a null to a new null
scene.clone({from: {id: importId, child: 'Objects'}}, {withNull: 'New Parent Null'});

// Clone children, without also cloning dependencies.


// Return the path to the transform operator
scene.find('Box','Transform','translation'); -> ['uuid','Transform',0]
// Match the first node that starts with Box
scene.find('Box*');

(static) filter(query) → {Array}

This function will iterate through the scene graph, returning an array of all elements that match the parameters provided.

The return value of this function will either be an array of ids (if nodequery and plug are provied), or an array of paths (if property is provided).

(See Working with the Scene Graph)

Parameters:
Name Type Description
query String | QueryObject

The query object to filter on (or a string that gets converted to a query object).
Returns:
Type
Array

(static) find(query)

Finds first matching node. If propertyName is specified, will look for the first matching operator, and if found, return a path to the operator property. (See Working with the Scene Graph)

Parameters:
Name Type Description
query String | QueryObject

The query object to filter on (or a string that gets converted to a query object).
Example
// Return the node uuid
scene.find('Box'); -> 'uuid'
// Return the path to the transform operator
scene.find('Box','Transform','translation'); -> ['uuid','Transform',0]
// Match the first node that starts with Box
scene.find('Box*');

(static) get(query) → {any}

Returns the value at the matching property.

(See Working with the Scene Graph)

Parameters:
Name Type Description
query String | QueryObject | Path

The query object to filter on (or a string that gets converted to a query object).
Returns:
Type
any

(static) getAll(query) → {Array.<any>}

Returns an array of values for the matching properties

(See Working with the Scene Graph)

Parameters:
Name Type Description
query String | QueryObject | Path

The query object to filter on (or a found path)
Returns:
Type
Array.<any>

(static) getNodeBoundingBox(id)

Returns the bounding box of a node.

Parameters:
Name Type Description
id String

The uuid of a node
Example
var nodeId = scene.find({ name: 'Gear' });
var boundingBox = scene.getNodeBoundingBox(nodeId);

(static) getRelativeTransform(id, rootId) → (nullable) {Matrix4}

Get the transform for a node relative to a specified ancestor node. If rootId is not in id's ancestry, the result is simply the world transform.

Parameters:
Name Type Description
id String
rootId String

the node for which we want to calculated id's relative transform from
Returns:
Type
Matrix4

(static) getScreenPosition(id) → {Object}

Returns the two dimensional screen position of a node.

Parameters:
Name Type Description
id String

The uuid of a node
Returns:

{ x, y, top, left, width, height }

Type
Object
Example
var nodeId = scene.find({ name: 'Gear' });
var position = scene.getScreenPosition(nodeId);
console.log('position: ', position.x, position.y);
console.log('box: ', position.top, position.left, position.width, position.height);

(static) getWorldTransform(id) → (nullable) {Matrix4}

Get the world transform for a node.

Parameters:
Name Type Description
id String
Returns:
Type
Matrix4

(static) reparent(parent, array)

Reparent nodes to the new parent.

Parameters:
Name Type Description
parent String | QueryObject

id or a queryObject to specific the new parent node
array Array | QueryObject

of childid or a queryObject that specific the node to reparent
Example
// reparent direct children of 'MyModel' to 'NewParentNull', this will still keep the hierarchy structure of MyModel's children
const parentId = scene.find({ name: 'NewParentNull' });
scene.reparent(parentId, { from: { name: 'MyModel' }, shallow: true });

(static) set(query, value)

Sets the property at path to value.

(See Working with the Scene Graph)

Parameters:
Name Type Description
query Path | QueryObject | String

The query object to filter on (or a string that gets converted to a query object).
value any

The value to set, the type must match the property being set.

(static) setAll(query, value)

Given an array of paths, will set the value on each path. This can be combined with find to set a number of properties at once.

(See Working with the Scene Graph)

Parameters:
Name Type Description
query Array.<Path> | QueryObject | String

An array of path arrays, or a QueryObject
value any

The value to set the properties to.
Example
// Move all boxes to the origin
const paths = ctx.find('Box*', 'Transform', 'translation');
setAll(paths, {x: 0, y: 0, z: 0});