Views

Read and manage the saved 2D/3D views used to prepare presentations. A view is a camera bookmark — a sheet-ready 2D plan or a saved 3D camera position — not geometry. Accessed via snaptrude.presentation.views.

All methods are host API calls that return Promises. Reads never throw for a missing view (get and getActive return null, list returns an empty array). setActive, create, rename, delete, and updateSettings are writes, but they move the camera or manage bookmarks — they never modify geometry.

At a glance

Method	What it does	Mutates?
list()	List all saved views in the project	—
get(viewId)	Get a single view by id	—
getActive()	Get the currently active view	—
capture(options?)	Screenshot the current viewport (or a saved view) as a base64 image	—
setActive(viewId)	Move the camera to a saved view	✓
create(name?, options?)	Save the current camera as a new view	✓
rename(viewId, name)	Rename a saved view	✓
delete(viewId)	Delete a saved view	✓
getSettings(viewId)	Read a view's display settings	—
updateSettings(viewId, settings)	Update a view's display settings	✓

Create and capture from the Design context

create and capture work off the live Design canvas — creating a view while Present mode is open is not supported.

Types

PluginPresentationView

A saved presentation view.

Property	Type	Description
id	string	Unique view id
name	string	Display name
type	"2d" | "3d"	Whether this is a 2D plan view or a 3D view
isActive	boolean	Whether this view is the currently active view
storey	number | null	The storey the view was saved on (null on older views saved without one)

PluginPresentationViewColorMode

How a view colours the model.

Value	Meaning
'department'	Colour by department
'monochrome'	Single flat colour
'texture'	Show material textures
'tag:<categoryId>'	Colour by a project tag category (e.g. tag:ZONE)

The tag:<categoryId> form carries the product's tag-based colour schemes losslessly — reading a view that uses one returns the tag: string as-is, and writing it back preserves the scheme (read-then-write is safe).

PluginPresentationViewSettings

A view's display settings (read/written via getSettings / updateSettings).

Property	Type	Description
backgroundColor	string	Canvas background as #rrggbb
colorMode	PluginPresentationViewColorMode	How the model is coloured
viewMode	"perspective" | "isometric"	Camera projection — the first control in the product's view-settings modal. Writable on 3D views only; a 2D plan is always orthographic, reads "isometric", and accepts only "isometric" (a no-op). Older views without a stored mode derive it from the saved camera
showAxis	boolean	Show the axis widget
showEdges	boolean	Show object edges
showLabels	boolean	Master label switch — whether on-canvas labels are shown at all. true always pairs with a non-empty labels selection (labels render only while the selection is non-empty; there is no labels-on-with-empty-selection state)
labels	Array<'department' | 'objectLabels' | 'areas'>	Which label categories are selected. When showLabels is false the view stores no selection and this reads []

Functions

list()

List the saved views in the active project.

• Returns: { views: PluginPresentationView[] } — empty when the project has none.

const { views } = await snaptrude.presentation.views.list();
const plans = views.filter((v) => v.type === "2d");
console.log(`${views.length} views, ${plans.length} 2D plans`);

---

get(viewId)

Get a single saved view by id.

• Parameters:
  • viewId: string — the id of the view to read
• Returns: PluginPresentationView | null — null if no view has that id.

const { views } = await snaptrude.presentation.views.list();
const view = await snaptrude.presentation.views.get(views[0].id);
if (view) console.log(view.name, view.type);

---

getActive()

Get the currently active view. Paired with setActive.

• Returns: PluginPresentationView | null — null if no view is active.

const active = await snaptrude.presentation.views.getActive();
if (active) console.log(`Active: ${active.name} (${active.type})`);

---

capture(options?)

Capture a screenshot as a base64 image. By default it shoots the current viewport; pass a viewId to capture a specific saved view — that view is briefly applied to the scene, captured, and the previously active view is restored (if no saved view was active, the target view stays applied).

• Parameters (all optional):
  • options.viewId: string | undefined — capture this saved view; omit to capture the current viewport
  • options.format: "png" | "jpeg" | undefined — output image format (default "png")
  • options.resolution: string | undefined — output resolution (e.g. "1280x720"; default 1280x720)
• Returns: { image: string } — the captured image as a base64 data URL.
• Throws: HANDLE_INVALID if a given viewId does not match a saved view.

// Current viewport, as a JPEG at 1920x1080
const { image } = await snaptrude.presentation.views.capture({
  format: "jpeg",
  resolution: "1920x1080"
});
console.log(image.slice(0, 23)); // "data:image/jpeg;base64,"

// A specific saved view (applied + restored around the shot)
const { views } = await snaptrude.presentation.views.list();
const shot = await snaptrude.presentation.views.capture({ viewId: views[0].id });

---

setActive(viewId)

Activate a saved view — move the camera to it and restore its scene state. Applies the view's camera, visibility, and storey state to the live scene. Paired with getActive.

• Parameters:
  • viewId: string — the id of the view to activate
• Returns: { id: string } — the now-active view's id.
• Throws: If no view has the given id.

const { views } = await snaptrude.presentation.views.list();
const plan = views.find((v) => v.type === "2d");
if (plan) await snaptrude.presentation.views.setActive(plan.id);

---

create(name?, options?)

Save the current camera/scene state as a new named view — a camera bookmark from where the camera is now, not geometry.

• Parameters (all optional):
  • name: string | undefined — name for the new view (a default is used when omitted)
  • options.kind: "view" | "sitePlan" | undefined — what kind of view to save (default "view"). "sitePlan" saves a site plan (persisted with the site-plan view kind); "plan" is not offered (the host cannot create a plan view without a planId this API does not carry).
  • options.storey: number | undefined — save the view on this storey. The storey is activated first (the view is captured on it, and the saved view is left active there); defaults to the current active storey. Throws if no such storey exists.
• Returns: PluginPresentationView — the newly created view (its storey reflects where it was saved).
• Throws: If storey is given but no such storey exists, or the view could not be saved.
• Note: 2D plan views cannot be created through this API. Created views can be removed again with delete.

const view = await snaptrude.presentation.views.create("Lobby Perspective");
console.log(view.id, view.type, view.storey);

// Capture the view on a specific storey (activated before the shot)
const level2 = await snaptrude.presentation.views.create("Level 2", { storey: 2 });

---

rename(viewId, name)

Rename a saved view — the same rename the views panel runs, with the same validation: the name must be non-empty, unique within the proposal, and free of the characters \ : { } [ ] | ; < > ? ~. Persists and updates the panel immediately.

• Parameters:
  • viewId: string — the id of the view to rename
  • name: string — the new display name (non-empty after trimming)
• Returns: PluginPresentationView — the renamed view.
• Throws: HANDLE_INVALID if no view has the given id; OPERATION_FAILED if the native rename refuses the name (duplicate within the proposal, or invalid characters).

const { views } = await snaptrude.presentation.views.list();
const view = await snaptrude.presentation.views.rename(views[0].id, "Entrance");
console.log(view.name); // "Entrance"

---

delete(viewId)

Delete a saved view — the views panel's own delete path. Persists the removal and updates the panel; if the deleted view was the active one, the product falls back to the default plan/3D view (the same fallback the panel performs). Shows the product's "View deleted" toast, exactly as deleting from the panel does.

• Parameters:
  • viewId: string — the id of the view to delete
• Returns: { id: string } — the id of the deleted view.
• Throws: HANDLE_INVALID if no view has the given id; PRECONDITION_FAILED if the view is a default view (the built-in plan/3D/site-plan entries cannot be deleted); OPERATION_FAILED if the native delete path refuses.

const temp = await snaptrude.presentation.views.create("Temp shot");
// ... capture, export, etc.
await snaptrude.presentation.views.delete(temp.id);

---

getSettings(viewId)

Read a view's display settings — background colour, colour mode, camera projection (viewMode), axis/edge/label toggles, and the active label categories.

• Parameters:
  • viewId: string — the id of the view to read
• Returns: PluginPresentationViewSettings | null — null if no view has that id.

const settings = await snaptrude.presentation.views.getSettings(viewId);
if (settings) console.log(settings.colorMode, settings.showEdges);

---

updateSettings(viewId, settings)

Update a view's display settings with a sparse patch — only the fields you pass change. Persists + broadcasts (matching the view-settings UI) and reflects live when the view is the active one. This is a write; it is not on the local undo stack.

Label patch semantics (mirroring the product, which stores no label selection while labels are off):

• { showLabels: true } alone turns labels on; if the view has no stored selection, the product defaults (objectLabels, areas) are applied — labels are never "on" with an empty selection.
• { labels: [...] } alone sets the selection and turns labels on.
• { showLabels: false } turns labels off and clears the stored selection — a later read returns labels: [].
• { showLabels: false, labels: [...] } with a non-empty list is contradictory and rejected (nothing is silently discarded).
• { showLabels: true, labels: [] } is likewise contradictory and rejected — pass a non-empty list, or omit labels to get the defaults.

colorMode accepts the tag:<categoryId> scheme strings returned by getSettings, so read-then-write round-trips a tag-based colour scheme unchanged.

viewMode ("perspective" | "isometric") applies to 3D views only — a 2D plan is always orthographic, so a viewMode: "perspective" patch on a 2D view is rejected with PRECONDITION_FAILED; "isometric" on a 2D plan is accepted as a no-op (the plan is already orthographic), so writing back exactly what getSettings returned is always a no-op. On the active view the camera switches projection immediately (the same toggle the view-settings modal runs); on other views the persisted mode is applied the next time the view is activated.

• Parameters:
  • viewId: string — the id of the view to update
  • settings: Partial<PluginPresentationViewSettings> — the fields to change
• Returns: { id: string } — the updated view's id.
• Throws: If no view has the given id, the patch is contradictory (showLabels: false with a non-empty labels, or showLabels: true with an explicitly empty labels list), or viewMode: "perspective" is patched on a 2D plan view.

await snaptrude.presentation.views.updateSettings(viewId, {
  colorMode: "monochrome",
  showEdges: false
});

// Switch a 3D view to an isometric (orthographic) projection
await snaptrude.presentation.views.updateSettings(viewId, { viewMode: "isometric" });

---

Errors

Failed calls reject with a typed PluginError — see Error Handling. Conditions specific to this namespace:

Code	Thrown by	When	details
HANDLE_INVALID	capture, setActive, updateSettings, rename, delete	No saved view has the given id	—
PRECONDITION_FAILED	create	options.storey was given but no such storey exists	storey
PRECONDITION_FAILED	updateSettings	viewMode: "perspective" was patched on a 2D plan view (always orthographic; "isometric" is a no-op there)	viewMode
PRECONDITION_FAILED	delete	The view is a default view (built-in plan/3D/site-plan entries cannot be deleted)	viewId
OPERATION_FAILED	create	The server-side screenshot save failed, or the created view could not be read back	kind / viewId
OPERATION_FAILED	rename, delete	The native panel path refused (duplicate name, invalid characters, delete failure)	viewId / name

list, get, and getActive never throw — they return an empty list / null on a miss.