@algorisys/tinyfly 0.100.0 → 0.102.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 +6 -6
- package/bin/tinyfly.mjs +16 -6
- 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 +22 -4
- package/docs/maps.md +2 -2
- package/docs/scene-3d.md +140 -9
- package/docs/teaching.md +1 -1
- package/docs/video-rendering.md +198 -1
- package/lib/addons/adapters.js +431 -332
- package/lib/addons/characters.js +3889 -3773
- package/lib/addons/load-scene-oWNsYYC1.js +372 -0
- package/lib/addons/scene-3d-webgl.js +31 -31
- package/lib/addons/scene-3d.js +669 -314
- package/lib/addons/shading-0lPgnXmD.js +96 -0
- package/lib/browser/tinyfly-scene-3d-webgl.iife.js +2 -2
- package/lib/browser/tinyfly-scene-3d.iife.js +2 -2
- package/lib/browser/tinyfly.iife.js +15 -15
- package/lib/browser/tinyfly.js +6232 -5723
- package/lib/browser/tinyfly.umd.js +15 -15
- package/lib/engine/tinyfly-engine.js +1563 -1170
- package/lib/engine/tinyfly-engine.umd.cjs +2 -2
- package/lib/headless/headless.js +189 -6
- package/lib/types/adapters/canvas/framing.d.ts +27 -0
- package/lib/types/adapters/canvas/impossible.d.ts +15 -0
- package/lib/types/adapters/canvas/index.d.ts +4 -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-script-3d.d.ts +21 -1
- package/lib/types/characters/character.d.ts +23 -3
- package/lib/types/characters/head/face.d.ts +19 -2
- package/lib/types/characters/index.d.ts +2 -1
- package/lib/types/characters/staging-3d.d.ts +56 -0
- 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/framing.d.ts +48 -0
- package/lib/types/engine/authoring/index.d.ts +4 -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/audio-mix.d.ts +40 -0
- package/lib/types/headless/ffmpeg-args.d.ts +2 -0
- package/lib/types/headless/frame-renderer.d.ts +7 -1
- package/lib/types/headless/index.d.ts +2 -0
- package/lib/types/headless/loop-audio.d.ts +21 -0
- package/lib/types/headless/node-audio.d.ts +39 -0
- package/lib/types/headless/node-video.d.ts +2 -0
- package/lib/types/headless/video-scene.d.ts +21 -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 +7 -3
- package/lib/types/scene-3d/lighting.d.ts +58 -0
- package/lib/types/scene-3d/resolve-scene.d.ts +18 -2
- package/lib/types/scene-3d/scene-3d-adapter.d.ts +4 -0
- package/lib/types/scene-3d/scene-types.d.ts +43 -6
- package/lib/types/scene-3d/shading.d.ts +2 -0
- package/lib/types/scene-3d/shots.d.ts +162 -0
- package/lib/types/scene-3d/software-renderer.d.ts +40 -0
- package/llms-full.txt +395 -23
- package/llms.txt +29 -29
- package/package.json +1 -1
- package/skills/tinyfly/SKILL.md +11 -1
- package/lib/addons/load-scene-CQvcFWGJ.js +0 -331
- package/lib/addons/shading-o5T_v9DT.js +0 -89
|
@@ -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];
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A sound mix on plain samples: a music bed, narration, sound effects at
|
|
3
|
+
* times, each with a gain and fades, the music ducked under the voice, all
|
|
4
|
+
* summed into one track for the video. Pure (no Node, no DOM); `renderMix`
|
|
5
|
+
* decodes files into it and writes the WAV.
|
|
6
|
+
*/
|
|
7
|
+
export interface MixLayer {
|
|
8
|
+
/** A name other layers' `duck` can point at */
|
|
9
|
+
id?: string;
|
|
10
|
+
/** Mono samples at the mix's sample rate */
|
|
11
|
+
samples: Float32Array;
|
|
12
|
+
/** When it starts, ms (default 0); with `at`, where each copy goes instead */
|
|
13
|
+
start?: number;
|
|
14
|
+
/** A sound effect: a copy at each of these times, ms */
|
|
15
|
+
at?: number[];
|
|
16
|
+
/** Volume, 1 as recorded (default 1) */
|
|
17
|
+
gain?: number;
|
|
18
|
+
/** Fades, ms (default none) */
|
|
19
|
+
fadeIn?: number;
|
|
20
|
+
fadeOut?: number;
|
|
21
|
+
/** Repeat the samples to the end of the mix (a bed shorter than the film) */
|
|
22
|
+
loop?: boolean;
|
|
23
|
+
/** Make way for another layer: while `under` sounds, drop to `1 − amount` (default 0.7 of the way down) */
|
|
24
|
+
duck?: {
|
|
25
|
+
under: string;
|
|
26
|
+
amount?: number;
|
|
27
|
+
attack?: number;
|
|
28
|
+
release?: number;
|
|
29
|
+
threshold?: number;
|
|
30
|
+
};
|
|
31
|
+
}
|
|
32
|
+
export interface MixOptions {
|
|
33
|
+
sampleRate: number;
|
|
34
|
+
/** The mix's length, ms */
|
|
35
|
+
duration: number;
|
|
36
|
+
/** Volume of the whole mix (default 1); the result is soft-limited so peaks do not clip */
|
|
37
|
+
master?: number;
|
|
38
|
+
}
|
|
39
|
+
/** Sum the layers into one mono track `duration` ms long, ducked where asked, soft-limited. */
|
|
40
|
+
export declare function mixAudio(layers: ReadonlyArray<MixLayer>, options: MixOptions): Float32Array;
|
|
@@ -16,6 +16,8 @@ export interface FfmpegOptions {
|
|
|
16
16
|
crf?: number;
|
|
17
17
|
/** x264 preset (default `medium`) */
|
|
18
18
|
preset?: string;
|
|
19
|
+
/** `h264` (default): an MP4 for the web. `prores`: Apple ProRes 422 HQ in a .mov for editing elsewhere (10-bit, PCM audio) */
|
|
20
|
+
codec?: 'h264' | 'prores';
|
|
19
21
|
}
|
|
20
22
|
export declare function ffmpegArgs(options: FfmpegOptions): string[];
|
|
21
23
|
/** Decode any audio file ffmpeg reads to mono 32-bit float samples on stdout. */
|
|
@@ -36,8 +36,14 @@ export declare class FrameRenderer {
|
|
|
36
36
|
id: string;
|
|
37
37
|
time: number;
|
|
38
38
|
}>;
|
|
39
|
-
/**
|
|
39
|
+
/**
|
|
40
|
+
* Clear the context and draw the scene at `time` ms. With `supersample` the
|
|
41
|
+
* frame is drawn larger and scaled down; with `motionBlur` it is the average
|
|
42
|
+
* of several drawings across the shutter's time.
|
|
43
|
+
*/
|
|
40
44
|
render(ctx: CanvasRenderingContext2D, time: number, index?: number): void;
|
|
45
|
+
/** One drawing of the scene at `time` on a context, at an output scale. */
|
|
46
|
+
private paint;
|
|
41
47
|
/** Run scene code without letting its context changes leak into the rest. */
|
|
42
48
|
private drawIsolated;
|
|
43
49
|
}
|
|
@@ -10,4 +10,6 @@ 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';
|
|
14
|
+
export * from './audio-mix';
|
|
13
15
|
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;
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { type NarrationLine, type NarrationOptions, type NarrationPlan } from '../engine/authoring/narration';
|
|
2
|
+
import { type MixLayer, type MixOptions } from './audio-mix';
|
|
2
3
|
/**
|
|
3
4
|
* Voice-over for a video: time the lines from their recorded clips and write
|
|
4
5
|
* the narration track.
|
|
@@ -39,6 +40,44 @@ export interface VoicedNarration {
|
|
|
39
40
|
* write the whole narration as one WAV.
|
|
40
41
|
*/
|
|
41
42
|
export declare function voiceNarration(scenes: VoicedScene[], options: VoiceNarrationOptions): Promise<VoicedNarration>;
|
|
43
|
+
export interface CutAudioToLoopOptions {
|
|
44
|
+
/** WAV file to write, relative to `baseDir` */
|
|
45
|
+
output: string;
|
|
46
|
+
/** The loop's length, ms (a looping scene's duration) */
|
|
47
|
+
period: number;
|
|
48
|
+
/** The tail blends into the head over this long, ms (default 2% of the period) */
|
|
49
|
+
crossfade?: number;
|
|
50
|
+
/** Fade in and out, ms (default none): a riser from nothing */
|
|
51
|
+
fadeIn?: number;
|
|
52
|
+
fadeOut?: number;
|
|
53
|
+
baseDir?: string;
|
|
54
|
+
sampleRate?: number;
|
|
55
|
+
ffmpeg?: string;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* A drone, a riser or a beat cut to a loop: decode the file, trim it to the
|
|
59
|
+
* period with its end blended into its start (tiling it first if it is
|
|
60
|
+
* shorter), and write the WAV to pass as the scene's `audio`.
|
|
61
|
+
*/
|
|
62
|
+
export declare function cutAudioToLoop(file: string, options: CutAudioToLoopOptions): Promise<string>;
|
|
63
|
+
export interface MixFileLayer extends Omit<MixLayer, 'samples'> {
|
|
64
|
+
/** The audio file, relative to `baseDir` (any format ffmpeg reads) */
|
|
65
|
+
file: string;
|
|
66
|
+
}
|
|
67
|
+
export interface RenderMixOptions extends Omit<MixOptions, 'sampleRate'> {
|
|
68
|
+
/** WAV file to write, relative to `baseDir` */
|
|
69
|
+
output: string;
|
|
70
|
+
baseDir?: string;
|
|
71
|
+
sampleRate?: number;
|
|
72
|
+
ffmpeg?: string;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* A film's sound: decode a music bed, the narration and sound effects, mix
|
|
76
|
+
* them (gains, fades, effects at times, the music ducked under the voice)
|
|
77
|
+
* and write the WAV to pass as the scene's `audio`; ffmpeg muxes it with the
|
|
78
|
+
* picture. `mixAudio` is the pure step.
|
|
79
|
+
*/
|
|
80
|
+
export declare function renderMix(layers: MixFileLayer[], options: RenderMixOptions): Promise<string>;
|
|
42
81
|
/** Decode an audio file to mono float samples with ffmpeg. */
|
|
43
82
|
export declare function decodeAudio(file: string, options?: {
|
|
44
83
|
sampleRate?: number;
|
|
@@ -22,6 +22,8 @@ export interface RenderVideoOptions extends HeadlessOptions {
|
|
|
22
22
|
preset?: string;
|
|
23
23
|
/** ffmpeg executable (default `ffmpeg`) */
|
|
24
24
|
ffmpeg?: string;
|
|
25
|
+
/** `h264` (default) or `prores` (a .mov for editing) */
|
|
26
|
+
codec?: 'h264' | 'prores';
|
|
25
27
|
/** Called after each frame */
|
|
26
28
|
onProgress?: (done: number, total: number) => void;
|
|
27
29
|
}
|
|
@@ -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 */
|
|
@@ -60,6 +67,18 @@ export interface VideoScene {
|
|
|
60
67
|
* See `applyBloom`.
|
|
61
68
|
*/
|
|
62
69
|
bloom?: boolean | BloomOptions;
|
|
70
|
+
/**
|
|
71
|
+
* Motion blur by sub-frame sampling: each frame is the average of `samples`
|
|
72
|
+
* drawings spread over the shutter's open time (`shutter` as a share of the
|
|
73
|
+
* frame, default 0.5: a 180° shutter). Deterministic; `samples` times the
|
|
74
|
+
* work.
|
|
75
|
+
*/
|
|
76
|
+
motionBlur?: {
|
|
77
|
+
samples: number;
|
|
78
|
+
shutter?: number;
|
|
79
|
+
};
|
|
80
|
+
/** Anti-aliasing by supersampling: draw at this many times the size and scale down (2 is plenty; 4× the work) */
|
|
81
|
+
supersample?: number;
|
|
63
82
|
/** Soundtrack to mux into the video, relative to the scene file */
|
|
64
83
|
audio?: string;
|
|
65
84
|
/** Font files to register before drawing, by family, relative to the scene file */
|
|
@@ -75,6 +94,8 @@ export interface FrameInfo {
|
|
|
75
94
|
index: number;
|
|
76
95
|
/** Time in ms */
|
|
77
96
|
time: number;
|
|
97
|
+
/** The loop's period, ms (the duration), when the scene has `loop: true` */
|
|
98
|
+
period?: number;
|
|
78
99
|
/** Timeline state at `time`, when the scene has a timeline */
|
|
79
100
|
state?: AnimationState;
|
|
80
101
|
/** 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
|
-
/**
|
|
7
|
-
|
|
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,15 @@ 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';
|
|
22
|
+
export { SoftwareRenderer, drawResolvedSceneWithDepth, rasterizeResolvedScene, type RasterImage, type RasterOptions } from './software-renderer';
|
|
23
|
+
export { shotAt, checkShots, snapShotsToBeats, shotTracks, shotMarkers, transitionAt, withActiveCamera, cameraPoseAt, cameraMoveTracks, cameraFollowTracks, cameraHandheldTracks, type Shot, type ShotTransition, type ActiveTransition, type CameraPose, type CameraMoveOptions, type CameraFollowOptions, type HandheldOptions } from './shots';
|
|
24
|
+
export { LIGHTING_PRESETS, lightingPreset, lightingTracks, ground, type LightingMood, type LightingPresetName, type LightingOptions, type LightingTrackOptions, type GroundOptions } from './lighting';
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import type { Track } from '../engine/types';
|
|
2
|
+
import type { LightObject, MeshObject, Material3D, Scene3D, SkyGradient } from './scene-types';
|
|
3
|
+
/**
|
|
4
|
+
* Light for mood, as data: presets (day, dusk, night, a stage spotlight)
|
|
5
|
+
* that give a scene its lights, sky and fog in one go, tracks that take the
|
|
6
|
+
* lights from one mood to another over a span, and a ground to stand things
|
|
7
|
+
* on. Every preset uses the same light ids (`key`, `fill`, `sky`, `spot`),
|
|
8
|
+
* so a change of mood is a change of values, never of objects.
|
|
9
|
+
*/
|
|
10
|
+
export interface LightingMood {
|
|
11
|
+
/** The lights, with the ids `key`, `fill`, `sky` and `spot` (a spot only where the mood has one) */
|
|
12
|
+
lights: Array<Omit<LightObject, 'id'> & {
|
|
13
|
+
id: 'key' | 'fill' | 'sky' | 'spot';
|
|
14
|
+
}>;
|
|
15
|
+
background: SkyGradient;
|
|
16
|
+
fog: NonNullable<Scene3D['fog']>;
|
|
17
|
+
}
|
|
18
|
+
export declare const LIGHTING_PRESETS: Record<'day' | 'dusk' | 'night' | 'stage', LightingMood>;
|
|
19
|
+
export type LightingPresetName = keyof typeof LIGHTING_PRESETS;
|
|
20
|
+
export interface LightingOptions {
|
|
21
|
+
/** Put this before each light's id (default none): `set-key`, `set-fill`… */
|
|
22
|
+
prefix?: string;
|
|
23
|
+
}
|
|
24
|
+
/** A mood's lights as scene objects, with its sky and fog to spread into the scene. */
|
|
25
|
+
export declare function lightingPreset(name: LightingPresetName, options?: LightingOptions): {
|
|
26
|
+
objects: LightObject[];
|
|
27
|
+
background: SkyGradient;
|
|
28
|
+
fog: NonNullable<Scene3D['fog']>;
|
|
29
|
+
};
|
|
30
|
+
export interface LightingTrackOptions extends LightingOptions {
|
|
31
|
+
scene: string;
|
|
32
|
+
/** ms */
|
|
33
|
+
start: number;
|
|
34
|
+
end: number;
|
|
35
|
+
easing?: Track['keyframes'][number]['easing'];
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Tracks that take a scene's lights from one mood to another over a span:
|
|
39
|
+
* each light's `color`, `intensity`, `position` and `target` keyed at the
|
|
40
|
+
* start and the end. A light one mood has and the other lacks fades out (or
|
|
41
|
+
* in). The scene must hold the preset's lights (see `lightingPreset`).
|
|
42
|
+
*/
|
|
43
|
+
export declare function lightingTracks(from: LightingPresetName, to: LightingPresetName, options: LightingTrackOptions): Track[];
|
|
44
|
+
export interface GroundOptions {
|
|
45
|
+
id?: string;
|
|
46
|
+
/** Metres across (default 24) */
|
|
47
|
+
size?: number;
|
|
48
|
+
color?: string;
|
|
49
|
+
/** Faces per side (default 24): more lets light pools and fog fall across it */
|
|
50
|
+
segments?: number;
|
|
51
|
+
/** Its height (default 0, the scene's ground) */
|
|
52
|
+
y?: number;
|
|
53
|
+
}
|
|
54
|
+
/** A ground to stand things on: a floor plane on layer −1 and its material, to spread into a scene. */
|
|
55
|
+
export declare function ground(options?: GroundOptions): {
|
|
56
|
+
objects: MeshObject[];
|
|
57
|
+
materials: Record<string, Material3D>;
|
|
58
|
+
};
|
|
@@ -58,6 +58,8 @@ export interface DrawTriangle {
|
|
|
58
58
|
screen: [ScreenPoint, ScreenPoint, ScreenPoint];
|
|
59
59
|
/** Distance in front of the camera, metres: what the draw order sorts by */
|
|
60
60
|
depth: number;
|
|
61
|
+
/** Each screen corner's distance in front of the camera, metres (a depth buffer interpolates these) */
|
|
62
|
+
depths: [number, number, number];
|
|
61
63
|
/** World centre of the face (lighting, fog) */
|
|
62
64
|
centroid: Vec3;
|
|
63
65
|
/** World face normal, unit, toward the viewer */
|
|
@@ -69,8 +71,15 @@ export interface DrawTriangle {
|
|
|
69
71
|
color?: string;
|
|
70
72
|
/** The object's opacity times the material's */
|
|
71
73
|
opacity: number;
|
|
72
|
-
/** Edges to ink on top of this triangle (silhouettes, creases, open rims), when
|
|
74
|
+
/** Edges to ink on top of this triangle (silhouettes, creases, open rims), when it has an `ink` */
|
|
73
75
|
outline: Array<[ScreenPoint, ScreenPoint]>;
|
|
76
|
+
/** The ink edges' end depths, metres, in `outline`'s order */
|
|
77
|
+
outlineDepths: Array<[number, number]>;
|
|
78
|
+
/** The outline's look: the material's, with the object's `outlineWidth` and `outlineColor` over it */
|
|
79
|
+
ink?: {
|
|
80
|
+
width: number;
|
|
81
|
+
color: string;
|
|
82
|
+
};
|
|
74
83
|
}
|
|
75
84
|
/**
|
|
76
85
|
* A visible mesh in world space, for renderers that keep geometry 3D (the
|
|
@@ -99,7 +108,7 @@ export interface ResolvedScene3D {
|
|
|
99
108
|
height: number;
|
|
100
109
|
/** ms: the moment drawn (for looks that move with time, such as a boiling pencil line) */
|
|
101
110
|
time: number;
|
|
102
|
-
background?:
|
|
111
|
+
background?: Scene3D['background'];
|
|
103
112
|
fog?: Scene3D['fog'];
|
|
104
113
|
camera: ResolvedCamera;
|
|
105
114
|
lights: ResolvedLight[];
|
|
@@ -123,6 +132,13 @@ export interface ResolveOptions {
|
|
|
123
132
|
* trails ask where what they follow was. Without it, trails draw nothing.
|
|
124
133
|
*/
|
|
125
134
|
valuesAt?: (time: number) => SceneValues;
|
|
135
|
+
/** A looping video's period, ms: trails without their own `period` wrap at it */
|
|
136
|
+
period?: number;
|
|
137
|
+
/** Over the scene's `nearFade`: geometry nearer than `to` fades, gone at `from` (metres in front of the camera) */
|
|
138
|
+
nearFade?: {
|
|
139
|
+
from: number;
|
|
140
|
+
to: number;
|
|
141
|
+
};
|
|
126
142
|
}
|
|
127
143
|
/** The frame at these animated values (an `AnimationState`'s `values`, or none for the scene as authored). */
|
|
128
144
|
export declare function resolveScene3D(loaded: LoadedScene3D, values: SceneValues | undefined, options: ResolveOptions): ResolvedScene3D;
|
|
@@ -47,6 +47,10 @@ 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;
|
|
52
|
+
/** Draw through a software depth buffer (shapes that cut through each other draw right; hard edges) instead of back to front */
|
|
53
|
+
depthBuffer?: boolean;
|
|
50
54
|
valuesAt?: (time: number) => SceneValues;
|
|
51
55
|
stateAt?: (time: number) => {
|
|
52
56
|
values: SceneValues;
|
|
@@ -19,14 +19,21 @@ export interface Scene3D {
|
|
|
19
19
|
/** In order: parents before children; array order breaks depth ties */
|
|
20
20
|
objects: Object3D[];
|
|
21
21
|
materials?: Record<string, Material3D>;
|
|
22
|
-
/** Background colour, or 'transparent' (default) */
|
|
23
|
-
background?: string;
|
|
24
|
-
/**
|
|
22
|
+
/** Background colour, or 'transparent' (default), or a sky: a vertical gradient from `top` to `bottom` */
|
|
23
|
+
background?: string | SkyGradient;
|
|
24
|
+
/** The ground's height, metres, where blob shadows lie (default 0) */
|
|
25
|
+
ground?: number;
|
|
26
|
+
/** Fog from `near` to `far` metres from the camera, toward `color` (outlines fade with it too) */
|
|
25
27
|
fog?: {
|
|
26
28
|
color: string;
|
|
27
29
|
near: number;
|
|
28
30
|
far: number;
|
|
29
31
|
};
|
|
32
|
+
/** Geometry nearer the camera than `to` metres fades out, gone at `from`: a dive passes through things as if they were glass */
|
|
33
|
+
nearFade?: {
|
|
34
|
+
from: number;
|
|
35
|
+
to: number;
|
|
36
|
+
};
|
|
30
37
|
/** Realistic mode: an equirectangular HDR asset for light and reflections (stylized ignores it) */
|
|
31
38
|
environment?: string;
|
|
32
39
|
}
|
|
@@ -62,9 +69,25 @@ export interface MeshObject extends ObjectBase {
|
|
|
62
69
|
geometry: Geometry3D;
|
|
63
70
|
/** A key of `materials` */
|
|
64
71
|
material: string;
|
|
72
|
+
/** A soft blob shadow on the ground under it (default none): `true`, or its opacity and a ground height of its own */
|
|
73
|
+
shadow?: boolean | {
|
|
74
|
+
opacity?: number;
|
|
75
|
+
ground?: number;
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
/** A sky as a vertical gradient: `top` at the top of the frame to `bottom` at the bottom. */
|
|
79
|
+
export interface SkyGradient {
|
|
80
|
+
top: string;
|
|
81
|
+
bottom: string;
|
|
65
82
|
}
|
|
66
|
-
|
|
83
|
+
interface CameraBase extends ObjectBase {
|
|
67
84
|
kind: 'camera';
|
|
85
|
+
/** Roll about the view axis, degrees, clockwise on screen (a `roll` track animates it) */
|
|
86
|
+
roll?: number;
|
|
87
|
+
/** Which way is up for `lookAt` (default +y) */
|
|
88
|
+
up?: Vec3Tuple;
|
|
89
|
+
}
|
|
90
|
+
export interface PerspectiveCamera extends CameraBase {
|
|
68
91
|
projection: 'perspective';
|
|
69
92
|
/** Vertical field of view, degrees */
|
|
70
93
|
fov: number;
|
|
@@ -74,8 +97,7 @@ export interface PerspectiveCamera extends ObjectBase {
|
|
|
74
97
|
/** A point to look at, overriding the camera's rotation */
|
|
75
98
|
lookAt?: Vec3Tuple;
|
|
76
99
|
}
|
|
77
|
-
export interface OrthographicCamera extends
|
|
78
|
-
kind: 'camera';
|
|
100
|
+
export interface OrthographicCamera extends CameraBase {
|
|
79
101
|
projection: 'orthographic';
|
|
80
102
|
/** Height of the view, metres */
|
|
81
103
|
height: number;
|
|
@@ -246,6 +268,20 @@ export type Geometry3D = {
|
|
|
246
268
|
depth: number;
|
|
247
269
|
width?: number;
|
|
248
270
|
curveSegments?: number;
|
|
271
|
+
}
|
|
272
|
+
/**
|
|
273
|
+
* A raw triangle mesh: `positions` as flat x, y, z runs, `indices` as
|
|
274
|
+
* triples winding counter-clockwise seen from outside, `normals` per
|
|
275
|
+
* vertex (computed flat when left out), and `colors` per face or per
|
|
276
|
+
* vertex (one per triangle, or one per vertex blended per face), over the
|
|
277
|
+
* material's colour. Warped beams, terrain, anything a tool exported.
|
|
278
|
+
*/
|
|
279
|
+
| {
|
|
280
|
+
type: 'mesh';
|
|
281
|
+
positions: number[];
|
|
282
|
+
indices: number[];
|
|
283
|
+
normals?: number[];
|
|
284
|
+
colors?: string[];
|
|
249
285
|
};
|
|
250
286
|
export interface Material3D {
|
|
251
287
|
color: string;
|
|
@@ -269,3 +305,4 @@ export interface Material3D {
|
|
|
269
305
|
roughness?: number;
|
|
270
306
|
metalness?: number;
|
|
271
307
|
}
|
|
308
|
+
export {};
|