@zkmake/three-cameras 0.0.0 → 0.2.0

package/README.md

@@ -7,7 +7,13 @@ reads each one's position and projection live, and draws a camera's frustum in t
 
 Pick a camera and you control it: edit its position, rotation and lens by typing or scrubbing, look
 through it in place of the app's main view, copy its setup as code, and save views to fly back to.
-Keyframed camera moves with curve and graph editors are next.
+Animate cameras on a keyframe timeline: key a camera, retime and ease its keys, and play the move
+back in the running scene, shaping them in a graph editor and an ease curve editor, with the
+motion path drawn in the scene.
+
+It's one panel, anchored across the bottom of the screen: the camera list as the timeline's left
+sidebar, each camera's row beside its key lane. Collapsed, it's a small widget with the picked
+camera (its kind, name, and whether it's live or looked through); click it to expand.
 
 ```sh
 bun add -d @zkmake/three-cameras   # or npm i -D / yarn add -D / pnpm add -D
@@ -70,6 +76,50 @@ so a picture-in-picture inset or a render target keeps its own camera. The camer
 view's aspect for the frame and put back after, and the app's camera is left where it was. A banner
 shows what you're looking through, with a way back.
 
+## The timeline
+
+The timeline animates cameras with keyframes. Its left column is the camera list: each camera's row
+sits beside its lane, and a row opened into its controls stretches its lane to match.
+
+- **Key** the picked camera as it is now at the playhead, or double-click its lane to key it there.
+  A key holds its position, rotation and lens.
+- **Drag** a key to retime it (snaps to 0.1 s; Shift for free). Click one to inspect it: its time,
+  its **ease** into the next key (ease in-out, linear, ease in, ease out, or hold), **Update** to
+  re-key it from the camera as it is now, and **Delete**.
+- **Play**, pause (Space), scrub the ruler, loop, and set the length. The camera travels a smooth
+  curve through its keys, turns evenly between them, and its lens eases too.
+- Once you play or scrub, tracked cameras are held to their tracks right before each frame, so a
+  track wins over an app that moves the camera itself. Edit a camera and it's let go, so the edit
+  sticks until you key it; **stop** lets every camera go back to the app.
+- Look through a camera while it plays to see the shot. Tracks are kept in localStorage, by camera
+  name. Pass `timeline: false` for the camera list alone.
+
+### Shaping a move
+
+- **Ease curve**: the key inspector draws the move from the picked key to the next as a curve of
+  progress over time, with two handles (CSS `cubic-bezier` terms). Drag a handle to reshape it: a
+  preset becomes a custom curve from the preset's shape. Handles go above 1 or below 0 for
+  overshoot and anticipation.
+- **Graph**: switch the timeline to Graph for the picked camera's channels over time: position x,
+  y, z, rotation x, y, z (degrees), fov or zoom, near and far, drawn as the track plays them. Drag
+  a key's dot up or down to change that value (Shift for fine), or sideways to retime the key. Click
+  between keys to pick that segment's ease; double-click to add a key. Channels are stretched to
+  their own ranges; "values" puts them on one scale.
+
+### Motion paths in the scene
+
+A camera that moves shows its path in the scene by itself, while it moves (cameras in the scene;
+your own view camera is left out):
+
+- **Keyed** cameras show their track, an amber curve with a white dot per key. **Drag a dot** in the
+  scene to move that key: it slides on a plane facing you, Shift for straight up or down. The path
+  and the move reshape as you drag, and the press doesn't reach orbit controls.
+- **App-driven** cameras (moved by your code, not keys) show where they've been over the last 8
+  seconds, a light blue line. Your code drives that move, so it can't be dragged; **Bake to keys**
+  in the camera's controls turns it into keys (one where the path bends, linear timing), and it's a
+  track to edit like any other. Played, the track takes over from the app.
+- The path toggle on a camera's row shows or hides its path by hand.
+
 ## How it finds cameras
 
 - **The scene graph:** anything with `isCamera` under `scene`. A `CubeCamera` is one row; its six face
@@ -83,25 +133,28 @@ panel's wrapper stays in place and just passes through.
 
 ## Options
 
-| Option             | Default                             | What it does                                                                      |
-| ------------------ | ----------------------------------- | --------------------------------------------------------------------------------- |
-| `scene`            | required                            | Where to look for cameras, and where frustum helpers go                           |
-| `renderer`         | none                                | Watched for the cameras it draws with; without it nothing is "live"               |
-| `cameras`          | `[]`                                | `{ name, camera }` to list whether or not the scene holds them yet                |
-| `invalidate`       | none                                | Ask for frames after an edit, a toggle, or during a move (render-on-demand loops) |
-| `store`            | localStorage, by `storageKey`       | Where saved views live: `{ load(), save(views) }`                                 |
-| `storageKey`       | `"three-cameras"`                   | localStorage prefix for the dock and compact state; `null` for none               |
-| `defaultPlacement` | `{ edge: "right", align: "start" }` | Where it docks on a first visit                                                   |
-| `theme`            | `"system"`                          | `"dark"`, `"light"` or `"system"`                                                 |
-| `compact`          | `false`                             | Start compact, showing the brand row and the count                                |
-| `container`        | `document.body`                     | Where to mount                                                                    |
+| Option             | Default                             | What it does                                                                                     |
+| ------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `scene`            | required                            | Where to look for cameras, and where frustum helpers go                                          |
+| `renderer`         | none                                | Watched for the cameras it draws with; without it nothing is "live"                              |
+| `cameras`          | `[]`                                | `{ name, camera }` to list whether or not the scene holds them yet                               |
+| `invalidate`       | none                                | Ask for frames after an edit, a toggle, or during a move (render-on-demand loops)                |
+| `store`            | localStorage, by `storageKey`       | Where saved views live: `{ load(), save(views) }`                                                |
+| `trackStore`       | localStorage, by `storageKey`       | Where keyframe tracks live: `{ load(), save({ duration, tracks }) }`                             |
+| `timeline`         | `true`                              | The timeline, with the camera list as its sidebar, across the bottom; `false` for the list alone |
+| `storageKey`       | `"three-cameras"`                   | localStorage prefix for the dock and compact state; `null` for none                              |
+| `defaultPlacement` | `{ edge: "right", align: "start" }` | Where the list alone docks on a first visit (with the timeline it spans the bottom)              |
+| `theme`            | `"system"`                          | `"dark"`, `"light"` or `"system"`                                                                |
+| `compact`          | `false`                             | Start compact, showing the brand row and the count                                               |
+| `container`        | `document.body`                     | Where to mount                                                                                   |
 
 ## The engine
 
 `CameraLab` is the panel's engine, with no DOM, for scripting or a panel of your own:
 
 ```ts
-import { CameraLab } from "@zkmake/three-cameras";
+import { CameraLab, writeChannel } from "@zkmake/three-cameras";
+import { Vector3 } from "three";
 import { createCameraPanel } from "@zkmake/three-cameras/ui";
 
 const lab = new CameraLab({ scene, renderer });
@@ -115,13 +168,25 @@ lab.setHelper("dolly", true);
 const home = lab.saveView("dolly", "home");
 lab.goToView("dolly", home.id, { duration: 800 });
 
+lab.addKey("dolly", { time: 0 }); // the camera as it is now
+lab.addKey("dolly", { time: 4, ease: "ease-out" });
+lab.play(); // pause(), seek(2), stop(), setLoop(false), setDuration(12)
+
+const [first] = lab.keys("dolly");
+lab.updateKey("dolly", first.id, { bezier: [0.3, 1.4, 0.6, 1] }); // overshoot
+lab.updateKey("dolly", first.id, { pose: writeChannel(first.pose, "fov", 30) });
+lab.setTrail("dolly", true); // or false, or "auto" (the default)
+lab.bakeMotion("dolly"); // its recorded move as keys
+lab.moveKeyTo("dolly", home.id, new Vector3(0, 3, 8)); // a key to a world point
+
 tab.append(createCameraPanel(lab).element); // the bare panel, for a host with its own tabs
 ```
 
 ## The dev-panel frame
 
-It docks in three-meter's `mountDevPanel`, so it drags, snaps to an edge, compacts and dims exactly
-like the three-meter HUD and the three-textures panel, with its brand label on top.
+It sits in three-meter's `mountDevPanel`, so it compacts and dims like the three-meter HUD and the
+three-textures panel, with its brand label on top. With the timeline it's anchored across the
+bottom (no drag grip); the list alone drags and snaps to an edge like the others.
 
 ## License