Request

Response

    Object Tree

    Instances you add through the Scene API are rendered, but the Viewer doesn’t know what they are. Selection, isolation, the Model Browser and theming all work on nodes of an object tree, identified by a dbId. Loaded models get their tree from the property database. For a model you build yourself, you define the tree and tell each instance which node it belongs to.

    ObjectTreeBuilder collects the nodes: each one has a dbId, a parent and a name. build() turns them into an ObjectTree, and Model.setObjectTree installs it. The tree’s structure can’t change after that; to change it, build a new tree and install it again.

    What can change is which instances belong to a node. InstanceCollection3D.setDbId moves an instance to a node, and setDbId(instanceId) without a dbId detaches it. You can also pass the dbId directly to InstanceCollection3D.add. Removing an instance detaches it from its node.

    This example creates a 3x2 grid of boxes and groups them into a top and a bottom row. Each box is a leaf node of its row. Selecting a row highlights its three boxes, and the Model Browser lists both rows.

    // show edges for better visibility of the primitives
    viewer.setDisplayEdges(true);
    
    const mat = new StandardMaterial({ color: 0xff0000 });
    const geom = GeometryFactory.createBox(2, 2, 2, true);
    
    // Create a 3x2 grid of box instances.
    const instanceIds = [];
    for (let row = 0; row < 2; row++) {
      for (let col = 0; col < 3; col++) {
        const t = new Matrix4().setPosition(
          new Vector3((col - 1) * 3, (row - 0.5) * 3, 0));
        instanceIds.push(instances.add(geom, mat, t));
      }
    }
    
    // Build the hierarchy in-memory first: two group nodes
    // under the root, plus one leaf node per box.
    const builder = new ObjectTreeBuilder();
    const rootId = builder.getRootId();
    
    const topRow = builder.createNode(1000, rootId, 'Top Row',
      NODE_TYPE.NODE_TYPE_COLLECTION);
    const bottomRow = builder.createNode(
      1001, rootId, 'Bottom Row',
      NODE_TYPE.NODE_TYPE_COLLECTION);
    
    instanceIds.forEach((instanceId, i) => {
      const dbId = i + 1;          // stable dbId per box
      const parent = i < 3 ? bottomRow : topRow;
      builder.createNode(dbId, parent, `Box ${i + 1}`,
        NODE_TYPE.NODE_TYPE_GEOMETRY);
    });
    
    // Freeze the hierarchy and install it.
    model.setObjectTree(builder.build());
    
    // Connect each rendered instance to its node.
    instanceIds.forEach((instanceId, i) => {
      const dbId = i + 1;
      instances.setDbId(instanceId, dbId);
    });
    
    viewer.refresh(true);
    
    // Selection, isolation and the Model Browser now work
    // against the tree: selecting the group highlights all
    // three of its boxes.
    viewer.select([topRow]);
    
    Show More

    A model without an object tree still supports selection: each instance is then selected by its instance id, as if it were its own node.