Menu Items


A Menu Item describes one set of data to load into a Project View's 3D scene: an Entity Type, an Assembly, a Tileset, a KML file and so on. Users toggle them in Navigator's panel, and Bookmarks enable them by ID.

Menu Items don't have their own records. They sit within their Project View record.

This article will cover where Menu Items are stored, the settings every Menu Item shares, and the settings for each Menu Item type.

Where Menu Items are stored

Menu Items live in the "menuItems" array of a Project View's "Settings". There are no requests for a single Menu Item, so you create, update and delete them by saving the Project View with the changed array. You can read about saving Project Views in Project Views and Bookmarks.

A Bookmark enables Menu Items by listing their "id" values in its "menuItemIds" setting. Enabling a folder also enables its children. You can read about "menuItemIds" and per-Bookmark overrides in Bookmark: Menu Items.

interface IProjectViewSettings {
    // Extending the Project View settings.
    ...
    // The Menu Item tree for the scene.
    menuItems?: IMenuItem[];
}

Data model

Below are the settings that are consistent between the different Menu Item types. Each type adds its own settings, described in the sections below.

interface IMenuItem {
    // Unique ID for this Menu Item within the Project View.
    // Bookmarks refer to the Menu Item by this ID.
    id: string;
    // Human readable name shown in Navigator's panel.
    Caption: string;
    // (Optional) text shown under the caption in Navigator's panel.
    Description?: string;

    // The type of Menu Item.
    // This drives what is loaded and which other settings apply.
    Type: EType;

    // Child Menu Items.
    // Only a folder (Type "NONE") renders its children.
    Children?: IMenuItem[];

    // Priority in relation to other Menu Items.
    // If two Menu Items draw the same Entity, the higher priority is drawn and the other is hidden.
    // If the priority is equal, both are drawn at the same time.
    // The default depends on the type, see each type's section.
    renderPriority?: number;
}

enum EType {
    // Folder for other Menu Items.
    None = "NONE",

    // Renders Entities of an Entity Type around the viewport.
    Entities = "BruceEntity",
    // Renders a Tileset built from an Entity Type's Entities.
    EntityTileset = "EntitiesTileset",
    // Renders Entities matching specific IDs.
    EntitiesIds = "EntitiesIds",
    // Renders the Entities a DataLab query selects around the viewport.
    DataLab = "DataLab",

    // Renders an Assembly through its Tileset.
    CadTileset = "ModelTileset",
    // Renders an Assembly that has no Tileset, Entity by Entity.
    Assembly = "Assembly",
    // Renders a point cloud imported from a LAS/LAZ file.
    PointCloud = "PointCloudTileset",
    // Renders a static Nextspace Tileset, an XGrids splat or an external Cesium Tileset.
    ArbTileset = "ArbitraryTileset",
    // Renders a Cesium Ion asset.
    IonTileset = "Cesium3DTileset",
    // Renders an ArcGIS I3S scene layer.
    I3sTileset = "I3STileset",
    // Renders KML files.
    Kml = "StaticKML",

    // Renders Cesium OSM Buildings.
    Osm = "OSMBuildingsTileset",
    // Renders the Google Photorealistic 3D Tiles.
    GooglePhotoTileset = "GooglePhotoTileset",
    // Renders Google Places matching a keyword around the viewport.
    GoogleSearch = "GoogleSearch"
}

When Navigator opens a Project View in model space, only "ModelTileset" and "Assembly" Menu Items can be enabled.

Zoom control

Menu Items that render Entities one by one ("BruceEntity", "EntitiesIds" and "DataLab") use a "CameraZoomSettings" array to decide how each Entity looks at different distances from the camera. An Entity outside every row's range is not drawn, so the largest "MaxZoom" is how far away the Entities stay visible.

interface IMenuItem {
    // Extending the type's data model.
    ...
    // When unset or empty, a single row applies:
    // { MinZoom: 0, MaxZoom: 200000, DisplayType: "3d", LODCategoryID: "glb", LODLevel: 0, StyleID: 0 }.
    CameraZoomSettings?: IZoomControl[];
}

interface IZoomControl {
    // The minimum distance in meters from the camera to enable this row.
    MinZoom: number;
    // The maximum distance in meters from the camera to enable this row.
    MaxZoom: number;

    // The display type to use for this row.
    // This determines the "best" allowed rendering type.
    /**
     * hidden = the Entity is not rendered.
     * point = renders a point from any available Entity data.
     * geometry = tries multi-geometry, polygon, polyline, then point.
     * 3d = tries a 3D model, multi-geometry, polygon, polyline, then point.
     */
    DisplayType?: "hidden" | "point" | "geometry" | "3d";

    // ID or Key of the Style to apply.
    // When unset or 0, the Entity Type's default Style is used.
    // If that is missing, hard-coded defaults apply.
    StyleID?: number | string;
    // (Optional) ordered Styles the user can swap between in Navigator.
    // Only used when this is the only row whose DisplayType is not "hidden".
    // The first entry is the default.
    StyleIDs?: (number | string)[];

    // The LOD category of 3D model to request.
    // Default is "glb".
    LODCategoryID?: string;
    // The LOD level of 3D model to request.
    // Default is 0, the highest quality.
    LODLevel?: number;
}

You can read about Style records in Entity Styles.

Item: Folder

A folder only groups other Menu Items. It loads nothing itself.

interface IMenuItem {
    "Type": "NONE";
    // The Menu Items inside this folder.
    Children: IMenuItem[];

    // If true, Navigator's panel does not list the children.
    // Enabling the folder still enables them.
    // Ignored when childrenAsRadios is true.
    hideChildren?: boolean;

    // If true, the direct children act as radio buttons so only one is enabled at a time.
    // The first child is enabled unless a Bookmark's menuItemIds names another.
    childrenAsRadios?: boolean;
}

Item: Entity Type

Loads the Entities of an Entity Type that are around the viewport, and requests more as the camera moves. You can read about the attribute filter in Entities, and about historic records in Entity historic data.

interface IMenuItem {
    "Type": "BruceEntity";
    "BruceEntity": {
        // ID of the Entity Type to query.
        "EntityType.ID": string;

        // (Optional) Entity attribute filter to apply.
        // This is the same "Filter" body as requesting a list of Entities with an attribute query.
        // It is combined with a viewport boundary search when requesting Entities.
        "Filter"?: any;

        // (Optional) Scenario Key or ID to use when requesting Entities.
        // Entities that have this Scenario load its data instead of the primary record.
        "Scenario"?: string | number;

        // (Optional) If true, historic Entity records are requested for the scene's date and time.
        // The Entities are requested again whenever the scene's time changes.
        historic?: boolean;
        // (Optional) Attribute path of one historic attribute to request, in place of "historic".
        // Attribute path segments are separated by a forward slash. Eg: 'address/city'.
        historicAttrKey?: string;

        // (Optional) ID of an alternative Data Schema to request the Entities with.
        schemaId?: string;

        // (Optional) If true, Navigator lists Tags as sub-items so users can filter the Entities by Tag.
        ExpandLayers?: boolean;
        // The Tag IDs enabled in Navigator, rendered when ExpandLayers is true.
        // When this is empty, nothing is rendered for the Menu Item.
        SelectedExpandLayers?: number[];
    };

    // Tag IDs that limit which Tags are listed when BruceEntity.ExpandLayers is true.
    // When unset or empty, all Tags are listed.
    layers?: number[];
    // If true, the Tags in "layers" are left out of the list instead.
    showAllLayersExcludeBelow?: boolean;

    // If true, historic Entities move smoothly between records as the scene's time changes.
    // This slows down the first render as more data is requested.
    historicInterpolation?: boolean;
    // If true, historic point, icon and 3D model Entities draw their movement as a polyline.
    // Polyline styling applies.
    historicDrawTrack?: boolean;

    // If true, Entities are requested through the account's Content Delivery Network.
    // Default is false.
    cdnEnabled?: boolean;

    // Default is 1.
    renderPriority?: number;
}

Point, icon and 3D model Entities can be clustered when they are close together and the camera is far away.

interface IMenuItem {
    // Extending the "BruceEntity" data model.
    ...
    // If true, nearby point, icon and 3D model Entities are drawn as clusters.
    // Default is false.
    enableClustering?: boolean;
    clustering?: {
        // Minimum distance in meters from the camera before Entities cluster.
        // Default is 5000.
        minDistance?: number;
        // Minimum number of Entities loaded for the Menu Item before clustering starts.
        // Default is 0.
        minTotalCount?: number;
    };
}

Navigator can let users create new Entities of the type by clicking in the scene. The authoring settings decide how a new record relates to the Entity that was clicked.

interface IMenuItem {
    // Extending the "BruceEntity" data model.
    ...
    // If true, Navigator shows a button on the Menu Item to create new Entities of the type.
    // Default is false.
    authoringEnabled?: boolean;
    authoring?: {
        // If true, Navigator records the Entity under the cursor when a new Entity is placed.
        readClickedEntity?: boolean;
        // (Optional) Relationship Type ID to create between the clicked Entity and the new one.
        // The clicked Entity is the principal and the new Entity is the related one.
        // Only used when readClickedEntity is true.
        clickedRelationTypeId?: string;
    };
}

When a Menu Item of this type has a Tileset set, Operator saves it as the "EntitiesTileset" type below instead.

Item: Entity Type Tileset

Loads a Tileset built from an Entity Type's Entities, instead of requesting the Entities one by one. Only the 3D model part of a Style applies to it.

interface IMenuItem {
    "Type": "EntitiesTileset";
    "tileset": {
        // ID of the Tileset record to load.
        "TilesetID": string;
        // (Optional) ID of the account that published the Tileset.
        // When unset, the Project View's account is used.
        "ClientAccountID"?: string;
    };
    "BruceEntity"?: {
        // ID of the Entity Type the Tileset was built from.
        "EntityType.ID"?: string;
        // (Optional) If true, historic Entity records are requested for the scene's date and time.
        historic?: boolean;
        // (Optional) Attribute path of one historic attribute to request, in place of "historic".
        historicAttrKey?: string;
    };

    // If true, Style records are applied to the Tileset.
    // When false, the Tileset shows the colours it was built with.
    // Default is false. Operator turns it on when you pick a Tileset.
    ApplyStyles?: boolean;
    // ID or Key of the Style to apply when ApplyStyles is true.
    // When unset, the Entity Type's default Style is used.
    styleId?: number | string;
    // (Optional) ordered Styles the user can swap between in Navigator.
    // The first entry is the default.
    styleIds?: (number | string)[];

    // If true, point clouds in the Tileset are drawn with attenuation.
    // Default is true.
    attenuation?: boolean;
    // Maximum point size in pixels when attenuation is on.
    // Default is 20.
    attenuationMax?: number;

    // If true, the Tileset is loaded through the account's Content Delivery Network.
    // Default is true.
    cdnEnabled?: boolean;
    // If true, this Tileset is left out of the memory allowance shared between Tilesets.
    // Default is false.
    noMaximumMemory?: boolean;

    // Default is 0.
    renderPriority?: number;
}

Item: Entity IDs

If you want to keep things simple and render a specific set of Entities, you can use this type. It uses the same zoom control as the Entity Type item.

interface IMenuItem {
    "Type": "EntitiesIds";
    "BruceEntity": {
        // Array of Entity IDs to load.
        EntityIds: string[];

        // (Optional) If true, historic Entity records are requested for the scene's date and time.
        historic?: boolean;
        // (Optional) Attribute path of one historic attribute to request, in place of "historic".
        historicAttrKey?: string;
    };

    // If true, historic point, icon and 3D model Entities draw their movement as a polyline.
    historicDrawTrack?: boolean;

    // If true, nearby point, icon and 3D model Entities are drawn as clusters.
    // Default is false.
    enableClustering?: boolean;
    // Same as the Entity Type item's clustering settings.
    clustering?: {
        minDistance?: number;
        minTotalCount?: number;
    };

    // Default is 2.
    renderPriority?: number;
}

Item: DataLab query

Loads the Entities that a DataLab query's primary selection criteria match around the viewport. It uses the same zoom control as the Entity Type item. You can read about creating queries in DataLab queries.

interface IMenuItem {
    "Type": "DataLab";
    // ID of the DataLab query to run.
    DataLabQueryID: number;

    // If true, Entities are requested through the account's Content Delivery Network.
    // Default is false.
    cdnEnabled?: boolean;

    // Default is 3.
    renderPriority?: number;
}

Item: Assembly

Loads an Assembly imported into Nextspace (IFC, RVT and the like). When the Assembly has a Tileset, the Menu Item is the "ModelTileset" type and the Tileset is loaded. When it has none, the Menu Item is the "Assembly" type and the Assembly's Entities are loaded one by one from its hierarchy. Operator picks the type when you save, based on whether "tileset.TilesetID" is set.

interface IMenuItem {
    "Type": "ModelTileset" | "Assembly";
    // ID of the Assembly to load. Required for "Assembly".
    "Assembly.ID"?: number;
    // The Assembly's Tileset. Required for "ModelTileset".
    "tileset"?: {
        // ID of the Tileset record to load.
        "TilesetID": string;
        // (Optional) ID of the account that published the Tileset.
        // When unset, the Project View's account is used.
        "ClientAccountID"?: string;
    };

    "BruceEntity"?: {
        // (Optional) If true, the Assembly follows its root Entity's historic positions as the scene's time changes.
        historic?: boolean;
    };
    // If true, a trail is drawn through the root Entity's historic positions.
    historicDrawTrack?: boolean;

    // Default is 0 for "ModelTileset" and 1 for "Assembly".
    renderPriority?: number;
}

The settings below only apply to the "ModelTileset" type. An Assembly can contain Entities from a range of Entity Types, so Styles can be mapped per Entity Type.

interface IMenuItem {
    // Extending the "ModelTileset" data model.
    ...
    // Mapping between Entity Type IDs and the Style to apply to their Entities.
    "StyleMapping"?: {
        // The Entity Type ID to map to a Style.
        "EntityTypeID": string;
        // ID or Key of the Style to apply.
        "StyleID": number | string;
    }[];
    // ID or Key of the Style to use for Entity Types without a mapping.
    // When unset, each Entity Type's default Style is used.
    "styleId"?: number | string;
    // (Optional) ordered fallback Styles the user can swap between in Navigator.
    // The first entry is the default.
    "styleIds"?: (number | string)[];

    // How Style colours blend with the model's own colours.
    // When unset, Cesium's default blending applies.
    StyleBlending?: {
        // highlight = 0, replace = 1, mix = 2.
        // Default is 2.
        blendMode: 0 | 1 | 2;
        // 1 = only the Style colour, 0 = only the model colour.
        // Default is 0.9.
        blendPercent: number;
    };

    // If true, the Tileset is loaded through the account's Content Delivery Network.
    // Default is true.
    cdnEnabled?: boolean;
    // If true, this Tileset is left out of the memory allowance shared between Tilesets.
    // Default is false.
    noMaximumMemory?: boolean;
}

Item: Point cloud

Loads a point cloud imported from a LAS or LAZ file.

interface IMenuItem {
    "Type": "PointCloudTileset";
    "tileset": {
        // ID of the Tileset record to load.
        "TilesetID": string;
        // (Optional) ID of the account that published the Tileset.
        // When unset, the Project View's account is used.
        "ClientAccountID"?: string;
    };

    // If true, the Tileset is loaded through the account's Content Delivery Network.
    // Default is true.
    cdnEnabled?: boolean;
    // If true, this Tileset is left out of the memory allowance shared between Tilesets.
    // Default is false.
    noMaximumMemory?: boolean;
}

Item: Cesium Tileset

Loads a static Nextspace Tileset, an XGrids splat, or an external Cesium Tileset by URL.

interface IMenuItem {
    "Type": "ArbitraryTileset";
    "tileset": {
        // ID of the Tileset record to load.
        "TilesetID"?: string;
        // (Optional) ID of the account that published the Tileset.
        // When unset, the Project View's account is used.
        "ClientAccountID"?: string;
        // URL to an external "tileset.json" file, used in place of TilesetID.
        // This is not recommended for accessing Nextspace Tilesets.
        "TilesetURL"?: string;
    };
    "BruceEntity"?: {
        // (Optional) Entity Type suggested when a user creates an Entity for a part of the Tileset that has no record.
        "EntityType.ID"?: string;
    };

    // If true, the Style settings below are applied to the Tileset.
    // Default is false.
    ApplyStyles?: boolean;
    // Mapping between Entity Type IDs and the Style to apply to their Entities.
    "StyleMapping"?: {
        "EntityTypeID": string;
        "StyleID": number | string;
    }[];
    // ID or Key of the Style to use for Entity Types without a mapping.
    "styleId"?: number | string;
    // (Optional) ordered fallback Styles the user can swap between in Navigator.
    "styleIds"?: (number | string)[];

    // (Optional) CSS colour string applied to the whole Tileset.
    // This follows Cesium logic: pure white keeps the Tileset's colours and only applies the alpha.
    // Eg: "rgba(255,255,255,0.5)" to show the Tileset at half opacity.
    colorMask?: string;

    // If true, the Tileset is loaded through the account's Content Delivery Network.
    // Default is true.
    cdnEnabled?: boolean;
    // If true, this Tileset is left out of the memory allowance shared between Tilesets.
    // This is occasionally needed for poorly optimised Tilesets.
    // Default is false.
    noMaximumMemory?: boolean;
    // If true, Cesium respects the double-sided setting of the glTF materials.
    // Default is false.
    backFaceCulling?: boolean;

    // Default is 0.
    renderPriority?: number;
}

Item: Cesium Ion asset

Loads a Cesium Ion asset by its asset ID. Unlike the Cesium Tileset item, the Style settings are always applied.

interface IMenuItem {
    "Type": "Cesium3DTileset";
    IonResource: {
        // ID of the Cesium Ion asset.
        AssetID: string | number;
        // (Optional) Cesium Ion access token.
        // If not supplied then the account default is used.
        AccessToken?: string;
    };
    "BruceEntity"?: {
        // (Optional) Entity Type suggested when a user creates an Entity for a part of the Tileset that has no record.
        "EntityType.ID"?: string;
    };

    // Same as the Cesium Tileset item.
    "StyleMapping"?: {
        "EntityTypeID": string;
        "StyleID": number | string;
    }[];
    "styleId"?: number | string;
    "styleIds"?: (number | string)[];
    noMaximumMemory?: boolean;

    // Default is 0.
    renderPriority?: number;
}

Item: I3S Tileset

Loads an ArcGIS I3S scene layer. Both URLs are required, and the Menu Item loads nothing when either is missing.

interface IMenuItem {
    "Type": "I3STileset";
    "tileset": {
        // URL to the I3S scene layer.
        "TilesetURL": string;
    };
    // URL to an ArcGIS tiled elevation service.
    // It converts between the layer's gravity related heights and ellipsoid heights.
    geoidServiceUrl: string;
}

Item: KML file

Loads one or more KML files into the scene. This is purely visual: the shapes are not Entity records.

interface IMenuItem {
    "Type": "StaticKML";
    // KML files to load.
    // Set either ClientFile or fileUrl on each entry.
    KML?: {
        // Client File record holding the KML file.
        ClientFile?: {
            ID: string;
        };
        // URL to a KML file hosted elsewhere.
        fileUrl?: string;
    }[];
}

Item: OSM Buildings

This is a data-set provided by Cesium. Learn more about IP rights and usage at Cesium OSM Buildings.

This Menu Item will load the Cesium OSM Buildings tileset into the scene. It is recommended to pair this with the Cesium World Terrain to ensure buildings are on the ground.

interface IMenuItem {
    "Type": "OSMBuildingsTileset";
    BruceEntity?: {
        // Preferred Entity Type ID for making new Entity records.
        // When a building is selected and no record is found, this type ID is suggested.
        "EntityType.ID"?: string;

        // ID of the Data Source that stores the mapping between OSM IDs and Nextspace Entity IDs.
        // If not set then Entity selection will not work.
        // Create a "Simple ID mapping" Data Source through Operator and use its ID.
        // Keep the ID consistent between different projects to maintain the same mapping.
        SourceId: number;
    };

    // If true then pending OSM buildings will be partially transparent.
    // A building is pending while its Nextspace ID is being looked up, so this needs a SourceId.
    ghostLoading?: boolean;
}

Item: Google Photorealistic 3D Tiles

This is a data-set provided by Google. Learn more about IP rights and usage at Google 3D Photorealistic tiles.

Your account (organisation) must have a Cesium Ion key or a Google Photogrammetry key in Operator's application keys. When it has a Cesium Ion key, we load the tiles through Cesium Ion. It is recommended to hide the globe when this is enabled.

interface IMenuItem {
    "Type": "GooglePhotoTileset";

    // (Optional) CSS colour string applied to the whole tileset.
    // This follows Cesium logic: pure white keeps the tileset's colours and only applies the alpha.
    colorMask?: string;
}

Item: Google Places search

This is a data-set provided by Google. Learn more about IP rights and usage at Google Places API.

This Menu Item searches Google Places for a keyword around the viewport and draws each result as an icon. Requests go through the Bruce API, which uses the Google API key in your account's application keys in Operator. Without that key nothing is drawn.

interface IMenuItem {
    "Type": "GoogleSearch";

    // Search keyword. Eg: "restaurants".
    keyword: string;
}