@algorisys/tinyfly 0.100.0 → 0.101.0
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 +5 -5
- package/bin/tinyfly.mjs +7 -3
- package/docs/character-appearance.md +26 -0
- package/docs/editor-guide.md +1 -1
- package/docs/examples.md +1 -1
- package/docs/getting-started.md +1 -1
- package/docs/gsap-compat.md +1 -1
- package/docs/llm-guide.md +14 -2
- package/docs/maps.md +2 -2
- package/docs/scene-3d.md +23 -4
- package/docs/teaching.md +1 -1
- package/docs/video-rendering.md +154 -0
- package/lib/addons/adapters.js +387 -333
- package/lib/addons/characters.js +4467 -4448
- package/lib/addons/load-scene-oWNsYYC1.js +372 -0
- package/lib/addons/scene-3d-webgl.js +1 -1
- package/lib/addons/scene-3d.js +323 -277
- package/lib/addons/shading-0lPgnXmD.js +96 -0
- package/lib/browser/tinyfly-scene-3d.iife.js +2 -2
- package/lib/browser/tinyfly.iife.js +14 -14
- package/lib/browser/tinyfly.js +5888 -5511
- package/lib/browser/tinyfly.umd.js +14 -14
- package/lib/engine/tinyfly-engine.js +1389 -1031
- package/lib/engine/tinyfly-engine.umd.cjs +2 -2
- package/lib/headless/headless.js +39 -0
- package/lib/types/adapters/canvas/impossible.d.ts +15 -0
- package/lib/types/adapters/canvas/index.d.ts +3 -0
- package/lib/types/adapters/canvas/nested-zoom.d.ts +40 -0
- package/lib/types/adapters/canvas/zoom-blur.d.ts +49 -0
- package/lib/types/characters/character.d.ts +23 -3
- package/lib/types/characters/head/face.d.ts +19 -2
- package/lib/types/engine/authoring/beat-loop.d.ts +46 -0
- package/lib/types/engine/authoring/curve.d.ts +26 -0
- package/lib/types/engine/authoring/index.d.ts +3 -0
- package/lib/types/engine/authoring/periodic.d.ts +89 -0
- package/lib/types/engine/path/goo.d.ts +103 -0
- package/lib/types/engine/path/impossible.d.ts +92 -0
- package/lib/types/engine/path/index.d.ts +6 -0
- package/lib/types/engine/path/similarity.d.ts +48 -0
- package/lib/types/headless/index.d.ts +1 -0
- package/lib/types/headless/loop-audio.d.ts +21 -0
- package/lib/types/headless/node-audio.d.ts +20 -0
- package/lib/types/headless/video-scene.d.ts +9 -0
- package/lib/types/scene-3d/camera.d.ts +11 -2
- package/lib/types/scene-3d/geometry/mesh.d.ts +2 -0
- package/lib/types/scene-3d/geometry/primitives.d.ts +7 -0
- package/lib/types/scene-3d/impossible-3d.d.ts +29 -0
- package/lib/types/scene-3d/index.d.ts +4 -3
- package/lib/types/scene-3d/resolve-scene.d.ts +13 -1
- package/lib/types/scene-3d/scene-3d-adapter.d.ts +2 -0
- package/lib/types/scene-3d/scene-types.d.ts +29 -4
- package/lib/types/scene-3d/shading.d.ts +2 -0
- package/llms-full.txt +226 -15
- package/llms.txt +29 -29
- package/package.json +1 -1
- package/skills/tinyfly/SKILL.md +7 -0
- package/lib/addons/load-scene-CQvcFWGJ.js +0 -331
- package/lib/addons/shading-o5T_v9DT.js +0 -89
package/README.md
CHANGED
|
@@ -97,7 +97,7 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
|
|
|
97
97
|
- **Camera** - Animate a pan/zoom/rotate over the whole stage (a reserved `Camera` layer driven by ordinary tracks). One-click add, a **🎥 Camera inspector** (Pan/Zoom/Rotation keyframed at the playhead), on-stage **✋ Pan** dragging, and a dedicated 🎥 lane at the top of the timeline; applies in every preview, export, and embed. Ready-made Push In / Pan Across / Orbit Reveal samples
|
|
98
98
|
- **Polygon & star shapes** - ⬡ Polygon and ★ Star elements are parametric paths — edit sides / points / inner ratio in Properties and they regenerate and rescale; they render and export like any path
|
|
99
99
|
- **Pen tool** - ✒️ Draw custom bezier paths: click for corners, click-drag for curves (Alt for a cusp), drag existing anchors/handles to adjust, snap points to grid/guides, click the first point or Enter to finish
|
|
100
|
-
- **Loop check** - `tinyfly video scene.mjs --loop-check` renders five frames and says whether a video loops: whether the frame at the duration matches the first, and whether the last → first seam looks like any other step (exit 1 when it does not). `--frames 0,79,88` renders stills at chosen frames. See [docs/video-rendering.md](docs/video-rendering.md#loops)
|
|
100
|
+
- **Loop check** - `tinyfly video scene.mjs --loop-check` renders five frames and says whether a video loops: whether the frame at the duration matches the first, and whether the last → first seam looks like any other step (exit 1 when it does not). `--frames 0,79,88` renders stills at chosen frames. See [docs/video-rendering.md](docs/video-rendering.md#loops) A scene with `loop: true` is checked before it renders, its frames carry the `period`, and periodic helpers repeat exactly over it: `wobble`, `loopEase`, `loopNoise` (seeded noise round a circle), `torusNoise`; `nestedZoom` draws a Droste picture (a `similarityAbout` step, one level per loop, only the visible levels); `applyZoomBlur` and `drawDiveLines` for dives; the Penrose triangle and stairs as boxes that line up from one viewpoint (`penroseTriangle`, `penroseStairs`, `penroseTriangle3D`); goo as geometry: metaballs that merge and split (`metaballContours`), drips (`dripPath`), bubbles that grow, wobble and pop (`bubblePath`, `bubblePop`) and area-keeping squash and stretch (`squashStretch`)
|
|
101
101
|
- **Bloom** - `bloom: true` on a video scene adds a deterministic glow around bright things (bright pass, blur, add; no `ctx.filter`), and 3D materials take `emissive` light that shines in the dark and feeds it. `applyBloom(ctx)` works on any 2D canvas. See [docs/video-rendering.md](docs/video-rendering.md#bloom)
|
|
102
102
|
- **Light trails** - `trailSamples` + `drawTrail` draw comets and light streaks on any 2D canvas: a tapering, fading band with a round head, smooth at any speed, and deterministic (the trail is where the thing was, asked of the timeline, not a frame history). 3D scenes get `line` and `trail` objects whose segments sort by depth among the meshes. See [docs/video-rendering.md](docs/video-rendering.md#light-trails) and [docs/scene-3d.md](docs/scene-3d.md#lines-and-trails)
|
|
103
103
|
- **3D scenes** - `@algorisys/tinyfly/scene-3d`: cameras, lights, meshes (box, sphere, cylinder, cone, torus, floor, any SVG path extruded) and props from the catalog (also from the editor's 3D Scene palette) as JSON in metres, animated by ordinary tracks (`stage/box`), cut between cameras with one keyframe, drawn on a plain canvas with flat, smooth or toon shading, ink outlines and fog: in the browser, in Workers, and to MP4 in Node. Characters stand in scenes and dance, seen by any camera, in their pen looks (clean, pencil) or as solid figures (`characterObjects`); props (cars, houses, trees, animals, birds) stand in them by preset name (`propObjects`), sorted a column at a time so figures walk round them rightly, and lit by the scene's lights (a sunset, a night with lit windows). Both are scripted in world metres (`propScript3D`, `characterScript3D`): drive or walk to a point or along a path, wheels and feet keeping pace with the ground. In the editor, a 🧊 3D Scene element builds them without code: add shapes, characters and lights, key them, dance from the playhead, cut between cameras. No WebGL needed (about 7 KB gzipped, its own entry and CDN script); for big or tangled scenes the optional WebGL2 renderer (`@algorisys/tinyfly/scene-3d/webgl`) adds a depth buffer and light per pixel. See [docs/scene-3d.md](docs/scene-3d.md)
|
|
@@ -237,7 +237,7 @@ GSAP-shaped functions at the top level. Teaching embeds are included: add
|
|
|
237
237
|
itself.
|
|
238
238
|
|
|
239
239
|
```html
|
|
240
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
240
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly.iife.js"></script>
|
|
241
241
|
<script>
|
|
242
242
|
tinyfly.to('.box', { x: 200, rotate: 90, duration: 1, ease: 'power2.out' })
|
|
243
243
|
|
|
@@ -273,7 +273,7 @@ A teaching figure needs no code at all:
|
|
|
273
273
|
<script type="application/json" data-tinyfly-timeline>{ …timeline JSON with markers… }</script>
|
|
274
274
|
<figcaption>Appending to a full slice</figcaption>
|
|
275
275
|
</figure>
|
|
276
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
276
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
|
|
277
277
|
```
|
|
278
278
|
|
|
279
279
|
See [Teaching Animations](docs/teaching.md).
|
|
@@ -372,7 +372,7 @@ Without a build step, the player bundle puts the same functions on a `tinyfly` g
|
|
|
372
372
|
<div data-tinyfly="box" style="width: 60px; height: 60px; background: #4a9eff;"></div>
|
|
373
373
|
</div>
|
|
374
374
|
|
|
375
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
375
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly-player.iife.js"></script>
|
|
376
376
|
<script>
|
|
377
377
|
tinyfly.play('#animation', './animation.json', { loop: -1 })
|
|
378
378
|
</script>
|
|
@@ -481,7 +481,7 @@ Or skip the code entirely with declarative embeds (see [Teaching Animations](doc
|
|
|
481
481
|
<svg viewBox="0 0 720 200">…</svg>
|
|
482
482
|
<script type="application/json" data-tinyfly-timeline>{ …timeline JSON… }</script>
|
|
483
483
|
</figure>
|
|
484
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
484
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
|
|
485
485
|
```
|
|
486
486
|
|
|
487
487
|
### Audio / Video Sync
|
package/bin/tinyfly.mjs
CHANGED
|
@@ -190,15 +190,19 @@ async function video() {
|
|
|
190
190
|
if (vttFile) writeFileSync(vttFile, headless.toWebVTT(cues))
|
|
191
191
|
console.error(`captions: ${cues.length} cue(s)`)
|
|
192
192
|
}
|
|
193
|
-
if (loopCheck) {
|
|
193
|
+
if (loopCheck || (scene.loop && !stillsDir)) {
|
|
194
|
+
// A scene that says it loops is checked before any frame is encoded.
|
|
194
195
|
const report = await headless.checkLoop(scene, { baseDir, scale, fps })
|
|
195
196
|
const db = (value) => (Number.isFinite(value) ? `${value.toFixed(2)} dB` : 'identical')
|
|
196
197
|
console.error(`frame at the duration vs the first: ${db(report.closure)}`)
|
|
197
198
|
console.error(`last → first (the seam): ${db(report.seam)}`)
|
|
198
199
|
console.error(`ordinary steps: ${db(report.steps[0])}, ${db(report.steps[1])}`)
|
|
199
200
|
console.error(`${report.loops ? '✓' : '✗'} ${report.verdict}`)
|
|
200
|
-
if (!report.loops)
|
|
201
|
-
|
|
201
|
+
if (!report.loops) {
|
|
202
|
+
if (!loopCheck) console.error('the scene has `loop: true`; fix the motion (or drop the flag) and render again')
|
|
203
|
+
process.exit(1)
|
|
204
|
+
}
|
|
205
|
+
if (loopCheck) return
|
|
202
206
|
}
|
|
203
207
|
if (stillsDir) {
|
|
204
208
|
// Stills at chosen frames or times, else one per marker step.
|
|
@@ -293,6 +293,32 @@ tracks animate them): `blush` (rosy cheeks, with hatch lines past 0.5),
|
|
|
293
293
|
`tears` (a drop under each eye, running down past 0.6) and `sweat` (a bead at
|
|
294
294
|
the temple).
|
|
295
295
|
|
|
296
|
+
## Close-ups
|
|
297
|
+
|
|
298
|
+
For a face filling the frame there are three more pose fields and a bigger
|
|
299
|
+
drawing:
|
|
300
|
+
|
|
301
|
+
- `pupil` (1 the usual size): bigger for excitement or a dive into it,
|
|
302
|
+
smaller for fear. `lid` (0..1) lowers the upper lids over the eye (sleepy,
|
|
303
|
+
suspicious, bored). `bulge` (0..1) pops the eyes out of the head, whites and
|
|
304
|
+
all. `scared`, `afraid`, `sleepy`, `suspicious` and `excited` use them.
|
|
305
|
+
- `face: { nose: true }` adds a small nose; `face: { teeth, tongue }` are
|
|
306
|
+
above.
|
|
307
|
+
- `drawCharacterHead(ctx, who, pose, { x, y, radius, time })` draws just the
|
|
308
|
+
head (hair, hat, glasses, ears, the face), its centre at `x`, `y` and its
|
|
309
|
+
radius `radius` px, in the character's look with the line weight scaled to
|
|
310
|
+
the size. The pose turns and nods it and sets the face.
|
|
311
|
+
- `face: { inPupil(ctx, pupil) }` draws inside each pupil, the context
|
|
312
|
+
clipped to its circle on screen (`{ x, y, r, side }`): another scene, or the
|
|
313
|
+
same head again for a Droste face:
|
|
314
|
+
|
|
315
|
+
```js
|
|
316
|
+
function head(ctx, x, y, r, depth = 0) {
|
|
317
|
+
const who = character({ hair: 'spiky', face: { nose: true, inPupil: depth < 4 ? (c, p) => head(c, p.x, p.y, p.r, depth + 1) : undefined } })
|
|
318
|
+
drawCharacterHead(ctx, who, humanPose({ bulge: 0.9, pupil: 1.5 }), { x, y, radius: r })
|
|
319
|
+
}
|
|
320
|
+
```
|
|
321
|
+
|
|
296
322
|
## Everyday actions, held items and meeting hands
|
|
297
323
|
|
|
298
324
|
The motion and everyday-life sheets add poses to `HUMAN_POSES`: `sleep`,
|
package/docs/editor-guide.md
CHANGED
|
@@ -1128,7 +1128,7 @@ The dialog shows the generated HTML/JavaScript code with a **Copy Code** button.
|
|
|
1128
1128
|
**Steps to embed:**
|
|
1129
1129
|
1. Build the player: `npm run build:player`
|
|
1130
1130
|
2. Copy `lib/player/tinyfly-player.iife.js` to your project (or load
|
|
1131
|
-
`https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
1131
|
+
`https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly-player.iife.js`
|
|
1132
1132
|
instead; see [Deployment](DEPLOYMENT.md))
|
|
1133
1133
|
3. Copy the generated code into your HTML
|
|
1134
1134
|
4. Adjust the script `src` path if needed
|
package/docs/examples.md
CHANGED
|
@@ -694,7 +694,7 @@ For simple website embedding without a build system.
|
|
|
694
694
|
</html>
|
|
695
695
|
```
|
|
696
696
|
|
|
697
|
-
Build the player with `npm run build:player` to generate `lib/player/tinyfly-player.iife.js`, or load it from the CDN: `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
697
|
+
Build the player with `npm run build:player` to generate `lib/player/tinyfly-player.iife.js`, or load it from the CDN: `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly-player.iife.js`.
|
|
698
698
|
|
|
699
699
|
---
|
|
700
700
|
|
package/docs/getting-started.md
CHANGED
|
@@ -185,7 +185,7 @@ with a GSAP-style call (durations are in seconds here):
|
|
|
185
185
|
```html
|
|
186
186
|
<div class="box" style="width:60px;height:60px;background:#4a9eff"></div>
|
|
187
187
|
|
|
188
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
188
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly.iife.js"></script>
|
|
189
189
|
<script>
|
|
190
190
|
tinyfly.to('.box', { x: 200, duration: 1 })
|
|
191
191
|
</script>
|
package/docs/gsap-compat.md
CHANGED
|
@@ -74,7 +74,7 @@ Without a build step, the all-in-one bundle exposes the same functions on a
|
|
|
74
74
|
global — `tinyfly.to()`, `tinyfly.timeline()` and so on:
|
|
75
75
|
|
|
76
76
|
```html
|
|
77
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
77
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly.iife.js"></script>
|
|
78
78
|
<script>
|
|
79
79
|
tinyfly.to('.box', { x: 200, duration: 1 })
|
|
80
80
|
</script>
|
package/docs/llm-guide.md
CHANGED
|
@@ -63,8 +63,11 @@ code: `build` (`child`, `tall`, `short`…), `hair` (a style name, or
|
|
|
63
63
|
from. Age is hair, glasses and clothes, never a stoop; a `cane` in a hand or
|
|
64
64
|
a `wheelchair()` to ride (`RIDING_POSES.wheeling`) is an accessory any
|
|
65
65
|
character can have. Expressions come from `HUMAN_EXPRESSIONS`
|
|
66
|
-
and are pose fields, as are the face marks `blush`, `tears` and `sweat` (0–1)
|
|
67
|
-
|
|
66
|
+
and are pose fields, as are the face marks `blush`, `tears` and `sweat` (0–1)
|
|
67
|
+
and the close-up fields `pupil`, `lid` and `bulge`, so any face goes with any
|
|
68
|
+
action or view; `drawCharacterHead(ctx, who, pose, { x, y, radius })` draws
|
|
69
|
+
just the head big, and `face: { nose, inPupil }` adds a nose and a drawing in
|
|
70
|
+
the pupils. Hair and hats turn with the head:
|
|
68
71
|
don't draw a different hairstyle per view. Hanging hair swings on its own:
|
|
69
72
|
after the character's tracks add `hairFollowTracks(target, tracks, who)` (or,
|
|
70
73
|
posing per frame, `hairFollow` once and `hairMotionAt(keys, t)` each frame)
|
|
@@ -145,12 +148,21 @@ them before calling it done:
|
|
|
145
148
|
|
|
146
149
|
```bash
|
|
147
150
|
npx @algorisys/tinyfly video scene.mjs --stills frames --times 0,800,1600,2400
|
|
151
|
+
npx @algorisys/tinyfly video scene.mjs --loop-check # a looping video: does the frame at the duration match the first?
|
|
148
152
|
```
|
|
149
153
|
|
|
150
154
|
A model that can read images should look at the PNGs: is the hand on the
|
|
151
155
|
word, does the figure stand on the line, does the text land where it should?
|
|
152
156
|
Fix, render again.
|
|
153
157
|
|
|
158
|
+
**A video that loops** (Shorts, Reels): say `loop: true` on the scene and
|
|
159
|
+
make every motion a function of `frame.time / frame.period` that repeats
|
|
160
|
+
exactly: `wobble`, `loopEase`, `loopNoise` for motion, `nestedZoom` for a
|
|
161
|
+
zoom that steps one level per loop, `bubblePath` with `period`, `beatPulse`
|
|
162
|
+
on a tempo from `loopBeats`, and `cutAudioToLoop` for the sound. Whole
|
|
163
|
+
numbers of turns and cycles only; `--loop-check` must say "closes". See the
|
|
164
|
+
Loops chapter of `docs/video-rendering.md`.
|
|
165
|
+
|
|
154
166
|
## The rules that trip models up
|
|
155
167
|
|
|
156
168
|
- **Milliseconds in JSON, seconds in the GSAP-style API.** Timeline keyframes
|
package/docs/maps.md
CHANGED
|
@@ -14,8 +14,8 @@ On a page with no build step, load the maps add-on after the browser bundle; it
|
|
|
14
14
|
adds to the same `tinyfly` global:
|
|
15
15
|
|
|
16
16
|
```html
|
|
17
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
18
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
17
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly.iife.js"></script>
|
|
18
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly-maps.iife.js"></script>
|
|
19
19
|
```
|
|
20
20
|
|
|
21
21
|
It is a separate script because the offline world map it carries adds about
|
package/docs/scene-3d.md
CHANGED
|
@@ -57,7 +57,7 @@ number or three), `parent` (an earlier object it moves with), `visible`, and
|
|
|
57
57
|
|---|---|
|
|
58
58
|
| `group` | (just a transform: move several objects together, or carry a camera) |
|
|
59
59
|
| `mesh` | `geometry`, `material` (a key of `materials`) |
|
|
60
|
-
| `camera` | `projection: 'perspective'` with `fov` (vertical, degrees), or `'orthographic'` with `height` (metres); `near`, `far`; optional `lookAt: [x, y, z]` |
|
|
60
|
+
| `camera` | `projection: 'perspective'` with `fov` (vertical, degrees), or `'orthographic'` with `height` (metres); `near`, `far`; optional `lookAt: [x, y, z]`, `up` (which way is up for it, default +y) and `roll` (degrees about the view axis, clockwise on screen) |
|
|
61
61
|
| `light` | `light: 'ambient' \| 'directional' \| 'point' \| 'spot'`, `color`, `intensity` (1 is full light); directional and spot shine from their position toward `target` (default the origin); point and spot fade to nothing at `range`; spot's cone is `angle` (half-angle, default 30°) |
|
|
62
62
|
|
|
63
63
|
**Geometry**: `box` (`size: [w, h, d]`), `sphere` (`radius`, `segments`),
|
|
@@ -67,7 +67,11 @@ facing up, `segments` per side), and `extrude`: any SVG `path` made solid,
|
|
|
67
67
|
`depth` metres thick and scaled to `width` metres wide (default 1), with
|
|
68
68
|
`curveSegments` points per curve (default 12). Subpaths inside others are
|
|
69
69
|
holes (an "o", a ring); outlines inside holes are solid again. The path's y
|
|
70
|
-
(down) is flipped to 3D's y (up). All centred on the origin.
|
|
70
|
+
(down) is flipped to 3D's y (up). All centred on the origin. A raw `mesh`
|
|
71
|
+
takes `positions` (flat x, y, z runs), `indices` (triples, counter-clockwise
|
|
72
|
+
from outside), optional `normals` per vertex (flat ones are computed) and
|
|
73
|
+
`colors`, one per face or one per vertex (blended per face), over the
|
|
74
|
+
material's colour: warped beams, terrain, anything exported from a tool.
|
|
71
75
|
|
|
72
76
|
```js
|
|
73
77
|
{ id: 'star', kind: 'mesh', material: 'gold',
|
|
@@ -93,7 +97,9 @@ milestone); the stylized renderers ignore them, so one material serves both.
|
|
|
93
97
|
|
|
94
98
|
The scene can have `background` and `fog: { color, near, far }` (metres from
|
|
95
99
|
the camera). A scene with no lights gets a soft default (ambient plus a key
|
|
96
|
-
light from upper right).
|
|
100
|
+
light from upper right). Outlines fade into the fog too. `nearFade: { from, to }` fades geometry
|
|
101
|
+
nearer the camera than `to` metres, gone at `from`, so a dive passes through
|
|
102
|
+
things as if they were glass (also an option of `resolveScene3D`).
|
|
97
103
|
|
|
98
104
|
## Animating it
|
|
99
105
|
|
|
@@ -108,8 +114,9 @@ live in the same timeline as everything else.
|
|
|
108
114
|
| `visible` | any object | 0 or 1 (children hide with their parent) |
|
|
109
115
|
| `opacity` | meshes | 0..1, times the material's |
|
|
110
116
|
| `color` | meshes, lights | a colour, over the material's or light's |
|
|
117
|
+
| `outlineWidth`, `outlineColor` | meshes | px and a colour, over the material's outline (0 switches it off) |
|
|
111
118
|
| `intensity`, `target` | lights | |
|
|
112
|
-
| `fov` / `height`, `lookAt` | cameras | |
|
|
119
|
+
| `fov` / `height`, `lookAt`, `roll` | cameras | |
|
|
113
120
|
| `color`, `width`, `opacity` | lines, trails | |
|
|
114
121
|
| `length` | trails | ms |
|
|
115
122
|
| `activeCamera` | the scene, target `<sceneId>` | a camera's id: **a cut is one keyframe** |
|
|
@@ -394,6 +401,18 @@ objects, prepares them once, and each frame returns meshes (shaded and sorted
|
|
|
394
401
|
with the scene's) and drawables (drawn whole at their depth). Pass it in
|
|
395
402
|
`loadScene3D(scene, { kinds })`.
|
|
396
403
|
|
|
404
|
+
## Impossible objects
|
|
405
|
+
|
|
406
|
+
`penroseTriangle3D({ length, thickness, material, id, position, distance })`
|
|
407
|
+
returns three box objects (beams along x, up y and along z, each starting
|
|
408
|
+
where the last ends) and an orthographic camera on the (1, 1, 1) diagonal
|
|
409
|
+
from which the third beam's end meets the first's start on screen. Add the
|
|
410
|
+
objects with a material of that name and the camera, or place your own camera
|
|
411
|
+
along the diagonal; from anywhere else the loop is open. The third corner
|
|
412
|
+
shows the beams' ends as a real sculpture's does. For a clean drawing see the
|
|
413
|
+
2D `penroseTriangle` and `penroseStairs` in
|
|
414
|
+
[Video from code](video-rendering.md#dives-and-impossible-objects).
|
|
415
|
+
|
|
397
416
|
## The WebGL2 renderer
|
|
398
417
|
|
|
399
418
|
`@algorisys/tinyfly/scene-3d/webgl` (`tinyfly-scene-3d-webgl.iife.js` for
|
package/docs/teaching.md
CHANGED
|
@@ -25,7 +25,7 @@ path for all of that:
|
|
|
25
25
|
</figure>
|
|
26
26
|
|
|
27
27
|
<!-- once, anywhere on the page (a site-wide footer is fine) -->
|
|
28
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
28
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
|
|
29
29
|
```
|
|
30
30
|
|
|
31
31
|
Every `[data-tinyfly-embed]` mounts when the page is ready, with no per-post
|
package/docs/video-rendering.md
CHANGED
|
@@ -557,6 +557,141 @@ The numbers are PSNR (higher is more alike; fast or trembling motion makes
|
|
|
557
557
|
every step lower). From code: `checkLoop(scene)` returns the same report, and
|
|
558
558
|
`psnr(a, b)` / `loopReport(frames)` work on any RGBA frames.
|
|
559
559
|
|
|
560
|
+
### A scene that loops
|
|
561
|
+
|
|
562
|
+
Say so with `loop: true`: the duration is the period. `tinyfly video` then
|
|
563
|
+
runs the loop check before it encodes anything and stops (exit 1) if the loop
|
|
564
|
+
does not close; every frame carries `period`, which the periodic helpers and
|
|
565
|
+
3D trails without a `period` of their own use.
|
|
566
|
+
|
|
567
|
+
```js
|
|
568
|
+
import { wobble, loopNoise, loopEase } from '@algorisys/tinyfly'
|
|
569
|
+
|
|
570
|
+
export default {
|
|
571
|
+
width: 1280, height: 720, duration: 4000, loop: true,
|
|
572
|
+
draw(ctx, frame) {
|
|
573
|
+
const sway = wobble(frame.time, { period: frame.period, cycles: 2, amplitude: 12 }) // a sine, two whole cycles
|
|
574
|
+
const drift = loopNoise(frame.time, { period: frame.period, seed: 'tree' }) * 30 // smooth noise round a circle
|
|
575
|
+
const breathe = loopEase(frame.time, { period: frame.period, easing: 'ease-in-out' }) // 0 → 1 → 0, eased
|
|
576
|
+
},
|
|
577
|
+
}
|
|
578
|
+
```
|
|
579
|
+
|
|
580
|
+
| Helper | Repeats exactly every `period` |
|
|
581
|
+
|---|---|
|
|
582
|
+
| `wobble(t, { period, cycles, amplitude, phase, shape })` | A sine (or `triangle`, `square`) with a whole number of cycles |
|
|
583
|
+
| `loopEase(t, { period, cycles, easing, phase })` | 0 → 1 → 0, the easing on the way up and mirrored down |
|
|
584
|
+
| `loopNoise(t, { period, seed, cycles, octaves, phase })` | Seeded value noise read round a circle, about −1..1: the end meets the start |
|
|
585
|
+
| `torusNoise(t, along, { period, periodAlong, seed, … })` | Noise periodic in time and along a length (ripples, grass, a flag) |
|
|
586
|
+
| `phaseOf(t, period, cycles)`, `pingPong(u)` | The building blocks: where in the cycle, and there-and-back |
|
|
587
|
+
|
|
588
|
+
Each is a pure function of time, so frames render in any order and the loop
|
|
589
|
+
check reports "closes", not "seamless".
|
|
590
|
+
|
|
591
|
+
### Sound for a loop
|
|
592
|
+
|
|
593
|
+
A loop's sound must come round with its picture. `cutAudioToLoop(file, {
|
|
594
|
+
output, period, crossfade, fadeIn, fadeOut })` (Node) decodes a drone, a
|
|
595
|
+
riser or a beat, trims it to the period with its end blended into its start
|
|
596
|
+
(tiling it first if it is shorter) and writes the WAV to pass as the scene's
|
|
597
|
+
`audio`; `loopSamples` is the pure step on samples. For motion on the beat,
|
|
598
|
+
`loopBeats(period, grid)` cuts a tempo to the loop (the nearest whole number
|
|
599
|
+
of beats, the bpm nudged to fit exactly), `beatPulse(time, grid, { attack,
|
|
600
|
+
decay, barAccent })` spikes to 1 on every beat and decays, and
|
|
601
|
+
`beatPeriod(grid, beats)` is the length of so many beats. For motion that
|
|
602
|
+
follows the sound itself, `audioEnvelope(samples, sampleRate, { fps,
|
|
603
|
+
smoothing })` gives a level per frame (rising at once, letting go slowly,
|
|
604
|
+
loudest 1) and `envelopeAt(levels, time, fps, period)` reads it at any time,
|
|
605
|
+
wrapped for the loop:
|
|
606
|
+
|
|
607
|
+
```js
|
|
608
|
+
import { decodeAudio, cutAudioToLoop } from '@algorisys/tinyfly/headless'
|
|
609
|
+
import { audioEnvelope, envelopeAt, loopBeats, beatPulse, detectTempo } from '@algorisys/tinyfly'
|
|
610
|
+
|
|
611
|
+
const PERIOD = 4000
|
|
612
|
+
const audio = await cutAudioToLoop('drone.wav', { output: 'build/drone-loop.wav', period: PERIOD, baseDir: here })
|
|
613
|
+
const samples = await decodeAudio(audio, { sampleRate: 48000 })
|
|
614
|
+
const levels = audioEnvelope(samples, 48000, { fps: 30 })
|
|
615
|
+
const { grid } = loopBeats(PERIOD, detectTempo(samples, 48000))
|
|
616
|
+
export default {
|
|
617
|
+
width: 1280, height: 720, duration: PERIOD, loop: true, audio,
|
|
618
|
+
draw(ctx, frame) {
|
|
619
|
+
const level = envelopeAt(levels, frame.time, 30, frame.period) // 0..1 with the sound
|
|
620
|
+
const pulse = beatPulse(frame.time, grid) // 1 on each beat, decaying
|
|
621
|
+
},
|
|
622
|
+
}
|
|
623
|
+
```
|
|
624
|
+
|
|
625
|
+
### Nested zooms (Droste)
|
|
626
|
+
|
|
627
|
+
A picture inside itself, the camera diving in: after one step every level is
|
|
628
|
+
where the next one was, so a video one step long loops. `similarityAbout(
|
|
629
|
+
scale, turn, centre)` is the step (a scale, a turn and a move as one value;
|
|
630
|
+
`powSimilarity(step, k)` is a fraction of it, `composeSimilarity` chains
|
|
631
|
+
them, `similarityFixedPoint` is the centre everything converges on), and
|
|
632
|
+
`nestedZoom` draws the levels:
|
|
633
|
+
|
|
634
|
+
```js
|
|
635
|
+
import { similarityAbout } from '@algorisys/tinyfly'
|
|
636
|
+
import { nestedZoom } from '@algorisys/tinyfly/adapters'
|
|
637
|
+
|
|
638
|
+
const step = similarityAbout(0.5, 12, { x: 640, y: 360 })
|
|
639
|
+
export default {
|
|
640
|
+
width: 1280, height: 720, duration: 3000, loop: true, background: '#05030c',
|
|
641
|
+
draw(ctx, frame) {
|
|
642
|
+
nestedZoom(ctx, {
|
|
643
|
+
step,
|
|
644
|
+
phase: frame.time / frame.period, // 0..1: how far into one step
|
|
645
|
+
extent: 1600, // how far a level's drawing reaches at level 0, px
|
|
646
|
+
coversAbove: 1.1, // a level this big fills the frame: nothing behind it is drawn
|
|
647
|
+
draw(ctx, level, scale) { drawFrame(ctx, level) }, // in level-0 coordinates
|
|
648
|
+
})
|
|
649
|
+
},
|
|
650
|
+
}
|
|
651
|
+
```
|
|
652
|
+
|
|
653
|
+
Levels smaller than `minSize` px (default 1) are skipped, and so is
|
|
654
|
+
everything behind a level at or above `coversAbove`, so a zoom of twenty
|
|
655
|
+
levels draws the five or six that show. `draw` gets the level number (0 is
|
|
656
|
+
the one at natural size at phase 0, 1 the one inside it) and its screen
|
|
657
|
+
scale, to keep line widths readable; colour or detail that should travel with
|
|
658
|
+
the zoom is a function of `level - phase`. `examples/headless-video/nested-zoom.mjs`
|
|
659
|
+
is a looping neon zoom built this way; `nestedZoomTransform(step, level,
|
|
660
|
+
phase)` gives a level's similarity for drawing it some other way.
|
|
661
|
+
|
|
662
|
+
A Droste *face*: `drawCharacterHead` draws a character's head big, and its
|
|
663
|
+
`face.inPupil` hook draws inside each pupil, clipped to it, so the head can
|
|
664
|
+
hold itself (see [Close-ups](character-appearance.md#close-ups)). Anything
|
|
665
|
+
that should change with a level's size on screen rather than with time (the
|
|
666
|
+
eyes opening as a head grows, a colour cooling with depth) is a `curve`:
|
|
667
|
+
`curve([{ at: 20, value: 0 }, { at: 300, value: 1, easing: 'ease-out' }])(radius)`
|
|
668
|
+
reads keyframes and easings at any input, holding beyond its ends.
|
|
669
|
+
|
|
670
|
+
### Dives and impossible objects
|
|
671
|
+
|
|
672
|
+
Two post-effects for a dive, both deterministic. `applyZoomBlur(ctx, { centre,
|
|
673
|
+
strength, samples, blend })` streaks the finished frame out from a point (a
|
|
674
|
+
fixed set of scaled copies, averaged, or added with `blend: 'add'` for neon);
|
|
675
|
+
`drawDiveLines(ctx, { centre, count, inner, outer, length, phase, seed, color,
|
|
676
|
+
blend })` streams seeded lines past the camera, and `phase: phaseOf(time,
|
|
677
|
+
period)` moves them one line along per loop so they repeat exactly.
|
|
678
|
+
|
|
679
|
+
The impossible objects are built the way the sculptures are: real boxes that
|
|
680
|
+
line up from one viewpoint. `penroseTriangle({ size, thickness, centre, scale })`
|
|
681
|
+
and `penroseStairs({ steps, tread, rise, width, base, centre, scale })` give
|
|
682
|
+
boxes and their visible faces in drawing order for the isometric view (along
|
|
683
|
+
the (1, 1, 1) diagonal, z up); `drawIsometricFaces(ctx, faces, { top, left,
|
|
684
|
+
right, fill, outline })` fills them. The triangle's third beam ends one
|
|
685
|
+
diagonal from where the first began, so on screen the loop closes (the first
|
|
686
|
+
beam is drawn again over the third's end); the stairs climb all the way round
|
|
687
|
+
and the last step meets the first. `projectIsometric`, `isometricBoxFaces`
|
|
688
|
+
and `isometricFaces` are the building blocks for your own. In a 3D scene,
|
|
689
|
+
`penroseTriangle3D({ length, thickness, material })` returns the three beams
|
|
690
|
+
and an orthographic camera down the diagonal: from it the loop closes, from
|
|
691
|
+
anywhere else it is three beams (its third corner shows the beams' ends,
|
|
692
|
+
as a real sculpture's does; a `rotateY` track on a group round it breaks and
|
|
693
|
+
remakes the illusion).
|
|
694
|
+
|
|
560
695
|
## Bloom
|
|
561
696
|
|
|
562
697
|
`bloom: true` (or options) adds a glow around everything bright, after each
|
|
@@ -633,6 +768,25 @@ beads where segments overlap and no seams between them. `ribbon(points)` and
|
|
|
633
768
|
`line` and `trail` objects, sorted by depth among the meshes (see
|
|
634
769
|
[3D Scenes](scene-3d.md#lines-and-trails)).
|
|
635
770
|
|
|
771
|
+
## Satisfying matter
|
|
772
|
+
|
|
773
|
+
Goo as geometry, every shape a pure function of its inputs:
|
|
774
|
+
|
|
775
|
+
| Helper | Gives |
|
|
776
|
+
|---|---|
|
|
777
|
+
| `metaballContours(balls, { threshold, cell, smooth })` | The outlines of balls (`{ x, y, r }`) that merge through necks as they near and split as they part, as closed polygons; `metaballField` is the field itself |
|
|
778
|
+
| `dripPath({ x, y, length, width, progress })` | A drip under a surface: a neck thinning to a thread and a head swelling as `progress` runs 0 → 1 |
|
|
779
|
+
| `bubblePath({ x, y, r, grow, time, period, wobble })` | A bubble growing from nothing (with a little swell on the way) whose surface quivers with the time; with `period` the quiver repeats exactly |
|
|
780
|
+
| `bubblePop({ x, y, r, progress, pieces })` | The pop: arcs of the rim flying out and shrinking, gone at 1 |
|
|
781
|
+
| `squashStretch(amount, { keep })`, `scalePoints(points, scale, about)` | Stretch taller (or squash, negative) with the width giving way so the area (or the `volume`) stays; apply it about the point a blob lands on |
|
|
782
|
+
|
|
783
|
+
```js
|
|
784
|
+
draw(ctx, frame) {
|
|
785
|
+
const balls = [{ x: 400, y: 300, r: 60 }, { x: 400 + wobble(frame.time, { period: frame.period, amplitude: 90 }), y: 300, r: 40 }]
|
|
786
|
+
for (const loop of metaballContours(balls, { cell: 3 })) fillPolygon(ctx, loop, '#b6ff3b')
|
|
787
|
+
}
|
|
788
|
+
```
|
|
789
|
+
|
|
636
790
|
## Camera, overlay and drawing on twos
|
|
637
791
|
|
|
638
792
|
- `camera: true` sees the scene through the tracks of the `Camera` target:
|