@zkmake/three-cameras 0.2.6 → 0.2.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +54 -34
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -33,6 +33,9 @@ const panel = mountCameraPanel({ scene, renderer });
|
|
|
33
33
|
// later: panel.dispose()
|
|
34
34
|
```
|
|
35
35
|
|
|
36
|
+
The handle has the engine (`panel.lab`, below), `element`, `setCompact(compact)` and
|
|
37
|
+
`setTheme(mode)`.
|
|
38
|
+
|
|
36
39
|
## React Three Fiber
|
|
37
40
|
|
|
38
41
|
```tsx
|
|
@@ -44,17 +47,20 @@ import { CameraPanel } from "@zkmake/three-cameras/react";
|
|
|
44
47
|
```
|
|
45
48
|
|
|
46
49
|
It reads the scene and renderer from the canvas, so the canvas's camera shows as live, and asks for
|
|
47
|
-
a frame after a frustum toggles, so `frameloop="demand"` works.
|
|
50
|
+
a frame after a frustum toggles, so `frameloop="demand"` works. Its props are the options (below)
|
|
51
|
+
but `scene`, `renderer` and `invalidate`, plus `onReady(lab)` for the engine. `theme` follows its
|
|
52
|
+
prop; the rest are read on mount (remount with a new `key` to change them).
|
|
48
53
|
|
|
49
54
|
## What each row shows
|
|
50
55
|
|
|
51
|
-
| Part | What it is
|
|
52
|
-
| ------------- |
|
|
53
|
-
| icon | The kind: perspective, orthographic, array or cube. Green while the camera draws.
|
|
54
|
-
| live · 60 fps | It drew a frame in the last half second, and how many in the last second
|
|
55
|
-
| second line | fov, near–far and aspect (perspective), or zoom and near–far (orthographic); "not in scene"
|
|
56
|
-
|
|
|
57
|
-
|
|
|
56
|
+
| Part | What it is |
|
|
57
|
+
| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
58
|
+
| icon | The kind: perspective, orthographic, array or cube. Green while the camera draws. |
|
|
59
|
+
| live · 60 fps | It drew a frame in the last half second, and how many in the last second |
|
|
60
|
+
| second line | fov, near–far and aspect (perspective), or zoom and near–far (orthographic); its key count, or "moving"; "not in scene" |
|
|
61
|
+
| path | With the timeline: show or hide its motion path in the scene (see below) |
|
|
62
|
+
| look through | Show the main view through it (see below) |
|
|
63
|
+
| frustum | Draw its view volume in the scene. It follows the camera, and hides while you look through it |
|
|
58
64
|
|
|
59
65
|
Rows are named by the `cameras` option, else the camera's `name`, else its kind (`perspective camera
|
|
60
66
|
2`). Name your cameras and the panel reads better.
|
|
@@ -74,7 +80,8 @@ Pick a row (click its name) and it opens into the camera's controls:
|
|
|
74
80
|
**Look through** swaps a camera into the app's main view: the view drawing the most of the screen,
|
|
75
81
|
so a picture-in-picture inset or a render target keeps its own camera. The camera is fitted to that
|
|
76
82
|
view's aspect for the frame and put back after, and the app's camera is left where it was. A banner
|
|
77
|
-
shows what you're looking through, with a way back
|
|
83
|
+
shows what you're looking through, with a way back; its row reads "viewing", and the app camera's
|
|
84
|
+
"replaced".
|
|
78
85
|
|
|
79
86
|
## The timeline
|
|
80
87
|
|
|
@@ -84,10 +91,11 @@ sits beside its lane, and a row opened into its controls stretches its lane to m
|
|
|
84
91
|
- **Key** the picked camera as it is now at the playhead, or double-click its lane to key it there.
|
|
85
92
|
A key holds its position, rotation and lens.
|
|
86
93
|
- **Drag** a key to retime it (snaps to 0.1 s; Shift for free). Click one to inspect it: its time,
|
|
87
|
-
its **ease** into the next key (ease in-out, linear, ease in, ease out, or
|
|
88
|
-
re-key it from the camera as it is now, and **Delete
|
|
94
|
+
its **ease** into the next key (ease in-out, linear, ease in, ease out, hold, or a custom curve),
|
|
95
|
+
**Update** to re-key it from the camera as it is now, and **Delete** (or the Delete key).
|
|
89
96
|
- **Play**, pause (Space), scrub the ruler, loop, and set the length. The camera travels a smooth
|
|
90
|
-
curve through its keys, turns evenly between them, and its lens eases too.
|
|
97
|
+
curve through its keys, turns evenly between them, and its lens eases too. Playing steps on the
|
|
98
|
+
renderer's frames, so it needs `renderer`.
|
|
91
99
|
- Once you play or scrub, tracked cameras are held to their tracks right before each frame, so a
|
|
92
100
|
track wins over an app that moves the camera itself. Edit a camera and it's let go, so the edit
|
|
93
101
|
sticks until you key it; **stop** lets every camera go back to the app.
|
|
@@ -101,10 +109,11 @@ sits beside its lane, and a row opened into its controls stretches its lane to m
|
|
|
101
109
|
preset becomes a custom curve from the preset's shape. Handles go above 1 or below 0 for
|
|
102
110
|
overshoot and anticipation.
|
|
103
111
|
- **Graph**: switch the timeline to Graph for the picked camera's channels over time: position x,
|
|
104
|
-
y, z, rotation x, y, z (degrees), fov or zoom, near and far, drawn as the track plays them
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
112
|
+
y, z, rotation x, y, z (degrees), fov or zoom, near and far, drawn as the track plays them
|
|
113
|
+
(position and fov at first; click a channel's chip to show or hide it). Drag a key's dot up or
|
|
114
|
+
down to change that value (Shift for fine), or sideways to retime the key. Click between keys to
|
|
115
|
+
pick that segment's ease; double-click to add a key. Channels are stretched to their own ranges;
|
|
116
|
+
"values" puts them on one scale.
|
|
108
117
|
|
|
109
118
|
### Motion paths in the scene
|
|
110
119
|
|
|
@@ -133,20 +142,20 @@ panel's wrapper stays in place and just passes through.
|
|
|
133
142
|
|
|
134
143
|
## Options
|
|
135
144
|
|
|
136
|
-
| Option | Default | What it does
|
|
137
|
-
| ------------------ | ----------------------------------- |
|
|
138
|
-
| `scene` | required | Where to look for cameras, and where frustum helpers go
|
|
139
|
-
| `renderer` | none | Watched for the cameras it draws with; without it nothing is "live"
|
|
140
|
-
| `cameras` | `[]` | `{ name, camera }` to list whether or not the scene holds them yet
|
|
141
|
-
| `invalidate` | none | Ask for frames after an edit, a toggle, or during a move (render-on-demand loops)
|
|
142
|
-
| `store` | localStorage, by `storageKey` | Where saved views live: `{ load(), save(views) }`
|
|
143
|
-
| `trackStore` | localStorage, by `storageKey` | Where keyframe tracks live: `{ load(), save({ duration, tracks }) }`
|
|
144
|
-
| `timeline` | `true` | The timeline, with the camera list as its sidebar, across the bottom; `false` for the list alone
|
|
145
|
-
| `storageKey` | `"three-cameras"` | localStorage prefix for the dock
|
|
146
|
-
| `defaultPlacement` | `{ edge: "right", align: "start" }` | Where the list alone docks on a first visit (with the timeline it spans the bottom)
|
|
147
|
-
| `theme` | `"system"` | `"dark"`, `"light"` or `"system"`
|
|
148
|
-
| `compact` | `false` | Start
|
|
149
|
-
| `container` | `document.body` | Where to mount
|
|
145
|
+
| Option | Default | What it does |
|
|
146
|
+
| ------------------ | ----------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
147
|
+
| `scene` | required | Where to look for cameras, and where frustum helpers go |
|
|
148
|
+
| `renderer` | none | Watched for the cameras it draws with; without it nothing is "live", and look through and play don't run |
|
|
149
|
+
| `cameras` | `[]` | `{ name, camera }` to list whether or not the scene holds them yet |
|
|
150
|
+
| `invalidate` | none | Ask for frames after an edit, a toggle, or during a move (render-on-demand loops) |
|
|
151
|
+
| `store` | localStorage, by `storageKey` | Where saved views live: `{ load(), save(views) }` |
|
|
152
|
+
| `trackStore` | localStorage, by `storageKey` | Where keyframe tracks live: `{ load(), save({ duration, tracks }) }` |
|
|
153
|
+
| `timeline` | `true` | The timeline, with the camera list as its sidebar, across the bottom; `false` for the list alone |
|
|
154
|
+
| `storageKey` | `"three-cameras"` | localStorage prefix for the dock, compact state, saved views and tracks; `null` keeps them for this page |
|
|
155
|
+
| `defaultPlacement` | `{ edge: "right", align: "start" }` | Where the list alone docks on a first visit (with the timeline it spans the bottom) |
|
|
156
|
+
| `theme` | `"system"` | `"dark"`, `"light"` or `"system"` |
|
|
157
|
+
| `compact` | `false` | Start collapsed to the small widget. A choice stored under `storageKey` wins |
|
|
158
|
+
| `container` | `document.body` | Where to mount |
|
|
150
159
|
|
|
151
160
|
## The engine
|
|
152
161
|
|
|
@@ -168,26 +177,37 @@ lab.setHelper("dolly", true);
|
|
|
168
177
|
const home = lab.saveView("dolly", "home");
|
|
169
178
|
lab.goToView("dolly", home.id, { duration: 800 });
|
|
170
179
|
|
|
171
|
-
lab.addKey("dolly", { time: 0 }); // the camera as it is now
|
|
180
|
+
const first = lab.addKey("dolly", { time: 0 }); // the camera as it is now
|
|
172
181
|
lab.addKey("dolly", { time: 4, ease: "ease-out" });
|
|
173
182
|
lab.play(); // pause(), seek(2), stop(), setLoop(false), setDuration(12)
|
|
174
183
|
|
|
175
|
-
const [first] = lab.keys("dolly");
|
|
176
184
|
lab.updateKey("dolly", first.id, { bezier: [0.3, 1.4, 0.6, 1] }); // overshoot
|
|
177
185
|
lab.updateKey("dolly", first.id, { pose: writeChannel(first.pose, "fov", 30) });
|
|
186
|
+
lab.moveKeyTo("dolly", first.id, new Vector3(0, 3, 8)); // a key to a world point
|
|
178
187
|
lab.setTrail("dolly", true); // or false, or "auto" (the default)
|
|
179
|
-
lab.bakeMotion("dolly"); // its recorded move as keys
|
|
180
|
-
lab.moveKeyTo("dolly", home.id, new Vector3(0, 3, 8)); // a key to a world point
|
|
188
|
+
lab.bakeMotion("dolly"); // its recorded move as keys, replacing its track
|
|
181
189
|
|
|
182
190
|
tab.append(createCameraPanel(lab).element); // the bare panel, for a host with its own tabs
|
|
183
191
|
```
|
|
184
192
|
|
|
193
|
+
Also on the lab: `select(id)` / `selected` (the camera the panels act on), `subscribe(listener)`,
|
|
194
|
+
`keys`, `deleteKey`, `views`, `deleteView`, `motion`, `keyHandles`, `viewTransform`, `refresh` and
|
|
195
|
+
`dispose`. The rest of the timeline is in `/ui` too: `createTimelinePanel(lab, { sidebar })` takes
|
|
196
|
+
a `createCameraPanel(lab, { paths: true })` as its left column, and `createPathEditor(lab, canvas)`
|
|
197
|
+
makes key dots draggable on the renderer's canvas. The core also exports the pieces under the
|
|
198
|
+
engine: `findCameras`, `capturePose` / `applyPose` / `blendPoses` / `poseToCode`, `sampleTrack`,
|
|
199
|
+
`applyEase`, `cubicBezier`, and the graph's channels (`readChannel`, `writeChannel`,
|
|
200
|
+
`sampleChannel`).
|
|
201
|
+
|
|
185
202
|
## The dev-panel frame
|
|
186
203
|
|
|
187
204
|
It sits in three-meter's `mountDevPanel`, so it compacts and dims like the three-meter HUD and the
|
|
188
205
|
three-textures panel, with its brand label on top. With the timeline it's anchored across the
|
|
189
206
|
bottom (no drag grip); the list alone drags and snaps to an edge like the others.
|
|
190
207
|
|
|
208
|
+
[three-devtools](../three-devtools) mounts it behind `?debug` with the rest of the dev tools:
|
|
209
|
+
`panels: { cameras: () => import("@zkmake/three-cameras/ui") }`.
|
|
210
|
+
|
|
191
211
|
## License
|
|
192
212
|
|
|
193
213
|
MIT
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zkmake/three-cameras",
|
|
3
|
-
"version": "0.2.
|
|
4
|
-
"description": "A dev panel for the cameras in a three.js scene: every camera, the ones rendering right now, their settings live, and
|
|
3
|
+
"version": "0.2.7",
|
|
4
|
+
"description": "A dev panel for the cameras in a three.js scene: every camera, the ones rendering right now, their settings live, frustum helpers, and a keyframe timeline with motion paths. Vanilla three and React Three Fiber.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"camera",
|
|
7
7
|
"cameras",
|
|
@@ -45,7 +45,7 @@
|
|
|
45
45
|
"typecheck": "tsc"
|
|
46
46
|
},
|
|
47
47
|
"dependencies": {
|
|
48
|
-
"@zkmake/three-meter": "^0.13.
|
|
48
|
+
"@zkmake/three-meter": "^0.13.3"
|
|
49
49
|
},
|
|
50
50
|
"devDependencies": {
|
|
51
51
|
"@arethetypeswrong/core": "catalog:",
|