@motionscript/math 0.0.0-stage → 0.1.0-alpha.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (335) hide show
  1. package/CHANGELOG.md +144 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +49 -0
  4. package/README.md +389 -2
  5. package/dist/annotate/angle-mark.d.ts +96 -0
  6. package/dist/annotate/angle-mark.d.ts.map +1 -0
  7. package/dist/annotate/angle-mark.js +97 -0
  8. package/dist/annotate/angle-mark.js.map +1 -0
  9. package/dist/annotate/curly-brace.d.ts +115 -0
  10. package/dist/annotate/curly-brace.d.ts.map +1 -0
  11. package/dist/annotate/curly-brace.js +99 -0
  12. package/dist/annotate/curly-brace.js.map +1 -0
  13. package/dist/annotate/emphasis-mark.d.ts +80 -0
  14. package/dist/annotate/emphasis-mark.d.ts.map +1 -0
  15. package/dist/annotate/emphasis-mark.js +80 -0
  16. package/dist/annotate/emphasis-mark.js.map +1 -0
  17. package/dist/browser/THIRD_PARTY_LICENSES.txt +420 -0
  18. package/dist/browser/chunks/chunk-IRZCG6PM.js +2 -0
  19. package/dist/browser/chunks/chunk-IRZCG6PM.js.map +7 -0
  20. package/dist/browser/chunks/chunk-WMVW6ZIV.js +2 -0
  21. package/dist/browser/chunks/chunk-WMVW6ZIV.js.map +7 -0
  22. package/dist/browser/chunks/mathjax-WV55AC2P.js +61 -0
  23. package/dist/browser/chunks/mathjax-WV55AC2P.js.map +7 -0
  24. package/dist/browser/index.js +2 -0
  25. package/dist/browser/index.js.map +7 -0
  26. package/dist/browser/kit.js +2 -0
  27. package/dist/browser/kit.js.map +7 -0
  28. package/dist/browser/manifest.json +30 -0
  29. package/dist/browser/tex.js +2 -0
  30. package/dist/browser/tex.js.map +7 -0
  31. package/dist/engine.d.ts +71 -0
  32. package/dist/engine.d.ts.map +1 -0
  33. package/dist/engine.js +45 -0
  34. package/dist/engine.js.map +1 -0
  35. package/dist/index.d.ts +30 -0
  36. package/dist/index.d.ts.map +1 -0
  37. package/dist/index.js +30 -0
  38. package/dist/index.js.map +1 -0
  39. package/dist/kit/brace.d.ts +8 -0
  40. package/dist/kit/brace.d.ts.map +1 -0
  41. package/dist/kit/brace.js +36 -0
  42. package/dist/kit/brace.js.map +1 -0
  43. package/dist/kit/cache.d.ts +30 -0
  44. package/dist/kit/cache.d.ts.map +1 -0
  45. package/dist/kit/cache.js +53 -0
  46. package/dist/kit/cache.js.map +1 -0
  47. package/dist/kit/component.d.ts +51 -0
  48. package/dist/kit/component.d.ts.map +1 -0
  49. package/dist/kit/component.js +30 -0
  50. package/dist/kit/component.js.map +1 -0
  51. package/dist/kit/contour.d.ts +8 -0
  52. package/dist/kit/contour.d.ts.map +1 -0
  53. package/dist/kit/contour.js +93 -0
  54. package/dist/kit/contour.js.map +1 -0
  55. package/dist/kit/coords.d.ts +69 -0
  56. package/dist/kit/coords.d.ts.map +1 -0
  57. package/dist/kit/coords.js +224 -0
  58. package/dist/kit/coords.js.map +1 -0
  59. package/dist/kit/curve.d.ts +28 -0
  60. package/dist/kit/curve.d.ts.map +1 -0
  61. package/dist/kit/curve.js +29 -0
  62. package/dist/kit/curve.js.map +1 -0
  63. package/dist/kit/equation.d.ts +61 -0
  64. package/dist/kit/equation.d.ts.map +1 -0
  65. package/dist/kit/equation.js +168 -0
  66. package/dist/kit/equation.js.map +1 -0
  67. package/dist/kit/equation3d.d.ts +50 -0
  68. package/dist/kit/equation3d.d.ts.map +1 -0
  69. package/dist/kit/equation3d.js +103 -0
  70. package/dist/kit/equation3d.js.map +1 -0
  71. package/dist/kit/expression.d.ts +35 -0
  72. package/dist/kit/expression.d.ts.map +1 -0
  73. package/dist/kit/expression.js +124 -0
  74. package/dist/kit/expression.js.map +1 -0
  75. package/dist/kit/field-mark.d.ts +79 -0
  76. package/dist/kit/field-mark.d.ts.map +1 -0
  77. package/dist/kit/field-mark.js +109 -0
  78. package/dist/kit/field-mark.js.map +1 -0
  79. package/dist/kit/field.d.ts +14 -0
  80. package/dist/kit/field.d.ts.map +1 -0
  81. package/dist/kit/field.js +46 -0
  82. package/dist/kit/field.js.map +1 -0
  83. package/dist/kit/follow.d.ts +109 -0
  84. package/dist/kit/follow.d.ts.map +1 -0
  85. package/dist/kit/follow.js +163 -0
  86. package/dist/kit/follow.js.map +1 -0
  87. package/dist/kit/furniture.d.ts +32 -0
  88. package/dist/kit/furniture.d.ts.map +1 -0
  89. package/dist/kit/furniture.js +92 -0
  90. package/dist/kit/furniture.js.map +1 -0
  91. package/dist/kit/geometry.d.ts +13 -0
  92. package/dist/kit/geometry.d.ts.map +1 -0
  93. package/dist/kit/geometry.js +54 -0
  94. package/dist/kit/geometry.js.map +1 -0
  95. package/dist/kit/graph.d.ts +46 -0
  96. package/dist/kit/graph.d.ts.map +1 -0
  97. package/dist/kit/graph.js +90 -0
  98. package/dist/kit/graph.js.map +1 -0
  99. package/dist/kit/mark.d.ts +72 -0
  100. package/dist/kit/mark.d.ts.map +1 -0
  101. package/dist/kit/mark.js +87 -0
  102. package/dist/kit/mark.js.map +1 -0
  103. package/dist/kit/part-fills.d.ts +23 -0
  104. package/dist/kit/part-fills.d.ts.map +1 -0
  105. package/dist/kit/part-fills.js +46 -0
  106. package/dist/kit/part-fills.js.map +1 -0
  107. package/dist/kit/place.d.ts +20 -0
  108. package/dist/kit/place.d.ts.map +1 -0
  109. package/dist/kit/place.js +66 -0
  110. package/dist/kit/place.js.map +1 -0
  111. package/dist/kit/sampler.d.ts +17 -0
  112. package/dist/kit/sampler.d.ts.map +1 -0
  113. package/dist/kit/sampler.js +250 -0
  114. package/dist/kit/sampler.js.map +1 -0
  115. package/dist/kit/scale.d.ts +12 -0
  116. package/dist/kit/scale.d.ts.map +1 -0
  117. package/dist/kit/scale.js +37 -0
  118. package/dist/kit/scale.js.map +1 -0
  119. package/dist/kit/source.d.ts +22 -0
  120. package/dist/kit/source.d.ts.map +1 -0
  121. package/dist/kit/source.js +45 -0
  122. package/dist/kit/source.js.map +1 -0
  123. package/dist/kit/system.d.ts +31 -0
  124. package/dist/kit/system.d.ts.map +1 -0
  125. package/dist/kit/system.js +71 -0
  126. package/dist/kit/system.js.map +1 -0
  127. package/dist/kit/ticks.d.ts +19 -0
  128. package/dist/kit/ticks.d.ts.map +1 -0
  129. package/dist/kit/ticks.js +78 -0
  130. package/dist/kit/ticks.js.map +1 -0
  131. package/dist/kit/withdrawn.d.ts +9 -0
  132. package/dist/kit/withdrawn.d.ts.map +1 -0
  133. package/dist/kit/withdrawn.js +9 -0
  134. package/dist/kit/withdrawn.js.map +1 -0
  135. package/dist/marks/curve-area.d.ts +51 -0
  136. package/dist/marks/curve-area.d.ts.map +1 -0
  137. package/dist/marks/curve-area.js +59 -0
  138. package/dist/marks/curve-area.js.map +1 -0
  139. package/dist/marks/drop-lines.d.ts +57 -0
  140. package/dist/marks/drop-lines.d.ts.map +1 -0
  141. package/dist/marks/drop-lines.js +43 -0
  142. package/dist/marks/drop-lines.js.map +1 -0
  143. package/dist/marks/plot-point.d.ts +71 -0
  144. package/dist/marks/plot-point.d.ts.map +1 -0
  145. package/dist/marks/plot-point.js +71 -0
  146. package/dist/marks/plot-point.js.map +1 -0
  147. package/dist/marks/riemann-sum.d.ts +58 -0
  148. package/dist/marks/riemann-sum.d.ts.map +1 -0
  149. package/dist/marks/riemann-sum.js +63 -0
  150. package/dist/marks/riemann-sum.js.map +1 -0
  151. package/dist/marks/tangent-line.d.ts +71 -0
  152. package/dist/marks/tangent-line.d.ts.map +1 -0
  153. package/dist/marks/tangent-line.js +89 -0
  154. package/dist/marks/tangent-line.js.map +1 -0
  155. package/dist/marks/vector-arrow.d.ts +60 -0
  156. package/dist/marks/vector-arrow.d.ts.map +1 -0
  157. package/dist/marks/vector-arrow.js +67 -0
  158. package/dist/marks/vector-arrow.js.map +1 -0
  159. package/dist/nodes.d.ts +43 -0
  160. package/dist/nodes.d.ts.map +1 -0
  161. package/dist/nodes.js +57 -0
  162. package/dist/nodes.js.map +1 -0
  163. package/dist/plots/function-plot.d.ts +159 -0
  164. package/dist/plots/function-plot.d.ts.map +1 -0
  165. package/dist/plots/function-plot.js +184 -0
  166. package/dist/plots/function-plot.js.map +1 -0
  167. package/dist/plots/points-plot.d.ts +64 -0
  168. package/dist/plots/points-plot.d.ts.map +1 -0
  169. package/dist/plots/points-plot.js +72 -0
  170. package/dist/plots/points-plot.js.map +1 -0
  171. package/dist/plots/stream-lines.d.ts +76 -0
  172. package/dist/plots/stream-lines.d.ts.map +1 -0
  173. package/dist/plots/stream-lines.js +122 -0
  174. package/dist/plots/stream-lines.js.map +1 -0
  175. package/dist/plots/traced-path.d.ts +70 -0
  176. package/dist/plots/traced-path.d.ts.map +1 -0
  177. package/dist/plots/traced-path.js +41 -0
  178. package/dist/plots/traced-path.js.map +1 -0
  179. package/dist/plots/vector-field.d.ts +60 -0
  180. package/dist/plots/vector-field.d.ts.map +1 -0
  181. package/dist/plots/vector-field.js +77 -0
  182. package/dist/plots/vector-field.js.map +1 -0
  183. package/dist/structures/graph-layout.d.ts +11 -0
  184. package/dist/structures/graph-layout.d.ts.map +1 -0
  185. package/dist/structures/graph-layout.js +135 -0
  186. package/dist/structures/graph-layout.js.map +1 -0
  187. package/dist/structures/network-graph.d.ts +174 -0
  188. package/dist/structures/network-graph.d.ts.map +1 -0
  189. package/dist/structures/network-graph.js +240 -0
  190. package/dist/structures/network-graph.js.map +1 -0
  191. package/dist/structures/sample-space.d.ts +114 -0
  192. package/dist/structures/sample-space.d.ts.map +1 -0
  193. package/dist/structures/sample-space.js +161 -0
  194. package/dist/structures/sample-space.js.map +1 -0
  195. package/dist/systems/axes2d.d.ts +197 -0
  196. package/dist/systems/axes2d.d.ts.map +1 -0
  197. package/dist/systems/axes2d.js +157 -0
  198. package/dist/systems/axes2d.js.map +1 -0
  199. package/dist/systems/number-line.d.ts +101 -0
  200. package/dist/systems/number-line.d.ts.map +1 -0
  201. package/dist/systems/number-line.js +91 -0
  202. package/dist/systems/number-line.js.map +1 -0
  203. package/dist/systems/number-plane.d.ts +168 -0
  204. package/dist/systems/number-plane.d.ts.map +1 -0
  205. package/dist/systems/number-plane.js +186 -0
  206. package/dist/systems/number-plane.js.map +1 -0
  207. package/dist/systems/polar-plane.d.ts +98 -0
  208. package/dist/systems/polar-plane.d.ts.map +1 -0
  209. package/dist/systems/polar-plane.js +139 -0
  210. package/dist/systems/polar-plane.js.map +1 -0
  211. package/dist/tex/geometry.d.ts +85 -0
  212. package/dist/tex/geometry.d.ts.map +1 -0
  213. package/dist/tex/geometry.js +632 -0
  214. package/dist/tex/geometry.js.map +1 -0
  215. package/dist/tex/index.d.ts +11 -0
  216. package/dist/tex/index.d.ts.map +1 -0
  217. package/dist/tex/index.js +10 -0
  218. package/dist/tex/index.js.map +1 -0
  219. package/dist/tex/mathjax.d.ts +33 -0
  220. package/dist/tex/mathjax.d.ts.map +1 -0
  221. package/dist/tex/mathjax.js +74 -0
  222. package/dist/tex/mathjax.js.map +1 -0
  223. package/dist/tex/matrix.d.ts +101 -0
  224. package/dist/tex/matrix.d.ts.map +1 -0
  225. package/dist/tex/matrix.js +56 -0
  226. package/dist/tex/matrix.js.map +1 -0
  227. package/dist/tex/node.d.ts +98 -0
  228. package/dist/tex/node.d.ts.map +1 -0
  229. package/dist/tex/node.js +25 -0
  230. package/dist/tex/node.js.map +1 -0
  231. package/dist/tex/tween.d.ts +50 -0
  232. package/dist/tex/tween.d.ts.map +1 -0
  233. package/dist/tex/tween.js +253 -0
  234. package/dist/tex/tween.js.map +1 -0
  235. package/dist/tex/typeset.d.ts +133 -0
  236. package/dist/tex/typeset.d.ts.map +1 -0
  237. package/dist/tex/typeset.js +403 -0
  238. package/dist/tex/typeset.js.map +1 -0
  239. package/dist/three/axes3d.d.ts +247 -0
  240. package/dist/three/axes3d.d.ts.map +1 -0
  241. package/dist/three/axes3d.js +187 -0
  242. package/dist/three/axes3d.js.map +1 -0
  243. package/dist/three/curve-plot3d.d.ts +126 -0
  244. package/dist/three/curve-plot3d.d.ts.map +1 -0
  245. package/dist/three/curve-plot3d.js +109 -0
  246. package/dist/three/curve-plot3d.js.map +1 -0
  247. package/dist/three/entries.d.ts +17 -0
  248. package/dist/three/entries.d.ts.map +1 -0
  249. package/dist/three/entries.js +15 -0
  250. package/dist/three/entries.js.map +1 -0
  251. package/dist/three/label3d.d.ts +11 -0
  252. package/dist/three/label3d.d.ts.map +1 -0
  253. package/dist/three/label3d.js +42 -0
  254. package/dist/three/label3d.js.map +1 -0
  255. package/dist/three/plot-point3d.d.ts +99 -0
  256. package/dist/three/plot-point3d.d.ts.map +1 -0
  257. package/dist/three/plot-point3d.js +34 -0
  258. package/dist/three/plot-point3d.js.map +1 -0
  259. package/dist/three/space.d.ts +43 -0
  260. package/dist/three/space.d.ts.map +1 -0
  261. package/dist/three/space.js +58 -0
  262. package/dist/three/space.js.map +1 -0
  263. package/dist/three/surface-plot3d.d.ts +207 -0
  264. package/dist/three/surface-plot3d.d.ts.map +1 -0
  265. package/dist/three/surface-plot3d.js +261 -0
  266. package/dist/three/surface-plot3d.js.map +1 -0
  267. package/dist/three/vector-arrow3d.d.ts +96 -0
  268. package/dist/three/vector-arrow3d.d.ts.map +1 -0
  269. package/dist/three/vector-arrow3d.js +53 -0
  270. package/dist/three/vector-arrow3d.js.map +1 -0
  271. package/package.json +80 -3
  272. package/registry.json +251 -0
  273. package/src/annotate/angle-mark.ts +137 -0
  274. package/src/annotate/curly-brace.ts +148 -0
  275. package/src/annotate/emphasis-mark.ts +118 -0
  276. package/src/engine.ts +86 -0
  277. package/src/index.ts +29 -0
  278. package/src/kit/brace.ts +37 -0
  279. package/src/kit/cache.ts +61 -0
  280. package/src/kit/component.ts +57 -0
  281. package/src/kit/contour.ts +94 -0
  282. package/src/kit/coords.ts +278 -0
  283. package/src/kit/curve.ts +47 -0
  284. package/src/kit/equation.ts +181 -0
  285. package/src/kit/equation3d.ts +137 -0
  286. package/src/kit/expression.ts +159 -0
  287. package/src/kit/field-mark.ts +171 -0
  288. package/src/kit/field.ts +50 -0
  289. package/src/kit/follow.ts +229 -0
  290. package/src/kit/furniture.ts +113 -0
  291. package/src/kit/geometry.ts +49 -0
  292. package/src/kit/graph.ts +116 -0
  293. package/src/kit/mark.ts +152 -0
  294. package/src/kit/part-fills.ts +61 -0
  295. package/src/kit/place.ts +77 -0
  296. package/src/kit/sampler.ts +281 -0
  297. package/src/kit/scale.ts +39 -0
  298. package/src/kit/source.ts +57 -0
  299. package/src/kit/system.ts +105 -0
  300. package/src/kit/ticks.ts +85 -0
  301. package/src/kit/withdrawn.ts +8 -0
  302. package/src/marks/curve-area.ts +89 -0
  303. package/src/marks/drop-lines.ts +71 -0
  304. package/src/marks/plot-point.ts +102 -0
  305. package/src/marks/riemann-sum.ts +99 -0
  306. package/src/marks/tangent-line.ts +119 -0
  307. package/src/marks/vector-arrow.ts +98 -0
  308. package/src/nodes.ts +99 -0
  309. package/src/plots/function-plot.ts +220 -0
  310. package/src/plots/points-plot.ts +103 -0
  311. package/src/plots/stream-lines.ts +160 -0
  312. package/src/plots/traced-path.ts +70 -0
  313. package/src/plots/vector-field.ts +107 -0
  314. package/src/structures/graph-layout.ts +145 -0
  315. package/src/structures/network-graph.ts +291 -0
  316. package/src/structures/sample-space.ts +210 -0
  317. package/src/systems/axes2d.ts +226 -0
  318. package/src/systems/number-line.ts +130 -0
  319. package/src/systems/number-plane.ts +232 -0
  320. package/src/systems/polar-plane.ts +177 -0
  321. package/src/tex/geometry.ts +703 -0
  322. package/src/tex/index.ts +15 -0
  323. package/src/tex/mathjax.ts +82 -0
  324. package/src/tex/matrix.ts +97 -0
  325. package/src/tex/node.ts +74 -0
  326. package/src/tex/tween.ts +308 -0
  327. package/src/tex/typeset.ts +461 -0
  328. package/src/three/axes3d.ts +267 -0
  329. package/src/three/curve-plot3d.ts +146 -0
  330. package/src/three/entries.ts +42 -0
  331. package/src/three/label3d.ts +52 -0
  332. package/src/three/plot-point3d.ts +63 -0
  333. package/src/three/space.ts +92 -0
  334. package/src/three/surface-plot3d.ts +318 -0
  335. package/src/three/vector-arrow3d.ts +88 -0
@@ -0,0 +1,267 @@
1
+ import {
2
+ component2d,
3
+ Flow,
4
+ Geo,
5
+ Graphics3D,
6
+ Mat,
7
+ Paint,
8
+ provides,
9
+ Shapes,
10
+ Types,
11
+ View3D,
12
+ type Canvas3DProps,
13
+ type Color,
14
+ type NodeOf,
15
+ type Scene3D,
16
+ type Transform3D,
17
+ type Values,
18
+ type Vector3,
19
+ type Vector3Input,
20
+ // Named so the emitted declaration reaches these through the sdk, not core.
21
+ type Alignment as _Alignment,
22
+ type CornerRadiusResolved as _CornerRadiusResolved,
23
+ type CornerStyleResolved as _CornerStyleResolved,
24
+ type Fill as _Fill,
25
+ type FillResolved as _FillResolved,
26
+ type FlowMode as _FlowMode,
27
+ type FlowResolved as _FlowResolved,
28
+ type GapSize as _GapSize,
29
+ type Node2D as _Node2D,
30
+ type Node2DProps as _Node2DProps,
31
+ type NormalizedColor as _NormalizedColor,
32
+ type PostEffect3D as _PostEffect3D,
33
+ type RectCornerRadius as _RectCornerRadius,
34
+ type RectCornerStyle as _RectCornerStyle,
35
+ type Shadow as _Shadow,
36
+ type ShadowResolved as _ShadowResolved,
37
+ type Shadows3D as _Shadows3D,
38
+ type Stroke as _Stroke,
39
+ type StrokeResolved as _StrokeResolved,
40
+ type ToneMapping3D as _ToneMapping3D,
41
+ type Vector2 as _Vector2,
42
+ } from "@motionscript/sdk";
43
+ import type { Interval } from "../kit/coords";
44
+ import { AXIS_COLOR, lerpInterval, readInterval } from "../kit/furniture";
45
+ import { clamp } from "../kit/geometry";
46
+ import { formatTick, ticksFor } from "../kit/ticks";
47
+ import { drawLabel3D, type LabelStyle3D } from "./label3d";
48
+ import { GRAPH_3D, graphSpace, type Graph3D, type GraphSpace } from "./space";
49
+
50
+ export interface Axes3dProps extends Canvas3DProps {
51
+ xRange?: Interval;
52
+ yRange?: Interval;
53
+ zRange?: Interval;
54
+ xLength?: number;
55
+ yLength?: number;
56
+ zLength?: number;
57
+ xStep?: number;
58
+ yStep?: number;
59
+ zStep?: number;
60
+ color?: Color;
61
+ thickness?: number;
62
+ tips?: boolean;
63
+ ticks?: boolean;
64
+ tickSize?: number;
65
+ grid?: boolean;
66
+ gridLineColor?: Color;
67
+ labels?: boolean;
68
+ labelSize?: number;
69
+ labelColor?: Color;
70
+ fontFamily?: string;
71
+ xLabel?: string;
72
+ yLabel?: string;
73
+ zLabel?: string;
74
+ }
75
+
76
+ /** How many pixels of a 2D axis one scene unit counts as, when an axis picks its own tick spacing. */
77
+ const UNIT_AS_PIXELS = 64;
78
+
79
+ type AxisName = "x" | "y" | "z";
80
+
81
+ /** The turn that lays a shape built along the scene's +y along each graph axis. */
82
+ const ALONG: Record<AxisName, Vector3Input> = { x: [90, 0, 0], y: [0, 0, -90], z: [0, 0, 0] };
83
+
84
+ /** The graph axis each axis's tick marks lie along. */
85
+ const TICK_ALONG: Record<AxisName, AxisName> = { x: "y", y: "x", z: "y" };
86
+
87
+ function range(initial: Interval) {
88
+ return Types.custom<Interval>(initial, { resolve: readInterval, lerp: lerpInterval });
89
+ }
90
+
91
+ /** The axes' own entries, beside a 3D canvas's. */
92
+ const own = {
93
+ xRange: range([-3, 3]),
94
+ yRange: range([-3, 3]),
95
+ zRange: range([-2, 2]),
96
+ /** How long each axis is drawn, in scene units. */
97
+ xLength: Types.number(6, { min: 0.01, step: 0.1 }),
98
+ yLength: Types.number(6, { min: 0.01, step: 0.1 }),
99
+ zLength: Types.number(4, { min: 0.01, step: 0.1 }),
100
+ /** The spacing of each axis's ticks; zero picks a tidy one for the axis's length. */
101
+ xStep: Types.number(0, { min: 0 }),
102
+ yStep: Types.number(0, { min: 0 }),
103
+ zStep: Types.number(0, { min: 0 }),
104
+ color: Types.color(AXIS_COLOR),
105
+ /** The radius of an axis line, in scene units. */
106
+ thickness: Types.number(0.02, { min: 0, step: 0.005 }),
107
+ tips: Types.boolean(true, { animatable: false }),
108
+ ticks: Types.boolean(true, { animatable: false }),
109
+ tickSize: Types.number(0.16, { min: 0, step: 0.01 }),
110
+ /** Lines across the plane the x and y axes lie in, at each of their ticks. */
111
+ grid: Types.boolean(false, { animatable: false }),
112
+ /** (`gridColor` is the viewport's own reference grid.) */
113
+ gridLineColor: Types.color("#374151"),
114
+ /** A number at each tick. */
115
+ labels: Types.boolean(false, { animatable: false }),
116
+ /** The height of a label's text, in scene units. */
117
+ labelSize: Types.number(0.26, { min: 0.01, step: 0.01 }),
118
+ labelColor: Types.color(AXIS_COLOR),
119
+ fontFamily: Types.text("", { animatable: false }),
120
+ /** A title at the positive end of each axis. */
121
+ xLabel: Types.text("x", { animatable: false }),
122
+ yLabel: Types.text("y", { animatable: false }),
123
+ zLabel: Types.text("z", { animatable: false }),
124
+ };
125
+
126
+ type AxesValues = Values<typeof own>;
127
+
128
+ /**
129
+ * A 3D graph: three axes through a box of graph coordinates, z up, seen through
130
+ * a camera of its own, so it stands on a 2D stage as it is, the way `axes2d`
131
+ * does. Its 3D children sit in its graph coordinates: a surface, a space curve,
132
+ * a point, an arrow, or any 3D node. `orbitTo` swings the camera round it.
133
+ */
134
+ export const Axes3d = component2d({
135
+ key: "axes3d",
136
+ state: { ...Paint.state, ...Flow.state, ...Shapes.corners, ...View3D.state, ...own },
137
+ defaults: { width: "fill", height: "fill" },
138
+ commands: {
139
+ ...Paint.commands,
140
+ ...View3D.commands,
141
+ /** Animate the window of values the axes show; everything drawn in them follows. */
142
+ rangeTo: { args: ["xRange", "yRange", "zRange"] },
143
+ },
144
+ allowedChildren: ["2d", "3d"],
145
+ load: (loader, s) => {
146
+ View3D.load(loader, furnish(s));
147
+ if (s.fontFamily !== "") loader.font(s.fontFamily);
148
+ },
149
+ provide: (s) => [provides(GRAPH_3D, graphOfAxes(s))],
150
+ space: (s) => axesSpace(s),
151
+ measure: (measurer, s, children) => Flow.measure(measurer, s, children, Paint.inset(s)),
152
+ layout: (box, s, children) => Flow.layout(box, s, children, Paint.inset(s)),
153
+ render: (ctx, s) => View3D.draw(ctx, s, furnish(s)),
154
+ });
155
+
156
+ export type Axes3d = NodeOf<typeof Axes3d>;
157
+
158
+ /** The axes' own drawing, added to the scene: what `render` draws and `load` declares. */
159
+ function furnish(s: AxesValues): (scene: Scene3D) => void {
160
+ return (scene) => scene.draw(furniture(s));
161
+ }
162
+
163
+ /** The last space worked out for each axes, kept while its ranges and lengths are unchanged. */
164
+ const spaces = new WeakMap<object, { readonly key: string; readonly space: GraphSpace }>();
165
+
166
+ /** The coordinates of a 3D graph: what its children's `x`, `y` and `z` are in. */
167
+ function axesSpace(s: AxesValues): GraphSpace {
168
+ const { xRange, yRange, zRange, xLength, yLength, zLength } = s;
169
+ const key = [xRange, yRange, zRange, xLength, yLength, zLength].join("|");
170
+ let kept = spaces.get(s);
171
+ if (kept?.key !== key) spaces.set(s, (kept = { key, space: graphSpace(xRange, yRange, zRange, { x: xLength, y: yLength, z: zLength }) }));
172
+ return kept.space;
173
+ }
174
+
175
+ // One per axes, so the context its subtree holds is the same from frame to frame.
176
+ const graphs = new WeakMap<object, Graph3D>();
177
+
178
+ function graphOfAxes(s: AxesValues): Graph3D {
179
+ let graph = graphs.get(s);
180
+ if (!graph) graphs.set(s, (graph = { space: () => axesSpace(s) }));
181
+ return graph;
182
+ }
183
+
184
+ /** The axes, their ticks, numbers and titles, and the grid, in the scene's units. */
185
+ function furniture(s: AxesValues): Graphics3D {
186
+ const space = axesSpace(s);
187
+ const g3 = new Graphics3D();
188
+ const ranges: Record<AxisName, Interval> = { x: space.xRange, y: space.yRange, z: space.zRange };
189
+ const lengths: Record<AxisName, number> = { x: s.xLength, y: s.yLength, z: s.zLength };
190
+ const steps: Record<AxisName, number> = { x: s.xStep, y: s.yStep, z: s.zStep };
191
+ const titles: Record<AxisName, string> = { x: s.xLabel, y: s.yLabel, z: s.zLabel };
192
+ // Where each axis is crossed by the other two: their zero, or the nearest end of a range without one.
193
+ const cross: Record<AxisName, number> = {
194
+ x: clamp(0, ranges.x[0], ranges.x[1]),
195
+ y: clamp(0, ranges.y[0], ranges.y[1]),
196
+ z: clamp(0, ranges.z[0], ranges.z[1]),
197
+ };
198
+ const at = (axis: AxisName, value: number, shift: Partial<Record<AxisName, number>> = {}): Vector3 => {
199
+ const point = { ...cross, [axis]: value };
200
+ const local = space.toLocal(point.x, point.y, point.z);
201
+ const moved = space.offset(0, 0, 0);
202
+ for (const key of ["x", "y", "z"] as const) {
203
+ const by = shift[key];
204
+ if (by === undefined) continue;
205
+ // A shift is in scene units, along the graph axis it names.
206
+ if (key === "x") moved.z += by;
207
+ else if (key === "y") moved.x += by;
208
+ else moved.y += by;
209
+ }
210
+ return { x: local.x + moved.x, y: local.y + moved.y, z: local.z + moved.z };
211
+ };
212
+
213
+ const { thickness, tickSize } = s;
214
+ const paint = Mat.basic({ color: s.color });
215
+ const style: LabelStyle3D = { size: s.labelSize, color: s.labelColor, fontFamily: s.fontFamily };
216
+ const tipLength = s.tips ? thickness * 9 : 0;
217
+ const marks: Transform3D[] = [];
218
+ const plane: Vector3[] = [];
219
+
220
+ for (const axis of ["x", "y", "z"] as const) {
221
+ const [min, max] = ranges[axis];
222
+ const length = lengths[axis];
223
+ if (!(max > min) || !(length > 0)) continue;
224
+
225
+ if (thickness > 0) {
226
+ const from = at(axis, min);
227
+ const to = at(axis, max);
228
+ g3.mesh(Geo.cylinder({ radius: thickness, height: length, segments: [12, 1] }), paint, {
229
+ position: { x: (from.x + to.x) / 2, y: (from.y + to.y) / 2, z: (from.z + to.z) / 2 },
230
+ rotation: ALONG[axis],
231
+ });
232
+ if (s.tips) {
233
+ g3.mesh(Geo.cone({ radius: thickness * 3.2, height: tipLength, segments: [16, 1] }), paint, {
234
+ position: at(axis, max, { [axis]: tipLength / 2 }),
235
+ rotation: ALONG[axis],
236
+ });
237
+ }
238
+ }
239
+
240
+ const ticks = ticksFor(ranges[axis], steps[axis], length * UNIT_AS_PIXELS);
241
+ const side = TICK_ALONG[axis];
242
+ for (const value of ticks.values) {
243
+ // The crossing is marked by the other axes, and the far end by the tip.
244
+ if (Math.abs(value - cross[axis]) < 1e-9 || (s.tips && Math.abs(value - max) < 1e-9)) continue;
245
+ if (s.ticks && tickSize > 0) marks.push({ position: at(axis, value), rotation: ALONG[side] });
246
+ if (s.labels) {
247
+ drawLabel3D(g3, formatTick(value, ticks.step), at(axis, value, { [side]: -(tickSize / 2 + style.size * 0.8) }), style);
248
+ }
249
+ }
250
+ drawLabel3D(g3, titles[axis], at(axis, max, { [axis]: tipLength + style.size * 0.9 }), style);
251
+
252
+ if (s.grid && axis !== "z") {
253
+ const other = axis === "x" ? "y" : "x";
254
+ for (const value of ticks.values) {
255
+ const a = { x: 0, y: 0, z: cross.z, [axis]: value, [other]: ranges[other][0] };
256
+ const b = { ...a, [other]: ranges[other][1] };
257
+ plane.push(space.toLocal(a.x, a.y, a.z), space.toLocal(b.x, b.y, b.z));
258
+ }
259
+ }
260
+ }
261
+
262
+ if (marks.length > 0) {
263
+ g3.instances(Geo.cylinder({ radius: Math.max(thickness * 0.7, 0.008), height: tickSize, segments: [8, 1] }), paint, marks);
264
+ }
265
+ if (plane.length > 0) g3.line({ points: plane, segments: true, stroke: { fill: s.gridLineColor } });
266
+ return g3;
267
+ }
@@ -0,0 +1,146 @@
1
+ import {
2
+ component3d,
3
+ Geo,
4
+ Graphics3D,
5
+ Material,
6
+ Types,
7
+ type Geometry3D,
8
+ type Mesh3DProps,
9
+ type NodeOf,
10
+ type Values,
11
+ type Vector3,
12
+ // Named so the emitted declaration reaches these through the sdk, not core.
13
+ type Blend3D as _Blend3D,
14
+ type Color as _Color,
15
+ type Faces3D as _Faces3D,
16
+ type Fill3D as _Fill3D,
17
+ type Material3D as _Material3D,
18
+ type Node3D as _Node3D,
19
+ type Node3DProps as _Node3DProps,
20
+ type NormalizedColor as _NormalizedColor,
21
+ type Shading3D as _Shading3D,
22
+ type Texture3D as _Texture3D,
23
+ } from "@motionscript/sdk";
24
+ import type { Interval } from "../kit/coords";
25
+ import { parseSpaceCurve, spaceCurveParams, type SpaceCurveEquation } from "../kit/equation3d";
26
+ import type { ExpressionScope } from "../kit/expression";
27
+ import { PLOT_COLOR } from "../kit/furniture";
28
+ import { clamp } from "../kit/geometry";
29
+ import { lerpParams, lerpSource, readSource, scopeFor, type PlotSource } from "../kit/source";
30
+ import { domainEntry, meshEntries } from "./entries";
31
+ import { graphEntry, graphOf, type GraphSpace } from "./space";
32
+
33
+ export interface CurvePlot3dProps extends Mesh3DProps {
34
+ expression?: string | PlotSource;
35
+ domain?: Interval | null;
36
+ params?: ExpressionScope;
37
+ samples?: number;
38
+ thickness?: number;
39
+ start?: number;
40
+ end?: number;
41
+ }
42
+
43
+ const state = {
44
+ ...meshEntries,
45
+ expression: Types.custom<string | PlotSource, PlotSource>("", {
46
+ resolve: readSource,
47
+ lerp: lerpSource,
48
+ kind: "spaceCurveEquation",
49
+ }),
50
+ /** The span of `t` that is drawn; 0 to 1 when left out. */
51
+ domain: domainEntry(0, 1),
52
+ params: Types.custom<ExpressionScope>({}, { lerp: lerpParams }),
53
+ /** How many points the curve is drawn through. */
54
+ samples: Types.number(160, { min: 2, max: 2000, step: 1, animatable: false }),
55
+ /** The radius of the line, in scene units. */
56
+ thickness: Types.number(0.04, { min: 0.001, step: 0.005 }),
57
+ /** The part of the curve that is drawn, as shares of its length in `t`. */
58
+ start: Types.number(0, { min: 0, max: 1, step: 0.01 }),
59
+ end: Types.number(1, { min: 0, max: 1, step: 0.01 }),
60
+ graph: graphEntry(),
61
+ };
62
+
63
+ type CurveValues = Values<typeof state>;
64
+
65
+ /** A curve through a 3D graph, three parts in `t`: `(cos(t), sin(t), t / 4)`. */
66
+ export const CurvePlot3d = component3d({
67
+ key: "curvePlot3d",
68
+ state,
69
+ defaults: { fill: PLOT_COLOR },
70
+ commands: {
71
+ /** Change the equation, the curve bending from the one into the other. */
72
+ morphTo: { args: ["expression"] },
73
+ /** Animate the equation's named values. */
74
+ paramsTo: { args: ["params"] },
75
+ /** Animate the span of `t` that is drawn. */
76
+ domainTo: { args: ["domain"] },
77
+ /** Draw the curve on, or wipe it off: animates `start` and `end`. */
78
+ progressTo: { args: ["start", "end"] },
79
+ },
80
+ // Declaring, its paint on a stand-in: only a material loads, and the curve's points are not sampled.
81
+ render: (ctx, s) => ctx.draw(ctx.declaring ? new Graphics3D().plane(Material.shorthand(s)) : Material.mesh(s, curveGeometry(s))),
82
+ });
83
+
84
+ export type CurvePlot3d = NodeOf<typeof CurvePlot3d>;
85
+
86
+ function curveGeometry(s: CurveValues): Geometry3D | undefined {
87
+ const space = graphOf(s);
88
+ if (!space) return undefined;
89
+ const points = pointsOf(s, space);
90
+ if (points.length < 2) return undefined;
91
+ return Geo.tube({ points, radius: s.thickness, segments: [points.length - 1, 8] });
92
+ }
93
+
94
+ /** The last run drawn for each curve, kept while what it is drawn from is unchanged. */
95
+ const runs = new WeakMap<object, { readonly key: string; readonly run: Vector3[] }>();
96
+
97
+ function pointsOf(s: CurveValues, space: GraphSpace): Vector3[] {
98
+ const { source, blend } = s.expression;
99
+ const start = clamp(s.start, 0, 1);
100
+ const end = clamp(s.end, 0, 1);
101
+ const samples = Math.max(2, Math.round(s.samples));
102
+ const key = [source, blend?.from, blend?.t, space.revision, s.domain, JSON.stringify(s.params), start, end, samples].join("|");
103
+ const kept = runs.get(s);
104
+ if (kept?.key === key) return kept.run;
105
+ const run: Vector3[] = [];
106
+ runs.set(s, { key, run });
107
+ const to = curveOf(s, source);
108
+ if (!to || !(end > start)) return run;
109
+ const from = blend ? curveOf(s, blend.from) : null;
110
+ const steps = Math.max(1, Math.round(samples * (end - start)));
111
+ const a: Vector3 = { x: 0, y: 0, z: 0 };
112
+ const b: Vector3 = { x: 0, y: 0, z: 0 };
113
+ for (let i = 0; i <= steps; i++) {
114
+ const u = start + ((end - start) * i) / steps;
115
+ if (!to(u, b)) continue;
116
+ if (from && blend) {
117
+ if (!from(u, a)) continue;
118
+ b.x = a.x + (b.x - a.x) * blend.t;
119
+ b.y = a.y + (b.y - a.y) * blend.t;
120
+ b.z = a.z + (b.z - a.z) * blend.t;
121
+ }
122
+ run.push(space.offset(b.x, b.y, b.z));
123
+ }
124
+ return run;
125
+ }
126
+
127
+ /** `source` as a graph point for a share `u` of its span, or `false` where it has none. */
128
+ function curveOf(s: CurveValues, source: string): ((u: number, out: Vector3) => boolean) | null {
129
+ const equation = equationOf(source);
130
+ if (!equation) return null;
131
+ const params = scopeFor(spaceCurveParams(source), s.params);
132
+ const [t0, t1] = s.domain ?? [0, 1];
133
+ const { x, y, z } = equation;
134
+ return (u, out) => {
135
+ const t = t0 + (t1 - t0) * u;
136
+ out.x = x(t, 0, params);
137
+ out.y = y(t, 0, params);
138
+ out.z = z(t, 0, params);
139
+ return Number.isFinite(out.x) && Number.isFinite(out.y) && Number.isFinite(out.z);
140
+ };
141
+ }
142
+
143
+ function equationOf(source: string): SpaceCurveEquation | null {
144
+ const equation = parseSpaceCurve(source, spaceCurveParams(source));
145
+ return equation instanceof Error ? null : equation;
146
+ }
@@ -0,0 +1,42 @@
1
+ import {
2
+ Material,
3
+ Types,
4
+ type EntryOptions,
5
+ type Geometry3D,
6
+ type Type,
7
+ // Named so the emitted declaration reaches these through the sdk, not core.
8
+ type Blend3D as _Blend3D,
9
+ type Color as _Color,
10
+ type Faces3D as _Faces3D,
11
+ type Fill3D as _Fill3D,
12
+ type Material3D as _Material3D,
13
+ type NormalizedColor as _NormalizedColor,
14
+ type Shading3D as _Shading3D,
15
+ type Texture3D as _Texture3D,
16
+ } from "@motionscript/sdk";
17
+ import type { Interval } from "../kit/coords";
18
+ import { lerpDomain } from "../kit/source";
19
+
20
+ type MeshState = { readonly geometry: Type<Geometry3D | undefined> } & typeof Material.state;
21
+ // Restated key by key, so a mark spreading these names each entry's type through the sdk: spread
22
+ // as inferred, a mark's declaration copied `emission`'s colour types from core's own.
23
+ type Restated<T> = { [K in Extract<keyof T, string>]: T[K] };
24
+
25
+ /**
26
+ * A mesh's entries, as a 3D mark draws with them: its surface, and the
27
+ * `geometry` a mesh takes, which a mark builds itself and never reads.
28
+ */
29
+ export const meshEntries: Restated<MeshState> = {
30
+ geometry: Types.custom<Geometry3D | undefined>(undefined),
31
+ ...Material.state,
32
+ };
33
+
34
+ interface RangeHints extends EntryOptions {
35
+ readonly defaultMin: number;
36
+ readonly defaultMax: number;
37
+ }
38
+
39
+ /** A span of a variable, unset until given: what a host offers as a range from `defaultMin` to `defaultMax`. */
40
+ export function domainEntry(defaultMin: number, defaultMax: number): Type<Interval | null> {
41
+ return Types.custom<Interval | null, Interval | null, RangeHints>(null, { lerp: lerpDomain, kind: "range", defaultMin, defaultMax });
42
+ }
@@ -0,0 +1,52 @@
1
+ import { Fills, Graphics2D, Mat, Tex, type Color, type Graphics3D, type SurfaceTexture3D, type Vector3 } from "@motionscript/sdk";
2
+ import { createBoundedCache } from "../kit/cache";
3
+
4
+ /** Text in a 3D graph: a camera-facing card, so a number reads square-on from wherever the scene is seen. */
5
+
6
+ export interface LabelStyle3D {
7
+ /** The height of the text's em, in scene units. */
8
+ size: number;
9
+ color: Color;
10
+ fontFamily: string;
11
+ }
12
+
13
+ /** The em the text is rasterized at, in buffer pixels, and the card's height around it. */
14
+ const EM = 64;
15
+ const CARD_HEIGHT = 96;
16
+
17
+ // A texture's identity is its source object, so one text in one style is one source for as long as it is asked for.
18
+ const cards = createBoundedCache<{ texture: SurfaceTexture3D; width: number }>(256);
19
+
20
+ function card(text: string, style: LabelStyle3D): { texture: SurfaceTexture3D; width: number } {
21
+ const key = `${style.fontFamily}|${JSON.stringify(style.color)}|${text}`;
22
+ const hit = cards.get(key);
23
+ if (hit) return hit;
24
+ const width = Math.min(1024, Math.max(128, Math.ceil((text.length * EM * 0.62 + EM) / 32) * 32));
25
+ const source = new Graphics2D()
26
+ .text({
27
+ text,
28
+ fontSize: EM,
29
+ ...(style.fontFamily === "" ? {} : { fontFamily: style.fontFamily }),
30
+ wrap: false,
31
+ width,
32
+ textAlign: "center",
33
+ })
34
+ .fill(Fills.color(style.color));
35
+ // Its pixels never change, so the renderer rasterizes it once rather than every frame.
36
+ const texture: SurfaceTexture3D = { ...Tex.surface(source, { width, height: CARD_HEIGHT }), static: true, identity: `label3d:${key}` };
37
+ const made = { texture, width };
38
+ cards.set(key, made);
39
+ return made;
40
+ }
41
+
42
+ /** Draw `text` centred on `at`, a local point. */
43
+ export function drawLabel3D(g3: Graphics3D, text: string, at: Vector3, style: LabelStyle3D): void {
44
+ if (text === "" || !(style.size > 0)) return;
45
+ const { texture, width } = card(text, style);
46
+ const height = (style.size * CARD_HEIGHT) / EM;
47
+ g3.sprite({
48
+ material: Mat.sprite({ map: texture, transparent: true, depthWrite: false }),
49
+ position: at,
50
+ scale: [(height * width) / CARD_HEIGHT, height, 1],
51
+ });
52
+ }
@@ -0,0 +1,63 @@
1
+ import {
2
+ component3d,
3
+ Geo,
4
+ Material,
5
+ Types,
6
+ type Color,
7
+ type Mesh3DProps,
8
+ type NodeOf,
9
+ // Named so the emitted declaration reaches these through the sdk, not core.
10
+ type Blend3D as _Blend3D,
11
+ type Color as _Color,
12
+ type Faces3D as _Faces3D,
13
+ type Fill3D as _Fill3D,
14
+ type Geometry3D as _Geometry3D,
15
+ type Material3D as _Material3D,
16
+ type Node3D as _Node3D,
17
+ type Node3DProps as _Node3DProps,
18
+ type NormalizedColor as _NormalizedColor,
19
+ type Shading3D as _Shading3D,
20
+ type Texture3D as _Texture3D,
21
+ } from "@motionscript/sdk";
22
+ import { meshEntries } from "./entries";
23
+ import { drawLabel3D } from "./label3d";
24
+
25
+ export interface PlotPoint3dProps extends Mesh3DProps {
26
+ radius?: number;
27
+ label?: string;
28
+ labelSize?: number;
29
+ labelColor?: Color;
30
+ fontFamily?: string;
31
+ }
32
+
33
+ /**
34
+ * A dot at graph coordinates in a 3D graph, with an optional label. Put inside
35
+ * a surface it rides it: its `x` and `y` say where, and its height is the surface's.
36
+ */
37
+ export const PlotPoint3d = component3d({
38
+ key: "plotPoint3d",
39
+ state: {
40
+ ...meshEntries,
41
+ /** In scene units, so a point is the same size whatever the axes show. */
42
+ radius: Types.number(0.1, { min: 0, step: 0.01 }),
43
+ label: Types.text("", { animatable: false }),
44
+ /** The height of the label's text, in scene units. */
45
+ labelSize: Types.number(0.26, { min: 0.01, step: 0.01 }),
46
+ labelColor: Types.color("#e5e7eb"),
47
+ fontFamily: Types.text("", { animatable: false }),
48
+ },
49
+ load: (loader, s) => {
50
+ if (s.fontFamily !== "") loader.font(s.fontFamily);
51
+ },
52
+ render: (ctx, s) => {
53
+ const g3 = Material.mesh(s, s.radius > 0 ? Geo.sphere({ radius: s.radius, segments: [24, 16] }) : undefined);
54
+ drawLabel3D(g3, s.label, { x: 0, y: s.radius + s.labelSize * 0.85, z: 0 }, {
55
+ size: s.labelSize,
56
+ color: s.labelColor,
57
+ fontFamily: s.fontFamily,
58
+ });
59
+ ctx.draw(g3);
60
+ },
61
+ });
62
+
63
+ export type PlotPoint3d = NodeOf<typeof PlotPoint3d>;
@@ -0,0 +1,92 @@
1
+ import {
2
+ createContext,
3
+ Types,
4
+ type ChildSpace3D,
5
+ type Node3D,
6
+ type Type,
7
+ type Vector3,
8
+ // Named so the emitted declaration reaches these through the sdk, not core.
9
+ type Context as _Context,
10
+ } from "@motionscript/sdk";
11
+ import type { Interval } from "../kit/coords";
12
+
13
+ /**
14
+ * A 3D graph's coordinates, as its axes' local space sees them. A graph is
15
+ * right-handed with z up, and the scene has y up, so graph x, y and z run along
16
+ * the scene's z, x and y: looked at head-on, y is to the right and z is up.
17
+ */
18
+ export interface GraphSpace extends ChildSpace3D {
19
+ readonly xRange: Interval;
20
+ readonly yRange: Interval;
21
+ readonly zRange: Interval;
22
+ /** Changes exactly when the mapping does: what a mark's geometry is cached under. */
23
+ readonly revision: string;
24
+ /** A step from one graph point to another, as the local one: what a mark's own geometry is drawn in. */
25
+ offset(x: number, y: number, z: number): Vector3;
26
+ }
27
+
28
+ /** The space of a box `lengths` on a side, in scene units, showing the three ranges, centred on its node. */
29
+ export function graphSpace(xRange: Interval, yRange: Interval, zRange: Interval, lengths: Vector3): GraphSpace {
30
+ const ux = unit(xRange, lengths.x);
31
+ const uy = unit(yRange, lengths.y);
32
+ const uz = unit(zRange, lengths.z);
33
+ const cx = (xRange[0] + xRange[1]) / 2;
34
+ const cy = (yRange[0] + yRange[1]) / 2;
35
+ const cz = (zRange[0] + zRange[1]) / 2;
36
+ return {
37
+ xRange,
38
+ yRange,
39
+ zRange,
40
+ revision: [xRange, yRange, zRange, lengths.x, lengths.y, lengths.z].join("|"),
41
+ toLocal: (x, y, z) => ({ x: (y - cy) * uy, y: (z - cz) * uz, z: (x - cx) * ux }),
42
+ offset: (x, y, z) => ({ x: y * uy, y: z * uz, z: x * ux }),
43
+ };
44
+ }
45
+
46
+ function unit([min, max]: Interval, length: number): number {
47
+ const span = max - min;
48
+ return span > 0 ? length / span : 0;
49
+ }
50
+
51
+ /** A 3D graph, as the marks inside it see it: its coordinates as they stand now. */
52
+ export interface Graph3D {
53
+ space(): GraphSpace;
54
+ }
55
+
56
+ /** The graph a mark is inside: `axes3d` provides itself to everything in it. */
57
+ export const GRAPH_3D = createContext<Graph3D | null>(null, "math:graph3d");
58
+
59
+ /**
60
+ * The entry a mark reads the graph it is drawn in through, set from the nearest
61
+ * `axes3d` above it, through any 3D node between; `null` outside one.
62
+ */
63
+ export function graphEntry(): Type<Graph3D | null, Graph3D | null, true> {
64
+ return Types.custom<Graph3D | null, Graph3D | null, { readonly private: true }>(null, {
65
+ private: true,
66
+ inherit: (use) => use(GRAPH_3D),
67
+ });
68
+ }
69
+
70
+ /** The graph space a mark with a {@link graphEntry} is drawn in, or `null` outside a graph. */
71
+ export function graphOf(mark: { readonly graph: Graph3D | null }): GraphSpace | null {
72
+ return mark.graph?.space() ?? null;
73
+ }
74
+
75
+ /** The graph a 3D node is drawn in: what the nearest `axes3d` above it provides, once it is in the tree. */
76
+ export function spaceOf(mark: Node3D): GraphSpace | null {
77
+ return mark.useContext(GRAPH_3D)?.space() ?? null;
78
+ }
79
+
80
+ /** A unit quaternion turning the scene's +y, the way a cylinder or a cone points, onto `direction`. */
81
+ export function aim(direction: Vector3): { x: number; y: number; z: number; w: number } {
82
+ const length = Math.hypot(direction.x, direction.y, direction.z);
83
+ if (!(length > 0)) return { x: 0, y: 0, z: 0, w: 1 };
84
+ const dx = direction.x / length;
85
+ const dy = direction.y / length;
86
+ const dz = direction.z / length;
87
+ // Straight down is the one turn with no single axis: any in the ground plane will do.
88
+ if (dy < -1 + 1e-9) return { x: 1, y: 0, z: 0, w: 0 };
89
+ const w = 1 + dy;
90
+ const norm = Math.hypot(dz, dx, w);
91
+ return { x: dz / norm, y: 0, z: -dx / norm, w: w / norm };
92
+ }