@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.
Files changed (58) hide show
  1. package/README.md +5 -5
  2. package/bin/tinyfly.mjs +7 -3
  3. package/docs/character-appearance.md +26 -0
  4. package/docs/editor-guide.md +1 -1
  5. package/docs/examples.md +1 -1
  6. package/docs/getting-started.md +1 -1
  7. package/docs/gsap-compat.md +1 -1
  8. package/docs/llm-guide.md +14 -2
  9. package/docs/maps.md +2 -2
  10. package/docs/scene-3d.md +23 -4
  11. package/docs/teaching.md +1 -1
  12. package/docs/video-rendering.md +154 -0
  13. package/lib/addons/adapters.js +387 -333
  14. package/lib/addons/characters.js +4467 -4448
  15. package/lib/addons/load-scene-oWNsYYC1.js +372 -0
  16. package/lib/addons/scene-3d-webgl.js +1 -1
  17. package/lib/addons/scene-3d.js +323 -277
  18. package/lib/addons/shading-0lPgnXmD.js +96 -0
  19. package/lib/browser/tinyfly-scene-3d.iife.js +2 -2
  20. package/lib/browser/tinyfly.iife.js +14 -14
  21. package/lib/browser/tinyfly.js +5888 -5511
  22. package/lib/browser/tinyfly.umd.js +14 -14
  23. package/lib/engine/tinyfly-engine.js +1389 -1031
  24. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  25. package/lib/headless/headless.js +39 -0
  26. package/lib/types/adapters/canvas/impossible.d.ts +15 -0
  27. package/lib/types/adapters/canvas/index.d.ts +3 -0
  28. package/lib/types/adapters/canvas/nested-zoom.d.ts +40 -0
  29. package/lib/types/adapters/canvas/zoom-blur.d.ts +49 -0
  30. package/lib/types/characters/character.d.ts +23 -3
  31. package/lib/types/characters/head/face.d.ts +19 -2
  32. package/lib/types/engine/authoring/beat-loop.d.ts +46 -0
  33. package/lib/types/engine/authoring/curve.d.ts +26 -0
  34. package/lib/types/engine/authoring/index.d.ts +3 -0
  35. package/lib/types/engine/authoring/periodic.d.ts +89 -0
  36. package/lib/types/engine/path/goo.d.ts +103 -0
  37. package/lib/types/engine/path/impossible.d.ts +92 -0
  38. package/lib/types/engine/path/index.d.ts +6 -0
  39. package/lib/types/engine/path/similarity.d.ts +48 -0
  40. package/lib/types/headless/index.d.ts +1 -0
  41. package/lib/types/headless/loop-audio.d.ts +21 -0
  42. package/lib/types/headless/node-audio.d.ts +20 -0
  43. package/lib/types/headless/video-scene.d.ts +9 -0
  44. package/lib/types/scene-3d/camera.d.ts +11 -2
  45. package/lib/types/scene-3d/geometry/mesh.d.ts +2 -0
  46. package/lib/types/scene-3d/geometry/primitives.d.ts +7 -0
  47. package/lib/types/scene-3d/impossible-3d.d.ts +29 -0
  48. package/lib/types/scene-3d/index.d.ts +4 -3
  49. package/lib/types/scene-3d/resolve-scene.d.ts +13 -1
  50. package/lib/types/scene-3d/scene-3d-adapter.d.ts +2 -0
  51. package/lib/types/scene-3d/scene-types.d.ts +29 -4
  52. package/lib/types/scene-3d/shading.d.ts +2 -0
  53. package/llms-full.txt +226 -15
  54. package/llms.txt +29 -29
  55. package/package.json +1 -1
  56. package/skills/tinyfly/SKILL.md +7 -0
  57. package/lib/addons/load-scene-CQvcFWGJ.js +0 -331
  58. package/lib/addons/shading-o5T_v9DT.js +0 -89
@@ -0,0 +1,26 @@
1
+ import type { AnimatableValue, EasingType, TrackInterpolation } from '../types';
2
+ /**
3
+ * A keyframe curve over any input, not just time: the same keys and easings a
4
+ * track has, read at a number of your own. A face that opens its eyes as it
5
+ * grows on screen, a colour that cools with depth, a line width that follows
6
+ * a zoom's scale.
7
+ *
8
+ * const glow = curve([{ at: 0, value: '#223' }, { at: 300, value: '#ff2bd6', easing: 'ease-out' }])
9
+ * ctx.strokeStyle = glow(distanceToCamera)
10
+ *
11
+ * Before the first key the curve holds its first value, after the last its
12
+ * last; between keys it eases exactly as a track does.
13
+ */
14
+ export interface CurveKey<T extends AnimatableValue = number> {
15
+ /** The input this key is at */
16
+ at: number;
17
+ value: T;
18
+ /** Easing into this key from the one before (ignored on the first) */
19
+ easing?: EasingType;
20
+ }
21
+ export interface CurveOptions {
22
+ /** How values blend (default by their type: numbers, colours, arrays) */
23
+ interpolation?: TrackInterpolation;
24
+ }
25
+ /** A function of the input from keys, holding the first and last values beyond them. */
26
+ export declare function curve<T extends AnimatableValue = number>(keys: ReadonlyArray<CurveKey<T>>, options?: CurveOptions): (x: number) => T;
@@ -6,3 +6,6 @@ export * from './beats';
6
6
  export * from './camera-shots';
7
7
  export * from './did-you-mean';
8
8
  export * from './spring-follow';
9
+ export * from './periodic';
10
+ export * from './curve';
11
+ export * from './beat-loop';
@@ -0,0 +1,89 @@
1
+ import type { EasingFunction, EasingType } from '../types';
2
+ /**
3
+ * Motion that repeats exactly over a period, for videos that loop.
4
+ *
5
+ * A loop closes when the frame at time = duration is the first frame, so
6
+ * every motion must repeat over the duration: a whole number of cycles, a
7
+ * zoom that steps one level, noise that comes back to where it started. These
8
+ * helpers are periodic by construction. Each takes the `period` in ms (a
9
+ * looping video scene's `frame.period` is its duration) and gives the same
10
+ * value at `time` and `time + period` to the last bit, so a loop check
11
+ * reports "closes" rather than "seamless".
12
+ *
13
+ * draw(ctx, frame) {
14
+ * const sway = wobble(frame.time, { period: frame.period, cycles: 2, amplitude: 12 })
15
+ * const drift = loopNoise(frame.time, { period: frame.period, seed: 'tree' }) * 30
16
+ * }
17
+ *
18
+ * Everything is a pure function of time: frames render in any order, and the
19
+ * same scene gives the same video.
20
+ */
21
+ /** Where in its cycle a periodic motion is at `time`: 0 (inclusive) to 1 (exclusive). `cycles` whole cycles per period. */
22
+ export declare function phaseOf(time: number, period: number, cycles?: number): number;
23
+ /** 0 → 1 → 0 over one unit: `u` in 0..1 goes up to 1 at 0.5 and back, the same at 0 and 1. */
24
+ export declare function pingPong(u: number): number;
25
+ export interface WobbleOptions {
26
+ /** The period, ms: the motion repeats exactly every `period` */
27
+ period: number;
28
+ /** Whole cycles per period (default 1); a fraction would not repeat */
29
+ cycles?: number;
30
+ /** Peak value (default 1): the result swings between −amplitude and +amplitude */
31
+ amplitude?: number;
32
+ /** Start part way round the cycle, 0..1 (default 0) */
33
+ phase?: number;
34
+ /** The wave: a sine (default), a triangle, or a square */
35
+ shape?: 'sine' | 'triangle' | 'square';
36
+ }
37
+ /** A wave that repeats exactly every period: `cycles` whole cycles of a sine (or triangle, square). */
38
+ export declare function wobble(time: number, options: WobbleOptions): number;
39
+ export interface LoopEaseOptions {
40
+ /** The period, ms */
41
+ period: number;
42
+ /** Whole cycles per period (default 1) */
43
+ cycles?: number;
44
+ /** Easing for the way up, mirrored on the way down (default `ease-in-out`): a name or a function */
45
+ easing?: EasingType | EasingFunction;
46
+ /** Start part way round the cycle, 0..1 (default 0) */
47
+ phase?: number;
48
+ }
49
+ /**
50
+ * An eased there-and-back: 0 at the start of each cycle, 1 half way, 0 again
51
+ * at the end, the easing applied on the way up and mirrored on the way down.
52
+ * Unlike an easing of `time / period`, it repeats exactly.
53
+ */
54
+ export declare function loopEase(time: number, options: LoopEaseOptions): number;
55
+ export interface LoopNoiseOptions {
56
+ /** The period, ms */
57
+ period: number;
58
+ /** The seed: a number or any string (default 0). Different seeds give unrelated motion */
59
+ seed?: number | string;
60
+ /** How many wiggles per period (default 1): the noise's own cycles round its circle */
61
+ cycles?: number;
62
+ /** Layers of finer, fainter detail (default 1, up to 6) */
63
+ octaves?: number;
64
+ /** Start part way round (default 0) */
65
+ phase?: number;
66
+ }
67
+ /**
68
+ * Smooth random motion that repeats exactly every period: value noise read
69
+ * round a circle, so the end joins the start. About −1..1, seeded, and the
70
+ * same for the same time, seed and options anywhere.
71
+ */
72
+ export declare function loopNoise(time: number, options: LoopNoiseOptions): number;
73
+ export interface TorusNoiseOptions {
74
+ /** The period of the first input (time), ms */
75
+ period: number;
76
+ /** The period of the second input (a position along something): the noise repeats along it too */
77
+ periodAlong: number;
78
+ seed?: number | string;
79
+ /** Wiggles per period of time, and per period along (default 1 each) */
80
+ cycles?: number;
81
+ cyclesAlong?: number;
82
+ octaves?: number;
83
+ }
84
+ /**
85
+ * Noise periodic in two inputs, read round a torus: a field along a line
86
+ * (ripples, a flag, grass) that repeats over the loop's period in time and
87
+ * joins up along its length. About −1..1.
88
+ */
89
+ export declare function torusNoise(time: number, along: number, options: TorusNoiseOptions): number;
@@ -0,0 +1,103 @@
1
+ /**
2
+ * Satisfying matter, as plain geometry: metaballs that merge and split, drips
3
+ * that form and fall, bubbles that grow, wobble and pop, and squash and
4
+ * stretch that keeps a blob's area (or volume). Everything is a pure function
5
+ * of its inputs, so a frame draws the same at any time and in any order.
6
+ */
7
+ export interface GooPoint {
8
+ x: number;
9
+ y: number;
10
+ }
11
+ export interface Ball {
12
+ x: number;
13
+ y: number;
14
+ r: number;
15
+ }
16
+ export interface MetaballOptions {
17
+ /** Where the surface is: the field is 1 at each ball's own radius (default 1; lower is fatter, blobs merge sooner) */
18
+ threshold?: number;
19
+ /** Grid cell size, px (default 4): smaller is finer and slower */
20
+ cell?: number;
21
+ /** Round the contour's corners (default true) */
22
+ smooth?: boolean;
23
+ /** The area to trace, px (default: round the balls) */
24
+ bounds?: {
25
+ x: number;
26
+ y: number;
27
+ width: number;
28
+ height: number;
29
+ };
30
+ }
31
+ /** The metaball field at a point: each ball adds r² / d², so it is 1 at its own edge. */
32
+ export declare function metaballField(balls: ReadonlyArray<Ball>, x: number, y: number): number;
33
+ /**
34
+ * The outlines of merged balls, as closed polygons (marching squares over the
35
+ * field, corners rounded). Two balls near each other join through a neck;
36
+ * apart, each is its own circle.
37
+ */
38
+ export declare function metaballContours(balls: ReadonlyArray<Ball>, options?: MetaballOptions): GooPoint[][];
39
+ export interface DripOptions {
40
+ /** Where it hangs from, px */
41
+ x: number;
42
+ y: number;
43
+ /** How far it reaches when fully formed, px */
44
+ length: number;
45
+ /** Its width at the top, px */
46
+ width: number;
47
+ /** 0: nothing yet; 1: fully stretched, the head about to let go */
48
+ progress: number;
49
+ /** Points round the head (default 12) */
50
+ segments?: number;
51
+ }
52
+ /**
53
+ * A drip forming under a surface: a neck that thins as it stretches, a round
54
+ * head that swells, as a closed polygon (y down). `progress` runs it.
55
+ */
56
+ export declare function dripPath(options: DripOptions): GooPoint[];
57
+ export interface BubbleOptions {
58
+ x: number;
59
+ y: number;
60
+ /** Radius when fully grown, px */
61
+ r: number;
62
+ /** 0..1 grows it from nothing (default 1) */
63
+ grow?: number;
64
+ /** ms, for the wobble; with `period` the wobble repeats exactly */
65
+ time?: number;
66
+ period?: number;
67
+ /** How much the surface wobbles, as a share of the radius (default 0.05) */
68
+ wobble?: number;
69
+ /** Points round it (default 48) */
70
+ segments?: number;
71
+ /** Start the wobble somewhere else */
72
+ seed?: number;
73
+ }
74
+ /** A bubble: a circle whose surface wobbles with three gentle lobes, growing from nothing. */
75
+ export declare function bubblePath(options: BubbleOptions): GooPoint[];
76
+ export interface PopOptions {
77
+ x: number;
78
+ y: number;
79
+ r: number;
80
+ /** 0: the moment it pops; 1: the pieces are gone */
81
+ progress: number;
82
+ /** Fragments round the rim (default 8) */
83
+ pieces?: number;
84
+ }
85
+ /** A bubble popping: arcs of its rim flying outward and shrinking, as polylines. Empty before and after. */
86
+ export declare function bubblePop(options: PopOptions): GooPoint[][];
87
+ /**
88
+ * Squash and stretch that keeps the amount of stuff: stretched taller by
89
+ * `amount` (−1..1: negative squashes), the width gives way so the area stays
90
+ * (`keep: 'area'`, the default, for flat drawings) or the volume stays
91
+ * (`keep: 'volume'`, each side across shrinking by the square root).
92
+ */
93
+ export declare function squashStretch(amount: number, options?: {
94
+ keep?: 'area' | 'volume';
95
+ }): {
96
+ sx: number;
97
+ sy: number;
98
+ };
99
+ /** Scale points about a point (default the origin): a blob squashed where it lands. */
100
+ export declare function scalePoints(points: ReadonlyArray<GooPoint>, scale: {
101
+ sx: number;
102
+ sy: number;
103
+ }, about?: GooPoint): GooPoint[];
@@ -0,0 +1,92 @@
1
+ /**
2
+ * Impossible objects, as plain geometry: the Penrose triangle (three beams
3
+ * that seem to join in a loop) and the Penrose stairs (a flight that climbs
4
+ * for ever), built the way the sculptures are: real boxes in 3D that only
5
+ * line up from one viewpoint. Seen along the (1, 1, 1) diagonal (the
6
+ * isometric view), the ends meet on screen though they are far apart in
7
+ * depth, and drawing the boxes far to near makes the near end cover the far
8
+ * one. Everything here is pure: boxes in, screen polygons out, for any
9
+ * renderer that fills polygons.
10
+ */
11
+ export type Vec3 = [number, number, number];
12
+ export interface IsoPoint {
13
+ x: number;
14
+ y: number;
15
+ }
16
+ /** A box by its two corners, in a right-handed space with z up. */
17
+ export interface IsoBox {
18
+ min: Vec3;
19
+ max: Vec3;
20
+ /** Anything to carry to the faces (a bar's index, a step's number) */
21
+ tag?: number;
22
+ /** Faces not to draw (an end cap that another box's drawing should cover) */
23
+ hide?: Array<'top' | 'left' | 'right'>;
24
+ }
25
+ /** One visible face of a box on screen: its polygon, which way it faces, and its depth (further is smaller). */
26
+ export interface IsoFace {
27
+ points: IsoPoint[];
28
+ /** `top` faces up (+z), `left` faces +y (toward the lower left on screen), `right` faces +x (lower right) */
29
+ side: 'top' | 'left' | 'right';
30
+ depth: number;
31
+ tag?: number;
32
+ }
33
+ export interface IsoOptions {
34
+ /** Where the origin lands on screen (default 0, 0) */
35
+ centre?: IsoPoint;
36
+ /** Screen px per unit (default 1) */
37
+ scale?: number;
38
+ }
39
+ /**
40
+ * The isometric projection: the view along (1, 1, 1) with z up. +x runs to
41
+ * the lower right, +y to the lower left, +z straight up.
42
+ */
43
+ export declare function projectIsometric([x, y, z]: Vec3, options?: IsoOptions): IsoPoint;
44
+ /** How far along the view direction a point is: larger is nearer the viewer. */
45
+ export declare const isoDepth: ([x, y, z]: Vec3) => number;
46
+ /** The three faces of a box that show in the isometric view: top (+z), left (+y) and right (+x). */
47
+ export declare function isometricBoxFaces(box: IsoBox, options?: IsoOptions): IsoFace[];
48
+ /** Every visible face of a set of boxes, far to near, so filling them in order draws the picture. */
49
+ export declare function isometricFaces(boxes: IsoBox[], options?: IsoOptions): IsoFace[];
50
+ export interface PenroseTriangleOptions extends IsoOptions {
51
+ /** The beams' length, units (default 10) */
52
+ size?: number;
53
+ /** The beams' thickness, units (default 2) */
54
+ thickness?: number;
55
+ }
56
+ /**
57
+ * The Penrose triangle as three square beams: along x, then y, then up z,
58
+ * each starting where the last ended. The third ends exactly one diagonal
59
+ * (1, 1, 1) step from where the first began, so on screen the loop closes.
60
+ * Returns the beams (tag 0, 1, 2) and their faces in drawing order: far to
61
+ * near, then the first beam again over the third's end (its own end cap
62
+ * left out), which is what makes every corner look the same.
63
+ */
64
+ export declare function penroseTriangle(options?: PenroseTriangleOptions): {
65
+ boxes: IsoBox[];
66
+ faces: IsoFace[];
67
+ };
68
+ export interface PenroseStairsOptions extends IsoOptions {
69
+ /** Steps on each of the two long flights (default 8); the two coming back are shorter by the climb */
70
+ steps?: number;
71
+ /** A step's depth along the flight, units (default 1.5) */
72
+ tread?: number;
73
+ /** How much each step climbs, units (default 0.25); nudged so the loop closes exactly (see the result's `rise`) */
74
+ rise?: number;
75
+ /** The flights' width, units (default 3) */
76
+ width?: number;
77
+ /** How high the first step's top is above the floor the blocks stand on, units (default 1.5) */
78
+ base?: number;
79
+ }
80
+ /**
81
+ * The Penrose stairs: four flights round a square, every step a little higher
82
+ * than the last, and the last step one diagonal (1, 1, 1) from the first so
83
+ * the top step meets the bottom one on screen. The flights coming back are
84
+ * shorter by the climb (the ring is really a spiral), and the rise is nudged
85
+ * so that works out in whole steps. Returns the steps (tag: the step's
86
+ * number) and their faces, far to near, and the rise used.
87
+ */
88
+ export declare function penroseStairs(options?: PenroseStairsOptions): {
89
+ boxes: IsoBox[];
90
+ faces: IsoFace[];
91
+ rise: number;
92
+ };
@@ -11,3 +11,9 @@ export { pointsToPath, shapeToPathData } from './path-builders';
11
11
  export type { PathPoint, PointsToPathOptions, SvgShape } from './path-builders';
12
12
  export { trailSamples, ribbon, ribbonHeadCap } from './trail';
13
13
  export type { TrailOptions, TrailSample, RibbonPoint, Ribbon } from './trail';
14
+ export { similarity, similarityAbout, applySimilarity, composeSimilarity, invertSimilarity, powSimilarity, similarityFixedPoint, similarityMatrix, IDENTITY_SIMILARITY } from './similarity';
15
+ export type { Similarity, SimilarityPoint } from './similarity';
16
+ export { projectIsometric, isoDepth, isometricBoxFaces, isometricFaces, penroseTriangle, penroseStairs } from './impossible';
17
+ export type { IsoBox, IsoFace, IsoPoint, IsoOptions, PenroseTriangleOptions, PenroseStairsOptions } from './impossible';
18
+ export { metaballField, metaballContours, dripPath, bubblePath, bubblePop, squashStretch, scalePoints } from './goo';
19
+ export type { GooPoint, Ball, MetaballOptions, DripOptions, BubbleOptions, PopOptions } from './goo';
@@ -0,0 +1,48 @@
1
+ /**
2
+ * Similarity transforms: a scale, a turn and a move as one value, the maths
3
+ * of self-similar pictures (a Droste zoom, a spiral of copies, a picture in
4
+ * its own frame). Composing two is one; a fraction of one (`powSimilarity`)
5
+ * is the in-between step a zoom animates through; the fixed point is where
6
+ * everything converges.
7
+ *
8
+ * A similarity maps a point `z` to `scale · R(turn) · z + (x, y)`: in complex
9
+ * numbers, `a·z + b` with `a = scale·e^(i·turn)`. `turn` is in degrees,
10
+ * positive clockwise on a canvas (y down), as `rotate` tracks are.
11
+ */
12
+ export interface Similarity {
13
+ /** The scale factor (1: none; 0.5: half size) */
14
+ scale: number;
15
+ /** The turn, degrees (clockwise on a canvas) */
16
+ turn: number;
17
+ /** The move, applied after the scale and turn */
18
+ x: number;
19
+ y: number;
20
+ }
21
+ export interface SimilarityPoint {
22
+ x: number;
23
+ y: number;
24
+ }
25
+ export declare const IDENTITY_SIMILARITY: Similarity;
26
+ /** A similarity from any of its fields (the rest identity). */
27
+ export declare function similarity(fields?: Partial<Similarity>): Similarity;
28
+ /** A scale and turn about a point that stays where it is: the usual way to write a zoom's step. */
29
+ export declare function similarityAbout(scale: number, turn: number, centre: SimilarityPoint): Similarity;
30
+ /** Where a similarity takes a point. */
31
+ export declare function applySimilarity(s: Similarity, p: SimilarityPoint): SimilarityPoint;
32
+ /** `first`, then `then`, as one similarity. */
33
+ export declare function composeSimilarity(first: Similarity, then: Similarity): Similarity;
34
+ /** The similarity that undoes this one. */
35
+ export declare function invertSimilarity(s: Similarity): Similarity;
36
+ /**
37
+ * The point a similarity leaves where it is (the centre of a zoom or a
38
+ * spiral), or null for a pure move, which has none.
39
+ */
40
+ export declare function similarityFixedPoint(s: Similarity): SimilarityPoint | null;
41
+ /**
42
+ * The similarity applied `k` times, for any real `k`: `powSimilarity(step,
43
+ * 0.5)` is half a step of a zoom, `-1` a step back. The fixed point stays
44
+ * put; a pure move scales its distance.
45
+ */
46
+ export declare function powSimilarity(s: Similarity, k: number): Similarity;
47
+ /** The 2D matrix `[a, b, c, d, e, f]` for `ctx.transform(...)` or a DOMMatrix. */
48
+ export declare function similarityMatrix(s: Similarity): [number, number, number, number, number, number];
@@ -10,4 +10,5 @@ export * from './node-video';
10
10
  export * from './narration-audio';
11
11
  export * from './node-audio';
12
12
  export * from './loop-check';
13
+ export * from './loop-audio';
13
14
  export { toSRT, toWebVTT, captionCuesFromTimeline, type CaptionCue } from '../engine/export/captions';
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Sound cut to a loop, on plain samples: a drone, a riser or a beat trimmed
3
+ * to exactly the loop's length with its end blended into its start, so the
4
+ * audio comes round as seamlessly as the picture. Pure; `cutAudioToLoop`
5
+ * (Node) decodes and writes the files.
6
+ */
7
+ export interface LoopSamplesOptions {
8
+ /** The loop's length, samples */
9
+ length: number;
10
+ /** How many samples the tail blends into the head over (default 2% of the length) */
11
+ crossfade?: number;
12
+ /** Fade the start in and the end out over this many samples (default none): a riser rising from nothing */
13
+ fadeIn?: number;
14
+ fadeOut?: number;
15
+ }
16
+ /**
17
+ * Exactly `length` samples that loop: the first `crossfade` samples blend
18
+ * from what followed the loop's end into its own start, so the end runs on
19
+ * into the beginning. Audio shorter than the loop is tiled first.
20
+ */
21
+ export declare function loopSamples(samples: Float32Array, options: LoopSamplesOptions): Float32Array;
@@ -39,6 +39,26 @@ export interface VoicedNarration {
39
39
  * write the whole narration as one WAV.
40
40
  */
41
41
  export declare function voiceNarration(scenes: VoicedScene[], options: VoiceNarrationOptions): Promise<VoicedNarration>;
42
+ export interface CutAudioToLoopOptions {
43
+ /** WAV file to write, relative to `baseDir` */
44
+ output: string;
45
+ /** The loop's length, ms (a looping scene's duration) */
46
+ period: number;
47
+ /** The tail blends into the head over this long, ms (default 2% of the period) */
48
+ crossfade?: number;
49
+ /** Fade in and out, ms (default none): a riser from nothing */
50
+ fadeIn?: number;
51
+ fadeOut?: number;
52
+ baseDir?: string;
53
+ sampleRate?: number;
54
+ ffmpeg?: string;
55
+ }
56
+ /**
57
+ * A drone, a riser or a beat cut to a loop: decode the file, trim it to the
58
+ * period with its end blended into its start (tiling it first if it is
59
+ * shorter), and write the WAV to pass as the scene's `audio`.
60
+ */
61
+ export declare function cutAudioToLoop(file: string, options: CutAudioToLoopOptions): Promise<string>;
42
62
  /** Decode an audio file to mono float samples with ffmpeg. */
43
63
  export declare function decodeAudio(file: string, options?: {
44
64
  sampleRate?: number;
@@ -38,6 +38,13 @@ export interface VideoScene {
38
38
  camera?: boolean | string;
39
39
  /** Length in ms (default: the timeline's duration) */
40
40
  duration?: number;
41
+ /**
42
+ * The video loops: its duration is the period every motion repeats over.
43
+ * Frames carry it as `period` (for `wobble`, `loopNoise`, `nestedZoom`…),
44
+ * 3D trails wrap at it, and `tinyfly video` checks the loop closes before
45
+ * it renders.
46
+ */
47
+ loop?: boolean;
41
48
  /** Animation data; its markers drive stills and captions */
42
49
  timeline?: TimelineDefinition;
43
50
  /** Canvas targets by id, drawn in insertion order; tracks address them by id */
@@ -75,6 +82,8 @@ export interface FrameInfo {
75
82
  index: number;
76
83
  /** Time in ms */
77
84
  time: number;
85
+ /** The loop's period, ms (the duration), when the scene has `loop: true` */
86
+ period?: number;
78
87
  /** Timeline state at `time`, when the scene has a timeline */
79
88
  state?: AnimationState;
80
89
  /** Timeline state at any other time (trails ask where things were), when the scene has a timeline */
@@ -3,8 +3,17 @@ import { type Mat4, type Vec3 } from '../engine/math';
3
3
  * Camera matrices and camera moves, as pure functions. A camera looks down
4
4
  * its own -z with +y up, as in WebGL and glTF.
5
5
  */
6
- /** A view matrix looking from `eye` at `target`, level (when looking straight up or down, -z is "up" instead). */
7
- export declare function lookAtView(eye: Vec3, target: Vec3): Mat4;
6
+ /**
7
+ * A view matrix looking from `eye` at `target`, level (when looking straight
8
+ * up or down, -z is "up" instead), with `up` as which way is up and `roll`
9
+ * degrees of roll about the view axis, clockwise on screen.
10
+ */
11
+ export declare function lookAtView(eye: Vec3, target: Vec3, options?: {
12
+ up?: Vec3;
13
+ roll?: number;
14
+ }): Mat4;
15
+ /** A view matrix rolled about its own axis: `roll` degrees clockwise on screen. */
16
+ export declare function rollView(view: Mat4, roll: number): Mat4;
8
17
  /**
9
18
  * A point on a sphere around `target`: `yaw` degrees around the up axis (0 is
10
19
  * in front, +z), `pitch` degrees up from level, `distance` metres away. Animate
@@ -8,6 +8,8 @@ export interface Mesh {
8
8
  /** Per vertex, unit length: what smooth (lambert) shading reads */
9
9
  normals: number[];
10
10
  indices: number[];
11
+ /** A colour per triangle, over the material's (a raw mesh's `colors`) */
12
+ faceColors?: string[];
11
13
  }
12
14
  /** A mesh edge: two vertex indices and the one or two triangles that share it. */
13
15
  export interface MeshEdge {
@@ -14,3 +14,10 @@ export declare function coneMesh(radius: number, height: number, segments?: numb
14
14
  export declare function torusMesh(radius: number, tube: number, segments?: number): Mesh;
15
15
  /** The mesh for a geometry description. */
16
16
  export declare function geometryMesh(geometry: Geometry3D): Mesh;
17
+ /** A mesh from raw arrays: normals computed flat (each vertex gets the average of its faces') when not given; colours per face. */
18
+ export declare function rawMesh(geometry: {
19
+ positions: number[];
20
+ indices: number[];
21
+ normals?: number[];
22
+ colors?: string[];
23
+ }): Mesh;
@@ -0,0 +1,29 @@
1
+ import type { MeshObject, OrthographicCamera } from './scene-types';
2
+ export interface PenroseTriangle3DOptions {
3
+ /** Object ids start with this (default `penrose`) */
4
+ id?: string;
5
+ /** The beams' length, metres (default 4) */
6
+ length?: number;
7
+ /** The beams' thickness, metres (default 0.8) */
8
+ thickness?: number;
9
+ /** The material key for the beams (default `penrose`) */
10
+ material?: string;
11
+ /** Where the figure's first corner goes (default the origin) */
12
+ position?: [number, number, number];
13
+ /** The camera's distance from the figure's middle, metres (default 20) */
14
+ distance?: number;
15
+ }
16
+ /**
17
+ * The Penrose triangle in a 3D scene, as the sculptures do it: three square
18
+ * beams along x, up y and along z, each starting where the last ends, the
19
+ * last ending one (1, 1, 1) diagonal from where the first begins. From the
20
+ * orthographic camera returned, looking down that diagonal, the ends meet on
21
+ * screen and the loop closes; from anywhere else it is three beams. Add the
22
+ * objects to a scene with a material of that name, and the camera (or any
23
+ * camera placed along the diagonal); animate `rotateY` on a group round it
24
+ * to break and remake the illusion.
25
+ */
26
+ export declare function penroseTriangle3D(options?: PenroseTriangle3DOptions): {
27
+ objects: MeshObject[];
28
+ camera: OrthographicCamera;
29
+ };
@@ -10,11 +10,12 @@ export { validateScene3D } from './validate-scene';
10
10
  export { loadScene3D, prepareMesh, type LoadedScene3D, type PreparedMesh, type LoadOptions } from './load-scene';
11
11
  export type { ObjectKind, ObjectContext, ObjectView, PlacedMesh, Drawable } from './object-kind';
12
12
  export { resolveScene3D, type ResolvedScene3D, type ResolvedDrawable, type ResolvedCamera, type ResolvedLight, type DrawTriangle, type SceneValues, type ScreenPoint, type ResolveOptions } from './resolve-scene';
13
- export { lookAtView, orbitPosition, dollyPosition, projectionMatrix } from './camera';
14
- export { shadeTriangle, lightAt, fogAmount, parseColor } from './shading';
13
+ export { lookAtView, rollView, orbitPosition, dollyPosition, projectionMatrix } from './camera';
14
+ export { shadeTriangle, inkColor, lightAt, fogAmount, parseColor } from './shading';
15
15
  export { Canvas2DRenderer, drawResolvedScene, type Renderer3D } from './canvas-2d-renderer';
16
16
  export { Scene3DAdapter, drawScene3D } from './scene-3d-adapter';
17
- export { boxMesh, planeMesh, sphereMesh, cylinderMesh, coneMesh, torusMesh, geometryMesh } from './geometry/primitives';
17
+ export { boxMesh, planeMesh, sphereMesh, cylinderMesh, coneMesh, torusMesh, geometryMesh, rawMesh } from './geometry/primitives';
18
18
  export { MeshBuilder, meshEdges, type Mesh, type MeshEdge } from './geometry/mesh';
19
19
  export { extrudeMesh, type ExtrudeOptions } from './geometry/extrude';
20
20
  export { triangulate, signedArea, pointInPolygon, type Point2 } from './geometry/triangulate';
21
+ export { penroseTriangle3D, type PenroseTriangle3DOptions } from './impossible-3d';
@@ -69,8 +69,13 @@ export interface DrawTriangle {
69
69
  color?: string;
70
70
  /** The object's opacity times the material's */
71
71
  opacity: number;
72
- /** Edges to ink on top of this triangle (silhouettes, creases, open rims), when the material has an outline */
72
+ /** Edges to ink on top of this triangle (silhouettes, creases, open rims), when it has an `ink` */
73
73
  outline: Array<[ScreenPoint, ScreenPoint]>;
74
+ /** The outline's look: the material's, with the object's `outlineWidth` and `outlineColor` over it */
75
+ ink?: {
76
+ width: number;
77
+ color: string;
78
+ };
74
79
  }
75
80
  /**
76
81
  * A visible mesh in world space, for renderers that keep geometry 3D (the
@@ -123,6 +128,13 @@ export interface ResolveOptions {
123
128
  * trails ask where what they follow was. Without it, trails draw nothing.
124
129
  */
125
130
  valuesAt?: (time: number) => SceneValues;
131
+ /** A looping video's period, ms: trails without their own `period` wrap at it */
132
+ period?: number;
133
+ /** Over the scene's `nearFade`: geometry nearer than `to` fades, gone at `from` (metres in front of the camera) */
134
+ nearFade?: {
135
+ from: number;
136
+ to: number;
137
+ };
126
138
  }
127
139
  /** The frame at these animated values (an `AnimationState`'s `values`, or none for the scene as authored). */
128
140
  export declare function resolveScene3D(loaded: LoadedScene3D, values: SceneValues | undefined, options: ResolveOptions): ResolvedScene3D;
@@ -47,6 +47,8 @@ export declare function drawScene3D(ctx: CanvasRenderingContext2D, scene: Loaded
47
47
  width: number;
48
48
  height: number;
49
49
  time?: number;
50
+ /** A looping video's period (a frame's `period`): trails wrap at it */
51
+ period?: number;
50
52
  valuesAt?: (time: number) => SceneValues;
51
53
  stateAt?: (time: number) => {
52
54
  values: SceneValues;
@@ -21,12 +21,17 @@ export interface Scene3D {
21
21
  materials?: Record<string, Material3D>;
22
22
  /** Background colour, or 'transparent' (default) */
23
23
  background?: string;
24
- /** Fog from `near` to `far` metres from the camera, toward `color` */
24
+ /** Fog from `near` to `far` metres from the camera, toward `color` (outlines fade with it too) */
25
25
  fog?: {
26
26
  color: string;
27
27
  near: number;
28
28
  far: number;
29
29
  };
30
+ /** Geometry nearer the camera than `to` metres fades out, gone at `from`: a dive passes through things as if they were glass */
31
+ nearFade?: {
32
+ from: number;
33
+ to: number;
34
+ };
30
35
  /** Realistic mode: an equirectangular HDR asset for light and reflections (stylized ignores it) */
31
36
  environment?: string;
32
37
  }
@@ -63,8 +68,14 @@ export interface MeshObject extends ObjectBase {
63
68
  /** A key of `materials` */
64
69
  material: string;
65
70
  }
66
- export interface PerspectiveCamera extends ObjectBase {
71
+ interface CameraBase extends ObjectBase {
67
72
  kind: 'camera';
73
+ /** Roll about the view axis, degrees, clockwise on screen (a `roll` track animates it) */
74
+ roll?: number;
75
+ /** Which way is up for `lookAt` (default +y) */
76
+ up?: Vec3Tuple;
77
+ }
78
+ export interface PerspectiveCamera extends CameraBase {
68
79
  projection: 'perspective';
69
80
  /** Vertical field of view, degrees */
70
81
  fov: number;
@@ -74,8 +85,7 @@ export interface PerspectiveCamera extends ObjectBase {
74
85
  /** A point to look at, overriding the camera's rotation */
75
86
  lookAt?: Vec3Tuple;
76
87
  }
77
- export interface OrthographicCamera extends ObjectBase {
78
- kind: 'camera';
88
+ export interface OrthographicCamera extends CameraBase {
79
89
  projection: 'orthographic';
80
90
  /** Height of the view, metres */
81
91
  height: number;
@@ -246,6 +256,20 @@ export type Geometry3D = {
246
256
  depth: number;
247
257
  width?: number;
248
258
  curveSegments?: number;
259
+ }
260
+ /**
261
+ * A raw triangle mesh: `positions` as flat x, y, z runs, `indices` as
262
+ * triples winding counter-clockwise seen from outside, `normals` per
263
+ * vertex (computed flat when left out), and `colors` per face or per
264
+ * vertex (one per triangle, or one per vertex blended per face), over the
265
+ * material's colour. Warped beams, terrain, anything a tool exported.
266
+ */
267
+ | {
268
+ type: 'mesh';
269
+ positions: number[];
270
+ indices: number[];
271
+ normals?: number[];
272
+ colors?: string[];
249
273
  };
250
274
  export interface Material3D {
251
275
  color: string;
@@ -269,3 +293,4 @@ export interface Material3D {
269
293
  roughness?: number;
270
294
  metalness?: number;
271
295
  }
296
+ export {};