Project Views
A Project View is a record that configures a Navigator scene: the Menu Items that load data into it, the basemaps and terrains on offer, who can open it and what happens when an Entity is selected. You manage Project Views in Operator and open them in Navigator.
Each Project View holds a list of Bookmarks. A Bookmark is a saved state of the scene: the camera, the enabled Menu Items, the basemaps, the time and the state of individual Entities. A Bookmark can also show a Custom Dashboard, an embedded web page or a 2D diagram instead of the 3D scene. Bookmarks can be sorted into Bookmark groups.
"Slide" is an older name for a Bookmark. The API still uses it in routes and field names such as "UI.SlideGroup.ID". This article will cover how to manage Project View, Bookmark and Bookmark group records and descriptions about their settings.
Data model
Below is the core data model for a Project View. You can manage a record without populating the settings.
Settings
The settings hold everything Navigator needs to set up the scene. Larger parts have their own sections below, and the smaller ones are described here.
Settings are replaced as a whole on update, so send the full settings rather than only the part that changed.
You can read about Menu Items in Project View Menu Items and about plugins in Navigator plugins.
Settings: Access
Two settings control who can open a Project View and its Bookmarks. They are stored as their own columns but read and written through the settings, and the API always returns both.
So a Project View is either public, open to every signed in user of the account, or restricted to chosen User Groups. You grant User Groups access in Operator. Account administrators and users with access to every Project View can open them all. The list request only returns the Project Views the requesting user can open.
Editing a Project View, and managing its Bookmarks, are separate permissions from opening it. The "Permission" value on each record tells you what the requesting user can do with it.
Basemaps and terrains
A Project View lists the basemaps ("imageries") and terrains ("terrains") pinned in Navigator for users to pick from. A Bookmark then says which basemaps and which terrain are enabled. Both use the same tile reference, and a Bookmark basemap adds display values on top.
If the account has no Cesium Ion key, Navigator replaces the Bing basemaps with Mapbox ones and Cesium World Terrain with flat terrain.
Settings: Entity selection
The selection settings decide what happens when a user selects an Entity in Navigator. Navigator looks for a mapping with the Entity's Entity Type first, then uses the default action. Without either, the Entity opens in the Info View, our standard Entity details panel.
You can read about Custom Forms in Custom Forms.
Settings: Bookmark defaults
The "defaults" setting holds a camera and any of the Bookmark settings described further down. When a Bookmark leaves a value out, Navigator uses the Project View's default, then its own default.
The settings that fall back this way are "contentType", "imagery", "terrain", "terrainWireframe", "globeColor", "globeAlpha", "globeHidden", "groundOcclusion", "hillShades", "quality", "shadows", "ambientOcclusion", "lighting", "dateTime", "timeline" and "states". The enabled Menu Items, markup, contours, weather and walkthrough are only read from the Bookmark.
The camera default is used when a Bookmark's camera has no valid latitude, longitude and altitude. Its "cameraFrustum" and "transition" are used when the Bookmark leaves those out.
Two more settings live in the defaults and apply to the whole Project View rather than to one Bookmark.
Requesting Project Views
You can request a list of Project Views or one by its ID. The list leaves out the settings unless you set "expand", and returns everything in one page unless you set a page size.
Get a list of Project Views
Get a Project View by ID
Get the Project View of a Bookmark
Check a Project View ID is available
Create and update Project Views
You create a Project View with a POST to the ID you picked, and update it with a PUT to the same route. A POST to an ID that is already in use fails with an "IDConflict" error.
An update only changes the top level fields you include. The settings are replaced as a whole.
Operator also creates a first Bookmark named "Default" for each new Project View. The API does not, so create one yourself if you want Navigator to open on a saved state.
Create a Project View
Update a Project View
Delete a Project View
We don't provide any bulk deletion but you can delete by record ID. The Project View's Bookmarks and Bookmark groups are deleted with it. A Project View with "IsDeleteDisabled" set cannot be deleted. Deleting an ID that does not exist still succeeds.
Delete a Project View
Send a support message
This is the request behind Navigator's contact dialog. It emails the message to the Project View's "SupportEmail", and fails with a not found error when none is set. Users who are not signed in can send one if they can open the Project View.
Send a support message
Bookmark data model
Below is the core data model for a Bookmark. The camera and settings are described in the sections that follow.
A draft Bookmark is only listed to the User who created it, and Navigator marks it as "Your Draft". Anyone who can open the Project View can still get a draft by its ID, except users who are not signed in.
A User Group can be allowed to manage only their own draft Bookmarks on a Project View. Bookmarks those users create are always saved as drafts, and they can only change or delete drafts they created.
Bookmark: Camera
The camera is where Navigator flies to when the Bookmark opens. A "WEB_3D" Bookmark uses latitude, longitude and altitude, and a "WEB_3D_MODEL_SPACE" Bookmark uses x, y and z.
The camera moves instantly instead of flying when the frustum changes, and when moving into or out of model space over more than 10 km. A model space Bookmark without a valid position opens 500 metres above the origin, looking straight down.
Bookmark: Content types
The "contentType" setting decides what the Bookmark shows. Navigator offers each of these when you create a Bookmark. The scene settings in the next sections only apply to "WEB_3D" and "WEB_3D_MODEL_SPACE".
When an "iframeUrl" is on one of our embed hosts (Eg: embed.nextspace.host), Navigator substitutes these placeholders before loading it: ${ssid} and ${sessionId} with the user's session ID, and ${accountId}, ${envId}, ${viewId}, ${bookmarkId} and ${userId}. Other URLs are loaded as they are.
You can read about Dashboards in Custom Dashboards and about the markup structure in JSON: Markup.
Bookmark: Menu Items
A Bookmark enables Menu Items from its Project View by ID. Menu Items that are not listed are turned off when the Bookmark opens. Enabling a folder Menu Item enables its children too, or one of them when the folder's children act as radio buttons.
A Bookmark can also change some values of an enabled Menu Item without changing the Project View. A value the Bookmark leaves out uses the Menu Item's own value.
You can read about Menu Items, folders and their zoom control rows in Project View Menu Items.
Bookmark: Scene
These settings set up the globe, basemaps, terrain and effects. The defaults listed are used when neither the Bookmark nor the Project View defaults set a value.
Bookmark: Time
The scene time drives historic data, lighting and anything else that changes over time.
Bookmark: Entity states
States change how individual Entities look when the Bookmark opens. When a Bookmark has states, they replace the states the scene had before.
Bookmark: Diagram
A "DIAGRAM" Bookmark draws Entities and their relationships on a flat 2D canvas instead of the globe. Navigator saves an empty camera on the record and keeps the diagram's own camera in the settings.
Requesting Bookmarks
Bookmarks are returned in display order, then by title. The list leaves out drafts made by other users. Account power users can include them with "Drafts".
Get a list of Bookmarks
Get a Bookmark by ID
Get a Bookmark by ID without its Project View
Create and update Bookmarks
Leave the Bookmark ID out of the route to create one, and the API generates the ID. An update only changes the fields you include, and the camera and settings are each replaced as a whole. A Bookmark cannot be moved to another Project View.
Create or update a Bookmark
To reorder Bookmarks, send their IDs in the new order. Each listed Bookmark gets the next display order, starting from "DisplayOrder.Start". IDs that are not in the Project View are skipped, and Bookmarks you leave out keep their display order.
Set the order of Bookmarks
Delete a Bookmark
We don't provide any bulk deletion but you can delete by record ID. Comments made on the Bookmark are deleted with it.
Delete a Bookmark
Bookmark groups
Bookmark groups sort a Project View's Bookmarks into named folders. A group belongs to one Project View, and a Bookmark is in at most one group, set by its "UI.SlideGroup.ID". Set it to 0 to take the Bookmark out of its group.
Deleting a group moves its Bookmarks out of it rather than deleting them. Deleting a Project View deletes its groups. Groups use the same permissions as Bookmarks.
Navigator's Bookmarks panel lists the groups first, by display order then name, with the ungrouped Bookmarks after them. Each group is a folder the user can open and close, and it starts closed until the user opens it. Within a group, Bookmarks are sorted by display order then title. A Bookmark whose group ID matches no group is shown as ungrouped.
When a user reorders Bookmarks in Navigator, it numbers the display order of every Bookmark in one sequence: the groups' Bookmarks in group order, then the ungrouped ones. Follow the same rule if you want your order to match what Navigator writes.
Bookmark groups: Requests
Get a list of Bookmark groups
Get a Bookmark group by ID
Create or update a Bookmark group
Delete a Bookmark group
Set the order of Bookmark groups
Opening in Navigator
Navigator opens a Project View from its "viewId" query parameter, and a Bookmark from its "bookmarkId" query parameter. Eg: "/?viewId=abc12345&bookmarkId={bookmark_id}" on your Navigator address. Without a Bookmark ID it opens the first Bookmark in the order the API returns them.
Navigator gets the Project View with "Expand=*", so the Bookmarks and groups arrive in the same request. When a Bookmark opens, any setting it leaves out comes from the Project View's Bookmark defaults, as described above.