Diagrams

Generate diagrams from the model, and place ready diagram images onto presentation sheets. generateProgram runs the model-based Program auto-generation (creating new sheets); generateSite runs the site-diagram flow (location / streetview / climate sheets from the map terrain); place pastes ready-made images onto an existing sheet — it does not generate graphics itself. Adjacency data is read and computed via snaptrude.program.adjacency. Accessed via snaptrude.presentation.diagrams.

All methods are host API calls that return a Promise and write to the Present canvas. The generators create new layout sheets and return their ids; place creates one canvas shape per image URL and returns the created shape ids.

At a glance

Method	What it does	Mutates?
generateProgram()	Auto-generate space + department diagrams into new sheets	✓
generateSite(options?)	Generate location / streetview / climate diagram sheets	✓
place(sheetId, urls, options?)	Drop diagram image URLs onto a sheet as canvas shapes	✓

Present mode required

All methods require Present mode (the documentation editor) to be open and throw otherwise.

No generateAdjacency

There is intentionally no generateAdjacency. The host's adjacency generator runs its sheet-creation task fire-and-forget internally, so a single call cannot return the sheets it creates. Use the Present-mode Adjacency menu for those, then place a pre-rendered adjacency image if you need it through the API.

Functions

generateProgram()

Generate the program (space + department) diagrams for the current model, creating new layout sheets. Runs the same auto-generation as the Present-mode Program action: reads the project's spaces and departments, lays them out to scale, and creates one or more new sheets holding the generated diagram graphics.

• Parameters: none
• Returns: { sheetIds: string[] } — ids of the sheets created by the generator.
• Throws: If Present mode is not open, or the model has no spaces/departments to generate from.

const { sheetIds } = await snaptrude.presentation.diagrams.generateProgram();
console.log(`Generated ${sheetIds.length} program sheet(s)`);

generateSite(options?)

Generate the site diagrams (location, streetview, climate) for the current model, creating new layout sheets. Runs the same auto-generation as the Present-mode site-diagram flow: each requested type renders its diagram from the project's map terrain and creates a new sheet holding it. options.types selects which diagrams to generate (default: all three).

Regenerate semantics — skip, never duplicate

Generation is tracked per proposal (the same flags the mount-time flow reads). A type whose diagram was already generated for the active proposal is skipped, not duplicated — existing site-diagram sheets are never replaced, and the flag persists even if the sheet was later deleted. sheetIds therefore contains only the sheets created by this call and can be empty when everything already exists. Refreshing an existing site diagram is an interactive action (the sheet header's refresh) and is not exposed here.

• Parameters:
  • options.types: ("location" | "streetview" | "climate")[] | undefined — which site diagrams to generate (default: all three, in that fixed order)
• Returns: { sheetIds: string[] } — ids of the sheets created by this call (possibly empty — see above).
• Throws: If Present mode is not open, the project has no map terrain to generate from, or a generation pass is already running.

const { sheetIds } = await snaptrude.presentation.diagrams.generateSite({
  types: ["location", "climate"]
});
console.log(`Generated ${sheetIds.length} site diagram sheet(s)`);

place(sheetId, urls, options?)

Place diagram images onto a sheet. Drops the given diagram image URLs onto the sheet and returns the ids of the created canvas shapes.

• Parameters:
  • sheetId: string — the sheet to place onto
  • urls: string[] — diagram image URLs
  • options.position: { x: number; y: number } | undefined — where to place them, relative to the sheet (optional)
• Returns: { shapeIds: string[] } — ids of the created canvas shapes.
• Throws: If Present mode is not open or the sheet id is invalid.

const { sheets } = await snaptrude.presentation.sheets.list();
const { shapeIds } = await snaptrude.presentation.diagrams.place(
  sheets[0].id,
  ["https://example.com/adjacency-diagram.png"],
  { position: { x: 0, y: 0 } }
);
console.log(`Placed ${shapeIds.length} diagram image(s)`);

Errors

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

Code	Thrown by	When	details
PRECONDITION_FAILED	generateProgram	Present mode is not open	—
PRECONDITION_FAILED	generateProgram	The model has no spaces or departments to generate from	—
OPERATION_FAILED	generateProgram	The model has content but no diagram sheets were created	—
VALIDATION	generateSite	types is empty or contains an unknown diagram type	—
PRECONDITION_FAILED	generateSite	Present mode is not open	—
PRECONDITION_FAILED	generateSite	The project has no map terrain to generate site diagrams from	—
PRECONDITION_FAILED	generateSite	A site-diagram generation pass is already running	—
OPERATION_FAILED	generateSite	A generator failed mid-pass (completed types keep their sheets and flags)	type, error
PRECONDITION_FAILED	place	Present mode is not open	—
HANDLE_INVALID	place	sheetId is unknown or is not a sheet (frame)	—
OPERATION_FAILED	place	A diagram url could not be fetched (network/CORS)	url — the unreachable url
OPERATION_FAILED	place	No canvas shapes were created — a url does not point to a supported image (svg/png/jpeg)	urls