vizmatic 0.8.1 → 0.9.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/PROMPT.md +42 -9
- package/README.md +172 -61
- package/ROADMAP.md +9 -6
- package/SCIENCE.md +70 -5
- package/assets/THIRD_PARTY_LICENSES.md +3 -3
- package/assets/fonts/SourceSerif4-24pt-SemiBold.ttf +0 -0
- package/assets/licenses/raster-codecs-MIT.txt +2 -2
- package/dist/chunk-6JI55YX4.js +604 -0
- package/dist/{chunk-LTX44BAE.js → chunk-BYKXNUX7.js} +25 -4
- package/dist/{chunk-ZB3HK7RM.js → chunk-EPZLNABN.js} +345 -25
- package/dist/chunk-EWCO6ZT6.js +696 -0
- package/dist/{chunk-DZHX76RS.js → chunk-G7HRSKHV.js} +33 -4
- package/dist/{chunk-RPAHMKAR.js → chunk-JTWC2OPN.js} +7 -5
- package/dist/chunk-LJZO36IR.js +124 -0
- package/dist/chunk-REL2BZ2B.js +88 -0
- package/dist/chunk-RLPEOWST.js +1 -0
- package/dist/chunk-VMHOWCDL.js +296 -0
- package/dist/chunk-YDD63HHD.js +1 -0
- package/dist/chunk-YNGDEARY.js +7230 -0
- package/dist/cli.js +124 -270
- package/dist/gpu-selection-CDWCZH27.js +1 -0
- package/dist/gpu-selection-MX6NHMNA.js +635 -0
- package/dist/index.cjs +1492 -217
- package/dist/index.d.cts +233 -230
- package/dist/index.d.ts +233 -230
- package/dist/index.js +1103 -479
- package/dist/math-E7W5LFWO.js +1 -0
- package/dist/{math-LXB4FH4E.js → math-NEFQUPRV.js} +3 -1
- package/dist/scene-browser-chunks/chunk-RQNLYYJN.js +70 -0
- package/dist/scene-browser-chunks/{scene-browser-layout-M3XSXMV4.js → scene-browser-layout-RC3ECYRK.js} +1 -1
- package/dist/scene-browser.js +18 -18
- package/dist/scene-cli.js +1 -1
- package/dist/scene-runtime.cjs +28 -5
- package/dist/scene-runtime.js +2 -2
- package/dist/{server-2FYHZ4UO.js → server-Q4COUZHV.js} +3 -3
- package/dist/stage-browser/browser.d.ts +8962 -685
- package/dist/stage-browser/gpu-renderer.js +138 -0
- package/dist/stage-browser/{math-4WFNHVV2.js → math-KYHUOK7A.js} +46 -10
- package/dist/stage-browser/stage.js +110 -5
- package/dist/stage-export.cjs +8616 -3888
- package/dist/stage-export.d.cts +65 -4
- package/dist/stage-export.d.ts +65 -4
- package/dist/stage-export.js +314 -325
- package/dist/stage.cjs +36997 -8756
- package/dist/stage.d.cts +8456 -634
- package/dist/stage.d.ts +8456 -634
- package/dist/stage.js +28135 -3502
- package/dist/{svg-import-C-RG1t7s.d.cts → svg-import-CSCFWYaB.d.cts} +473 -62
- package/dist/{svg-import-C-RG1t7s.d.ts → svg-import-CSCFWYaB.d.ts} +473 -62
- package/dist/teaching-math-DTKc0XsB.d.cts +243 -0
- package/dist/teaching-math-ydDBhJ2M.d.ts +243 -0
- package/dist/{video-BSwNJZkn.d.cts → theme-DhVdDQKO.d.cts} +4 -212
- package/dist/{video-BSwNJZkn.d.ts → theme-DhVdDQKO.d.ts} +4 -212
- package/dist/video-BYCeOz8F.d.ts +259 -0
- package/dist/video-CGLxJXqu.d.cts +259 -0
- package/examples/README.md +1 -1
- package/examples/_teaching/layer-stack-connector.ts +36 -0
- package/examples/_teaching/layer-stack-recurrence.ts +29 -0
- package/examples/_teaching/layer-stack-tiny-gpt.ts +37 -0
- package/examples/_teaching/layer-stack-transformer.ts +44 -0
- package/examples/catalog-convolution-kernel.tsx +6 -7
- package/examples/catalog-science-physics.tsx +6 -6
- package/examples/{aurora-incident.tsx → checkout-incident.tsx} +1 -1
- package/examples/films/_boltzmann-entropy/model.ts +63 -0
- package/examples/films/_catalysis/model.ts +49 -0
- package/examples/films/_gravitational-waves/model.ts +32 -0
- package/examples/films/_heat-equation/model.ts +54 -0
- package/examples/films/_hydrogen-orbitals/model.ts +31 -0
- package/examples/films/_maxwell/model.ts +84 -0
- package/examples/films/_planetary-orbits/appearance.ts +71 -0
- package/examples/films/_planetary-orbits/model.ts +152 -0
- package/examples/films/_planetary-orbits/saturn.ts +142 -0
- package/examples/films/_quantum-tunneling/model.ts +58 -0
- package/examples/films/_reaction-diffusion/model.ts +61 -0
- package/examples/films/_stationary-action/model.ts +38 -0
- package/examples/films/attention.ts +309 -253
- package/examples/films/beam-search.ts +324 -0
- package/examples/films/boltzmann-entropy.ts +104 -0
- package/examples/films/cache-miss.ts +387 -393
- package/examples/films/catalog.json +251 -60
- package/examples/films/catalysis.ts +128 -0
- package/examples/films/central-limit.ts +27 -22
- package/examples/films/complex-maps.ts +70 -56
- package/examples/films/deck-example.ts +261 -200
- package/examples/films/euler-circle.ts +72 -28
- package/examples/films/flash-attention.ts +549 -0
- package/examples/films/forecast.ts +354 -0
- package/examples/films/fourier-epicycles.ts +21 -20
- package/examples/films/gradient-descent.ts +23 -49
- package/examples/films/gravitational-waves.ts +179 -0
- package/examples/films/heat-equation.ts +124 -0
- package/examples/films/hydrogen-orbitals.ts +135 -0
- package/examples/films/io-uring.ts +635 -0
- package/examples/films/linear-maps.ts +42 -31
- package/examples/films/lorenz.ts +42 -79
- package/examples/films/maxwell.ts +197 -0
- package/examples/films/passage/chunking.ts +40 -0
- package/examples/films/passage/evidence.ts +44 -0
- package/examples/films/passage/prompt.ts +34 -0
- package/examples/films/pathlines.ts +85 -0
- package/examples/films/paxos.ts +596 -0
- package/examples/films/planetary-orbits.ts +146 -0
- package/examples/films/pythagoras.ts +18 -10
- package/examples/films/quantum-tunneling.ts +116 -0
- package/examples/films/rag-citations.ts +423 -0
- package/examples/films/reaction-diffusion.ts +70 -0
- package/examples/films/ring-allreduce.ts +531 -0
- package/examples/films/stationary-action.ts +170 -0
- package/examples/films/svd-3d.ts +605 -0
- package/examples/films/taylor-series.ts +10 -10
- package/examples/films/vizmatic-title.ts +1 -0
- package/examples/narrated-cues/README.md +32 -0
- package/examples/narrated-cues/data/numbers.json +1 -0
- package/examples/narrated-cues/film.json +9 -0
- package/examples/narrated-cues/film.ts +78 -0
- package/examples/narrated-cues/package.json +1 -0
- package/examples/narrated-cues/script.json +57 -0
- package/examples/narrated-cues/timing.json +1 -0
- package/examples/narrated-cues/tsconfig.json +1 -0
- package/examples/proofs/decoding-bars.ts +67 -0
- package/examples/proofs/pipeline.ts +27 -0
- package/examples/proofs/table/evaluation.ts +41 -0
- package/examples/proofs/table/ledger.ts +47 -0
- package/examples/proofs/table/routing.ts +46 -0
- package/examples/vizmatic-hero.tsx +102 -32
- package/package.json +11 -4
- package/templates/narrated/README.md +61 -0
- package/templates/narrated/data/numbers.json +5 -0
- package/templates/narrated/film.json +12 -0
- package/templates/narrated/film.ts +14 -0
- package/templates/narrated/gitignore +8 -0
- package/templates/narrated/package.json +1 -0
- package/templates/narrated/scenes/answer.ts +25 -0
- package/templates/narrated/scenes/kit.ts +39 -0
- package/templates/narrated/scenes/question.ts +31 -0
- package/templates/narrated/script.json +26 -0
- package/templates/narrated/sources.md +22 -0
- package/templates/narrated/timing.json +1 -0
- package/templates/narrated/tsconfig.json +1 -0
- package/tools/narration/README.md +123 -0
- package/tools/narration/beats.py +43 -0
- package/tools/narration/checks.py +587 -0
- package/tools/narration/draft.py +73 -0
- package/tools/narration/film.py +341 -0
- package/tools/narration/lag.py +58 -0
- package/tools/narration/mix.py +265 -0
- package/tools/narration/probe.py +99 -0
- package/tools/narration/record.py +33 -0
- package/tools/narration/resound.py +170 -0
- package/tools/narration/soundbed.py +404 -0
- package/tools/narration/sync.py +93 -0
- package/tools/narration/transcribe.py +84 -0
- package/tools/narration/verify.py +59 -0
- package/tools/narration/voice.py +113 -0
- package/dist/chunk-3F2VQ7NW.js +0 -1
- package/dist/chunk-6H2KTNJ7.js +0 -4774
- package/dist/chunk-6N6P2GJG.js +0 -88
- package/dist/math-QVCETQDQ.js +0 -1
- package/dist/scene-browser-chunks/chunk-5MVLYGXM.js +0 -70
package/PROMPT.md
CHANGED
|
@@ -15,10 +15,11 @@ For pnpm 11, allow esbuild's install script with `allowBuilds: { esbuild: true }
|
|
|
15
15
|
|
|
16
16
|
## Films
|
|
17
17
|
|
|
18
|
-
Start from a template, or write the function yourself. Templates are `explainer`, `equation`, `architecture`, `chart`, and `
|
|
18
|
+
Start from a template, or write the function yourself. Templates are `explainer`, `equation`, `architecture`, `chart`, `deck`, and `narrated`.
|
|
19
19
|
|
|
20
20
|
```bash
|
|
21
21
|
npx vizmatic new intro --template explainer
|
|
22
|
+
npx vizmatic new lesson --template narrated
|
|
22
23
|
```
|
|
23
24
|
|
|
24
25
|
```ts
|
|
@@ -60,7 +61,7 @@ Rules of the engine:
|
|
|
60
61
|
|
|
61
62
|
### Check, look, and export
|
|
62
63
|
|
|
63
|
-
|
|
64
|
+
Use checks and stills to inspect the picture. Play the export at normal speed with sound to judge the rhythm and the way motion meets speech.
|
|
64
65
|
|
|
65
66
|
```bash
|
|
66
67
|
npx vizmatic check intro.ts --json
|
|
@@ -68,11 +69,13 @@ npx vizmatic film intro.ts --frame 3,6.5,12 --width 1280 --out stills
|
|
|
68
69
|
npx vizmatic film intro.ts --out dist/films --look midnight,paper --quality high
|
|
69
70
|
```
|
|
70
71
|
|
|
71
|
-
|
|
72
|
+
Movie exports default to `--backend auto`: longer, demanding HD exports compare local CPU/GPU speed and sampled image quality. GPU rendering needs an installed Chrome, Edge, or Chromium; CI uses the CPU. `--backend cpu` forces software rendering, and `--backend gpu` requires a working GPU. `--encoder nvenc` requests NVIDIA H.264 encoding and fails if unavailable. Automatic film encoding retains `libx264` animation/grain settings. Hardware CQ and software CRF are different quality scales; inspect the resulting gradients and fine lines. `--json` records the selected backend, encoder, and selection reason.
|
|
72
73
|
|
|
73
|
-
|
|
74
|
+
`vizmatic check` samples the moments where the film comes to rest. It reports `film.off_canvas`, `film.text_edge`, `film.text_overlap`, `film.text_crossed`, and `film.missing_glyph`, each with times, a `box` in canvas pixels, and a `stage` center in authoring coordinates. Fix every error, then open the stills and look at them. `vizmatic preview intro.ts` opens a live player with a timeline for a person to review. The [Studio](https://bvolpato.github.io/vizmatic/studio.html) is a visual film editor in the browser for a person who wants to edit by hand.
|
|
74
75
|
|
|
75
|
-
|
|
76
|
+
The check does not look at motion, so a crossfade where two sentences overlap and a blank gap between two pictures both pass it. Add `--motion` to inspect every frame: `npx vizmatic check intro.ts --motion --json`. It reports a problem that appears only in motion as a warning, 0.2 seconds or more with nothing visible as `film.blank`, and text that leaves before a viewer can read it as `film.text_brief`. Judge each warning, because the check cannot tell a collision from one picture that replaces another. `--content-top <px>` sets where the content starts, so that a heading that stays up does not hide a blank. `--text-gap 0.3` also reports `film.text_crowded`: text that is nearer to a line, a shape, or an image than 0.3 of its font size, such as a caption that touches its figure, and text that runs past the edge of the shape behind it. `--text-size 26` flags unreadable small labels, `--empty-space 0.5` flags persistent large unused canvas areas, and `--stepped` checks chapter-stepped decks.
|
|
77
|
+
|
|
78
|
+
`--audio narration.wav` adds sound, padded or trimmed to the film's length, so hold until the voice ends. `s.caption(text, seconds)` writes a WebVTT sidecar and embeds a timed text track inside MP4 output while drawing nothing into the picture. For spoken lessons with `script.json`, `vizmatic narrated` (`build`, `voice`, `draft`, `mix`, `check`, `stills`, `sheet`, `beats`, `transcribe`, `sync`, `lag`, `probe`, `resound`) synthesizes per-beat takes, mixes background pads and cues (`vizmatic sounds list|export|bed`), checks every frame, and verifies voice-to-picture alignment. MP4 output is H.264 with settings that QuickTime can play. To join a clip to a film without encoding it again, encode the clip with `filmEncoderSettings(quality)` or `renderNarrationHold` from `vizmatic/stage/export`.
|
|
76
79
|
|
|
77
80
|
Motion guidance:
|
|
78
81
|
|
|
@@ -86,15 +89,45 @@ Motion guidance:
|
|
|
86
89
|
When a film must teach a topic, [lessons.md](https://bvolpato.github.io/vizmatic/references/lessons.md) has the full method. In short:
|
|
87
90
|
|
|
88
91
|
- Put accuracy first, then completeness, clarity, and brevity. There is no target length, so keep every passage that teaches.
|
|
89
|
-
- Finish the script before the film. Teach the problem, then the mechanism, then the limits.
|
|
90
|
-
- Compute every number in the film, and check it with `assert
|
|
92
|
+
- Finish the script before the film. Teach the problem, then the mechanism, then the limits. Carry a small example across a change when continuity helps. Switch examples when a fresh picture makes the next idea easier to see.
|
|
93
|
+
- Compute every number in the film, and check it with `assertEqual` from `'vizmatic/stage'` (never Node's `assert`, which breaks browser preview). The voice and the screen use the same values and the same rounding.
|
|
91
94
|
- Keep each title true for as long as it is visible. List every text block with its visible times, and read each one against the picture and the voice.
|
|
92
95
|
- Change pictures cleanly. Old text drops under about 25% opacity before new text reaches it, and something stays on screen through the change.
|
|
93
|
-
-
|
|
96
|
+
- Before publication, a person must watch the film at full speed with sound. Report which passages were played with sound and whether this full viewing has happened.
|
|
94
97
|
- Use the computed states from `vizmatic` where they fit: `weightedVectorState`, `categoricalSampling`, `planTeachingRoutedTransfer`, `byteDifferenceState`, and `tokenHistoryState`. Show the limits of each. `check` and `film` accept this import, and `preview` refuses it because it runs in the browser. A project with a checked canvas host can use the same constructions through `createTeachingCanvas(painter)`.
|
|
95
98
|
|
|
96
99
|
Read a finished film before you write a similar one. `examples/films/` in the package holds them with full source, and the [Films](https://bvolpato.github.io/vizmatic/films.html) page plays them.
|
|
97
100
|
|
|
101
|
+
### Scientific films
|
|
102
|
+
|
|
103
|
+
Use the same model values for the picture, equation, labels, and captions.
|
|
104
|
+
`tex.part()` and `.parts()` match formula structure, including scripts and local
|
|
105
|
+
macros; fragments without visible glyphs return no targets. `morphMatching`
|
|
106
|
+
preserves reordered symbols, pairing repeated symbols in reading order. `row`
|
|
107
|
+
aligns text and TeX baselines. Chemical notation uses bundled `mhchem`:
|
|
108
|
+
|
|
109
|
+
```ts
|
|
110
|
+
tex(String.raw`\ce{2 H2 + O2 -> 2 H2O}`)
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Use `axes` with `xScale` / `yScale` for linear, log, or symlog coordinates.
|
|
114
|
+
Opt into `plot(f, { adaptive: true, discontinuities: [[0, 0]] })` when uniform sampling
|
|
115
|
+
misses detail or bridges a known singularity. Use `scalarField` for concentrations
|
|
116
|
+
and probability slices, `contourPaths` for level curves, and `colorBar` with the
|
|
117
|
+
same fixed `domain`, `colors`, and `scale`. Label units and sampling limits.
|
|
118
|
+
`parametric` accepts the same adaptive options and parameter exclusions, with
|
|
119
|
+
tolerance measured in local pixels before later transforms.
|
|
120
|
+
|
|
121
|
+
`integrateTrajectory((t, state) => derivative, { initial, to, step })` precomputes
|
|
122
|
+
seekable RK4 trajectories. Check convergence; it is not a stiff solver.
|
|
123
|
+
`isosurface` renders an explicit scalar level inside `scene3d`. `molecule3d`
|
|
124
|
+
renders supplied coordinates or one supported V2000 MOL/SDF record, without
|
|
125
|
+
inferring bonds or conformations. Keep subject-specific physics in the film;
|
|
126
|
+
extract a public component only when it serves more than one model.
|
|
127
|
+
|
|
128
|
+
See `SCIENCE.md` and the Maxwell, hydrogen, reaction–diffusion, and catalysis films
|
|
129
|
+
for worked examples. Inspect full-size stills and browser playback in both looks.
|
|
130
|
+
|
|
98
131
|
## Figures
|
|
99
132
|
|
|
100
133
|
Create `frame.tsx`. `Scene` title and subtitle are optional.
|
|
@@ -157,4 +190,4 @@ After creating a visual, report:
|
|
|
157
190
|
- whether `vizmatic check` passed
|
|
158
191
|
- any overflow or layout fixes made
|
|
159
192
|
- for a film, which stills you opened, and whether you scanned the motion
|
|
160
|
-
-
|
|
193
|
+
- what you checked in stills, what you checked in playback, and any remaining review
|
package/README.md
CHANGED
|
@@ -3,31 +3,35 @@
|
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
5
|
<p align="center">
|
|
6
|
-
<strong>Explain
|
|
7
|
-
Vector films that play live in
|
|
6
|
+
<strong>Explain mechanisms in motion and in print, from TypeScript.</strong><br/>
|
|
7
|
+
Vector films with relational layout, TeX, and local narration that play live in the browser and export frame-exact to MP4.<br/>
|
|
8
|
+
Dense dark and light technical figures from TSX.
|
|
8
9
|
</p>
|
|
9
10
|
|
|
10
11
|
<p align="center">
|
|
11
12
|
<a href="https://github.com/bvolpato/vizmatic/actions/workflows/ci.yml"><img src="https://github.com/bvolpato/vizmatic/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
|
|
12
13
|
<a href="https://www.npmjs.com/package/vizmatic"><img src="https://img.shields.io/npm/v/vizmatic?color=%2334d058" alt="npm version" /></a>
|
|
14
|
+
<img src="https://img.shields.io/badge/node-%3E%3D20-43853d" alt="Node >= 20" />
|
|
13
15
|
<a href="https://github.com/bvolpato/vizmatic/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
|
|
14
16
|
</p>
|
|
15
17
|
|
|
16
18
|
<p align="center">
|
|
17
|
-
<a href="https://bvolpato.github.io/vizmatic/films.html"><img src="https://bvolpato.github.io/vizmatic/assets/films/fourier-epicycles.png" alt="A still from a Vizmatic film: rotating
|
|
19
|
+
<a href="https://bvolpato.github.io/vizmatic/films.html"><img src="https://bvolpato.github.io/vizmatic/assets/films/fourier-epicycles.png" alt="A still from a Vizmatic film: rotating Fourier epicycles trace a curve" width="840" /></a>
|
|
18
20
|
</p>
|
|
19
21
|
|
|
20
22
|
<p align="center">
|
|
21
23
|
<a href="https://bvolpato.github.io/vizmatic/films.html">Films</a> ·
|
|
22
24
|
<a href="https://bvolpato.github.io/vizmatic/docs/">Docs</a> ·
|
|
23
25
|
<a href="https://bvolpato.github.io/vizmatic/studio.html">Studio</a> ·
|
|
26
|
+
<a href="https://bvolpato.github.io/vizmatic/playground.html">Playground</a> ·
|
|
24
27
|
<a href="https://bvolpato.github.io/vizmatic/components.html">Components</a> ·
|
|
28
|
+
<a href="https://bvolpato.github.io/vizmatic/examples.html">Examples</a> ·
|
|
25
29
|
<a href="https://bvolpato.github.io/vizmatic/agents.html">For agents</a>
|
|
26
30
|
</p>
|
|
27
31
|
|
|
28
|
-
##
|
|
32
|
+
## Quick start: a film in 19 lines
|
|
29
33
|
|
|
30
|
-
Vizmatic
|
|
34
|
+
Vizmatic requires Node.js 20 or newer. MP4 and WebM export also require [FFmpeg](https://ffmpeg.org/download.html).
|
|
31
35
|
|
|
32
36
|
```bash
|
|
33
37
|
npm install vizmatic
|
|
@@ -36,51 +40,122 @@ npm install vizmatic
|
|
|
36
40
|
Create `intro.ts`:
|
|
37
41
|
|
|
38
42
|
```ts
|
|
39
|
-
import { axes, draw, fadeIn, film, tex, write } from 'vizmatic/stage'
|
|
43
|
+
import { axes, column, draw, fadeIn, film, place, sceneKit, tex, write } from 'vizmatic/stage'
|
|
44
|
+
|
|
45
|
+
export default film({ title: 'A parabola and its equation', font: 'text-serif' }, (s) => {
|
|
46
|
+
const { area, heading, note } = sceneKit()
|
|
47
|
+
const [left, right] = area.columns([2, 1])
|
|
48
|
+
|
|
49
|
+
s.add(heading('A parabola and its equation'))
|
|
50
|
+
const plot = place(axes({ x: [-3, 3], y: [-1, 9], width: 1000, height: 640, grid: true, labelSize: 28 }), left)
|
|
51
|
+
const eq = tex('y = x^2', { size: 84 })
|
|
52
|
+
const caption = note('slope doubles with x')
|
|
53
|
+
place(column([eq, caption], { gap: 'normal' }), right)
|
|
40
54
|
|
|
41
|
-
export default film({ title: 'My first film' }, (s) => {
|
|
42
|
-
const plot = s.add(axes({ x: [-3, 3], y: [-1, 9], grid: true }).at(-240, 40))
|
|
43
55
|
s.play(draw(plot.grid, { lag: 0.02 }), draw(plot.lines), fadeIn(plot.numbers))
|
|
44
|
-
s.play(draw(plot.plot((x) => x * x, { stroke: 'blue', width: 5 })))
|
|
45
|
-
s.play(write(
|
|
46
|
-
s.wait(1)
|
|
56
|
+
s.play(draw(plot.plot((x) => x * x, { stroke: 'blue', width: 5, glow: 6 })))
|
|
57
|
+
s.play(write(eq), fadeIn(caption))
|
|
58
|
+
s.wait(1.5)
|
|
47
59
|
})
|
|
48
60
|
```
|
|
49
61
|
|
|
50
|
-
|
|
62
|
+
Preview, check, inspect stills, and export:
|
|
51
63
|
|
|
52
64
|
```bash
|
|
53
|
-
npx vizmatic preview intro.ts
|
|
54
|
-
npx vizmatic check intro.ts
|
|
55
|
-
npx vizmatic film intro.ts --out
|
|
65
|
+
npx vizmatic preview intro.ts # live browser player with timeline, reloads on save
|
|
66
|
+
npx vizmatic check intro.ts --motion # static + per-frame collision, blank, and pacing scan
|
|
67
|
+
npx vizmatic film intro.ts --every 2 --sheet --out stills # timestamped contact sheet for visual review
|
|
68
|
+
npx vizmatic film intro.ts --look midnight,paper --quality high --out dist
|
|
56
69
|
```
|
|
57
70
|
|
|
58
|
-
`npx vizmatic new intro --template
|
|
71
|
+
Scaffold a working project with `npx vizmatic new intro --template explainer`. Built-in templates are `explainer`, `equation`, `architecture`, `chart`, `deck`, and `narrated`.
|
|
72
|
+
|
|
73
|
+
MP4 and WebM exports automatically compare CPU and GPU rendering for longer, demanding HD films when Chrome, Edge, or Chromium is installed locally. The comparison includes frame transfer and startup cost, and checks sampled pixels against the CPU renderer. Short exports and CI use the CPU. Use `--backend cpu` for reproducible software rendering or `--backend gpu` to require hardware rendering. Set `VIZMATIC_BROWSER_EXECUTABLE_PATH` if the browser is outside the usual locations.
|
|
74
|
+
|
|
75
|
+
For NVIDIA hardware encoding, use `--encoder nvenc`; FFmpeg must provide `h264_nvenc` and a working NVIDIA driver. A CUDA toolkit installation is not required. Drawing uses the browser's graphics backend, while NVENC encodes the video. Automatic film exports retain `libx264` animation and grain settings; hardware encoders have different quality scales, so inspect fine lines and dark gradients before delivery. `--json` reports the selected renderer, encoder, GPU, and selection reason.
|
|
76
|
+
|
|
77
|
+
<table>
|
|
78
|
+
<tr>
|
|
79
|
+
<td width="50%" align="center">
|
|
80
|
+
<a href="https://bvolpato.github.io/vizmatic/films.html"><img src="https://bvolpato.github.io/vizmatic/assets/films/attention.png" alt="Attention weights computed from real token vectors" /></a><br/>
|
|
81
|
+
<sub><strong>Scaled dot-product attention</strong> · computed weights, TeX, and live readouts</sub>
|
|
82
|
+
</td>
|
|
83
|
+
<td width="50%" align="center">
|
|
84
|
+
<a href="https://bvolpato.github.io/vizmatic/films.html"><img src="https://bvolpato.github.io/vizmatic/assets/films/cache-miss.png" alt="Cache hit and miss latency simulation" /></a><br/>
|
|
85
|
+
<sub><strong>Cache hit vs. database miss</strong> · queueing model, connectors, and system boxes</sub>
|
|
86
|
+
</td>
|
|
87
|
+
</tr>
|
|
88
|
+
</table>
|
|
89
|
+
|
|
90
|
+
## Domain objects on stage
|
|
91
|
+
|
|
92
|
+
Instead of assembling raw rectangles and coordinates for every explanation, `vizmatic/stage` includes relational layout and domain objects that measure their own labels, animate state transitions, and fail the build with actionable guidance when text does not fit. Run `npx vizmatic objects` to inspect the full catalog:
|
|
59
93
|
|
|
60
|
-
|
|
94
|
+
- **Layout and framing**: `sceneKit`, `sceneArea`, `row`, `column`, `grid`, `place`, `beside`, `between`, `fitted`, `boxOf`, `zone`, `card`, `steps`, `spotlight`, `focusOn`, `resetCamera`, `tagTrack`.
|
|
95
|
+
- **Math and scientific plots**: `tex` with structural term selection, matching morphs, and chemical notation; `axes` with linear/log/symlog scales and adaptive sampling; `contourPaths`, `scalarField`, `colorBar`, `integrateTrajectory`, `vectorField`, `streamLines`, `riemann`, `matrix`, `fourier`, and `epicycles`.
|
|
96
|
+
- **3D and chemistry**: `scene3d`, `surface`, `parametricSurface`, `isosurface`, `curve3d`, `point3d`, and `trail3d`; `molecule3d` renders supplied coordinates or a supported V2000 MOL/SDF record. See [the scientific guide](SCIENCE.md) for examples and model limits.
|
|
97
|
+
- **Systems, queues, and code**: `lanes` (actor timelines, child spans, deadlines, outages, boundary crossings), `pipeline` (stage gates, verdicts, counts, eject tray), `requestQueue`, `ringBuffer`, `boundary`, `stateGrid`, `bitField`, `eventLog`, `terminal`, `codeBlock` (including JSON, YAML, TLA+, Dafny, Lean, and SMT), `morphCode`, `connector` (`avoid`, `pulse`, `send`), `infoBox`, `pictogram` (57+ technical icons).
|
|
98
|
+
- **Models, data, and prose**: `layerStack`, `tokens`, `attentionMatrix`, `neuralNet`, `heatmap`, `barChart`, `histogram`, `scatter` (cells, hulls, k-NN), `dotChart` (linear or log), `segmentedBar`, `unitChart`, `lineChart`, `pie`, `donut`, `sparkline`, `table`, `passage` (claim marks, source links, diffs, chunking), `quote`, `quotePair`, `dateLine`.
|
|
61
99
|
|
|
62
|
-
|
|
100
|
+
## Narrated lessons and sound
|
|
63
101
|
|
|
64
|
-
|
|
102
|
+
For lessons driven by a voiceover, `--template narrated` creates a self-contained folder with `script.json`, `film.json`, `film.ts`, and `scenes/`. One incremental command synthesizes speech locally, mixes audio, checks layout, and renders the movie:
|
|
65
103
|
|
|
66
|
-
|
|
104
|
+
```bash
|
|
105
|
+
npx vizmatic new cache-lesson --template narrated
|
|
106
|
+
npx vizmatic narrated build cache-lesson --draft # local voice, sound mix, layout check, cache-lesson-draft.mp4
|
|
107
|
+
npx vizmatic narrated build cache-lesson # full delivery render with MP4 chapters and captions
|
|
108
|
+
```
|
|
67
109
|
|
|
68
|
-
|
|
110
|
+
Scenes lock visual changes directly to spoken phrases through `SceneClock`. If the script changes and a phrase disappears or occurs twice, the build stops with the exact scene and phrase rather than drifting out of sync:
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
import { assertEqual, narrated, place, type SceneClock, type Stage } from 'vizmatic/stage'
|
|
114
|
+
import timing from './timing.json'
|
|
115
|
+
import { claimTag, display, heading, kit, source } from './scenes/kit'
|
|
69
116
|
|
|
70
|
-
|
|
117
|
+
assertEqual(800 / 5, 160, 'speedup matches the spoken claim')
|
|
118
|
+
|
|
119
|
+
function answer(s: Stage, c: SceneClock) {
|
|
120
|
+
s.add(heading('With a cache in front'), source('Measured on warm hits'))
|
|
121
|
+
claimTag(c, { word: 'MEASURED', note: 'local benchmark' })
|
|
122
|
+
const speedup = place(display('160x faster'), kit.area)
|
|
123
|
+
c.show('one hundred and sixty times', speedup, { after: true })
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
export default narrated({ title: 'Why a cache matters', timing, scenes: { answer } })
|
|
127
|
+
```
|
|
71
128
|
|
|
72
|
-
|
|
129
|
+
Verify speech, cues, and sound from the CLI (`npx vizmatic narrated` lists every step):
|
|
73
130
|
|
|
74
|
-
|
|
131
|
+
- `vizmatic narrated beats <folder> --words` prints beat windows and spoken words to pick cues.
|
|
132
|
+
- `vizmatic narrated stills <folder>` and `sheet <folder>` render per-beat full-resolution stills and contact sheets.
|
|
133
|
+
- `vizmatic narrated transcribe <folder>`, `sync <folder>`, `lag <folder>`, and `probe <folder>` verify TTS pronunciation against `script.json`, measure audio-to-video alignment, and inspect streams, chapters, captions, and file hashes.
|
|
134
|
+
- `vizmatic narrated resound <folder>` swaps an updated `narration.wav` into a rendered MP4 without re-rendering frames.
|
|
135
|
+
- `vizmatic sounds list`, `vizmatic sounds render <tap|slide|latch|resolve|bell> --out cue.wav`, and `vizmatic sounds bed --voice narration.wav --out bed.wav --palette warm --timing timing.json` generate subtle cues and ducked stereo beds.
|
|
75
136
|
|
|
76
|
-
|
|
137
|
+
Read the [narrated films guide](https://github.com/bvolpato/vizmatic/blob/main/docs/guides/narrated-films.md) for the full workflow.
|
|
138
|
+
|
|
139
|
+
## Dense figures from TSX
|
|
140
|
+
|
|
141
|
+
For documentation, papers, architecture reviews, and slides, write TSX with typed components from `vizmatic`. Figures default to the `dense` density (10 to 12 px detail type, hairlines, and tight gutters) and render dark and light PNG and SVG from one source.
|
|
142
|
+
|
|
143
|
+
<p align="center">
|
|
144
|
+
<a href="https://bvolpato.github.io/vizmatic/examples.html">
|
|
145
|
+
<picture>
|
|
146
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/data-pipeline-lineage_dark.png" />
|
|
147
|
+
<source media="(prefers-color-scheme: light)" srcset="https://bvolpato.github.io/vizmatic/assets/examples/data-pipeline-lineage_light.png" />
|
|
148
|
+
<img src="https://bvolpato.github.io/vizmatic/assets/examples/data-pipeline-lineage_dark.png" alt="Data pipeline lineage figure rendered from TSX" width="840" />
|
|
149
|
+
</picture>
|
|
150
|
+
</a>
|
|
151
|
+
</p>
|
|
77
152
|
|
|
78
153
|
```tsx
|
|
79
|
-
<Scene title="Checkout
|
|
154
|
+
<Scene title="Checkout read path" subtitle="Envoy -> Cart -> Orders replica">
|
|
80
155
|
<Flow
|
|
81
156
|
stages={[
|
|
82
157
|
{ title: "Gateway", subtitle: "Envoy, p99 9 ms", tone: "blue" },
|
|
83
|
-
{ title: "Cart", subtitle: "Go, 840 rps", tone: "purple" },
|
|
158
|
+
{ title: "Cart service", subtitle: "Go, 840 rps", tone: "purple" },
|
|
84
159
|
{ title: "Orders DB", subtitle: "Postgres, primary + 3", tone: "green" },
|
|
85
160
|
]}
|
|
86
161
|
/>
|
|
@@ -88,63 +163,99 @@ Render a TSX figure in each theme:
|
|
|
88
163
|
```
|
|
89
164
|
|
|
90
165
|
```bash
|
|
91
|
-
npx vizmatic ./frame.tsx --
|
|
166
|
+
npx vizmatic check ./frame.tsx --theme dark,light --json
|
|
167
|
+
npx vizmatic render ./frame.tsx --out ./figures --theme dark,light --format both
|
|
92
168
|
```
|
|
93
169
|
|
|
94
|
-
|
|
170
|
+
- Omit `width` and `height` while iterating: bare `.tsx` frames start at `960x540` and auto-grow to fit content.
|
|
171
|
+
- Outputs are alpha-transparent by default; pass `--background theme` (or `background={c.bg}`) for an opaque canvas, and `preset = "engineering";` with `--theme light` for flat technical paper figures.
|
|
172
|
+
- Switch to `density="presentation"` (or `--density presentation`) when placing the same scene on a slide.
|
|
173
|
+
- Convert existing Mermaid or D2 diagrams into `GraphDiagram` props with `importMermaid` and `importD2`, or animate existing TSX figures to GIF and MP4 with `defineAnimation` (`vizmatic gif` and `vizmatic video`).
|
|
95
174
|
|
|
96
|
-
|
|
175
|
+
Browse the [component catalog](https://bvolpato.github.io/vizmatic/components.html), [examples gallery](https://bvolpato.github.io/vizmatic/examples.html), and [interactive playground](https://bvolpato.github.io/vizmatic/playground.html).
|
|
97
176
|
|
|
98
|
-
|
|
177
|
+
## What makes Vizmatic different
|
|
99
178
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
| `byteDifference` | [Locate a changed byte while retaining offsets and escaped control characters](examples/_teaching/teaching-byte-diff.ts) |
|
|
106
|
-
| `tokenHistory` | [Drop and rebuild KV while preserving accepted and emitted tokens](examples/_teaching/teaching-token-history.ts) |
|
|
179
|
+
- **Real geometry on stage.** Lines, glyphs, TeX equations, and grids are Bezier paths. Any path can draw itself, morph into another shape, or bend through a function, and `morphMatching` carries shared terms cleanly across steps of a derivation.
|
|
180
|
+
- **Pure function of time.** A film compiles once into a deterministic timeline that can be sampled at any timestamp in any order. Scrubbing is instant, identical frames share buffers automatically, and worker threads rasterize in parallel with optional motion blur and dithered bloom.
|
|
181
|
+
- **Five looks and two figure themes.** Films author against semantic tokens (`blue`, `teal`, `yellow`, `ink`, `dim`) and render across `midnight`, `paper`, `blueprint`, `chalk`, and `neon`. TSX figures render coordinated `dark` and `light` palettes.
|
|
182
|
+
- **Defects reported as structured data.** `vizmatic check --json` and `vizmatic check --motion --json` return clipped text, edge crowding (`--text-gap`), phone-unreadable type (`--text-size`), empty regions (`--empty-space`), strokes crossing text, brief flashes, and blank gaps with exact timestamps and bounding boxes.
|
|
183
|
+
- **Live web playback, visual Studio, and QuickJS sandboxing.** Embed live, seekable films anywhere with `<vz-film>` (including `<vz-film stepped>` for chapter decks), edit visually in [Studio](https://bvolpato.github.io/vizmatic/studio.html), or evaluate untrusted bare TSX inside a deterministic offline QuickJS sandbox via `vizmatic/scene-runtime` and `vizmatic-scene`.
|
|
107
184
|
|
|
108
|
-
|
|
185
|
+
## CLI at a glance
|
|
186
|
+
|
|
187
|
+
| Command | Purpose |
|
|
188
|
+
|---|---|
|
|
189
|
+
| `vizmatic new <name> [--template ...]` | Scaffold a film (`explainer`, `equation`, `architecture`, `chart`, `deck`, or `narrated`) |
|
|
190
|
+
| `vizmatic preview <file> [--port <n>] [--open]` | Live browser player with timeline scrubbing and hot reload |
|
|
191
|
+
| `vizmatic check <file-or-dir...> [--motion] [--json]` | Check films (`--motion`, `--text-gap`, `--text-size`, `--empty-space`, `--stepped`) or TSX frames (`--theme dark,light`) |
|
|
192
|
+
| `vizmatic film <file...> [--out <dir>]` | Export MP4, WebM, GIF, PNG stills (`--frame`, `--every`, `--sheet`), SVG, posters, captions, and chapters |
|
|
193
|
+
| `vizmatic narrated <step> <folder>` | Build, voice, mix, check, stills, sheet, beats, transcribe, sync, lag, probe, or resound narrated lessons |
|
|
194
|
+
| `vizmatic objects [--json]` / `vizmatic looks [--json]` | List stage domain objects and color looks |
|
|
195
|
+
| `vizmatic sounds <list\|render\|bed>` | List or synthesize sound effects and ducked stereo ambient beds |
|
|
196
|
+
| `vizmatic [render] <file-or-dir...>` | Render TSX figures to dark/light PNG and SVG (`--density`, `--background`, `--format png\|svg\|both`) |
|
|
197
|
+
| `vizmatic gif <file...>` / `vizmatic video <file...>` | Render animated TSX timelines (`createAnimation`) to GIF or MP4 |
|
|
198
|
+
| `vizmatic-scene --input req.json --output out.png\|out.mp4` | Render untrusted bare TSX inside the bounded QuickJS scene sandbox |
|
|
199
|
+
|
|
200
|
+
## Checked teaching helpers
|
|
201
|
+
|
|
202
|
+
For custom hosts and verified mechanism animations, Vizmatic exports pure state calculators (`vizmatic`), audio hold tools (`vizmatic/stage/export`), and `createTeachingCanvas(painter)` methods so displayed numbers and geometry come from one checked calculation:
|
|
203
|
+
|
|
204
|
+
| Helper / canvas component | Purpose and worked example |
|
|
205
|
+
|---|---|
|
|
206
|
+
| `weightedVectorState` / `vectorAccumulation` | [Retain momentum, add an opposing gradient, then reveal the resultant](examples/_teaching/teaching-weighted-vector.ts) |
|
|
207
|
+
| `categoricalSampling` | [Map supplied uniform draws through a CDF and watch tail loss](examples/_teaching/categorical-tail-loss.ts) |
|
|
208
|
+
| `planTeachingRoutedTransfer` / `routedTransfer` | [Route orthogonal value transfers around declared obstacles](examples/_teaching/teaching-routed-transfer.ts) |
|
|
209
|
+
| `byteDifferenceState` / `byteDifference` | [Locate changed bytes with stable offsets and escaped control bytes](examples/_teaching/teaching-byte-diff.ts) |
|
|
210
|
+
| `tokenHistoryState` / `tokenHistory` | [Drop and rebuild KV cache while preserving accepted and emitted tokens](examples/_teaching/teaching-token-history.ts) |
|
|
211
|
+
| `pcmEnvelope` / `waveform`, `renderNarrationHold` | Time-synced PCM waveform envelopes with cursors, plus 48 kHz speech-and-demo audio holds |
|
|
212
|
+
| `layoutCellGrid` / `tileTransfer`, `rasterWipe`, `planSampleCopies` | Checked grid addressing, row-staggered tile transfers, raster wipes, and sample-copy trajectories |
|
|
213
|
+
| `softmaxTileMass`, `combineSoftmaxMass`, `traceCrossCorrelation2d` | Online/tiled softmax mass summaries and 2D kernel cross-correlation traces |
|
|
214
|
+
| `createCueTrack`, `assertCueReveal` | Hold discrete snapshots across cues and verify answers never appear before their spoken phrase |
|
|
215
|
+
|
|
216
|
+
See the [canvas and TSX animation guide](https://bvolpato.github.io/vizmatic/docs/tsx-animation.html) for the painter contract and scope rules.
|
|
109
217
|
|
|
110
218
|
## For coding agents
|
|
111
219
|
|
|
112
|
-
Install the skill. It teaches
|
|
220
|
+
Install the bundled skill for Codex, Claude Code, Gemini CLI, Cursor, or OpenCode. It teaches output selection, relational stage layout, narrated film workflows, TSX figure density, and check loops:
|
|
113
221
|
|
|
114
222
|
```bash
|
|
115
223
|
npx skills add bvolpato/vizmatic --skill vizmatic -g -y
|
|
116
224
|
```
|
|
117
225
|
|
|
118
|
-
Agents can also read [`llms.txt`](https://bvolpato.github.io/vizmatic/llms.txt)
|
|
226
|
+
Agents can also read [`llms.txt`](https://bvolpato.github.io/vizmatic/llms.txt) and [`PROMPT.md`](PROMPT.md), or query `npx vizmatic objects --json` and `npx vizmatic looks --json` for the exact capabilities of the installed package.
|
|
119
227
|
|
|
120
228
|
## Documentation
|
|
121
229
|
|
|
122
|
-
|
|
|
230
|
+
| Guide | What it covers |
|
|
123
231
|
|---|---|
|
|
124
|
-
| [Getting started](https://bvolpato.github.io/vizmatic/docs/) |
|
|
125
|
-
| [Core concepts](https://bvolpato.github.io/vizmatic/docs/concepts.html) |
|
|
126
|
-
| [
|
|
127
|
-
| [
|
|
128
|
-
| [
|
|
129
|
-
| [
|
|
130
|
-
| [
|
|
131
|
-
| [
|
|
132
|
-
| [
|
|
133
|
-
| [
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
232
|
+
| [Getting started](https://bvolpato.github.io/vizmatic/docs/) | First film, preview, check, and export in two minutes |
|
|
233
|
+
| [Core concepts](https://bvolpato.github.io/vizmatic/docs/concepts.html) | Stage coordinates, pure timelines, and looks |
|
|
234
|
+
| [Layout](https://github.com/bvolpato/vizmatic/blob/main/docs/guides/layout.md) | Relational placement with `sceneKit`, `row`, `column`, `grid`, `place`, `beside`, and `fitted` |
|
|
235
|
+
| [Objects](https://bvolpato.github.io/vizmatic/docs/objects.html) | Math, plots, systems, queues, code, ML, prose, and 3D objects |
|
|
236
|
+
| [Narrated films](https://github.com/bvolpato/vizmatic/blob/main/docs/guides/narrated-films.md) | Script format, local TTS, `SceneClock`, motion checks, and delivery review |
|
|
237
|
+
| [Looks](https://bvolpato.github.io/vizmatic/docs/looks.html) | Semantic pigments and rendering across `midnight`, `paper`, `blueprint`, `chalk`, and `neon` |
|
|
238
|
+
| [CLI](https://bvolpato.github.io/vizmatic/docs/cli.html) and [Exporting](https://bvolpato.github.io/vizmatic/docs/exporting.html) | Every command, format, quality preset, sheet, and manifest |
|
|
239
|
+
| [Embedding](https://bvolpato.github.io/vizmatic/docs/embedding.html) and [Presentations](https://bvolpato.github.io/vizmatic/docs/presentations.html) | Live `<vz-film>` web player and chapter-stepped slide decks |
|
|
240
|
+
| [Diagrams and density](https://bvolpato.github.io/vizmatic/docs/diagrams.html) and [Figures](https://bvolpato.github.io/vizmatic/docs/figures.html) | Typed TSX components, themes, and engineering paper figures |
|
|
241
|
+
| [Editable scenes](https://bvolpato.github.io/vizmatic/docs/editable-scenes.html) | Evaluating untrusted TSX in a bounded QuickJS sandbox |
|
|
242
|
+
| [TSX animation](https://bvolpato.github.io/vizmatic/docs/tsx-animation.html) | Typed TSX timelines and checked teaching canvas hosts |
|
|
243
|
+
| [Science guide](SCIENCE.md) | Accurate math, physics, chemistry, and ML diagrams |
|
|
244
|
+
| [Roadmap](ROADMAP.md) and [Contributing](https://github.com/bvolpato/vizmatic/blob/main/CONTRIBUTING.md) | Shipped milestones, repository checks, and release workflow |
|
|
245
|
+
|
|
246
|
+
## Requirements and installation
|
|
247
|
+
|
|
248
|
+
- **Node.js 20+** is required for all commands. Vizmatic bundles its tested Satori renderer, self-hosted fonts, and Twemoji vector subset with no dependency overrides required.
|
|
249
|
+
- **FFmpeg** (`libx264`, `libvpx-vp9`, `aac`) is required on `PATH` for MP4, WebM, and audio muxing. PNG, SVG, and GIF exports run without FFmpeg.
|
|
250
|
+
- **`uv`** is required on `PATH` only when running local speech synthesis, transcription, or sound-bed tools (`vizmatic narrated`, `vizmatic sounds`).
|
|
251
|
+
|
|
252
|
+
For **pnpm 11**, allow esbuild's install script in the root `pnpm-workspace.yaml` so the CLI can compile films and frames:
|
|
140
253
|
|
|
141
254
|
```yaml
|
|
142
255
|
allowBuilds:
|
|
143
256
|
esbuild: true
|
|
144
257
|
```
|
|
145
258
|
|
|
146
|
-
Then add Vizmatic with your package manager.
|
|
147
|
-
|
|
148
259
|
## License
|
|
149
260
|
|
|
150
|
-
MIT. Bundled fonts and
|
|
261
|
+
MIT. Bundled fonts and third-party assets retain their own licenses; see [`assets/THIRD_PARTY_LICENSES.md`](assets/THIRD_PARTY_LICENSES.md).
|
package/ROADMAP.md
CHANGED
|
@@ -6,16 +6,19 @@ This page states what Vizmatic can do now and what comes next. Vizmatic aims to
|
|
|
6
6
|
|
|
7
7
|
### Films
|
|
8
8
|
|
|
9
|
-
- A
|
|
9
|
+
- A deterministic animation engine in `vizmatic/stage`. Vector shapes can trace, morph, and bend; sampled fields and imported images share their transforms and export path.
|
|
10
10
|
- A timeline that is a pure function of time. Any frame can be sampled in any order, so scrubbing is instant and output is reproducible.
|
|
11
11
|
- TeX glyphs for equations, with `morphMatching` to carry shared terms between lines.
|
|
12
12
|
- Objects for math, charts, computer science, and systems, plus 3D scenes with surfaces, curves, and an orbiting camera.
|
|
13
|
+
- Scientific plots with log/symlog axes, adaptive sampling, contours, sampled scalar fields, numeric color bars, RK4 trajectories, and implicit 3D surfaces.
|
|
14
|
+
- Structural equation targeting, reordered symbol morphs, chemical typesetting, and supplied 3D molecules with a bounded V2000 MOL/SDF importer.
|
|
13
15
|
- Five looks, gradient strokes, glow, and bloom.
|
|
14
16
|
- `<vz-film>`, a live, seekable player for any page, with chapters and a stepped presentation mode.
|
|
15
17
|
- `fromSvg` and `fromComponent`, which turn any SVG or TSX figure into shapes that films can animate.
|
|
16
|
-
- Export to MP4 and WebM with BT.709 color, GIF with a shared palette, PNG, and SVG. Frames rasterize on worker threads with a memory limit, with optional motion blur.
|
|
17
|
-
- `vizmatic new`, `preview`, `check`, `film`, `looks`, and `objects`. Preview reloads on save and keeps the playhead.
|
|
18
|
-
-
|
|
18
|
+
- Export to MP4 and WebM with BT.709 color, GIF with a shared palette, PNG, and SVG. Frames rasterize on worker threads with a memory limit, with optional motion blur, embedded MP4 chapter and caption tracks, and WebVTT sidecars.
|
|
19
|
+
- `vizmatic new`, `preview`, `check`, `film`, `narrated`, `sounds`, `looks`, and `objects`. Preview reloads on save and keeps the playhead.
|
|
20
|
+
- Narrated teaching films with `vizmatic narrated`: spoken beat takes, `timing.json` synchronization, background pads and cue sound effects (`vizmatic sounds`), transcript verification, and audio lag checks.
|
|
21
|
+
- `vizmatic check` for films: off-canvas marks, overlapping text, strokes through text, crowded text, small labels, and empty canvas space, with times and bounding boxes as JSON. `--motion` inspects every frame for collisions and blank gaps between pictures.
|
|
19
22
|
- The Studio, which builds and exports a film in the browser.
|
|
20
23
|
|
|
21
24
|
### Figures
|
|
@@ -34,10 +37,10 @@ This page states what Vizmatic can do now and what comes next. Vizmatic aims to
|
|
|
34
37
|
|
|
35
38
|
### Films
|
|
36
39
|
|
|
37
|
-
-
|
|
40
|
+
- Optional burned-in open captions rendered onto video frames. Synchronized narration timing, embedded MP4 caption tracks, and WebVTT sidecars are available now.
|
|
38
41
|
- ProRes and 4:4:4 masters for video editors. MP4 and WebM use 4:2:0 today for browser compatibility.
|
|
39
42
|
- Frame caching for faster incremental renders.
|
|
40
|
-
-
|
|
43
|
+
- Broader Canvas/SVG parity coverage beyond the current image, equation, scalar-field, bloom, and export regressions.
|
|
41
44
|
|
|
42
45
|
### Figures
|
|
43
46
|
|
package/SCIENCE.md
CHANGED
|
@@ -5,7 +5,59 @@ deterministic animation. Scientific components use the same public API and scene
|
|
|
5
5
|
registry in native rendering and the in-browser editor. They require no network
|
|
6
6
|
requests or scientific drawing service.
|
|
7
7
|
|
|
8
|
-
##
|
|
8
|
+
## Scientific films
|
|
9
|
+
|
|
10
|
+
Use `vizmatic/stage` for new animations. A film supplies its equations and model;
|
|
11
|
+
the engine supplies typesetting, geometry, scales, layout, and deterministic
|
|
12
|
+
playback. The same source runs in browser previews and video exports.
|
|
13
|
+
|
|
14
|
+
| Capability | Reusable tools | Film |
|
|
15
|
+
|---|---|---|
|
|
16
|
+
| Equations and derivations | `tex`, structural `.part()` / `.parts()`, `morphMatching`, baseline-aligned `row` | [Euler's circle](examples/films/euler-circle.ts) |
|
|
17
|
+
| Scalar fields and concentrations | `scalarField`, `colorBar`, `contourPaths` | [Reaction and diffusion](examples/films/reaction-diffusion.ts) |
|
|
18
|
+
| Scales and differential equations | `axes` with `xScale` / `yScale`, `integrateTrajectory` | [Lorenz](examples/films/lorenz.ts) |
|
|
19
|
+
| Waves and polarization | `scene3d`, `curve3d`, `vector3d`, `parametricSurface` | [Maxwell](examples/films/maxwell.ts) |
|
|
20
|
+
| Orbital motion and shaded geometry | `scene3d`, `curve3d`, `parametricSurface`, `scalarField` | [Eight worlds, one gravity](examples/films/planetary-orbits.ts) |
|
|
21
|
+
| Implicit surfaces and probability | `isosurface`, `scalarField`, `colorBar` | [Hydrogen orbitals](examples/films/hydrogen-orbitals.ts) |
|
|
22
|
+
| Molecular geometry and reaction paths | `molecule3d`, `tex` with `\ce`, `axes` | [Catalysis](examples/films/catalysis.ts) |
|
|
23
|
+
|
|
24
|
+
`axes({ x: [1, 100], xScale: 'log', yScale: 'symlog' })` applies the same transform to
|
|
25
|
+
coordinates, inverse coordinates, ticks, and plots. Log domains must be positive.
|
|
26
|
+
`plot(f, { adaptive: { tolerance: 0.5 }, discontinuities: [[0, 0]] })` refines sampled
|
|
27
|
+
geometry in stage pixels and leaves specified discontinuities open. Adaptive
|
|
28
|
+
sampling is bounded and cannot discover every narrow feature of an arbitrary
|
|
29
|
+
function. Series retain their original points; uniform sampling remains the
|
|
30
|
+
default.
|
|
31
|
+
Zero-baseline areas and Riemann rectangles cannot use a logarithmic y axis.
|
|
32
|
+
Use a positive `over` curve or `band` to fill a region on that scale.
|
|
33
|
+
|
|
34
|
+
`parametric(f, from, to, { adaptive: true })` uses the same bounded sampler for
|
|
35
|
+
curves such as particle trajectories. Its tolerance is in local pixels at
|
|
36
|
+
construction time, before later node or parent transforms. It accepts the same
|
|
37
|
+
parameter-interval exclusions; the default uniform spline remains unchanged.
|
|
38
|
+
|
|
39
|
+
`scalarField((x, y, t) => value, { x, y, domain, colors, scale })` draws a sampled
|
|
40
|
+
image, with positive y upward. Keep `domain`, `colors`, and `scale` identical in
|
|
41
|
+
its `colorBar`; do not renormalize each frame. Missing samples become transparent
|
|
42
|
+
holes. Spatial resolution is explicit, from 2 to 512 samples per axis. A field
|
|
43
|
+
supports the same placement, clipping, opacity, and blending as other nodes.
|
|
44
|
+
`contourPaths(f, { x, y, levels, resolution })` returns connected polylines in
|
|
45
|
+
data coordinates, for either 2D plots or projected 3D geometry.
|
|
46
|
+
|
|
47
|
+
`integrateTrajectory((t, state) => derivative, { initial, to, step })` precomputes
|
|
48
|
+
fixed-step RK4 with cubic interpolation. Sampling is independent of seek order.
|
|
49
|
+
Use it for time-dependent particle paths as well as autonomous systems. It is
|
|
50
|
+
not a stiff or adaptive solver; compare smaller steps and check the model's
|
|
51
|
+
invariants. `streamLines` depicts the geometry of a steady field, not the particle
|
|
52
|
+
paths of a changing field.
|
|
53
|
+
|
|
54
|
+
`isosurface(f, { x, y, z, level, resolution })` creates a cached, bounded
|
|
55
|
+
marching-tetrahedra mesh inside `scene3d`. The grid approximates the level set;
|
|
56
|
+
surfaces that touch the sampling box remain open. For density lobes, use
|
|
57
|
+
`normals: 'decreasing'`. A displayed probability isosurface is a chosen density
|
|
58
|
+
threshold, not an electron boundary or orbit.
|
|
59
|
+
|
|
60
|
+
## Still figures
|
|
9
61
|
|
|
10
62
|
| Subject | Components and helpers | Worked examples |
|
|
11
63
|
|---|---|---|
|
|
@@ -84,8 +136,7 @@ rejects embedded ICC profiles. Raster operations also cap dimensions at
|
|
|
84
136
|
accepts σ ≥ 0 and integer radius 0–64, and defaults the radius to `ceil(3σ)`.
|
|
85
137
|
An explicit radius at σ = 0 keeps the matching valid crop while leaving its
|
|
86
138
|
pixels unchanged. These helpers are not part of the bare QuickJS author-code
|
|
87
|
-
environment.
|
|
88
|
-
Vizmatic release that includes them.
|
|
139
|
+
environment.
|
|
89
140
|
|
|
90
141
|
See [PyTorch Conv2d](https://docs.pytorch.org/docs/stable/generated/torch.nn.Conv2d.html)
|
|
91
142
|
for learned spatial filters and [OpenCV image filtering](https://docs.opencv.org/4.x/d4/d86/group__imgproc__filter.html)
|
|
@@ -128,13 +179,27 @@ The worked lessons use these contracts:
|
|
|
128
179
|
`MoleculeDiagram` renders supplied 2D atom positions and bond orders. It checks
|
|
129
180
|
elements, identifiers, endpoints, and finite geometry. Supply the molecular
|
|
130
181
|
structure deliberately: the renderer does not infer bonds, valence, a 3D
|
|
131
|
-
conformation, stereochemistry, or chemical validity from a formula.
|
|
182
|
+
conformation, stereochemistry, or chemical validity from a formula. Single bonds
|
|
183
|
+
accept `stereo: 'wedge' | 'hashed'`; the narrow end is `from`, so atom order matters.
|
|
184
|
+
|
|
185
|
+
For films, `molecule3d({ atoms, bonds }, options)` places explicit 3D coordinates
|
|
186
|
+
in a `Scene3D`. `atom(id)` and `bond(from, to)` expose parts for animation. Display
|
|
187
|
+
radii are illustrative, not measured atomic radii. The same function accepts one
|
|
188
|
+
V2000 MOL/SDF string containing plain element atoms and explicit bonds. Unsupported
|
|
189
|
+
stereochemistry, charges, isotopes, query atoms, and property blocks are rejected;
|
|
190
|
+
V3000 and multiple SDF records are not supported. A planar input remains planar.
|
|
191
|
+
Vizmatic does not generate conformers or add missing hydrogens.
|
|
192
|
+
|
|
193
|
+
`tex` bundles MathJax's `mhchem` extension, including `\ce` and `\pu`, for formulas,
|
|
194
|
+
reaction arrows, charges, and units. This typesets the author's chemistry; it does
|
|
195
|
+
not infer its meaning or balance a reaction.
|
|
132
196
|
|
|
133
197
|
`ReactionEquation` displays supplied formulas, coefficients, and phase labels.
|
|
134
198
|
For conservation checks, supply an explicit `composition` map and optional
|
|
135
199
|
integer `charge` for each term. `reactionBalance` compares coefficient-weighted
|
|
136
200
|
element counts and charge. Missing composition means balance is unavailable;
|
|
137
|
-
the rendered formula is not parsed or automatically balanced.
|
|
201
|
+
the rendered formula is not parsed or automatically balanced. An electron term
|
|
202
|
+
uses `composition: {}` and `charge: -1`; it contributes charge without an element.
|
|
138
203
|
|
|
139
204
|
`ReactionEnergyDiagram` accepts absolute energy levels in one explicitly named
|
|
140
205
|
unit. The barrier is the peak energy, not activation energy itself. Activation
|