Entity interaction

Once a scene is rendered there are a few ways to interact with it. In this section we'll be going over Entity-specific interaction.

JSFiddle example

Menu item manager

Rendering of data is performed through Menu Items within these libraries. Menu items are actions with instructions on how to retrieve then draw data.

If you have data you'd prefer to load in yourself you can do so by either creating a Menu Item that delivers prepared JSON entities, or by manually adding them to the visual register through the register.AddRego method.

Please contact our support for examples as these are not prepared yet.

The Menu Item manager manages what Menu Items are enabled and lets you push Entity updates to the visuals register.

The Menu Item manager is accessible through your Cesium viewer instance.

import * as Cesium from "cesium";
import { ViewerUtils } from "bruce-cesium";

const container = document.getElementById("VIEWER");
const viewer = new Cesium.Viewer(container);

ViewerUtils.InitViewer({
    viewer: viewer
});

const manager = ViewerUtils.GetManager({
    viewer: viewer,
    createIfMissing: true
});

Here is how you can enable, disable, and know what Menu Items are enabled.

const enabledItemIds = manager.GetEnabledItemIds();
const enabledItem = manager.GetEnabledItem("my_menu_item_id");

manager.RemoveItemById({
    menuItemId: "my_menu_item_id",
    // Default is true, this means all child Menu Items will also be disabled.
    recursive: true
});

manager.RenderItem({
    // Cannot be null in real uses.
    // Read through "Render Entities" and "Render Tilesets" docs for how these can be created.
    item: null,
    // Default = true. This will enable all child Menu Items.
    recursive?: boolean
})

If you've updated an Entity record and would like the related visual to refresh then you can do it like so:

manager.ReRender({
    // Either an array of Entity IDs or Entity data must be provided.
    // If entity ids are provided then they will be retrieved from the server before being refreshed.
    entityIds: [],
    entities: null,
    // Optional string array to be explicit about what Menu Items to refresh.
    // This is highly recommended as it will be faster.
    menuItemIds: null,
    // Default = false, this will skip queues and render immediately.
    // Recommended to only use this for small batches if they are refreshing often.
    force: false
})

Visuals register

Any Nextspace Entity related object that is loaded into the scene will be registed into the visuals register for your Cesium viewer.

The register is accessible through the Menu Items manager.

import * as Cesium from "cesium";
import { ViewerUtils } from "bruce-cesium";

ViewerUtils.InitViewer({
    viewer: viewer
});

const manager = ViewerUtils.GetManager({
    viewer: viewer,
    createIfMissing: true
});

const register = manager.VisualsRegister;
console.log("register", register);

Here is how you can retrieve loaded Entities through different methods.

const register = manager.VisualsRegister;

// Get a registration for an Entity by ID for any Menu Item.
const rego = register.GetRego({
    entityId: "my_entity_id"
});

// Get a registration for an Entity by ID for a specific Menu Item.
const rego = register.GetRego({
    entityId: "my_entity_id",
    menuItemId: "my_menu_item_id"
});

// Get registrations from under your 2d cursor.
const regos = register.GetRegosFromCursor({
    cursor: {
        x: 100,
        y: 200
    }
});

// Get all registered Entity IDs.
const ids = register.GetEntityIds();

Here are some ways to apply adjustments to the Entities.

These methods will work regardless of whether the related Entity is loaded or not.

If you set an Entity ID to be hidden, then if that Entity loads in later it will hide anyways.

const register = manager.VisualsRegister;

// Select Entities like so:
register.ClearSelected();
register.SetSelected({
    selected: true,
    entityIds: ["a", "b", "c"]
});

// Check if something is selected.
const isSelected = register.GetIsSelected({
    entityId: "a"
});
const allSelectedIds = register.GetSelected();

// Isolating Entities will hide all other Entities.
register.ClearIsolated();
register.SetIsolated({
    entityIds: ["a"],
    isolated: true
})

// Check if something is isolated.
const isIsolated = register.GetIsIsolated({
    entityId: "a"
});
const allIsolatedIds = register.GetIsolated();

// Hide Entities.
register.ClearHidden();
register.SetHidden({
    entityIds: ["a"],
    hidden: true
});

// Check if something is hidden.
const isHidden = register.GetIsHidden({
    entityId: "a"
});
const allHiddenIds = register.GetHidden();

// Apply opacity.
register.SetOpacity({
    entityIds: ["a"],
    // Value between 0 and 1.
    opacity: 0.5
});

// Check opacity.
// If multiple Entities are supplied, then the average is returned.
// Unknown opacity is treated as 100% opacity.
const opacity = register.GetOpacity({
    entityIds: ["a"],
});

// Dictionary of Entity ID -> opacity value.
// This will only return Entities that have an opacity applied.
const opacityMap = register.GetOpacityMap();

// Clear any applied opacity.
register.ClearOpacity();

You can subscribe to the register's updates so you can know when an Entity has loaded in or out of the scene.

const register = manager.VisualsRegister;
const removal = register.OnUpdate.Subscribe((data) => {
    console.log(data);
});

// Call the removal function to unsubscribe.
//removal();