@motionscript/math 0.1.0-alpha.8 → 0.1.0-alpha.9
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/CHANGELOG.md +2 -0
- package/LICENSE +201 -201
- package/NOTICE +49 -49
- package/README.md +390 -391
- package/dist/annotate/angle-mark.js.map +1 -1
- package/dist/annotate/curly-brace.js.map +1 -1
- package/dist/annotate/emphasis-mark.js.map +1 -1
- package/dist/browser/chunks/{chunk-FETQZEN2.js → chunk-IRZCG6PM.js} +2 -2
- package/dist/browser/chunks/chunk-IRZCG6PM.js.map +7 -0
- package/dist/browser/chunks/{chunk-K77KLQX4.js → chunk-WMVW6ZIV.js} +2 -2
- package/dist/browser/chunks/chunk-WMVW6ZIV.js.map +7 -0
- package/dist/browser/chunks/{mathjax-DNP3YRES.js → mathjax-WV55AC2P.js} +1 -1
- package/dist/browser/chunks/{mathjax-DNP3YRES.js.map → mathjax-WV55AC2P.js.map} +1 -1
- package/dist/browser/index.js +1 -1
- package/dist/browser/index.js.map +1 -1
- package/dist/browser/kit.js +1 -1
- package/dist/browser/tex.js +1 -1
- package/dist/browser/tex.js.map +1 -1
- package/dist/engine.d.ts +1 -1
- package/dist/engine.js +1 -1
- package/dist/engine.js.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/kit/brace.js.map +1 -1
- package/dist/kit/cache.js.map +1 -1
- package/dist/kit/component.d.ts.map +1 -1
- package/dist/kit/component.js.map +1 -1
- package/dist/kit/contour.js.map +1 -1
- package/dist/kit/coords.js.map +1 -1
- package/dist/kit/curve.js.map +1 -1
- package/dist/kit/equation.js.map +1 -1
- package/dist/kit/equation3d.js.map +1 -1
- package/dist/kit/expression.js.map +1 -1
- package/dist/kit/field-mark.d.ts.map +1 -1
- package/dist/kit/field-mark.js.map +1 -1
- package/dist/kit/field.js.map +1 -1
- package/dist/kit/follow.d.ts.map +1 -1
- package/dist/kit/follow.js.map +1 -1
- package/dist/kit/furniture.js.map +1 -1
- package/dist/kit/geometry.js.map +1 -1
- package/dist/kit/graph.js.map +1 -1
- package/dist/kit/mark.js.map +1 -1
- package/dist/kit/part-fills.js.map +1 -1
- package/dist/kit/place.js.map +1 -1
- package/dist/kit/sampler.js.map +1 -1
- package/dist/kit/scale.js.map +1 -1
- package/dist/kit/source.js.map +1 -1
- package/dist/kit/system.js.map +1 -1
- package/dist/kit/ticks.js.map +1 -1
- package/dist/kit/withdrawn.js.map +1 -1
- package/dist/marks/curve-area.js.map +1 -1
- package/dist/marks/drop-lines.js.map +1 -1
- package/dist/marks/plot-point.js.map +1 -1
- package/dist/marks/riemann-sum.js.map +1 -1
- package/dist/marks/tangent-line.js.map +1 -1
- package/dist/marks/vector-arrow.js.map +1 -1
- package/dist/nodes.js.map +1 -1
- package/dist/plots/function-plot.d.ts.map +1 -1
- package/dist/plots/function-plot.js.map +1 -1
- package/dist/plots/points-plot.js.map +1 -1
- package/dist/plots/stream-lines.js.map +1 -1
- package/dist/plots/traced-path.js.map +1 -1
- package/dist/plots/vector-field.js.map +1 -1
- package/dist/structures/graph-layout.js.map +1 -1
- package/dist/structures/network-graph.js.map +1 -1
- package/dist/structures/sample-space.js.map +1 -1
- package/dist/systems/axes2d.d.ts.map +1 -1
- package/dist/systems/axes2d.js.map +1 -1
- package/dist/systems/number-line.js.map +1 -1
- package/dist/systems/number-plane.js.map +1 -1
- package/dist/systems/polar-plane.js.map +1 -1
- package/dist/tex/geometry.js.map +1 -1
- package/dist/tex/index.js.map +1 -1
- package/dist/tex/mathjax.js.map +1 -1
- package/dist/tex/matrix.js.map +1 -1
- package/dist/tex/node.js.map +1 -1
- package/dist/tex/tween.js.map +1 -1
- package/dist/tex/typeset.d.ts.map +1 -1
- package/dist/tex/typeset.js.map +1 -1
- package/dist/three/axes3d.js.map +1 -1
- package/dist/three/curve-plot3d.js.map +1 -1
- package/dist/three/entries.js.map +1 -1
- package/dist/three/label3d.js.map +1 -1
- package/dist/three/plot-point3d.js.map +1 -1
- package/dist/three/space.js.map +1 -1
- package/dist/three/surface-plot3d.js.map +1 -1
- package/dist/three/vector-arrow3d.js.map +1 -1
- package/package.json +4 -4
- package/registry.json +251 -251
- package/src/annotate/angle-mark.ts +137 -137
- package/src/annotate/curly-brace.ts +148 -148
- package/src/annotate/emphasis-mark.ts +118 -118
- package/src/engine.ts +86 -86
- package/src/index.ts +29 -29
- package/src/kit/brace.ts +37 -37
- package/src/kit/cache.ts +61 -61
- package/src/kit/component.ts +57 -57
- package/src/kit/contour.ts +94 -94
- package/src/kit/coords.ts +278 -278
- package/src/kit/curve.ts +47 -47
- package/src/kit/equation.ts +181 -181
- package/src/kit/equation3d.ts +137 -137
- package/src/kit/expression.ts +159 -159
- package/src/kit/field-mark.ts +171 -171
- package/src/kit/field.ts +50 -50
- package/src/kit/follow.ts +229 -229
- package/src/kit/furniture.ts +113 -113
- package/src/kit/geometry.ts +49 -49
- package/src/kit/graph.ts +116 -116
- package/src/kit/mark.ts +152 -152
- package/src/kit/part-fills.ts +61 -61
- package/src/kit/place.ts +77 -77
- package/src/kit/sampler.ts +281 -281
- package/src/kit/scale.ts +39 -39
- package/src/kit/source.ts +57 -57
- package/src/kit/system.ts +105 -105
- package/src/kit/ticks.ts +85 -85
- package/src/kit/withdrawn.ts +8 -8
- package/src/marks/curve-area.ts +89 -89
- package/src/marks/drop-lines.ts +71 -71
- package/src/marks/plot-point.ts +102 -102
- package/src/marks/riemann-sum.ts +99 -99
- package/src/marks/tangent-line.ts +119 -119
- package/src/marks/vector-arrow.ts +98 -98
- package/src/nodes.ts +99 -99
- package/src/plots/function-plot.ts +220 -220
- package/src/plots/points-plot.ts +103 -103
- package/src/plots/stream-lines.ts +160 -160
- package/src/plots/traced-path.ts +70 -70
- package/src/plots/vector-field.ts +107 -107
- package/src/structures/graph-layout.ts +145 -145
- package/src/structures/network-graph.ts +291 -291
- package/src/structures/sample-space.ts +210 -210
- package/src/systems/axes2d.ts +226 -226
- package/src/systems/number-line.ts +130 -130
- package/src/systems/number-plane.ts +232 -232
- package/src/systems/polar-plane.ts +177 -177
- package/src/tex/geometry.ts +703 -703
- package/src/tex/index.ts +15 -15
- package/src/tex/mathjax.ts +82 -82
- package/src/tex/matrix.ts +97 -97
- package/src/tex/node.ts +74 -74
- package/src/tex/tween.ts +308 -308
- package/src/tex/typeset.ts +461 -461
- package/src/three/axes3d.ts +267 -267
- package/src/three/curve-plot3d.ts +146 -146
- package/src/three/entries.ts +42 -42
- package/src/three/label3d.ts +52 -52
- package/src/three/plot-point3d.ts +63 -63
- package/src/three/space.ts +92 -92
- package/src/three/surface-plot3d.ts +318 -318
- package/src/three/vector-arrow3d.ts +88 -88
- package/dist/browser/chunks/chunk-FETQZEN2.js.map +0 -7
- package/dist/browser/chunks/chunk-K77KLQX4.js.map +0 -7
- package/dist/kit/placement.d.ts +0 -8
- package/dist/kit/placement.d.ts.map +0 -1
- package/dist/kit/placement.js +0 -8
- package/dist/kit/placement.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,391 +1,390 @@
|
|
|
1
|
-
# @motionscript/math
|
|
2
|
-
|
|
3
|
-
Math for [Motion Script](https://motionscript.dev): coordinate systems whose
|
|
4
|
-
children sit in graph coordinates, plots of equations, the marks that go on a
|
|
5
|
-
graph, and typeset formulas that morph into one another.
|
|
6
|
-
|
|
7
|
-
Hand the kit's nodes to the engine through your project entry's `nodes`, and any
|
|
8
|
-
document that engine opens can name them by key:
|
|
9
|
-
|
|
10
|
-
```ts
|
|
11
|
-
// src/project.ts
|
|
12
|
-
import { NODES } from '@motionscript/math';
|
|
13
|
-
|
|
14
|
-
export const nodes = NODES;
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
## Exports
|
|
18
|
-
|
|
19
|
-
| Entry | Holds |
|
|
20
|
-
| --- | --- |
|
|
21
|
-
| `@motionscript/math` | Every component, `NODES`, and the kit below |
|
|
22
|
-
| `@motionscript/math/kit` | What the nodes share and a copied node imports rather than copies: the systems' and marks' helpers (`systemLayout`, `traced`, `drawMark`, the plane a system hands its marks), the coordinate map, the equation language, the sampler, and the LaTeX helpers |
|
|
23
|
-
| `@motionscript/math/tex` | The typeset-math half alone: `Latex`, `TEX_NODES` and its helpers |
|
|
24
|
-
|
|
25
|
-
## Nodes
|
|
26
|
-
|
|
27
|
-
Every node also has the shape commands (`moveTo`, `fadeTo`, `fillTo`,
|
|
28
|
-
`strokeTo`, `progressTo`, …).
|
|
29
|
-
|
|
30
|
-
| Key | What it is | Goes in | Own commands |
|
|
31
|
-
| --- | --- | --- | --- |
|
|
32
|
-
| `numberLine` | One axis with ticks and numbers | anywhere | `rangeTo({ range })` |
|
|
33
|
-
| `axes2d` | An x and a y axis, linear or log | anywhere | `rangeTo({ xRange, yRange })` |
|
|
34
|
-
| `numberPlane` | Axes over a full grid, square units | anywhere | `rangeTo`, `transformTo({ matrix })`, `warpTo({ warp })` |
|
|
35
|
-
| `polarPlane` | Rings and spokes about an origin | anywhere | `rangeTo({ radius })` |
|
|
36
|
-
| `functionPlot` | The curve of an equation | a system | `morphTo({ expression })`, `paramsTo({ params })`, `domainTo({ domain })` |
|
|
37
|
-
| `pointsPlot` | A line or closed shape through listed graph points | a system | `pointsTo({ points })` |
|
|
38
|
-
| `plotPoint` | A labelled dot, free or riding a plot | a system or a `functionPlot` | |
|
|
39
|
-
| `vectorArrow` | An arrow from `tail` to `head` | a system | `endpointsTo({ tail, head })` |
|
|
40
|
-
| `curveArea` | The region under a plot, or between two | a system, beside a `functionPlot` | `domainTo({ domain })` |
|
|
41
|
-
| `riemannSum` | Rectangles approximating that region | a system, beside a `functionPlot` | `refineTo({ dx })`, `domainTo({ domain })` |
|
|
42
|
-
| `tangentLine` | The tangent to a plot, or a secant with its run and rise | a `functionPlot` | |
|
|
43
|
-
| `dropLines` | Guides from a graph point to the axes | a system or a `functionPlot` | |
|
|
44
|
-
| `latex` | A typeset formula with nameable parts | anywhere | `morphTo({ latex })`, `partFillTo({ part, fill })`, `writeTo({ written })` |
|
|
45
|
-
| `latexMatrix` | A matrix typeset from its entries | anywhere | `entriesTo({ entries })`, and a formula's |
|
|
46
|
-
| `curlyBrace` | A brace along a node, a part of a formula, or two points | anywhere | `retargetTo({ on, part })` |
|
|
47
|
-
| `emphasisMark` | A box, circle, underline or cross on a node or a part | anywhere | `retargetTo({ on, part })` |
|
|
48
|
-
| `angleMark` | An angle's arc or square, with its label | anywhere | `radiusTo({ radius })` |
|
|
49
|
-
| `axes3d` | A 3D graph: three axes through a box of graph coordinates, z up, seen through its own camera | anywhere 2D (it is a `canvas3d`) | `rangeTo({ xRange, yRange, zRange })`, and a `canvas3d`'s `orbitTo` |
|
|
50
|
-
| `surfacePlot3d` | A surface: a height over x and y, or three parts in u and v | an `axes3d` | `morphTo({ expression })`, `paramsTo({ params })`, `domainTo({ uDomain, vDomain })` |
|
|
51
|
-
| `curvePlot3d` | A curve through space, three parts in t | an `axes3d` | `morphTo`, `paramsTo`, `domainTo({ domain })`, `progressTo({ start, end })` |
|
|
52
|
-
| `plotPoint3d` | A labelled dot, free or riding a surface | an `axes3d` or a `surfacePlot3d` | |
|
|
53
|
-
| `vectorArrow3d` | An arrow from `tail` to `head` | an `axes3d` | `endpointsTo({ tail, head })` |
|
|
54
|
-
| `vectorField` | A grid of arrows showing a field, `(P, Q)` in x and y | a system | `morphTo({ expression })`, `paramsTo({ params })` |
|
|
55
|
-
| `streamLines` | The lines a field carries a point along | a system | `flowTo({ phase })`, `morphTo`, `paramsTo` |
|
|
56
|
-
| `tracedPath` | The trail a point leaves as a value changes | a system | `traceTo({ value })`, and a plot's |
|
|
57
|
-
| `networkGraph` | Vertices and edges, arranged in a circle, by springs, as a tree or in a grid | anywhere | `arrangeTo({ arrangement })`, `partFillTo({ part, fill })` |
|
|
58
|
-
| `sampleSpace` | A probability's whole cut into parts whose areas are their probabilities | anywhere | `divideTo({ columnShares, rowShares })` |
|
|
59
|
-
|
|
60
|
-
A system is a `numberLine`, an `axes2d`, a `numberPlane` or a `polarPlane`. The
|
|
61
|
-
Goes in column is where each node is made to go; offering it only there is the
|
|
62
|
-
host's to do, since the engine is told only a node's key, entries and commands.
|
|
63
|
-
Nothing checks it when a document builds: a plot outside a system builds and
|
|
64
|
-
draws nothing.
|
|
65
|
-
|
|
66
|
-
Each node takes only the paints it draws. A node spreads the shape paints
|
|
67
|
-
(`fill`, `stroke` and the outline trim `start`, `end`, `progressTo`, `flash`) it
|
|
68
|
-
has a use for and leaves the rest out, so they are not offered: a plot, a tangent, an arrow or a brace is a line with
|
|
69
|
-
no fill; an area is a fill with no outline; a field is one stroke for every arrow
|
|
70
|
-
or line; a formula and a traced path reveal themselves (`writeTo`, `traceTo`)
|
|
71
|
-
rather than by trimming; a dot, a sample space and a Riemann sum have nothing a
|
|
72
|
-
trim would draw on. `shadow` stays on all of them.
|
|
73
|
-
|
|
74
|
-
## Coordinate systems
|
|
75
|
-
|
|
76
|
-
```ts
|
|
77
|
-
const document = {
|
|
78
|
-
kind: 'composition',
|
|
79
|
-
variables: [{ id: 't', value: 0 }],
|
|
80
|
-
nodes: [
|
|
81
|
-
{ id: 'axes', type: 'axes2d', parentId: null, layerOrder: 0,
|
|
82
|
-
props: { width: 800, height: 450, xRange: [-4, 4], yRange: [-2, 2], fontFamily: 'Inter' } },
|
|
83
|
-
{ id: 'curve', type: 'functionPlot', parentId: 'axes', layerOrder: 0, props: { expression: 'sin(x)' } },
|
|
84
|
-
{ id: 'dot', type: 'plotPoint', parentId: 'curve', layerOrder: 0, props: { x: '=[t]' } },
|
|
85
|
-
{ id: 'note', type: 'text', parentId: 'axes', layerOrder: 1,
|
|
86
|
-
props: { x: 2, y: 1.5, text: 'y = sin x', fontSize: 24, fontFamily: 'Inter', fill: 'white' } },
|
|
87
|
-
],
|
|
88
|
-
commands: [
|
|
89
|
-
{ id: 'a', type: 'progressTo', targetId: 'curve', at: 0, duration: 1, args: { end: 1 } },
|
|
90
|
-
{ id: 'b', type: 'variableTo', targetId: 't', at: 1, duration: 2, args: { value: 3.14 } },
|
|
91
|
-
{ id: 'c', type: 'rangeTo', targetId: 'axes', at: 3, duration: 1, args: { xRange: [0, 8] } },
|
|
92
|
-
],
|
|
93
|
-
};
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
- **A child's `x`/`y` are graph units, whatever the child is.** A text, an image
|
|
97
|
-
or a shape dropped in a system sits at graph coordinates and keeps its own
|
|
98
|
-
size; `moveTo` moves it in graph units; a range tween carries it. On a
|
|
99
|
-
`numberLine`, `x` is a value on the line and `y` is pixels above it.
|
|
100
|
-
- **A mark is drawn through the system's map.** `functionPlot`, `pointsPlot`,
|
|
101
|
-
`vectorArrow`, `curveArea`, `riemannSum`, `tangentLine` and `dropLines` are
|
|
102
|
-
marks (`traced`): their geometry is in graph coordinates and their box is the tight box of
|
|
103
|
-
their ink. A plot's or an arrow's own `x`/`y` shift it in graph units; a
|
|
104
|
-
`tangentLine`'s and a `dropLines`'s `x` is where along the graph they are.
|
|
105
|
-
Outside a system a graph unit is a pixel and a plot draws nothing.
|
|
106
|
-
- **Riding a plot.** A `plotPoint`, `tangentLine` or `dropLines` inside a
|
|
107
|
-
`functionPlot` follows that plot, appears, moves and leaves with it, and is
|
|
108
|
-
drawn over the curve: a mark's stroke is its ink, painted before its children
|
|
109
|
-
rather than last as a shape's outline is (a mark drawn with `drawMark` that
|
|
110
|
-
strokes its ink its own way passes its own `ink`). In the system instead, a
|
|
111
|
-
point or guide names a plot by id in `on`, or none and is free. `curveArea`
|
|
112
|
-
and `riemannSum` sit in the system beside the plots they read and name one in
|
|
113
|
-
`on` (an area a second in `under`). A point that rides a plot
|
|
114
|
-
takes its height from the curve and keeps its own `y` only where the curve has
|
|
115
|
-
no value.
|
|
116
|
-
- **One value drives a scene through a variable.** Bind any graph prop with
|
|
117
|
-
`"=[t]"` and animate `t` with `variableTo`; a formula may sit at any depth, so
|
|
118
|
-
a `pointsPlot` corner can be `{ x: '=[t]', y: '=25/[t]' }`. `plotPoint.value`
|
|
119
|
-
and `tangentLine.slope` can be read back as `[key.value]` and `[key.slope]`.
|
|
120
|
-
- **A system's `stroke` is its axis line and its `fill` its backdrop.** So
|
|
121
|
-
`stroke.endCap` is the axis tip. Ticks, grid lines and numbers are drawn by the
|
|
122
|
-
system itself; they are not child nodes. Drawn on with `progressTo`, the ticks
|
|
123
|
-
and numbers appear as the line reaches them.
|
|
124
|
-
- **Numbers need a font.** A system's `fontFamily` is empty by default, which
|
|
125
|
-
takes the scene's default text style; a scene with none has to set it, as any
|
|
126
|
-
text does.
|
|
127
|
-
- **An axis crosses the other at its zero**, or at the nearest edge when zero is
|
|
128
|
-
out of range or the other axis is logarithmic. A `step` of `0` picks a tidy
|
|
129
|
-
spacing for the axis's length; a log axis is marked at the powers of ten.
|
|
130
|
-
|
|
131
|
-
## 3D graphs
|
|
132
|
-
|
|
133
|
-
```ts
|
|
134
|
-
nodes: [
|
|
135
|
-
{ id: 'axes', type: 'axes3d', parentId: null, layerOrder: 0, props: { width: 960, height: 540, labels: true, fontFamily: 'Inter' } },
|
|
136
|
-
{ id: 'bump', type: 'surfacePlot3d', parentId: 'axes', layerOrder: 0,
|
|
137
|
-
props: { expression: '1.8 exp(-(x^2 + y^2) / 2)', colorScale: ['#1d4ed8', '#22c55e', '#facc15', '#ef4444'] } },
|
|
138
|
-
{ id: 'dot', type: 'plotPoint3d', parentId: 'bump', layerOrder: 0, props: { x: 0.8, y: -0.6, label: 'P' } },
|
|
139
|
-
],
|
|
140
|
-
commands: [
|
|
141
|
-
{ id: 'a', type: 'orbitTo', targetId: 'axes', at: 0, duration: 2, args: { orbit: 80, elevation: 32 } },
|
|
142
|
-
{ id: 'b', type: 'morphTo', targetId: 'bump', at: 2, duration: 1, args: { expression: '(x^2 - y^2) / 5' } },
|
|
143
|
-
],
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
- **A 3D graph is right-handed with z up.** The scene has y up, so graph x, y and
|
|
147
|
-
z run along the scene's z, x and y: seen head-on, y is to the right and z is
|
|
148
|
-
up, and the axes' default camera shows x coming toward the viewer.
|
|
149
|
-
- **An `axes3d` is its own viewport.** It is a `canvas3d` (camera, lights,
|
|
150
|
-
`orbitTo`, a box on the stage), so it needs no canvas around it and cannot go
|
|
151
|
-
inside one; a 3D shape you want beside the graph goes inside it instead.
|
|
152
|
-
- **The axes are a box, `xLength` by `yLength` by `zLength` scene units, centred
|
|
153
|
-
in the scene**, showing the three ranges. An axis crosses the others at their
|
|
154
|
-
zero, or at the nearest end of a range without one.
|
|
155
|
-
- **A child's `x`/`y`/`z` are graph units, whatever the child is**, and it keeps
|
|
156
|
-
its own size and turn: a `sphere3d` at `x: 1, y: 2, z: 0.5` sits at that graph
|
|
157
|
-
point, the built-in `moveTo` moves it in graph units, and `rangeTo` carries it.
|
|
158
|
-
- **A surface is held inside the axes.** A height that leaves the z range is
|
|
159
|
-
drawn at its edge, and one with no value is drawn flat, so a pole does not tear
|
|
160
|
-
the mesh. Left out, `uDomain` and `vDomain` are the axes' x and y ranges for a
|
|
161
|
-
height and 0 to 1 for a parametric surface.
|
|
162
|
-
- **A point put inside a surface rides it**: its `x` and `y` say where, and its
|
|
163
|
-
height is the surface's, which `surfaceValueAt(surface, x, y)` reads.
|
|
164
|
-
- **`colorScale` colours a surface by height** over the axes' z range, lowest
|
|
165
|
-
first; without one it is painted in its `fill`, the plot blue unless given one
|
|
166
|
-
(a `curvePlot3d` too). `meshLines` rules it each way.
|
|
167
|
-
- **A surface takes the mesh material props** (`opacity`, `roughness`, `wireframe`,
|
|
168
|
-
…) and is lit by the axes' lights; it is drawn from both sides.
|
|
169
|
-
- **Lines are tubes and labels are cards.** A `curvePlot3d`'s and an axis's
|
|
170
|
-
`thickness`, a point's `radius` and a label's `labelSize` are scene units, so
|
|
171
|
-
they keep their size when a range changes. A label always faces the camera.
|
|
172
|
-
- **Moving the camera** is the canvas's `orbitTo({ orbit, elevation, zoom })`, or a
|
|
173
|
-
`camera3d`'s `orbitTo` and `lookTo` when the scene has one.
|
|
174
|
-
|
|
175
|
-
| Written as | Is | Variables |
|
|
176
|
-
| --- | --- | --- |
|
|
177
|
-
| `sin(x) * cos(y)`, `z = x^2 - y^2` | a surface, as a height | `x`, `y` |
|
|
178
|
-
| `(cos(u) sin(v), sin(u) sin(v), cos(v))` | a parametric surface | `u`, `v` |
|
|
179
|
-
| `(cos(t), sin(t), t / 4)` | a space curve | `t` |
|
|
180
|
-
|
|
181
|
-
Any other name is a named value, as in a 2D plot (`surfaceParams`,
|
|
182
|
-
`spaceCurveParams`); `surfaceError` and `spaceCurveError` say why text will not draw.
|
|
183
|
-
|
|
184
|
-
## Equations
|
|
185
|
-
|
|
186
|
-
A `functionPlot`'s `expression` is read the way it is written:
|
|
187
|
-
|
|
188
|
-
| Written as | Is | Free variable, `domain` when not given |
|
|
189
|
-
| --- | --- | --- |
|
|
190
|
-
| `sin(x)`, `y = sin(x)` | a function of `x` | `x`, the system's width |
|
|
191
|
-
| `x = y^2` | a function of `y` | `y`, the system's height |
|
|
192
|
-
| `r = 1 + cos(theta)` | polar | `theta`, one turn |
|
|
193
|
-
| `(cos(t), sin(t))` | parametric | `t`, 0 to 1 |
|
|
194
|
-
| `x^2 + y^2 = 4` | implicit | drawn where it holds, over what the system shows |
|
|
195
|
-
|
|
196
|
-
- **The language is the engine's expression grammar under its own dialect**:
|
|
197
|
-
bare names, trig in radians, `ln`, `log2`, `log10`, the hyperbolics, and the
|
|
198
|
-
constants `pi`, `e`, `tau`, `phi`. Implicit multiplication (`2x`, `2(x + 1)`)
|
|
199
|
-
and `^` work as in a document formula. It never evaluates text as code.
|
|
200
|
-
- **A name the equation does not know is a named value**, held in `params`:
|
|
201
|
-
`{ expression: 'a * sin(k * x)', params: { a: 2, k: '=[speed]' } }`. One left
|
|
202
|
-
unset is 1, so an equation draws as soon as it is written; `equationParams(source)`
|
|
203
|
-
lists them for a host that draws a field for each. `paramsTo` animates them.
|
|
204
|
-
- **`morphTo` bends one curve into another**, of any kind into any kind: the two
|
|
205
|
-
are blended point for point along their parameters.
|
|
206
|
-
- **Text that is not an equation draws nothing** and throws nothing, so a host can
|
|
207
|
-
commit on every keystroke; `equationError(source)` gives the reason.
|
|
208
|
-
- **A curve is sampled adaptively** and broken at an asymptote or the edge of its
|
|
209
|
-
domain, so `1/x`, `tan(x)` and `sqrt(x)` draw as they should.
|
|
210
|
-
|
|
211
|
-
## Planes, fields and trails
|
|
212
|
-
|
|
213
|
-
- **A number plane can be transformed.** `matrix` (`[[a, b], [c, d]]`, or flat)
|
|
214
|
-
sends every point of the plane through a linear map about its origin, and
|
|
215
|
-
`warp` (two parts in x and y, `(x + sin(y), y + sin(x))`) bends it by a
|
|
216
|
-
function of its own points. The grid, the axes and everything on the plane go
|
|
217
|
-
with it: a child's position, a plot's curve, a vector's ends. `transformTo`
|
|
218
|
-
and `warpTo` animate them, each point travelling straight to where it ends up,
|
|
219
|
-
and `warpTo({ warp: "" })` flattens the plane again. While it is transformed
|
|
220
|
-
the plane leaves its flat self behind, faintly (`ghost`). The grid is ruled
|
|
221
|
-
over whatever of the plane then falls in the box, up to four times its own
|
|
222
|
-
ranges, so it stays full under a turn, a shear or a fourfold shrink, and a
|
|
223
|
-
plane squeezed onto a line folds its grid into a narrowing band.
|
|
224
|
-
- **A polar plane is a plane with another ruling.** Its children are still at x
|
|
225
|
-
and y, in the units its rings count, so `r = 1 + cos(theta)` in a
|
|
226
|
-
`functionPlot`, a point or an arrow goes on it as on axes. `radius` is its
|
|
227
|
-
outer ring, `spokes` how many divide the turn, and `angleUnit` writes them in
|
|
228
|
-
degrees or as fractions of π.
|
|
229
|
-
- **An implicit equation is drawn where it holds.** `x^2 + y^2 = 4` in a
|
|
230
|
-
`functionPlot` is traced over what the system shows. It has no parameter to
|
|
231
|
-
bend along, so a morph to or from one changes over half way.
|
|
232
|
-
- **A field is two parts in x and y**, `(-y, x)`. A `vectorField` centres an
|
|
233
|
-
arrow on each point of a grid `spacing` apart, as long as the field is strong
|
|
234
|
-
there times `arrowScale` and never longer than the spacing; a `streamLines`
|
|
235
|
-
follows the field from each of those points for `length` graph units. With a
|
|
236
|
-
list of `strengthFills` both are painted by the field's strength, weakest
|
|
237
|
-
first; without one, in the stroke's own paint.
|
|
238
|
-
`streamLines.window` shows a stretch of each line and `flowTo({ phase })` sends
|
|
239
|
-
the stretches along: one whole turn of `phase` runs every line end to end.
|
|
240
|
-
- **A traced path is a plot whose end follows a value.** It draws its equation
|
|
241
|
-
from `from` to `value`; bind `value` to a variable (`"=[t]"`) and the trail
|
|
242
|
-
grows as the variable is driven, or drive it with `traceTo({ value })`. `tail`
|
|
243
|
-
keeps only its most recent stretch.
|
|
244
|
-
|
|
245
|
-
## Graphs and sample spaces
|
|
246
|
-
|
|
247
|
-
- **A network graph is its `vertices` (names) and `edges` (`{ from, to }`, or
|
|
248
|
-
pairs).** Its `fill` paints the vertices and its `stroke` the edges; with
|
|
249
|
-
`directed` each edge ends in an arrowhead, and an edge each way between two
|
|
250
|
-
vertices bows apart. Labels are the vertices' names.
|
|
251
|
-
- **`arrangement` places the vertices**: `circular` (the first at the top,
|
|
252
|
-
clockwise), `spring` (edges pull, every pair pushes; the same every time),
|
|
253
|
-
`tree` (levels down from `root`, a parent over its children), `grid`. A vertex
|
|
254
|
-
in `positions` is placed by hand, from -1 to 1 each way. `arrangeTo` moves every
|
|
255
|
-
vertex to where another arrangement puts it. (`layout` is every node's own box,
|
|
256
|
-
hence the other word.) `vertexPoints(graph, size)` says where each vertex is drawn.
|
|
257
|
-
- **`partFillTo({ part, fill })` paints a vertex by its name, or an edge written
|
|
258
|
-
`a-b`**, arriving over the graph's own paint, as a formula's parts are painted;
|
|
259
|
-
`partFills` holds them.
|
|
260
|
-
- **A sample space's `columnShares` cut it across** (any numbers, read as shares
|
|
261
|
-
of their sum) **and each column's entry in `rowShares` cuts that column**
|
|
262
|
-
(its upper share, 0 to 1), so each part's area is its probability. Braces name
|
|
263
|
-
the columns below (`columnLabels`) and the rows on the left (`rowLabels`);
|
|
264
|
-
`values` writes each part's probability in it; `divideTo` moves the cuts.
|
|
265
|
-
`sampleParts(space, size)` gives each part's box and probability.
|
|
266
|
-
|
|
267
|
-
## Annotations
|
|
268
|
-
|
|
269
|
-
`curlyBrace`, `emphasisMark` (box, circle, underline, cross) and `angleMark`
|
|
270
|
-
work anywhere, not only on a graph. A brace or an emphasis mark names a node
|
|
271
|
-
in `on`, and optionally one `part` of a formula, and is drawn on it wherever
|
|
272
|
-
the two are in the tree; `retargetTo` slides it to another. A brace with no
|
|
273
|
-
`on` spans `tail` to `head`. An angle mark sits at its own position and sweeps
|
|
274
|
-
`fromAngle` to `toAngle` in degrees, so binding one to a variable opens it.
|
|
275
|
-
A label written between dollar signs is typeset, on these and on a plot point
|
|
276
|
-
or an axis. `FOLLOW_STATE`, `FOLLOW_COMMANDS` and `followedQuad` in
|
|
277
|
-
`@motionscript/math/kit` are what a custom mark of this kind is built on.
|
|
278
|
-
|
|
279
|
-
## Latex
|
|
280
|
-
|
|
281
|
-
The formulas below were published as `@motionscript/latex` up to
|
|
282
|
-
`0.1.0-alpha.3`; that package is no longer updated, and the same node, key and
|
|
283
|
-
exports are here.
|
|
284
|
-
|
|
285
|
-
```ts
|
|
286
|
-
import type { CompositionDocument } from '@motionscript/sdk';
|
|
287
|
-
|
|
288
|
-
export default {
|
|
289
|
-
kind: 'composition',
|
|
290
|
-
nodes: [
|
|
291
|
-
{ id: 'eq', type: 'latex', parentId: null, layerOrder: 0,
|
|
292
|
-
props: { latex: 'a^2 + b^2 = c^2', fontSize: 64, fill: 'white' } },
|
|
293
|
-
],
|
|
294
|
-
commands: [
|
|
295
|
-
{ id: 'solve', type: 'morphTo', targetId: 'eq', at: 0, duration: 1.2,
|
|
296
|
-
args: { latex: 'c = \\sqrt{a^2 + b^2}' } },
|
|
297
|
-
],
|
|
298
|
-
} satisfies CompositionDocument;
|
|
299
|
-
```
|
|
300
|
-
|
|
301
|
-
- **`Latex`** node, a component that draws a formula as fillable, strokable
|
|
302
|
-
glyph paths. Set `latex` to the TeX source and `fontSize` to scale it; `fill`,
|
|
303
|
-
`stroke`, `shadow`, and `padding` work like any other shape.
|
|
304
|
-
- **Formula morphing**: `morphTo` (or any `to` that names `latex`) interpolates each
|
|
305
|
-
glyph between the current and target formula, matching tokens that persist,
|
|
306
|
-
fading out tokens that leave, and fading in tokens that arrive. A persisting
|
|
307
|
-
glyph is carried by its geometry, so one that changes size on the way — the
|
|
308
|
-
`2` of `b^2` becoming the `2` of `2a`, or a symbol dropping into a `\frac` —
|
|
309
|
-
grows or shrinks across the transition instead of snapping. The hugging box
|
|
310
|
-
resizes smoothly along with it.
|
|
311
|
-
- **Parts**: every piece of the source is a part, named by that source
|
|
312
|
-
(`a^2`, `\frac{d}{dx}`, or neighbours that spell it together). `partFills`
|
|
313
|
-
and `partFillTo` paint one with any paint, `latexPartBounds(node, part)` says where it is,
|
|
314
|
-
and a morph carries a term both formulas write as one, with its fill.
|
|
315
|
-
- **`written`** writes the formula on glyph by glyph, each outlined and then
|
|
316
|
-
filled; `writeTo` animates it. It is how a formula appears, so a formula has
|
|
317
|
-
no outline trim (`start`, `end`, `progressTo`, `flash`).
|
|
318
|
-
- **`latexMatrix`** typesets `entries` in the `brackets` it is given. Each entry
|
|
319
|
-
is a part; `entriesTo` morphs to new ones.
|
|
320
|
-
- **`buildLatexPath(latex, fontSize)`**, the underlying helper that turns TeX
|
|
321
|
-
into positioned `LatexToken` glyph paths plus intrinsic size and bounds, for
|
|
322
|
-
callers that want the geometry directly.
|
|
323
|
-
|
|
324
|
-
TeX is parsed through MathJax with the `base`, `ams`, `boldsymbol`,
|
|
325
|
-
`newcommand`, `cancel`, `color`, `mhchem`, `physics`, `bbox`, and `mathtools`
|
|
326
|
-
packages enabled. Rendering is synchronous and browser-only.
|
|
327
|
-
|
|
328
|
-
A formula MathJax cannot typeset (`\frac{a`, `\fra`, a stray `{`, or `\require`,
|
|
329
|
-
since only the packages above are loaded) throws a `LatexError` from
|
|
330
|
-
`buildLatexPath`, and from a `Latex` node that holds it whenever it is laid out
|
|
331
|
-
(a document holding one fails to build). The error carries the `latex` source and MathJax's `reason`. It is the same
|
|
332
|
-
in a browser and in Node; nothing is drawn in place of the formula.
|
|
333
|
-
|
|
334
|
-
This package is written against [`@motionscript/sdk`](https://github.com/motionscript-dev/motionscript/tree/main/packages/sdk), which it
|
|
335
|
-
takes as a peer dependency, and renders through whatever backend draws the
|
|
336
|
-
scene, such as [`@motionscript/browser`](https://github.com/motionscript-dev/motionscript/tree/main/packages/browser).
|
|
337
|
-
|
|
338
|
-
## Morphing, fills and what the host supplies
|
|
339
|
-
|
|
340
|
-
- **`morphTo({ latex })` is the document command, and every `to` of `latex` is a morph.**
|
|
341
|
-
Mid-tween `latex` (a matrix's `entries` and `brackets`) holds both ends, a
|
|
342
|
-
`Morph`, and the glyphs are drawn that far between them, so a seek to any time
|
|
343
|
-
draws the morph there. A `to` of `fontSize` alone sets the formula again at
|
|
344
|
-
each size. A morph reads its from-state on its **first evaluation**, not when
|
|
345
|
-
the command is built, so two morphs in sequence start the second from the
|
|
346
|
-
first's end.
|
|
347
|
-
- **Glyphs match by key.** A token's key is the character its MathJax glyph id
|
|
348
|
-
decodes to (a mathematical italic `𝑥` is not `x`); a rule or fraction bar is
|
|
349
|
-
`__rect_N` and a bare path `__path_N`, and those never match. `defaultLatexMorph`
|
|
350
|
-
pairs keys greedily in order, fades deleted tokens over the first half and added
|
|
351
|
-
ones over the second. A custom `morph` (`LatexStrategies`) replaces it, for a
|
|
352
|
-
node built on the typeset helpers, which take it as an argument
|
|
353
|
-
(`formulaFrame(source, fontSize, partFills, morph)`); a document cannot set it.
|
|
354
|
-
- **A `latex` row needs a `fill` or a `stroke` to draw anything**; `fill` defaults
|
|
355
|
-
to none. The formula is typeset in display style, so double each backslash inside
|
|
356
|
-
a JSON string.
|
|
357
|
-
- **MathJax loads only for a scene that typesets.** It and its default font,
|
|
358
|
-
including the `\mathbb`, `\mathcal`, `\mathfrak`, `\mathscr`, `\mathsf` and
|
|
359
|
-
`\mathtt` ranges, are bundled in a module of their own that `loadMathJax()`
|
|
360
|
-
imports once. A `latex` or `latexMatrix`, and a graph, a point, a brace or an
|
|
361
|
-
angle whose label is written between dollar signs, declares the
|
|
362
|
-
`math:mathjax` loader (`MATHJAX_LOADER`), which the host waits for before
|
|
363
|
-
layout; a scene with no formula never loads it. Until it is there a formula
|
|
364
|
-
draws nothing and is asked again. Code that typesets outside a scene (a tool, a
|
|
365
|
-
test) awaits `loadMathJax()` first: `buildLatexPath` throws `LatexNotLoaded`
|
|
366
|
-
before then, and `latexPartNames` answers with nothing.
|
|
367
|
-
- **Module state is shared per process**: one MathJax document, and two LRU memos
|
|
368
|
-
(typeset geometry by formula, 128 entries; paths by size and formula, 64).
|
|
369
|
-
Importing the module registers MathJax's HTML handler, with the DOM-free adaptor
|
|
370
|
-
when there is no `window` or `document`.
|
|
371
|
-
-
|
|
372
|
-
morph and the drawing (`tex/typeset.ts`) stay in this package behind `src/engine.ts`.
|
|
373
|
-
|
|
374
|
-
## Usage
|
|
375
|
-
|
|
376
|
-
```bash
|
|
377
|
-
npm install @motionscript/math @motionscript/sdk
|
|
378
|
-
```
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
pnpm --filter @motionscript/math
|
|
390
|
-
|
|
391
|
-
```
|
|
1
|
+
# @motionscript/math
|
|
2
|
+
|
|
3
|
+
Math for [Motion Script](https://motionscript.dev): coordinate systems whose
|
|
4
|
+
children sit in graph coordinates, plots of equations, the marks that go on a
|
|
5
|
+
graph, and typeset formulas that morph into one another.
|
|
6
|
+
|
|
7
|
+
Hand the kit's nodes to the engine through your project entry's `nodes`, and any
|
|
8
|
+
document that engine opens can name them by key:
|
|
9
|
+
|
|
10
|
+
```ts
|
|
11
|
+
// src/project.ts
|
|
12
|
+
import { NODES } from '@motionscript/math';
|
|
13
|
+
|
|
14
|
+
export const nodes = NODES;
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Exports
|
|
18
|
+
|
|
19
|
+
| Entry | Holds |
|
|
20
|
+
| --- | --- |
|
|
21
|
+
| `@motionscript/math` | Every component, `NODES`, and the kit below |
|
|
22
|
+
| `@motionscript/math/kit` | What the nodes share and a copied node imports rather than copies: the systems' and marks' helpers (`systemLayout`, `traced`, `drawMark`, the plane a system hands its marks), the coordinate map, the equation language, the sampler, and the LaTeX helpers |
|
|
23
|
+
| `@motionscript/math/tex` | The typeset-math half alone: `Latex`, `TEX_NODES` and its helpers |
|
|
24
|
+
|
|
25
|
+
## Nodes
|
|
26
|
+
|
|
27
|
+
Every node also has the shape commands (`moveTo`, `fadeTo`, `fillTo`,
|
|
28
|
+
`strokeTo`, `progressTo`, …).
|
|
29
|
+
|
|
30
|
+
| Key | What it is | Goes in | Own commands |
|
|
31
|
+
| --- | --- | --- | --- |
|
|
32
|
+
| `numberLine` | One axis with ticks and numbers | anywhere | `rangeTo({ range })` |
|
|
33
|
+
| `axes2d` | An x and a y axis, linear or log | anywhere | `rangeTo({ xRange, yRange })` |
|
|
34
|
+
| `numberPlane` | Axes over a full grid, square units | anywhere | `rangeTo`, `transformTo({ matrix })`, `warpTo({ warp })` |
|
|
35
|
+
| `polarPlane` | Rings and spokes about an origin | anywhere | `rangeTo({ radius })` |
|
|
36
|
+
| `functionPlot` | The curve of an equation | a system | `morphTo({ expression })`, `paramsTo({ params })`, `domainTo({ domain })` |
|
|
37
|
+
| `pointsPlot` | A line or closed shape through listed graph points | a system | `pointsTo({ points })` |
|
|
38
|
+
| `plotPoint` | A labelled dot, free or riding a plot | a system or a `functionPlot` | |
|
|
39
|
+
| `vectorArrow` | An arrow from `tail` to `head` | a system | `endpointsTo({ tail, head })` |
|
|
40
|
+
| `curveArea` | The region under a plot, or between two | a system, beside a `functionPlot` | `domainTo({ domain })` |
|
|
41
|
+
| `riemannSum` | Rectangles approximating that region | a system, beside a `functionPlot` | `refineTo({ dx })`, `domainTo({ domain })` |
|
|
42
|
+
| `tangentLine` | The tangent to a plot, or a secant with its run and rise | a `functionPlot` | |
|
|
43
|
+
| `dropLines` | Guides from a graph point to the axes | a system or a `functionPlot` | |
|
|
44
|
+
| `latex` | A typeset formula with nameable parts | anywhere | `morphTo({ latex })`, `partFillTo({ part, fill })`, `writeTo({ written })` |
|
|
45
|
+
| `latexMatrix` | A matrix typeset from its entries | anywhere | `entriesTo({ entries })`, and a formula's |
|
|
46
|
+
| `curlyBrace` | A brace along a node, a part of a formula, or two points | anywhere | `retargetTo({ on, part })` |
|
|
47
|
+
| `emphasisMark` | A box, circle, underline or cross on a node or a part | anywhere | `retargetTo({ on, part })` |
|
|
48
|
+
| `angleMark` | An angle's arc or square, with its label | anywhere | `radiusTo({ radius })` |
|
|
49
|
+
| `axes3d` | A 3D graph: three axes through a box of graph coordinates, z up, seen through its own camera | anywhere 2D (it is a `canvas3d`) | `rangeTo({ xRange, yRange, zRange })`, and a `canvas3d`'s `orbitTo` |
|
|
50
|
+
| `surfacePlot3d` | A surface: a height over x and y, or three parts in u and v | an `axes3d` | `morphTo({ expression })`, `paramsTo({ params })`, `domainTo({ uDomain, vDomain })` |
|
|
51
|
+
| `curvePlot3d` | A curve through space, three parts in t | an `axes3d` | `morphTo`, `paramsTo`, `domainTo({ domain })`, `progressTo({ start, end })` |
|
|
52
|
+
| `plotPoint3d` | A labelled dot, free or riding a surface | an `axes3d` or a `surfacePlot3d` | |
|
|
53
|
+
| `vectorArrow3d` | An arrow from `tail` to `head` | an `axes3d` | `endpointsTo({ tail, head })` |
|
|
54
|
+
| `vectorField` | A grid of arrows showing a field, `(P, Q)` in x and y | a system | `morphTo({ expression })`, `paramsTo({ params })` |
|
|
55
|
+
| `streamLines` | The lines a field carries a point along | a system | `flowTo({ phase })`, `morphTo`, `paramsTo` |
|
|
56
|
+
| `tracedPath` | The trail a point leaves as a value changes | a system | `traceTo({ value })`, and a plot's |
|
|
57
|
+
| `networkGraph` | Vertices and edges, arranged in a circle, by springs, as a tree or in a grid | anywhere | `arrangeTo({ arrangement })`, `partFillTo({ part, fill })` |
|
|
58
|
+
| `sampleSpace` | A probability's whole cut into parts whose areas are their probabilities | anywhere | `divideTo({ columnShares, rowShares })` |
|
|
59
|
+
|
|
60
|
+
A system is a `numberLine`, an `axes2d`, a `numberPlane` or a `polarPlane`. The
|
|
61
|
+
Goes in column is where each node is made to go; offering it only there is the
|
|
62
|
+
host's to do, since the engine is told only a node's key, entries and commands.
|
|
63
|
+
Nothing checks it when a document builds: a plot outside a system builds and
|
|
64
|
+
draws nothing.
|
|
65
|
+
|
|
66
|
+
Each node takes only the paints it draws. A node spreads the shape paints
|
|
67
|
+
(`fill`, `stroke` and the outline trim `start`, `end`, `progressTo`, `flash`) it
|
|
68
|
+
has a use for and leaves the rest out, so they are not offered: a plot, a tangent, an arrow or a brace is a line with
|
|
69
|
+
no fill; an area is a fill with no outline; a field is one stroke for every arrow
|
|
70
|
+
or line; a formula and a traced path reveal themselves (`writeTo`, `traceTo`)
|
|
71
|
+
rather than by trimming; a dot, a sample space and a Riemann sum have nothing a
|
|
72
|
+
trim would draw on. `shadow` stays on all of them.
|
|
73
|
+
|
|
74
|
+
## Coordinate systems
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
const document = {
|
|
78
|
+
kind: 'composition',
|
|
79
|
+
variables: [{ id: 't', value: 0 }],
|
|
80
|
+
nodes: [
|
|
81
|
+
{ id: 'axes', type: 'axes2d', parentId: null, layerOrder: 0,
|
|
82
|
+
props: { width: 800, height: 450, xRange: [-4, 4], yRange: [-2, 2], fontFamily: 'Inter' } },
|
|
83
|
+
{ id: 'curve', type: 'functionPlot', parentId: 'axes', layerOrder: 0, props: { expression: 'sin(x)' } },
|
|
84
|
+
{ id: 'dot', type: 'plotPoint', parentId: 'curve', layerOrder: 0, props: { x: '=[t]' } },
|
|
85
|
+
{ id: 'note', type: 'text', parentId: 'axes', layerOrder: 1,
|
|
86
|
+
props: { x: 2, y: 1.5, text: 'y = sin x', fontSize: 24, fontFamily: 'Inter', fill: 'white' } },
|
|
87
|
+
],
|
|
88
|
+
commands: [
|
|
89
|
+
{ id: 'a', type: 'progressTo', targetId: 'curve', at: 0, duration: 1, args: { end: 1 } },
|
|
90
|
+
{ id: 'b', type: 'variableTo', targetId: 't', at: 1, duration: 2, args: { value: 3.14 } },
|
|
91
|
+
{ id: 'c', type: 'rangeTo', targetId: 'axes', at: 3, duration: 1, args: { xRange: [0, 8] } },
|
|
92
|
+
],
|
|
93
|
+
};
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
- **A child's `x`/`y` are graph units, whatever the child is.** A text, an image
|
|
97
|
+
or a shape dropped in a system sits at graph coordinates and keeps its own
|
|
98
|
+
size; `moveTo` moves it in graph units; a range tween carries it. On a
|
|
99
|
+
`numberLine`, `x` is a value on the line and `y` is pixels above it.
|
|
100
|
+
- **A mark is drawn through the system's map.** `functionPlot`, `pointsPlot`,
|
|
101
|
+
`vectorArrow`, `curveArea`, `riemannSum`, `tangentLine` and `dropLines` are
|
|
102
|
+
marks (`traced`): their geometry is in graph coordinates and their box is the tight box of
|
|
103
|
+
their ink. A plot's or an arrow's own `x`/`y` shift it in graph units; a
|
|
104
|
+
`tangentLine`'s and a `dropLines`'s `x` is where along the graph they are.
|
|
105
|
+
Outside a system a graph unit is a pixel and a plot draws nothing.
|
|
106
|
+
- **Riding a plot.** A `plotPoint`, `tangentLine` or `dropLines` inside a
|
|
107
|
+
`functionPlot` follows that plot, appears, moves and leaves with it, and is
|
|
108
|
+
drawn over the curve: a mark's stroke is its ink, painted before its children
|
|
109
|
+
rather than last as a shape's outline is (a mark drawn with `drawMark` that
|
|
110
|
+
strokes its ink its own way passes its own `ink`). In the system instead, a
|
|
111
|
+
point or guide names a plot by id in `on`, or none and is free. `curveArea`
|
|
112
|
+
and `riemannSum` sit in the system beside the plots they read and name one in
|
|
113
|
+
`on` (an area a second in `under`). A point that rides a plot
|
|
114
|
+
takes its height from the curve and keeps its own `y` only where the curve has
|
|
115
|
+
no value.
|
|
116
|
+
- **One value drives a scene through a variable.** Bind any graph prop with
|
|
117
|
+
`"=[t]"` and animate `t` with `variableTo`; a formula may sit at any depth, so
|
|
118
|
+
a `pointsPlot` corner can be `{ x: '=[t]', y: '=25/[t]' }`. `plotPoint.value`
|
|
119
|
+
and `tangentLine.slope` can be read back as `[key.value]` and `[key.slope]`.
|
|
120
|
+
- **A system's `stroke` is its axis line and its `fill` its backdrop.** So
|
|
121
|
+
`stroke.endCap` is the axis tip. Ticks, grid lines and numbers are drawn by the
|
|
122
|
+
system itself; they are not child nodes. Drawn on with `progressTo`, the ticks
|
|
123
|
+
and numbers appear as the line reaches them.
|
|
124
|
+
- **Numbers need a font.** A system's `fontFamily` is empty by default, which
|
|
125
|
+
takes the scene's default text style; a scene with none has to set it, as any
|
|
126
|
+
text does.
|
|
127
|
+
- **An axis crosses the other at its zero**, or at the nearest edge when zero is
|
|
128
|
+
out of range or the other axis is logarithmic. A `step` of `0` picks a tidy
|
|
129
|
+
spacing for the axis's length; a log axis is marked at the powers of ten.
|
|
130
|
+
|
|
131
|
+
## 3D graphs
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
nodes: [
|
|
135
|
+
{ id: 'axes', type: 'axes3d', parentId: null, layerOrder: 0, props: { width: 960, height: 540, labels: true, fontFamily: 'Inter' } },
|
|
136
|
+
{ id: 'bump', type: 'surfacePlot3d', parentId: 'axes', layerOrder: 0,
|
|
137
|
+
props: { expression: '1.8 exp(-(x^2 + y^2) / 2)', colorScale: ['#1d4ed8', '#22c55e', '#facc15', '#ef4444'] } },
|
|
138
|
+
{ id: 'dot', type: 'plotPoint3d', parentId: 'bump', layerOrder: 0, props: { x: 0.8, y: -0.6, label: 'P' } },
|
|
139
|
+
],
|
|
140
|
+
commands: [
|
|
141
|
+
{ id: 'a', type: 'orbitTo', targetId: 'axes', at: 0, duration: 2, args: { orbit: 80, elevation: 32 } },
|
|
142
|
+
{ id: 'b', type: 'morphTo', targetId: 'bump', at: 2, duration: 1, args: { expression: '(x^2 - y^2) / 5' } },
|
|
143
|
+
],
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
- **A 3D graph is right-handed with z up.** The scene has y up, so graph x, y and
|
|
147
|
+
z run along the scene's z, x and y: seen head-on, y is to the right and z is
|
|
148
|
+
up, and the axes' default camera shows x coming toward the viewer.
|
|
149
|
+
- **An `axes3d` is its own viewport.** It is a `canvas3d` (camera, lights,
|
|
150
|
+
`orbitTo`, a box on the stage), so it needs no canvas around it and cannot go
|
|
151
|
+
inside one; a 3D shape you want beside the graph goes inside it instead.
|
|
152
|
+
- **The axes are a box, `xLength` by `yLength` by `zLength` scene units, centred
|
|
153
|
+
in the scene**, showing the three ranges. An axis crosses the others at their
|
|
154
|
+
zero, or at the nearest end of a range without one.
|
|
155
|
+
- **A child's `x`/`y`/`z` are graph units, whatever the child is**, and it keeps
|
|
156
|
+
its own size and turn: a `sphere3d` at `x: 1, y: 2, z: 0.5` sits at that graph
|
|
157
|
+
point, the built-in `moveTo` moves it in graph units, and `rangeTo` carries it.
|
|
158
|
+
- **A surface is held inside the axes.** A height that leaves the z range is
|
|
159
|
+
drawn at its edge, and one with no value is drawn flat, so a pole does not tear
|
|
160
|
+
the mesh. Left out, `uDomain` and `vDomain` are the axes' x and y ranges for a
|
|
161
|
+
height and 0 to 1 for a parametric surface.
|
|
162
|
+
- **A point put inside a surface rides it**: its `x` and `y` say where, and its
|
|
163
|
+
height is the surface's, which `surfaceValueAt(surface, x, y)` reads.
|
|
164
|
+
- **`colorScale` colours a surface by height** over the axes' z range, lowest
|
|
165
|
+
first; without one it is painted in its `fill`, the plot blue unless given one
|
|
166
|
+
(a `curvePlot3d` too). `meshLines` rules it each way.
|
|
167
|
+
- **A surface takes the mesh material props** (`opacity`, `roughness`, `wireframe`,
|
|
168
|
+
…) and is lit by the axes' lights; it is drawn from both sides.
|
|
169
|
+
- **Lines are tubes and labels are cards.** A `curvePlot3d`'s and an axis's
|
|
170
|
+
`thickness`, a point's `radius` and a label's `labelSize` are scene units, so
|
|
171
|
+
they keep their size when a range changes. A label always faces the camera.
|
|
172
|
+
- **Moving the camera** is the canvas's `orbitTo({ orbit, elevation, zoom })`, or a
|
|
173
|
+
`camera3d`'s `orbitTo` and `lookTo` when the scene has one.
|
|
174
|
+
|
|
175
|
+
| Written as | Is | Variables |
|
|
176
|
+
| --- | --- | --- |
|
|
177
|
+
| `sin(x) * cos(y)`, `z = x^2 - y^2` | a surface, as a height | `x`, `y` |
|
|
178
|
+
| `(cos(u) sin(v), sin(u) sin(v), cos(v))` | a parametric surface | `u`, `v` |
|
|
179
|
+
| `(cos(t), sin(t), t / 4)` | a space curve | `t` |
|
|
180
|
+
|
|
181
|
+
Any other name is a named value, as in a 2D plot (`surfaceParams`,
|
|
182
|
+
`spaceCurveParams`); `surfaceError` and `spaceCurveError` say why text will not draw.
|
|
183
|
+
|
|
184
|
+
## Equations
|
|
185
|
+
|
|
186
|
+
A `functionPlot`'s `expression` is read the way it is written:
|
|
187
|
+
|
|
188
|
+
| Written as | Is | Free variable, `domain` when not given |
|
|
189
|
+
| --- | --- | --- |
|
|
190
|
+
| `sin(x)`, `y = sin(x)` | a function of `x` | `x`, the system's width |
|
|
191
|
+
| `x = y^2` | a function of `y` | `y`, the system's height |
|
|
192
|
+
| `r = 1 + cos(theta)` | polar | `theta`, one turn |
|
|
193
|
+
| `(cos(t), sin(t))` | parametric | `t`, 0 to 1 |
|
|
194
|
+
| `x^2 + y^2 = 4` | implicit | drawn where it holds, over what the system shows |
|
|
195
|
+
|
|
196
|
+
- **The language is the engine's expression grammar under its own dialect**:
|
|
197
|
+
bare names, trig in radians, `ln`, `log2`, `log10`, the hyperbolics, and the
|
|
198
|
+
constants `pi`, `e`, `tau`, `phi`. Implicit multiplication (`2x`, `2(x + 1)`)
|
|
199
|
+
and `^` work as in a document formula. It never evaluates text as code.
|
|
200
|
+
- **A name the equation does not know is a named value**, held in `params`:
|
|
201
|
+
`{ expression: 'a * sin(k * x)', params: { a: 2, k: '=[speed]' } }`. One left
|
|
202
|
+
unset is 1, so an equation draws as soon as it is written; `equationParams(source)`
|
|
203
|
+
lists them for a host that draws a field for each. `paramsTo` animates them.
|
|
204
|
+
- **`morphTo` bends one curve into another**, of any kind into any kind: the two
|
|
205
|
+
are blended point for point along their parameters.
|
|
206
|
+
- **Text that is not an equation draws nothing** and throws nothing, so a host can
|
|
207
|
+
commit on every keystroke; `equationError(source)` gives the reason.
|
|
208
|
+
- **A curve is sampled adaptively** and broken at an asymptote or the edge of its
|
|
209
|
+
domain, so `1/x`, `tan(x)` and `sqrt(x)` draw as they should.
|
|
210
|
+
|
|
211
|
+
## Planes, fields and trails
|
|
212
|
+
|
|
213
|
+
- **A number plane can be transformed.** `matrix` (`[[a, b], [c, d]]`, or flat)
|
|
214
|
+
sends every point of the plane through a linear map about its origin, and
|
|
215
|
+
`warp` (two parts in x and y, `(x + sin(y), y + sin(x))`) bends it by a
|
|
216
|
+
function of its own points. The grid, the axes and everything on the plane go
|
|
217
|
+
with it: a child's position, a plot's curve, a vector's ends. `transformTo`
|
|
218
|
+
and `warpTo` animate them, each point travelling straight to where it ends up,
|
|
219
|
+
and `warpTo({ warp: "" })` flattens the plane again. While it is transformed
|
|
220
|
+
the plane leaves its flat self behind, faintly (`ghost`). The grid is ruled
|
|
221
|
+
over whatever of the plane then falls in the box, up to four times its own
|
|
222
|
+
ranges, so it stays full under a turn, a shear or a fourfold shrink, and a
|
|
223
|
+
plane squeezed onto a line folds its grid into a narrowing band.
|
|
224
|
+
- **A polar plane is a plane with another ruling.** Its children are still at x
|
|
225
|
+
and y, in the units its rings count, so `r = 1 + cos(theta)` in a
|
|
226
|
+
`functionPlot`, a point or an arrow goes on it as on axes. `radius` is its
|
|
227
|
+
outer ring, `spokes` how many divide the turn, and `angleUnit` writes them in
|
|
228
|
+
degrees or as fractions of π.
|
|
229
|
+
- **An implicit equation is drawn where it holds.** `x^2 + y^2 = 4` in a
|
|
230
|
+
`functionPlot` is traced over what the system shows. It has no parameter to
|
|
231
|
+
bend along, so a morph to or from one changes over half way.
|
|
232
|
+
- **A field is two parts in x and y**, `(-y, x)`. A `vectorField` centres an
|
|
233
|
+
arrow on each point of a grid `spacing` apart, as long as the field is strong
|
|
234
|
+
there times `arrowScale` and never longer than the spacing; a `streamLines`
|
|
235
|
+
follows the field from each of those points for `length` graph units. With a
|
|
236
|
+
list of `strengthFills` both are painted by the field's strength, weakest
|
|
237
|
+
first; without one, in the stroke's own paint.
|
|
238
|
+
`streamLines.window` shows a stretch of each line and `flowTo({ phase })` sends
|
|
239
|
+
the stretches along: one whole turn of `phase` runs every line end to end.
|
|
240
|
+
- **A traced path is a plot whose end follows a value.** It draws its equation
|
|
241
|
+
from `from` to `value`; bind `value` to a variable (`"=[t]"`) and the trail
|
|
242
|
+
grows as the variable is driven, or drive it with `traceTo({ value })`. `tail`
|
|
243
|
+
keeps only its most recent stretch.
|
|
244
|
+
|
|
245
|
+
## Graphs and sample spaces
|
|
246
|
+
|
|
247
|
+
- **A network graph is its `vertices` (names) and `edges` (`{ from, to }`, or
|
|
248
|
+
pairs).** Its `fill` paints the vertices and its `stroke` the edges; with
|
|
249
|
+
`directed` each edge ends in an arrowhead, and an edge each way between two
|
|
250
|
+
vertices bows apart. Labels are the vertices' names.
|
|
251
|
+
- **`arrangement` places the vertices**: `circular` (the first at the top,
|
|
252
|
+
clockwise), `spring` (edges pull, every pair pushes; the same every time),
|
|
253
|
+
`tree` (levels down from `root`, a parent over its children), `grid`. A vertex
|
|
254
|
+
in `positions` is placed by hand, from -1 to 1 each way. `arrangeTo` moves every
|
|
255
|
+
vertex to where another arrangement puts it. (`layout` is every node's own box,
|
|
256
|
+
hence the other word.) `vertexPoints(graph, size)` says where each vertex is drawn.
|
|
257
|
+
- **`partFillTo({ part, fill })` paints a vertex by its name, or an edge written
|
|
258
|
+
`a-b`**, arriving over the graph's own paint, as a formula's parts are painted;
|
|
259
|
+
`partFills` holds them.
|
|
260
|
+
- **A sample space's `columnShares` cut it across** (any numbers, read as shares
|
|
261
|
+
of their sum) **and each column's entry in `rowShares` cuts that column**
|
|
262
|
+
(its upper share, 0 to 1), so each part's area is its probability. Braces name
|
|
263
|
+
the columns below (`columnLabels`) and the rows on the left (`rowLabels`);
|
|
264
|
+
`values` writes each part's probability in it; `divideTo` moves the cuts.
|
|
265
|
+
`sampleParts(space, size)` gives each part's box and probability.
|
|
266
|
+
|
|
267
|
+
## Annotations
|
|
268
|
+
|
|
269
|
+
`curlyBrace`, `emphasisMark` (box, circle, underline, cross) and `angleMark`
|
|
270
|
+
work anywhere, not only on a graph. A brace or an emphasis mark names a node
|
|
271
|
+
in `on`, and optionally one `part` of a formula, and is drawn on it wherever
|
|
272
|
+
the two are in the tree; `retargetTo` slides it to another. A brace with no
|
|
273
|
+
`on` spans `tail` to `head`. An angle mark sits at its own position and sweeps
|
|
274
|
+
`fromAngle` to `toAngle` in degrees, so binding one to a variable opens it.
|
|
275
|
+
A label written between dollar signs is typeset, on these and on a plot point
|
|
276
|
+
or an axis. `FOLLOW_STATE`, `FOLLOW_COMMANDS` and `followedQuad` in
|
|
277
|
+
`@motionscript/math/kit` are what a custom mark of this kind is built on.
|
|
278
|
+
|
|
279
|
+
## Latex
|
|
280
|
+
|
|
281
|
+
The formulas below were published as `@motionscript/latex` up to
|
|
282
|
+
`0.1.0-alpha.3`; that package is no longer updated, and the same node, key and
|
|
283
|
+
exports are here.
|
|
284
|
+
|
|
285
|
+
```ts
|
|
286
|
+
import type { CompositionDocument } from '@motionscript/sdk';
|
|
287
|
+
|
|
288
|
+
export default {
|
|
289
|
+
kind: 'composition',
|
|
290
|
+
nodes: [
|
|
291
|
+
{ id: 'eq', type: 'latex', parentId: null, layerOrder: 0,
|
|
292
|
+
props: { latex: 'a^2 + b^2 = c^2', fontSize: 64, fill: 'white' } },
|
|
293
|
+
],
|
|
294
|
+
commands: [
|
|
295
|
+
{ id: 'solve', type: 'morphTo', targetId: 'eq', at: 0, duration: 1.2,
|
|
296
|
+
args: { latex: 'c = \\sqrt{a^2 + b^2}' } },
|
|
297
|
+
],
|
|
298
|
+
} satisfies CompositionDocument;
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
- **`Latex`** node, a component that draws a formula as fillable, strokable
|
|
302
|
+
glyph paths. Set `latex` to the TeX source and `fontSize` to scale it; `fill`,
|
|
303
|
+
`stroke`, `shadow`, and `padding` work like any other shape.
|
|
304
|
+
- **Formula morphing**: `morphTo` (or any `to` that names `latex`) interpolates each
|
|
305
|
+
glyph between the current and target formula, matching tokens that persist,
|
|
306
|
+
fading out tokens that leave, and fading in tokens that arrive. A persisting
|
|
307
|
+
glyph is carried by its geometry, so one that changes size on the way — the
|
|
308
|
+
`2` of `b^2` becoming the `2` of `2a`, or a symbol dropping into a `\frac` —
|
|
309
|
+
grows or shrinks across the transition instead of snapping. The hugging box
|
|
310
|
+
resizes smoothly along with it.
|
|
311
|
+
- **Parts**: every piece of the source is a part, named by that source
|
|
312
|
+
(`a^2`, `\frac{d}{dx}`, or neighbours that spell it together). `partFills`
|
|
313
|
+
and `partFillTo` paint one with any paint, `latexPartBounds(node, part)` says where it is,
|
|
314
|
+
and a morph carries a term both formulas write as one, with its fill.
|
|
315
|
+
- **`written`** writes the formula on glyph by glyph, each outlined and then
|
|
316
|
+
filled; `writeTo` animates it. It is how a formula appears, so a formula has
|
|
317
|
+
no outline trim (`start`, `end`, `progressTo`, `flash`).
|
|
318
|
+
- **`latexMatrix`** typesets `entries` in the `brackets` it is given. Each entry
|
|
319
|
+
is a part; `entriesTo` morphs to new ones.
|
|
320
|
+
- **`buildLatexPath(latex, fontSize)`**, the underlying helper that turns TeX
|
|
321
|
+
into positioned `LatexToken` glyph paths plus intrinsic size and bounds, for
|
|
322
|
+
callers that want the geometry directly.
|
|
323
|
+
|
|
324
|
+
TeX is parsed through MathJax with the `base`, `ams`, `boldsymbol`,
|
|
325
|
+
`newcommand`, `cancel`, `color`, `mhchem`, `physics`, `bbox`, and `mathtools`
|
|
326
|
+
packages enabled. Rendering is synchronous and browser-only.
|
|
327
|
+
|
|
328
|
+
A formula MathJax cannot typeset (`\frac{a`, `\fra`, a stray `{`, or `\require`,
|
|
329
|
+
since only the packages above are loaded) throws a `LatexError` from
|
|
330
|
+
`buildLatexPath`, and from a `Latex` node that holds it whenever it is laid out
|
|
331
|
+
(a document holding one fails to build). The error carries the `latex` source and MathJax's `reason`. It is the same
|
|
332
|
+
in a browser and in Node; nothing is drawn in place of the formula.
|
|
333
|
+
|
|
334
|
+
This package is written against [`@motionscript/sdk`](https://github.com/motionscript-dev/motionscript/tree/main/packages/sdk), which it
|
|
335
|
+
takes as a peer dependency, and renders through whatever backend draws the
|
|
336
|
+
scene, such as [`@motionscript/browser`](https://github.com/motionscript-dev/motionscript/tree/main/packages/browser).
|
|
337
|
+
|
|
338
|
+
## Morphing, fills and what the host supplies
|
|
339
|
+
|
|
340
|
+
- **`morphTo({ latex })` is the document command, and every `to` of `latex` is a morph.**
|
|
341
|
+
Mid-tween `latex` (a matrix's `entries` and `brackets`) holds both ends, a
|
|
342
|
+
`Morph`, and the glyphs are drawn that far between them, so a seek to any time
|
|
343
|
+
draws the morph there. A `to` of `fontSize` alone sets the formula again at
|
|
344
|
+
each size. A morph reads its from-state on its **first evaluation**, not when
|
|
345
|
+
the command is built, so two morphs in sequence start the second from the
|
|
346
|
+
first's end.
|
|
347
|
+
- **Glyphs match by key.** A token's key is the character its MathJax glyph id
|
|
348
|
+
decodes to (a mathematical italic `𝑥` is not `x`); a rule or fraction bar is
|
|
349
|
+
`__rect_N` and a bare path `__path_N`, and those never match. `defaultLatexMorph`
|
|
350
|
+
pairs keys greedily in order, fades deleted tokens over the first half and added
|
|
351
|
+
ones over the second. A custom `morph` (`LatexStrategies`) replaces it, for a
|
|
352
|
+
node built on the typeset helpers, which take it as an argument
|
|
353
|
+
(`formulaFrame(source, fontSize, partFills, morph)`); a document cannot set it.
|
|
354
|
+
- **A `latex` row needs a `fill` or a `stroke` to draw anything**; `fill` defaults
|
|
355
|
+
to none. The formula is typeset in display style, so double each backslash inside
|
|
356
|
+
a JSON string.
|
|
357
|
+
- **MathJax loads only for a scene that typesets.** It and its default font,
|
|
358
|
+
including the `\mathbb`, `\mathcal`, `\mathfrak`, `\mathscr`, `\mathsf` and
|
|
359
|
+
`\mathtt` ranges, are bundled in a module of their own that `loadMathJax()`
|
|
360
|
+
imports once. A `latex` or `latexMatrix`, and a graph, a point, a brace or an
|
|
361
|
+
angle whose label is written between dollar signs, declares the
|
|
362
|
+
`math:mathjax` loader (`MATHJAX_LOADER`), which the host waits for before
|
|
363
|
+
layout; a scene with no formula never loads it. Until it is there a formula
|
|
364
|
+
draws nothing and is asked again. Code that typesets outside a scene (a tool, a
|
|
365
|
+
test) awaits `loadMathJax()` first: `buildLatexPath` throws `LatexNotLoaded`
|
|
366
|
+
before then, and `latexPartNames` answers with nothing.
|
|
367
|
+
- **Module state is shared per process**: one MathJax document, and two LRU memos
|
|
368
|
+
(typeset geometry by formula, 128 entries; paths by size and formula, 64).
|
|
369
|
+
Importing the module registers MathJax's HTML handler, with the DOM-free adaptor
|
|
370
|
+
when there is no `window` or `document`.
|
|
371
|
+
- **A copy of `latex` takes only `tex/node.ts`** (`registry.json`); typesetting, the
|
|
372
|
+
morph and the drawing (`tex/typeset.ts`) stay in this package behind `src/engine.ts`.
|
|
373
|
+
|
|
374
|
+
## Usage
|
|
375
|
+
|
|
376
|
+
```bash
|
|
377
|
+
npm install @motionscript/math @motionscript/sdk
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
See the [docs](https://motionscript.dev/docs) for the full feature set and API
|
|
381
|
+
reference.
|
|
382
|
+
|
|
383
|
+
## Development
|
|
384
|
+
|
|
385
|
+
From the monorepo root:
|
|
386
|
+
|
|
387
|
+
```bash
|
|
388
|
+
pnpm --filter @motionscript/math build
|
|
389
|
+
pnpm --filter @motionscript/math test
|
|
390
|
+
```
|