An Object is a 3D element within a xeogl Scene.

Overview

Object is an abstract base class that's subclassed by:

• Mesh, which represents a drawable 3D primitive.
• Group, which is a composite Object that represents a group of child Objects.
• Model, which is a Group and is subclassed by GLTFModel, STLModel, OBJModel etc. A Model can contain child Groups and Meshes that represent its component parts.

As shown in the examples below, these component types can be connected into flexible scene hierarchies that contain content loaded from multiple sources and file formats. Since a Group implements the Composite pattern, property updates on a Group will apply recursively to all the Objects within it.

This page mostly covers the base functionality provided by Object, while the pages for the subclasses document the functionality specific to those subclasses.

Usage

• Creating an Object hierarchy
• Accessing Objects
• Updating Objects
• Adding and removing Objects
• Models within Groups
• Objects within Models
• Applying a semantic data model
• Destroying Objects

Creating an Object hierarchy

Let's create a Group that represents a table, with five child Meshes for its top and legs:

var boxGeometry = new xeogl.BoxGeometry(); // We'll reuse the same geometry for all our Meshes

var table = new xeogl.Group({

    id: "table",
    rotation: [0, 50, 0],
    position: [0, 0, 0],
    scale: [1, 1, 1],

    children: [

        new xeogl.Mesh({ // Red table leg
            id: "redLeg",                                  // <<-------- Optional ID within Scene
            guid: "5782d454-9f06-4d71-aff1-78c597eacbfb",  // <<-------- Optional GUID
            position: [-4, -6, -4],
            scale: [1, 3, 1],
            rotation: [0, 0, 0],
            geometry: boxGeometry,
            material: new xeogl.PhongMaterial({
                diffuse: [1, 0.3, 0.3]
            })
        }),

        new xeogl.Mesh({ // Green table leg
            id: "greenLeg",                                // <<-------- Optional ID within Scene
            guid: "c37e421f-5440-4ce1-9b4c-9bd06d8ab5ed",  // <<-------- Optional GUID
            position: [4, -6, -4],
            scale: [1, 3, 1],
            rotation: [0, 0, 0],
            geometry: boxGeometry,
            material: new xeogl.PhongMaterial({
                diffuse: [0.3, 1.0, 0.3]
            })
        }),

        new xeogl.Mesh({// Blue table leg
            id: "blueLeg",
            position: [4, -6, 4],
            scale: [1, 3, 1],
            rotation: [0, 0, 0],
            geometry: boxGeometry,
            material: new xeogl.PhongMaterial({
                diffuse: [0.3, 0.3, 1.0]
            })
        }),

        new xeogl.Mesh({  // Yellow table leg
            id: "yellowLeg",
            position: [-4, -6, 4],
            scale: [1, 3, 1],
            rotation: [0, 0, 0],
            geometry: boxGeometry,
            material: new xeogl.PhongMaterial({
                diffuse: [1.0, 1.0, 0.0]
            })
        })

        new xeogl.Mesh({ // Purple table top
            id: "tableTop",
            position: [0, -3, 0],
            scale: [6, 0.5, 6],
            rotation: [0, 0, 0],
            geometry: boxGeometry,
            material: new xeogl.PhongMaterial({
                diffuse: [1.0, 0.3, 1.0]
            })
        })
    ]
});

Accessing Objects

We can then get those Mesh Objects by index from the Group's children property:

var blueLeg = table.children[2];
blueLeg.highlighted = true;

We can also get them by ID from the Group's childMap property:

var blueLeg = table.childMap["blueLeg"];
blueLeg.highlighted = true;

or by ID from the Scene's components map:

var blueLeg = table.scene.components["blueLeg"];
blueLeg.highlighted = true;

or from the Scene's objects map (only Objects are in this map, and Meshes are Objects):

var blueLeg = table.scene.objects["blueLeg"];
blueLeg.highlighted = true;

or from the Scene's meshes map (only Meshes are in that map):

var blueLeg = table.scene.meshes["blueLeg"];
blueLeg.highlighted = true;

For convenience, the Scene's objects map explicitly registers what Objects exist within the Scene, while its meshes map explicitly registers what Meshes exist.

GUIDs

Note the optional globally unique identifiers (GUIDs) on the first two Objects. While regular IDs are unique within the Scene, GUIDs are unique throughout the entire universe, and are often used to identify elements in things like architectural models. We can find those Objects within their Scene using their GUIDs, like this:

var redLeg = scene.guidObjects["5782d454-9f06-4d71-aff1-78c597eacbfb"];
var greenLeg = scene.guidObjects["c37e421f-5440-4ce1-9b4c-9bd06d8ab5ed"];

Updating Objects

As mentioned earlier, property updates on a Group Object will apply recursively to all sub-Objects within it, eventually updating the Mesh Objects at the leaves.

These properties, defined in Object, are:

• visible
• highlighted
• ghosted
• selected
• edges
• colorize
• opacity
• clippable
• collidable
• pickable
• castShadow
• receiveShadow
• receiveShadow

Let's highlight the whole table in one shot:

table.highlighted = true;

That property value will then recursively propagate down our five Meshes.

Each Object has a local transformation that's applied within the coordinate space set up the transform of its parent, if it has one.

Let's rotate the table:

table.rotation = [0, 45, 0]; // (X,Y,Z)
table.childMap["tableTop"].position = [0, -10, 0]; // (X,Y,Z)

That will rotate the coordinate space containing the five child Meshes.

Now let's translate the table top Mesh:

table.childMap["tableTop"].position = [0, -10, 0]; // (X,Y,Z)

As we translated table top Mesh, we updated the extents its World-space boundary. That update, in addition to rotating the table Group, has updated the collective boundary of the whole table.

We can get the boundary of the table top like this:

var tableTopMesh = table.childMap["tableTop"].aabb;

We can get the collective boundary of the whole table, like this:

var tableTopMesh = table.aabb;

Just for fun, let's fit the view to the table top:

var cameraFlight = new xeogl.CameraFlightAnimation(); // Fit the boundary in view
cameraFlight.flyTo(tableTopMesh.aabb);

Those boundaries will automatically update whenever we add or remove child Objects or Meshes, or update child Meshes' Geometries or modeling transforms.

Let's follow the table top wherever it goes:

tableTopMesh.on("boundary", function() {
   cameraFlight.flyTo(this.aabb); // "this" is the table top Mesh
});

Or perhaps keep the whole table fitted to view whenever we transform any Objects or Meshes within the hierarchy, or add or remove Objects within the hierarchy:

table.on("boundary", function() {
    var aabb = this.aabb; // "this" is the table Group
    cameraFlight.flyTo(aabb);
});

Adding and removing Objects

Let's add another Mesh to our table Group, a sort of spherical ornament sitting on the table top:

table.addChild(new xeogl.Mesh({
    id: "myExtraObject",
    geometry: new xeogl.SphereGeometry({ radius: 1.0 }),
    position: [2, -3, 0],
    geometry: boxGeometry,
    material: new xeogl.PhongMaterial({
        diffuse: [0.3, 0.3, 1.0]
    })
});

That's going to update the Group's boundary, as mentioned earlier.

To remove it, just destroy it:

table.childMap["myExtraObject"].destroy();

Models within Groups

Now let's create a Group that contains three Models. Recall that Models are Groups, which are Objects.

var myModels = new xeogl.Group({

    rotation: [0, 0, 0],
    position: [0, 0, 0],
    scale: [1, 1, 1],

    children: [

        new xeogl.GLTFModel({
            id: "engine",
            src: "models/gltf/2CylinderEngine/glTF/2CylinderEngine.gltf",
            scale: [.2, .2, .2],
            position: [-110, 0, 0],
            rotation: [0, 90, 0],
            objectTree: true // <<----------------- Loads Object tree from glTF scene node graph
        }),

        new xeogl.GLTFModel({
            id: "hoverBike",
            src: "models/gltf/hover_bike/scene.gltf",
            scale: [.5, .5, .5],
            position: [0, -40, 0]
        }),

        new xeogl.STLModel({
            id: "f1Car",
            src: "models/stl/binary/F1Concept.stl",
            smoothNormals: true,
            scale: [3, 3, 3],
            position: [110, -20, 60],
            rotation: [0, 90, 0]
        })
    ]
});

Like with the Mesh Objects in the previous example, we can then get those Models by index from the Group's children property:

var hoverBike = myModels.children[1];
hoverBike.scale = [0.5, 0.5, 0.5];

or by ID from the Group's childMap property:

var hoverBike = myModels.childMap["hoverBike"];
hoverBike.scale = [0.5, 0.5, 0.5];

or by ID from the Scene's components map:

var hoverBike = myModels.scene.components["hoverBike"];
hoverBike.scale = [0.75, 0.75, 0.75];

or from the Scene's objects map (only Objects are in this map, and Models are Objects):

var hoverBike = myModels.scene.objects["hoverBike"];
hoverBike.scale = [0.75, 0.75, 0.75];

or from the Scene's models map (which only contains Models):

var hoverBike = myModels.scene.models["hoverBike"];
hoverBike.scale = [0.5, 0.5, 0.5];

For convenience, the Scene's objects map explicitly registers what Objects exist within the Scene, while its models map explicitly registers what Models exist.

As mentioned earlier, property updates on a Group will apply recursively to all the Objects within it. Let's highlight all the Models in the Group, in one shot:

myModels.highlighted = true;

and just for fun, let's scale the Group down, then rotate one of the Models, relative to the Group:

myModels.scale = [0.5, 0.5, 0.5]; // (X,Y,Z)
myModels.childMap["engine"].rotation = [0, 45, 0]; // (X,Y,Z)

Objects within Models

Models are Objects that plug into the scene graph, containing child Objects of their own. The GLTFModel in the previous example loads its child Objects from the glTF scene node graph.

The root Objects within the GLTFModel will be available in the GLTFModel's children and childMap properties, while all its Objects and Meshes (at the leaves) will be available in the GLTFModel's GLTFModel/objects:property property.

models.childMap["engine"].childMap["engine#0"].highlighted = true;

models.childMap["engine"].objects["engine#3.0"].highlighted=true;

models.childMap["engine"].meshes["engine#3.0"].highlighted=true;

Applying a semantic data model

xeogl allows us to organize our Objects using a generic conceptual data model that describes the semantics of our application domain. We do this by assigning "entity classes" to those Objects that we consider to be entities within our domain, and then we're able to reference those Objects according to their entity classes.

entityType

In xeogl, we classify an Object as an entity by setting its entityType to an arbitrary string value that represents its class. Once we've done that, we regard the Object as being an "entity" within our semantic data model, in addition to being a regular Object within our scene graph. Note that entities in xeogl are not to be confused with entity-component systems, which are a completely different concept.

This classification mechanism is useful for building IFC viewers on xeogl, in which case our entity classes would be the IFC element types. However, since xeogl's concept of entity classes is generic, our semantic model could include any arbitrary set of classes, such as "fluffy", "insulator", "essential" or "optional", for example.

This mechanism only goes as far as allowing us to assign entity classes to our Objects, for the purpose of finding them within the Scene using their classes. If we wanted to go a step further and model relationships between our classes, we would need to additionally use some sort of entity-relationship data structure, externally to xeogl, such as an IFC structure model in which the relation elements would reference our classes.

Objects that are not part of any semantic model, such as helpers and gizmos, would not get an entityType, and so would be effectively invisible to maps and methods that deal with specifically with entities. Use component IDs and "lower-level" maps like Scene#components, Scene#objects, Scene#meshes and Scene#models to work with such Objects as non-semantic scene elements, and "higher-level" maps like Scene#entities and Scene#entityTypes to work with Objects that are entities.

To show how to use a semantic model with xeogl, let's redefine the Object hierarchy we created earlier, this time assigning some imaginary domain-specific entity classes to our table Mesh Objects:

var boxGeometry = new xeogl.BoxGeometry(); // We'll reuse the same geometry for all our Meshes

var table = new xeogl.Group({

    id: "table",
    rotation: [0, 50, 0],
    position: [0, 0, 0],
    scale: [1, 1, 1],

    children: [

        new xeogl.Mesh({ // Red table leg
            id: "redLeg",
            entityType: "supporting",  // <<------------ Entity class
            position: [-4, -6, -4],
            scale: [1, 3, 1],
            rotation: [0, 0, 0],
            geometry: boxGeometry,
            material: new xeogl.PhongMaterial({
                diffuse: [1, 0.3, 0.3]
            })
        }),

        new xeogl.Mesh({ // Green table leg
            id: "greenLeg",
            entityType: "supporting",  // <<------------ Entity class
            position: [4, -6, -4],
            scale: [1, 3, 1],
            rotation: [0, 0, 0],
            geometry: boxGeometry,
            material: new xeogl.PhongMaterial({
                diffuse: [0.3, 1.0, 0.3]
            })
        }),

        new xeogl.Mesh({// Blue table leg
            id: "blueLeg",
            entityType: "supporting",  // <<------------ Entity class
            position: [4, -6, 4],
            scale: [1, 3, 1],
            rotation: [0, 0, 0],
            geometry: boxGeometry,
            material: new xeogl.PhongMaterial({
                diffuse: [0.3, 0.3, 1.0]
            })
        }),

        new xeogl.Mesh({  // Yellow table leg
            id: "yellowLeg",
            entityType: "supporting",  // <<------------ Entity class
            position: [-4, -6, 4],
            scale: [1, 3, 1],
            rotation: [0, 0, 0],
            geometry: boxGeometry,
            material: new xeogl.PhongMaterial({
                diffuse: [1.0, 1.0, 0.0]
            })
        })

        new xeogl.Mesh({ // Purple table top
            id: "tableTop",
            entityType: "surface",     // <<------------ Entity class
            position: [0, -3, 0],
            scale: [6, 0.5, 6],
            rotation: [0, 0, 0],
            geometry: boxGeometry,
            material: new xeogl.PhongMaterial({
                diffuse: [1.0, 0.3, 1.0]
            })
        })
    ]
});

This time, we've set the entityType property on our Mesh Objects, to assign our entity classes to them. Our arbitrary semantic model is very simple, with just two classes:

• "supporting" for entities that support things (eg. table legs), and
• "surface" for entities that provide a surface that you can put things on (eg. table tops).

Note that we can assign entity classes to any component type that extends Object, including Group, Mesh, Model, GLTFModel etc.

We can now conveniently work with our Mesh Objects as entities, in addition working with them as ordinary Objects.

We can find our entities in a dedicated map, that contains only the Objects that have the "entityType" property set:

var yellowLegMesh = scene.entities["yellowLeg"];

We can get a map of all Objects of a given entity class:

var supportingEntities = scene.entityTypes["supporting"];
var yellowLegMesh = supportingEntities["yellowLeg"];

We can do state updates on entity Objects by their entity class, in a batch:

scene.setVisible(["supporting"], false);               // Hide the legs
scene.setVisible(["supporting"], true);                // Show the legs again
scene.setHighlighted(["supporting", "surface"], true); // Highlight the legs and the table top

The Scene also has convenience maps dedicated to tracking the visibility, ghosted, highlighted and selected states of entity Objects:

var yellowLegMesh = scene.visibleEntities["yellowLeg"];
var isYellowLegVisible = yellowLegMesh !== undefined;

yellowLegMesh.highlighted = false;
var isYellowLegHighlighted = scene.highlightedEntities["yellowLeg"];

• Example

Limitations with state inheritance

Note that you can't currently nest entity Objects within a hierarchy. If we were to set an entityType on our Group, say "furniture", and then do this:

scene.setVisible(["furniture"], false);                // Hide the table

Then all our entity Meshes would be hidden, even though they are not "furniture" entities. The entity classification system does not currently work alongside the way xeogl does state inheritance within Object hierarchies, so keep your entities non-hierarchical.

Destroying Objects

Call an Object's Object#destroy() method to destroy it:

myObject.destroy();

That will also destroy all Objects in its subtree.