@snaptrude/plugin-core 0.9.15 → 0.9.16

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @snaptrude/plugin-core
 
+## 0.9.16
+
+### Patch Changes
+
+- e8d4ec3: Add camera pose and navigation APIs to `core.camera` (`getPose`, `setPose`, `move`, `rotate`, `getNavigationSettings`, `updateNavigationSettings`) and a new `presentation.walkthroughs` namespace for camera paths: create from keyframes, floor points or camera-move presets; edit walkthroughs and their keyframes; `sample`, `listIssues` and `capture` them; play them with `start`/`stop`/`getState`; and `export` them as a video onto the Present canvas as a job (`getJob`, `cancelJob`, `listJobs`).
+
 ## 0.9.15
 
 ### Patch Changes

package/api-manifest.json

@@ -494,6 +494,30 @@
     "argsType": null,
     "resultType": "PluginCameraMode"
   },
+  {
+    "path": "core.camera.getNavigationSettings",
+    "namespace": "core.camera",
+    "summary": "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}.",
+    "examplePrompts": [
+      "Is arrow-key navigation on?",
+      "What eye height does the camera use?\n\n# Example\n```ts\nconst { isKeyboardNavigationEnabled } =\nawait snaptrude.core.camera.getNavigationSettings()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginCameraNavigationSettings"
+  },
+  {
+    "path": "core.camera.getPose",
+    "namespace": "core.camera",
+    "summary": "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}.",
+    "examplePrompts": [
+      "Where is the camera right now?",
+      "Remember this viewpoint so we can come back to it",
+      "Which way is the camera facing?",
+      "How high above the ground is the camera?\n\n# Example\n```ts\nconst pose = await snaptrude.core.camera.getPose()\nconsole.log(pose.eye, pose.yawInDegrees, pose.pitchInDegrees)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginCameraPose"
+  },
   {
     "path": "core.camera.getProjection",
     "namespace": "core.camera",
@@ -519,6 +543,31 @@
     "argsType": "Vec3Handle",
     "resultType": "boolean"
   },
+  {
+    "path": "core.camera.move",
+    "namespace": "core.camera",
+    "summary": "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.",
+    "examplePrompts": [
+      "Walk forward 3 metres",
+      "Step to the right a little",
+      "Walk up the stairs ahead",
+      "Raise the camera by 2 metres\n\n# Example\n```ts\nconst metre = 1 / 0.254\nawait snaptrude.core.camera.move(\n{ forward: 3 * metre },\n{ followsFloor: true, durationInSeconds: 2 },\n)\n```"
+    ],
+    "argsType": "PluginCameraMoveDisplacement",
+    "resultType": "PluginCameraPose"
+  },
+  {
+    "path": "core.camera.rotate",
+    "namespace": "core.camera",
+    "summary": "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.",
+    "examplePrompts": [
+      "Turn around",
+      "Look 45 degrees to the left",
+      "Tilt the camera down a bit\n\n# Example\n```ts\nawait snaptrude.core.camera.rotate(180, 0, { durationInSeconds: 1 })\n```"
+    ],
+    "argsType": "number",
+    "resultType": "PluginCameraPose"
+  },
   {
     "path": "core.camera.setMode",
     "namespace": "core.camera",
@@ -532,6 +581,19 @@
     "argsType": "PluginCameraMode",
     "resultType": "boolean"
   },
+  {
+    "path": "core.camera.setPose",
+    "namespace": "core.camera",
+    "summary": "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:",
+    "examplePrompts": [
+      "Stand in the living room at eye level facing the window",
+      "Move the camera to (40, 12, 30) looking at the entrance",
+      "Fly the camera smoothly over to the courtyard",
+      "Put me back at the viewpoint we saved earlier\n\n# Example\n```ts\nconst { camera } = snaptrude.core\nawait camera.setPose({ standAt: { x: 20, y: 0, z: 35 }, yawInDegrees: 90 })\nawait camera.setPose(\n{ eye: { x: 60, y: 25, z: 60 }, target: { x: 0, y: 5, z: 0 } },\n{ durationInSeconds: 1.5 },\n)\n```"
+    ],
+    "argsType": "PluginCameraPoseInput",
+    "resultType": "PluginCameraPose"
+  },
   {
     "path": "core.camera.setProjection",
     "namespace": "core.camera",
@@ -559,6 +621,18 @@
     "argsType": "PluginStandardView",
     "resultType": "boolean"
   },
+  {
+    "path": "core.camera.updateNavigationSettings",
+    "namespace": "core.camera",
+    "summary": "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.",
+    "examplePrompts": [
+      "Turn off arrow-key navigation",
+      "Use a 1.6 m eye height",
+      "Make walking stop at walls\n\n# Example\n```ts\nawait snaptrude.core.camera.updateNavigationSettings({\neyeHeight: 1.6 / 0.254,\nisCollisionEnabled: true,\n})\n```"
+    ],
+    "argsType": "PluginCameraNavigationSettingsPatch",
+    "resultType": "PluginCameraNavigationSettings"
+  },
   {
     "path": "core.camera.zoomExtents",
     "namespace": "core.camera",
@@ -8115,6 +8189,232 @@
     "argsType": "string",
     "resultType": "PluginPresentationViewsUpdateSettingsResult"
   },
+  {
+    "path": "presentation.walkthroughs.cancelJob",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Cancel an export job. The recording stops and nothing is placed; a job that has already finished is returned unchanged. Write-gated.",
+    "examplePrompts": [
+      "Cancel the video export\n\n# Example\n```ts\nawait snaptrude.presentation.walkthroughs.cancelJob(jobId)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWalkthroughExportJob"
+  },
+  {
+    "path": "presentation.walkthroughs.capture",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Capture frames of a walkthrough as one contact-sheet image: a grid of views at evenly spaced moments (or at `options.timesInSeconds`), read left to right and top to bottom. The camera goes back to where it was afterwards. Switches from 2D plan view to 3D first.",
+    "examplePrompts": [
+      "Show me what the walkthrough looks like",
+      "Capture six frames of the fly-over\n\n# Example\n```ts\nconst { image } = await snaptrude.presentation.walkthroughs.capture(walkthroughId, {\ncount: 6,\n})\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWalkthroughCaptureResult"
+  },
+  {
+    "path": "presentation.walkthroughs.create",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Create a walkthrough from full keyframes: where the camera stands at each and how it looks there (ahead along the path, at a target, or in a fixed direction). A keyframe that follows the floor stands at the walkthrough's eye height above the floor, stair, terrain or ground at or below its `eye`, and the path between two such keyframes climbs stairs and ramps. The new walkthrough opens in the walkthrough dock. Write-gated; one undo step.",
+    "examplePrompts": [
+      "Make a walkthrough through these three viewpoints",
+      "Create a camera path that looks at the atrium the whole way\n\n# Example\n```ts\nconst walkthrough = await snaptrude.presentation.walkthroughs.create(\n[\n{ eye: { x: 0, y: 30, z: 80 }, look: { mode: \"target\", target: { x: 0, y: 10, z: 0 } } },\n{ eye: { x: 60, y: 30, z: 0 }, look: { mode: \"target\", target: { x: 0, y: 10, z: 0 } } },\n],\n{ name: \"Approach\", durationInSeconds: 10 },\n)\n```"
+    ],
+    "argsType": "PluginWalkthroughKeyframeInput[]",
+    "resultType": "PluginWalkthrough"
+  },
+  {
+    "path": "presentation.walkthroughs.createFromPoints",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Create a walkthrough that walks through points on the floor, the way the Walkthrough tool draws a route: the camera stands at eye height above the floor, stair, terrain or ground at each point, climbs stairs and ramps between them, and looks ahead along the path, or at `options.lookAt` the whole way. Write-gated; one undo step.",
+    "examplePrompts": [
+      "Walk from the entrance through the lobby to the stairs",
+      "Make a walkthrough that visits every room on this floor",
+      "Create a loop around the courtyard\n\n# Example\n```ts\nawait snaptrude.presentation.walkthroughs.createFromPoints(\n[{ x: 0, y: 0, z: 0 }, { x: 40, y: 0, z: 0 }, { x: 40, y: 0, z: 30 }],\n{ name: \"Ground floor tour\" },\n)\n```"
+    ],
+    "argsType": "Vec3Components[]",
+    "resultType": "PluginWalkthrough"
+  },
+  {
+    "path": "presentation.walkthroughs.createFromPreset",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Create a walkthrough from a camera move around a subject, as the Walkthrough button's menu does: `orbit` circles it facing its middle, `flyOver` passes above it looking ahead and down, `pushIn` and `pullBack` move toward and away from it, and `rise` cranes up from eye level. The subject is `options.subject`, else the selection, else the visible model without its terrain; the move is sized to fit it in view and starts on the side the camera is on. While the walkthrough is still a preset, {@linkcode PluginPresentationWalkthroughsApi.update} can change its distance, height and direction; editing a keyframe makes it ordinary. Write-gated; one undo step.",
+    "examplePrompts": [
+      "Orbit around the selected building",
+      "Make a drone fly-over of the site",
+      "Push in slowly toward the entrance",
+      "Crane up to reveal the whole campus\n\n# Example\n```ts\nawait snaptrude.presentation.walkthroughs.createFromPreset(\"orbit\", {\nsubject: [towerId],\nheightInDegrees: 35,\ndurationInSeconds: 20,\n})\n```"
+    ],
+    "argsType": "PluginWalkthroughPresetKind",
+    "resultType": "PluginWalkthrough"
+  },
+  {
+    "path": "presentation.walkthroughs.createKeyframe",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Add a keyframe to a walkthrough at `index` (0 to the keyframe count; default: the end). A preset walkthrough becomes ordinary. Write-gated; one undo step.",
+    "examplePrompts": [
+      "Add a stop in the kitchen after the second point\n\n# Example\n```ts\nawait snaptrude.presentation.walkthroughs.createKeyframe(\nwalkthroughId,\n{ eye: { x: 12, y: 0, z: 30 }, followsFloor: true, holdInSeconds: 2 },\n2,\n)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWalkthrough"
+  },
+  {
+    "path": "presentation.walkthroughs.delete",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Delete a walkthrough. Write-gated; one undo step.",
+    "examplePrompts": [
+      "Delete the old walkthrough\n\n# Example\n```ts\nawait snaptrude.presentation.walkthroughs.delete(walkthroughId)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "boolean"
+  },
+  {
+    "path": "presentation.walkthroughs.deleteKeyframe",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Remove a keyframe; the path then runs straight from the keyframe before it to the one after. Removing the last keyframe deletes the walkthrough. A preset walkthrough becomes ordinary. Write-gated; one undo step.",
+    "examplePrompts": [
+      "Remove the third stop from the walkthrough\n\n# Example\n```ts\nawait snaptrude.presentation.walkthroughs.deleteKeyframe(walkthroughId, keyframeId)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWalkthrough | null"
+  },
+  {
+    "path": "presentation.walkthroughs.export",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Record a walkthrough as a video and place it on the Present canvas, as an asynchronous job: this resolves at once with the queued job, and {@linkcode PluginPresentationWalkthroughsApi.getJob} reports it until it completes, fails or is cancelled. Recording plays the walkthrough in real time at the chosen size, so it takes about as long as the walkthrough plus the upload; the editor switches to Present mode to place the video, which keeps playing muted in a loop there. Only one export runs at a time. Write-gated.",
+    "examplePrompts": [
+      "Export the walkthrough as a video",
+      "Put a 1080p video of the orbit on a sheet\n\n# Example\n```ts\nconst walkthroughs = snaptrude.presentation.walkthroughs\nlet job = await walkthroughs.export(walkthroughId, { quality: \"1080p\" })\nwhile (job.status === \"queued\" || job.status === \"running\") {\nawait new Promise((resolve) => setTimeout(resolve, 2000))\njob = (await walkthroughs.getJob(job.jobId))!\n}\nconsole.log(job.result?.shapeId)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWalkthroughExportJob"
+  },
+  {
+    "path": "presentation.walkthroughs.get",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Get one walkthrough by id.",
+    "examplePrompts": [
+      "Show me the keyframes of the orbit walkthrough",
+      "How long does this walkthrough take?\n\n# Example\n```ts\nconst walkthrough = await snaptrude.presentation.walkthroughs.get(walkthroughId)\nconsole.log(walkthrough?.durationInSeconds)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWalkthrough | null"
+  },
+  {
+    "path": "presentation.walkthroughs.getJob",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Get an export job by id.",
+    "examplePrompts": [
+      "Is the video export done yet?\n\n# Example\n```ts\nconst job = await snaptrude.presentation.walkthroughs.getJob(jobId)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWalkthroughExportJob | null"
+  },
+  {
+    "path": "presentation.walkthroughs.getState",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Read the playback state: which walkthrough is playing or paused, and how far through it.",
+    "examplePrompts": [
+      "Is the walkthrough still playing?\n\n# Example\n```ts\nconst { status, timeInSeconds } = await snaptrude.presentation.walkthroughs.getState()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginWalkthroughPlaybackState"
+  },
+  {
+    "path": "presentation.walkthroughs.list",
+    "namespace": "presentation.walkthroughs",
+    "summary": "List the open project's walkthroughs, oldest first.",
+    "examplePrompts": [
+      "Which walkthroughs are there?",
+      "List the camera paths in this project\n\n# Example\n```ts\nconst { walkthroughs } = await snaptrude.presentation.walkthroughs.list()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginWalkthroughsListResult"
+  },
+  {
+    "path": "presentation.walkthroughs.listIssues",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Find places where a walkthrough's camera passes through the model: through anything walking would stop at, such as a wall, glazing, a column, a slab or a roof, which would show the inside of the geometry on screen. Doors, furniture and room masses don't count, as walking passes through them. Each issue gives the first moment and point of one pass. The camera itself does not move.",
+    "examplePrompts": [
+      "Does the walkthrough go through any walls?",
+      "Check the camera path for clashes and fix them\n\n# Example\n```ts\nconst { issues } = await snaptrude.presentation.walkthroughs.listIssues(walkthroughId)\nfor (const issue of issues) console.log(issue.timeInSeconds, issue.componentId)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWalkthroughListIssuesResult"
+  },
+  {
+    "path": "presentation.walkthroughs.listJobs",
+    "namespace": "presentation.walkthroughs",
+    "summary": "List export jobs, newest first: running ones and those that finished in the last 30 minutes.",
+    "examplePrompts": [
+      "Which video exports are running?\n\n# Example\n```ts\nconst { jobs } = await snaptrude.presentation.walkthroughs.listJobs()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginWalkthroughListJobsResult"
+  },
+  {
+    "path": "presentation.walkthroughs.reorderKeyframe",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Move a keyframe to position `index` in the walkthrough's order (the `presentation.sheets.reorder` convention). A preset walkthrough becomes ordinary. Write-gated; one undo step.",
+    "examplePrompts": [
+      "Visit the terrace before the living room\n\n# Example\n```ts\nawait snaptrude.presentation.walkthroughs.reorderKeyframe(walkthroughId, keyframeId, 0)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWalkthrough"
+  },
+  {
+    "path": "presentation.walkthroughs.sample",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Sample where the camera is and which way it looks at given moments of a walkthrough's playback, without moving the camera.",
+    "examplePrompts": [
+      "Where is the camera halfway through the walkthrough?",
+      "Check how high the camera flies over the roof\n\n# Example\n```ts\nconst walkthrough = await snaptrude.presentation.walkthroughs.get(walkthroughId)\nconst { samples } = await snaptrude.presentation.walkthroughs.sample(walkthroughId, [\n0,\nwalkthrough!.durationInSeconds / 2,\n])\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWalkthroughSampleResult"
+  },
+  {
+    "path": "presentation.walkthroughs.start",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Play a walkthrough in the viewport, from the start or `options.fromTimeInSeconds`. Arrow-key navigation pauses while it plays; {@linkcode PluginPresentationWalkthroughsApi.stop} puts the camera back where it was. Switches from 2D plan view to 3D first. Resolves once playback has started; a walkthrough that is already playing keeps playing.",
+    "examplePrompts": [
+      "Play the walkthrough",
+      "Show me the orbit\n\n# Example\n```ts\nawait snaptrude.presentation.walkthroughs.start(walkthroughId)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWalkthroughPlaybackState"
+  },
+  {
+    "path": "presentation.walkthroughs.stop",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Stop playback and put the camera back where it was before it started. A no-op when nothing is playing.",
+    "examplePrompts": [
+      "Stop the walkthrough\n\n# Example\n```ts\nawait snaptrude.presentation.walkthroughs.stop()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginWalkthroughPlaybackState"
+  },
+  {
+    "path": "presentation.walkthroughs.update",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Change a walkthrough: only the fields given change. Speed and duration are two ways to set one thing, so give at most one of them. `preset` changes a preset walkthrough's camera move and makes its keyframes again, keeping its duration; changing `isLoop` of a preset walkthrough makes it ordinary. Write-gated; one undo step.",
+    "examplePrompts": [
+      "Slow the walkthrough down to 30 seconds",
+      "Rename it to \"Evening approach\"",
+      "Make the orbit go the other way round and higher up\n\n# Example\n```ts\nawait snaptrude.presentation.walkthroughs.update(walkthroughId, {\ndurationInSeconds: 30,\nisRepeating: true,\n})\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWalkthrough"
+  },
+  {
+    "path": "presentation.walkthroughs.updateKeyframe",
+    "namespace": "presentation.walkthroughs",
+    "summary": "Change a keyframe: only the fields given change. A preset walkthrough becomes ordinary. Write-gated; one undo step.",
+    "examplePrompts": [
+      "Pause for three seconds at the second point",
+      "Make the last point look at the fireplace\n\n# Example\n```ts\nawait snaptrude.presentation.walkthroughs.updateKeyframe(walkthroughId, keyframeId, {\nlook: { mode: \"target\", target: { x: 5, y: 4, z: 10 } },\n})\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWalkthrough"
+  },
   {
     "path": "program.adjacency.compute",
     "namespace": "program.adjacency",