@snaptrude/plugin-core 0.11.0-rc.1 → 1.0.0

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,18 @@ 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.
+ *
+ * While Present mode is open these calls set the Design frame a view saved in
+ * Present (`presentation.views.create`) is taken from; they never move the
+ * Present sheet canvas. To pan, zoom or screenshot the Present canvas, use
+ * {@linkcode PluginPresentationCameraApi} (`presentation.camera`).
  */
 export abstract class PluginCameraApi {
   constructor() {}
@@ -18,6 +30,10 @@ export abstract class PluginCameraApi {
    * Point the camera: place its eye at `eye` looking toward `target` (world
    * coordinates, internal `babylon` units). View-state only — not undoable.
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @param eye - Camera position as a {@linkcode Vec3Handle}
    * @param target - Point the camera looks at as a {@linkcode Vec3Handle}
    * @returns `true` once the camera has been positioned.
@@ -44,6 +60,10 @@ export abstract class PluginCameraApi {
    * perspective) view. Mirrors the canvas view menu. View-state only — not
    * undoable. The orthographic presets exit 2D mode first if needed.
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @param view - The standard view to snap to ({@linkcode PluginStandardView})
    * @returns `true` once the view has been applied.
    *
@@ -84,6 +104,10 @@ export abstract class PluginCameraApi {
    * 2D/3D toggle: `3d` enters the isometric perspective view, `2d` drops to the
    * orthographic plan of the active storey. View-state only — not undoable.
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @param mode - `"2d"` or `"3d"` ({@linkcode PluginCameraMode})
    * @returns `true` once the mode switch has been requested.
    *
@@ -128,6 +152,10 @@ export abstract class PluginCameraApi {
    * `"orthographic"` is accepted as a no-op, while `"perspective"` is
    * rejected — switch to 3D first via `setMode("3d")`.
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @param projection - `"perspective"` or `"orthographic"` ({@linkcode PluginCameraProjection})
    * @returns `true` once the projection has been applied.
    *
@@ -151,6 +179,10 @@ export abstract class PluginCameraApi {
    * action. View-state only — not undoable. Canonical home of the zoom-extents
    * read (the deprecated `core.zoom.extents`).
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @returns `true` once the camera has been framed to the scene.
    *
    * @examplePrompt Zoom out so I can see the whole model
@@ -170,6 +202,10 @@ export abstract class PluginCameraApi {
    * undoable. Canonical home of the zoom-to-selection read (the deprecated
    * `core.zoom.selection`).
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @returns `true` if there was a selection to frame; `false` if nothing is
    *   selected (no-op).
    *
@@ -184,6 +220,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 +476,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
+>