@snaptrude/plugin-core 0.9.15 → 0.9.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.9.15",
+  "version": "0.9.16",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/api/core/camera/index.ts

@@ -1,6 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
-import { Vec3Handle } from "../../../handles"
+import { Vec3Components, Vec3Handle } from "../../../handles"
 
 /**
  * Camera controls.
@@ -10,6 +10,13 @@ import { Vec3Handle } from "../../../handles"
  * canvas view menu and the 2D/3D toggle. Like {@linkcode PluginZoomApi}, these
  * are transient VIEW-STATE changes: they are not model edits, so they are not
  * write-gated and are not undoable. Accessed via `snaptrude.core.camera`.
+ *
+ * Read and set the full camera pose (`getPose`/`setPose`), walk and turn it the
+ * way the arrow keys do (`move`/`rotate`), and read or change the arrow-key
+ * navigation settings (`getNavigationSettings`/`updateNavigationSettings`).
+ * Positions are world coordinates in internal `babylon` units (1 unit =
+ * 0.254 m, Y up); yaw is degrees clockwise from +z seen from above, pitch is
+ * degrees above level.
  */
 export abstract class PluginCameraApi {
   constructor() {}
@@ -184,6 +191,180 @@ export abstract class PluginCameraApi {
    * ```
    */
   public abstract zoomSelection(): PluginApiReturn<boolean>
+
+  /**
+   * Read where the camera is and where it looks: the eye and target positions
+   * (world coordinates, internal `babylon` units), the view direction as yaw
+   * and pitch, the vertical field of view, the projection and the 2D/3D mode.
+   * Paired with {@linkcode PluginCameraApi.setPose}.
+   *
+   * @returns The current {@linkcode PluginCameraPose}.
+   * @throws PRECONDITION_FAILED when there is no active camera.
+   *
+   * @examplePrompt Where is the camera right now?
+   * @examplePrompt Remember this viewpoint so we can come back to it
+   * @examplePrompt Which way is the camera facing?
+   * @examplePrompt How high above the ground is the camera?
+   *
+   * # Example
+   * ```ts
+   * const pose = await snaptrude.core.camera.getPose()
+   * console.log(pose.eye, pose.yawInDegrees, pose.pitchInDegrees)
+   * ```
+   */
+  public abstract getPose(): PluginApiReturn<PluginCameraPose>
+
+  /**
+   * Place the camera, optionally easing there over `options.durationInSeconds`,
+   * and resolve once the new view has been drawn, so a capture that follows sees
+   * it without a fixed wait. `pose` is one of:
+   *
+   * - `{ eye, target }`: stand at `eye` looking at `target`, as
+   *   {@linkcode PluginCameraApi.lookFrom} does with handles;
+   * - `{ eye, yawInDegrees, pitchInDegrees }`: stand at `eye` looking along a
+   *   direction;
+   * - `{ standAt, yawInDegrees? }`: stand on the floor, stair, terrain or
+   *   ground at or below `standAt`, at the user's eye height above it (the `I`
+   *   key), facing `yawInDegrees` (the current yaw when omitted).
+   *
+   * Stops a playing walkthrough and switches from 2D plan view to 3D first.
+   * View-state only: not write-gated, not undoable.
+   *
+   * @param pose - Where to put the camera ({@linkcode PluginCameraPoseInput})
+   * @param options - `durationInSeconds`: ease over this long (0 to 10, default 0 jumps)
+   * @returns The camera's {@linkcode PluginCameraPose} once it has arrived.
+   * @throws PRECONDITION_FAILED when there is no active camera, while a
+   *   walkthrough export is recording, or when `standAt` lies below the ground
+   *   with nothing under it. VALIDATION when `eye` and `target` coincide or a
+   *   pitch is beyond ±89°.
+   *
+   * @examplePrompt Stand in the living room at eye level facing the window
+   * @examplePrompt Move the camera to (40, 12, 30) looking at the entrance
+   * @examplePrompt Fly the camera smoothly over to the courtyard
+   * @examplePrompt Put me back at the viewpoint we saved earlier
+   *
+   * # Example
+   * ```ts
+   * const { camera } = snaptrude.core
+   * await camera.setPose({ standAt: { x: 20, y: 0, z: 35 }, yawInDegrees: 90 })
+   * await camera.setPose(
+   *   { eye: { x: 60, y: 25, z: 60 }, target: { x: 0, y: 5, z: 0 } },
+   *   { durationInSeconds: 1.5 },
+   * )
+   * ```
+   */
+  public abstract setPose(
+    pose: PluginCameraPoseInput,
+    options?: PluginCameraSetPoseOptions,
+  ): PluginApiReturn<PluginCameraPose>
+
+  /**
+   * Walk or fly the camera by a displacement in its own frame: `forward` along
+   * the level view direction, `right` to its side and `up` vertically, in
+   * internal `babylon` units. The view direction does not change. With
+   * `options.followsFloor` the camera keeps its height above the floor as it
+   * goes, climbing and descending stairs and ramps the way the arrow keys do.
+   * Stops a playing walkthrough and switches from 2D plan view to 3D first.
+   * View-state only: not write-gated, not undoable.
+   *
+   * @param displacement - {@linkcode PluginCameraMoveDisplacement}; omitted components are 0
+   * @param options - `followsFloor` (default `false`) and `durationInSeconds` (0 to 10, default 0)
+   * @returns The camera's {@linkcode PluginCameraPose} after the move.
+   * @throws PRECONDITION_FAILED when there is no active camera, or while a
+   *   walkthrough export is recording.
+   *
+   * @examplePrompt Walk forward 3 metres
+   * @examplePrompt Step to the right a little
+   * @examplePrompt Walk up the stairs ahead
+   * @examplePrompt Raise the camera by 2 metres
+   *
+   * # Example
+   * ```ts
+   * const metre = 1 / 0.254
+   * await snaptrude.core.camera.move(
+   *   { forward: 3 * metre },
+   *   { followsFloor: true, durationInSeconds: 2 },
+   * )
+   * ```
+   */
+  public abstract move(
+    displacement: PluginCameraMoveDisplacement,
+    options?: PluginCameraMoveOptions,
+  ): PluginApiReturn<PluginCameraPose>
+
+  /**
+   * Turn the camera in place by signed angles: `yawInDegrees` to the right
+   * (clockwise seen from above) and `pitchInDegrees` up. The eye does not move;
+   * the resulting pitch is kept within ±89°. Stops a playing walkthrough and
+   * switches from 2D plan view to 3D first. View-state only: not write-gated,
+   * not undoable.
+   *
+   * @param yawInDegrees - Turn to the right by this much (negative turns left)
+   * @param pitchInDegrees - Tilt up by this much (negative tilts down; default 0)
+   * @param options - `durationInSeconds` (0 to 10, default 0)
+   * @returns The camera's {@linkcode PluginCameraPose} after turning.
+   * @throws PRECONDITION_FAILED when there is no active camera, or while a
+   *   walkthrough export is recording.
+   *
+   * @examplePrompt Turn around
+   * @examplePrompt Look 45 degrees to the left
+   * @examplePrompt Tilt the camera down a bit
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.camera.rotate(180, 0, { durationInSeconds: 1 })
+   * ```
+   */
+  public abstract rotate(
+    yawInDegrees: number,
+    pitchInDegrees?: number,
+    options?: PluginCameraRotateOptions,
+  ): PluginApiReturn<PluginCameraPose>
+
+  /**
+   * Read the arrow-key navigation settings: whether the arrow keys walk the
+   * camera, the eye height used by `setPose`'s `standAt` and by walkthroughs
+   * that follow the floor, the walking speed, and whether walking stops at
+   * walls. Paired with {@linkcode PluginCameraApi.updateNavigationSettings}.
+   *
+   * @returns The current {@linkcode PluginCameraNavigationSettings}.
+   *
+   * @examplePrompt Is arrow-key navigation on?
+   * @examplePrompt What eye height does the camera use?
+   *
+   * # Example
+   * ```ts
+   * const { isKeyboardNavigationEnabled } =
+   *   await snaptrude.core.camera.getNavigationSettings()
+   * ```
+   */
+  public abstract getNavigationSettings(): PluginApiReturn<PluginCameraNavigationSettings>
+
+  /**
+   * Change arrow-key navigation settings; only the fields given change.
+   * `isKeyboardNavigationEnabled` is the user's Project Settings switch and is
+   * saved on this device; the other settings last for the session.
+   * Write-gated: this changes the user's preferences, not just the view.
+   *
+   * @param patch - The settings to change ({@linkcode PluginCameraNavigationSettingsPatch})
+   * @returns The {@linkcode PluginCameraNavigationSettings} after the change.
+   * @throws METHOD_NOT_PERMITTED when plugin writes are disabled.
+   *
+   * @examplePrompt Turn off arrow-key navigation
+   * @examplePrompt Use a 1.6 m eye height
+   * @examplePrompt Make walking stop at walls
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.camera.updateNavigationSettings({
+   *   eyeHeight: 1.6 / 0.254,
+   *   isCollisionEnabled: true,
+   * })
+   * ```
+   */
+  public abstract updateNavigationSettings(
+    patch: PluginCameraNavigationSettingsPatch,
+  ): PluginApiReturn<PluginCameraNavigationSettings>
 }
 
 /**
@@ -266,3 +447,221 @@ export const PluginCameraSetProjectionArgs = z.object({
 export type PluginCameraSetProjectionArgs = z.infer<
   typeof PluginCameraSetProjectionArgs
 >
+
+// Plain {x, y, z} record with finite components (the brepFromRevolution `axisOrigin` pattern).
+const FiniteVec3Components = z.object({
+  x: z.number().finite(),
+  y: z.number().finite(),
+  z: z.number().finite(),
+})
+
+/** Pitch is kept off the vertical, where yaw has no meaning. */
+const PitchInDegrees = z.number().finite().min(-89).max(89)
+
+/** How long a camera move eases for; 0 jumps. */
+const DurationInSeconds = z.number().finite().min(0).max(10)
+
+/**
+ * The camera's pose — result of {@linkcode PluginCameraApi.getPose},
+ * {@linkcode PluginCameraApi.setPose}, {@linkcode PluginCameraApi.move} and
+ * {@linkcode PluginCameraApi.rotate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `eye` | `{ x, y, z }` | Camera position (world, `babylon` units) |
+ * | `target` | `{ x, y, z }` | Point the camera looks at |
+ * | `yawInDegrees` | `number` | View direction, degrees clockwise from +z seen from above (-180 to 180) |
+ * | `pitchInDegrees` | `number` | View direction, degrees above level (negative looks down) |
+ * | `fieldOfViewInDegrees` | `number` | Vertical field of view |
+ * | `projection` | {@linkcode PluginCameraProjection} | `"perspective"` or `"orthographic"` |
+ * | `mode` | {@linkcode PluginCameraMode} | `"2d"` or `"3d"` |
+ */
+export const PluginCameraPose = z.object({
+  eye: Vec3Components,
+  target: Vec3Components,
+  yawInDegrees: z.number(),
+  pitchInDegrees: z.number(),
+  fieldOfViewInDegrees: z.number(),
+  projection: PluginCameraProjection,
+  mode: PluginCameraMode,
+})
+export type PluginCameraPose = z.infer<typeof PluginCameraPose>
+
+/**
+ * Where {@linkcode PluginCameraApi.setPose} puts the camera — exactly one of:
+ *
+ * | Shape | Meaning |
+ * |---|---|
+ * | `{ eye, target }` | Stand at `eye` looking at `target` |
+ * | `{ eye, yawInDegrees, pitchInDegrees }` | Stand at `eye` looking along a direction (pitch within ±89°) |
+ * | `{ standAt, yawInDegrees? }` | Stand at eye height on the floor, stair, terrain or ground at or below `standAt`, facing `yawInDegrees` (default: current yaw) |
+ *
+ * Points are plain `{ x, y, z }` world coordinates in `babylon` units.
+ */
+export const PluginCameraPoseInput = z.union([
+  z
+    .object({ eye: FiniteVec3Components, target: FiniteVec3Components })
+    .strict(),
+  z
+    .object({
+      eye: FiniteVec3Components,
+      yawInDegrees: z.number().finite(),
+      pitchInDegrees: PitchInDegrees,
+    })
+    .strict(),
+  z
+    .object({
+      standAt: FiniteVec3Components,
+      yawInDegrees: z.number().finite().optional(),
+    })
+    .strict(),
+])
+export type PluginCameraPoseInput = z.infer<typeof PluginCameraPoseInput>
+
+/**
+ * Options for {@linkcode PluginCameraApi.setPose}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `durationInSeconds` | `number \| undefined` | Ease to the pose over this long (0 to 10; default 0 jumps) |
+ */
+export const PluginCameraSetPoseOptions = z
+  .object({ durationInSeconds: DurationInSeconds.optional() })
+  .strict()
+export type PluginCameraSetPoseOptions = z.infer<
+  typeof PluginCameraSetPoseOptions
+>
+
+/**
+ * Arguments for {@linkcode PluginCameraApi.setPose}.
+ */
+export const PluginCameraSetPoseArgs = z.object({
+  pose: PluginCameraPoseInput,
+  options: PluginCameraSetPoseOptions.optional(),
+})
+export type PluginCameraSetPoseArgs = z.infer<typeof PluginCameraSetPoseArgs>
+
+/**
+ * A displacement in the camera's own frame, for {@linkcode PluginCameraApi.move}
+ * (`babylon` units; omitted components are 0).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `forward` | `number \| undefined` | Along the level view direction (negative walks back) |
+ * | `right` | `number \| undefined` | To the camera's right (negative steps left) |
+ * | `up` | `number \| undefined` | Vertically (negative descends) |
+ */
+export const PluginCameraMoveDisplacement = z
+  .object({
+    forward: z.number().finite().optional(),
+    right: z.number().finite().optional(),
+    up: z.number().finite().optional(),
+  })
+  .strict()
+export type PluginCameraMoveDisplacement = z.infer<
+  typeof PluginCameraMoveDisplacement
+>
+
+/**
+ * Options for {@linkcode PluginCameraApi.move}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `followsFloor` | `boolean \| undefined` | Keep the height above the floor, climbing stairs and ramps (default `false`) |
+ * | `durationInSeconds` | `number \| undefined` | Walk over this long (0 to 10; default 0 jumps) |
+ */
+export const PluginCameraMoveOptions = z
+  .object({
+    followsFloor: z.boolean().optional(),
+    durationInSeconds: DurationInSeconds.optional(),
+  })
+  .strict()
+export type PluginCameraMoveOptions = z.infer<typeof PluginCameraMoveOptions>
+
+/**
+ * Arguments for {@linkcode PluginCameraApi.move}.
+ */
+export const PluginCameraMoveArgs = z.object({
+  displacement: PluginCameraMoveDisplacement,
+  options: PluginCameraMoveOptions.optional(),
+})
+export type PluginCameraMoveArgs = z.infer<typeof PluginCameraMoveArgs>
+
+/**
+ * Options for {@linkcode PluginCameraApi.rotate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `durationInSeconds` | `number \| undefined` | Turn over this long (0 to 10; default 0 jumps) |
+ */
+export const PluginCameraRotateOptions = z
+  .object({ durationInSeconds: DurationInSeconds.optional() })
+  .strict()
+export type PluginCameraRotateOptions = z.infer<
+  typeof PluginCameraRotateOptions
+>
+
+/**
+ * Arguments for {@linkcode PluginCameraApi.rotate}.
+ */
+export const PluginCameraRotateArgs = z.object({
+  yawInDegrees: z.number().finite(),
+  pitchInDegrees: z.number().finite().optional(),
+  options: PluginCameraRotateOptions.optional(),
+})
+export type PluginCameraRotateArgs = z.infer<typeof PluginCameraRotateArgs>
+
+/**
+ * How fast the arrow keys walk: the Slow / Normal / Fast navigation setting.
+ */
+export const PluginCameraWalkSpeed = z.enum(["slow", "normal", "fast"])
+export type PluginCameraWalkSpeed = z.infer<typeof PluginCameraWalkSpeed>
+
+/**
+ * The arrow-key navigation settings — result of
+ * {@linkcode PluginCameraApi.getNavigationSettings} and
+ * {@linkcode PluginCameraApi.updateNavigationSettings}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `isKeyboardNavigationEnabled` | `boolean` | Whether the arrow keys walk the camera (Project Settings) |
+ * | `eyeHeight` | `number` | Eye height above the floor, `babylon` units |
+ * | `walkSpeed` | {@linkcode PluginCameraWalkSpeed} | Arrow-key walking speed |
+ * | `isCollisionEnabled` | `boolean` | Whether walking stops at walls |
+ */
+export const PluginCameraNavigationSettings = z.object({
+  isKeyboardNavigationEnabled: z.boolean(),
+  eyeHeight: z.number(),
+  walkSpeed: PluginCameraWalkSpeed,
+  isCollisionEnabled: z.boolean(),
+})
+export type PluginCameraNavigationSettings = z.infer<
+  typeof PluginCameraNavigationSettings
+>
+
+/**
+ * The settings to change in {@linkcode PluginCameraApi.updateNavigationSettings};
+ * omitted fields keep their value. `eyeHeight` is in `babylon` units, between
+ * 0.8 m and 2.5 m (3.15 to 9.84 units).
+ */
+export const PluginCameraNavigationSettingsPatch = z
+  .object({
+    isKeyboardNavigationEnabled: z.boolean().optional(),
+    eyeHeight: z.number().finite().min(3.15).max(9.84).optional(),
+    walkSpeed: PluginCameraWalkSpeed.optional(),
+    isCollisionEnabled: z.boolean().optional(),
+  })
+  .strict()
+export type PluginCameraNavigationSettingsPatch = z.infer<
+  typeof PluginCameraNavigationSettingsPatch
+>
+
+/**
+ * Arguments for {@linkcode PluginCameraApi.updateNavigationSettings}.
+ */
+export const PluginCameraUpdateNavigationSettingsArgs = z.object({
+  patch: PluginCameraNavigationSettingsPatch,
+})
+export type PluginCameraUpdateNavigationSettingsArgs = z.infer<
+  typeof PluginCameraUpdateNavigationSettingsArgs
+>

package/src/api/presentation/index.ts

@@ -10,6 +10,7 @@ import { PluginPresentationShapesApi } from "./shapes"
 import { PluginPresentationTablesApi } from "./tables"
 import { PluginPresentationSlideshowApi } from "./slideshow"
 import { PluginPresentationImportApi } from "./import"
+import { PluginPresentationWalkthroughsApi } from "./walkthroughs"
 import {
   PluginPresentationExportResult,
   type PluginPresentationExportFormat,
@@ -35,6 +36,7 @@ import {
  * - {@linkcode PluginPresentationApi.slideshow} — Run the Present-mode slideshow
  * - {@linkcode PluginPresentationApi.import} — Import reference images/PDFs onto the canvas
  * - {@linkcode PluginPresentationApi.aiInspiration} — Present-mode AI image/video generation
+ * - {@linkcode PluginPresentationApi.walkthroughs} — Camera paths through the model: create, play, capture, export as video
  *
  * Accessed via `snaptrude.presentation`.
  */
@@ -64,6 +66,12 @@ export abstract class PluginPresentationApi {
    * {@linkcode PluginPresentationAIInspirationApi}.
    */
   public abstract aiInspiration: PluginPresentationAIInspirationApi
+  /**
+   * Walkthroughs — camera paths through the model: create (keyframes, floor
+   * points, camera-move presets), play, capture and export as video onto the
+   * Present canvas. See {@linkcode PluginPresentationWalkthroughsApi}.
+   */
+  public abstract walkthroughs: PluginPresentationWalkthroughsApi
 
   /**
    * Export the presentation's layout sheets to a downloadable file (PDF / PNG /
@@ -114,4 +122,5 @@ export * from "./tables"
 export * from "./slideshow"
 export * from "./import"
 export * from "./aiInspiration"
+export * from "./walkthroughs"
 export * from "./export"