@beeson-group/tycho 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/AUTHORS +8 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +14 -0
  4. package/README.md +38 -0
  5. package/THIRD_PARTY_NOTICES.md +68 -0
  6. package/dist/tycho.esm.js +1517 -760
  7. package/dist/tycho.js +1517 -760
  8. package/dist/types/container.d.ts +64 -0
  9. package/dist/types/errors.d.ts +9 -0
  10. package/dist/types/evaluate/clock.d.ts +36 -0
  11. package/dist/types/evaluate/frames.d.ts +63 -0
  12. package/dist/types/evaluate/index.d.ts +21 -0
  13. package/dist/types/evaluate/layers.d.ts +108 -0
  14. package/dist/types/evaluate/resolve.d.ts +50 -0
  15. package/dist/types/evaluate/sets.d.ts +50 -0
  16. package/dist/types/evaluate/timeline.d.ts +60 -0
  17. package/dist/types/evaluate/types.d.ts +87 -0
  18. package/dist/types/index.d.ts +22 -0
  19. package/dist/types/runtime/colormaps.d.ts +10 -0
  20. package/dist/types/runtime/colors.d.ts +121 -0
  21. package/dist/types/runtime/element.d.ts +290 -0
  22. package/dist/types/runtime/export.d.ts +129 -0
  23. package/dist/types/runtime/geometry.d.ts +217 -0
  24. package/dist/types/runtime/icons.d.ts +66 -0
  25. package/dist/types/runtime/layout.d.ts +34 -0
  26. package/dist/types/runtime/outline.d.ts +29 -0
  27. package/dist/types/runtime/overlay.d.ts +33 -0
  28. package/dist/types/runtime/paint.d.ts +110 -0
  29. package/dist/types/runtime/raster.d.ts +33 -0
  30. package/dist/types/runtime/readouts.d.ts +136 -0
  31. package/dist/types/runtime/renderer.d.ts +551 -0
  32. package/dist/types/runtime/state.d.ts +104 -0
  33. package/dist/types/runtime/tiles.d.ts +33 -0
  34. package/dist/types/scene.d.ts +51 -0
  35. package/dist/types/scene.gen.d.ts +2033 -0
  36. package/dist/types/validate.d.ts +9 -0
  37. package/package.json +63 -35
  38. package/src/colormaps.ts +0 -42
  39. package/src/container.ts +0 -126
  40. package/src/element.ts +0 -1034
  41. package/src/frames.ts +0 -204
  42. package/src/index.ts +0 -14
  43. package/src/layout.ts +0 -82
  44. package/src/viewer.ts +0 -864
@@ -0,0 +1,551 @@
1
+ /**
2
+ * One WebGL renderer for the whole panel area. Every panel is a scissor rectangle of the one canvas,
3
+ * with a camera and a three.js scene per panel, and one redraw draws them all. A frame is a
4
+ * function of the state snapshot, the frame index, the panel area size, and the pixel scale, plus
5
+ * whatever the user did to a camera after it was fitted.
6
+ *
7
+ * A trajectory layer draws from the static buffers of geometry.ts, one pass per revolution (rule `revolutions` of
8
+ * spec/tycho-scene.md). Its shader compares each segment's two readings with the revealed range of
9
+ * its trajectory. Each range is read from a small float texture with one texel per trajectory, so that the
10
+ * reveals `none`, `grow`, and `trail` differ only in this range (rules `polyline`, `trail-wrap` and `revolutions`). The ranges
11
+ * are per trajectory rather than uniforms because in `value` mode every trajectory has a separate reading
12
+ * (rule `clock-mode`). A second texel per trajectory holds the opacity a highlight's kernel gives it. A line of
13
+ * width 1 is a GL line. A wider one is a quad per segment, offset in screen space by half the width
14
+ * in CSS pixels on each side, and along a trail the width and the opacity taper from the head to
15
+ * the tail. The CPU draws the pieces at the ends of the range, the heads (rule `head`), and the bodies
16
+ * and their trails (rule `body-layer`) with the evaluator's functions. A layer in the reference trajectory's context (rule `read-from`)
17
+ * keeps its buffers in the frame of its set, and its group's matrix is the affine map into the display
18
+ * frame at the reference trajectory's reading, i.e. the blend of the maps in the contexts of two reference samples.
19
+ * Under a 2d camera the axes and the grid follow the visible rectangle and give their tick
20
+ * numbers and titles as panel labels.
21
+ */
22
+ import * as THREE from 'three';
23
+ import { type TrajectoryClock } from '../evaluate/clock.js';
24
+ import { type Reference, type LayerEnv } from '../evaluate/layers.js';
25
+ import type { InsetBoxLayerResult, Vec3 } from '../evaluate/types.js';
26
+ import type { Context, Frames } from '../evaluate/frames.js';
27
+ import { type PanelScope } from '../evaluate/resolve.js';
28
+ import type { SetData } from '../evaluate/sets.js';
29
+ import type { ArrowLayer, BodyLayer, Camera, Clock, ColorSpec, LabelLayer, Layout, Marker, MarkLayer, InsetBoxLayer, PointsLayer, Scene, State, TrajectoriesLayer, Panel } from '../scene.js';
30
+ import { type Theme } from './colors.js';
31
+ import { type BoxPaint } from './paint.js';
32
+ import { GeometryCache } from './geometry.js';
33
+ import { type Colorbar, type PanelLabel } from './overlay.js';
34
+ import { type Rect } from './tiles.js';
35
+ /** Width of the gutter between two panels, in CSS pixels. */
36
+ export declare const GUTTER = 6;
37
+ /** A pleasant round step near `range / target`, which is 1, 2 or 5 times a power of ten. */
38
+ export declare function niceStep(range: number, target?: number): number;
39
+ /** Arrays and GPU buffers built once and shared by every geometry that draws them, kept for the renderer's life. */
40
+ export declare class Shared {
41
+ private readonly cache;
42
+ get<T>(key: string, make: () => T): T;
43
+ }
44
+ interface DrawContext {
45
+ scene: Scene;
46
+ geometry: GeometryCache;
47
+ shared: Shared;
48
+ theme: Theme;
49
+ disc: THREE.Texture;
50
+ }
51
+ export interface TrajectoryPlan {
52
+ kind: 'trajectories';
53
+ index: number;
54
+ layer: TrajectoriesLayer;
55
+ set: SetData | null;
56
+ /** The members of rule `members`, in increasing order. */
57
+ members: number[];
58
+ /** The highlighted member, when the highlight's parameter input resolves to one of the members. */
59
+ highlight: number | null;
60
+ /** The trajectory that the highlight's parameter input resolves to in the set, a member or not, which is the center of its kernel. */
61
+ selected: number | null;
62
+ /** The clock channel the layer reads, or null when it does not take a reading. */
63
+ channel: string | null;
64
+ /** The layer's color, where a colormap keyed on a choice is resolved to the colormap that the panel's value of the choice maps to (section 2.7). */
65
+ color: ColorSpec | undefined;
66
+ /** The context its samples are transformed in (rule `read-from`). */
67
+ readFrom: 'own' | 'reference';
68
+ /** The clock the layer reads, the scene's or its own (rule `layer-clock`). */
69
+ clock: Clock;
70
+ }
71
+ export interface BodyPlan {
72
+ kind: 'body';
73
+ index: number;
74
+ layer: BodyLayer;
75
+ }
76
+ export interface MarkPlan {
77
+ kind: 'axes' | 'grid';
78
+ index: number;
79
+ layer: MarkLayer;
80
+ }
81
+ export interface ArrowPlan {
82
+ kind: 'arrow';
83
+ index: number;
84
+ layer: ArrowLayer;
85
+ /** Null when the set query does not match any trajectory set. */
86
+ set: SetData | null;
87
+ /** The clock channel the layer reads. */
88
+ channel: string;
89
+ /** The clock the layer reads, the scene's or its own (rule `layer-clock`). */
90
+ clock: Clock;
91
+ }
92
+ export interface PointsPlan {
93
+ kind: 'points';
94
+ index: number;
95
+ layer: PointsLayer;
96
+ /** Null when the set query does not match any trajectory set. */
97
+ set: SetData | null;
98
+ }
99
+ export interface LabelPlan {
100
+ kind: 'label';
101
+ index: number;
102
+ layer: LabelLayer;
103
+ /** The set of an anchor at a member, or null. */
104
+ set: SetData | null;
105
+ }
106
+ export interface InsetBoxPlan {
107
+ kind: 'inset_box';
108
+ index: number;
109
+ layer: InsetBoxLayer;
110
+ }
111
+ export type LayerPlan = TrajectoryPlan | ArrowPlan | InsetBoxPlan | BodyPlan | MarkPlan | PointsPlan | LabelPlan;
112
+ export interface PanelPlan {
113
+ /** The id of the declared panel that the shown panel shows. */
114
+ declaredId: string;
115
+ declared: Panel;
116
+ display: string;
117
+ scope: PanelScope;
118
+ reference: Reference;
119
+ layers: LayerPlan[];
120
+ }
121
+ /** A layer's color with a colormap keyed on a choice (section 2.7) resolved by the panel's value of the choice (rule `input-scope`). */
122
+ export declare function resolveColor(scope: PanelScope, spec: ColorSpec | undefined): ColorSpec | undefined;
123
+ /** What a panel of a state draws: its display frame, its reference, and its visible layers resolved. */
124
+ export declare function planPanel(scene: Scene, geometry: GeometryCache, state: State, pid: string): PanelPlan;
125
+ /** What the camera fit depends on: the declared panel, the display frame, the reference trajectory's trajectory set, and the trajectory sets of the trajectory layers. */
126
+ export declare function contentKey(plan: PanelPlan): string;
127
+ type Box6 = [number, number, number, number, number, number];
128
+ /** An affine map p -> A p + b, as the rows of A followed by b. */
129
+ type Affine = Float64Array;
130
+ /** The affine map of rule `frame-path` from frame `from` to frame `to` in one context, read off the images of the origin and the three unit points. */
131
+ export declare function affineAt(frames: Frames, from: string, to: string, ctx: Context): Affine;
132
+ /**
133
+ * The affine map from frame `from` into the display frame at the reference trajectory's reading (rule `read-from`), i.e. the maps in the
134
+ * contexts of the reference trajectory's samples k and k + 1 blended by the weight w, as a matrix of three.js.
135
+ */
136
+ export declare function referenceMatrix(env: LayerEnv, from: string, reference: NonNullable<Reference>, out?: THREE.Matrix4, clock?: TrajectoryClock): THREE.Matrix4;
137
+ /**
138
+ * The box a panel's camera fits, which holds every member of every trajectory layer without `fit: false`, whole, in every revolution
139
+ * from 0 to the top, in the display frame. A layer in the reference trajectory's context is held at every sample of
140
+ * the reference trajectory's trajectory. The box is given as minimum then maximum x, y, z, and is null when the trajectory
141
+ * layers do not draw anything. A test passes a small `budget` in place of REFERENCE_FIT_BUDGET, to force the fit by the corners.
142
+ */
143
+ export declare function fitBox(plan: PanelPlan, geometry: GeometryCache, budget?: number): Box6 | null;
144
+ /**
145
+ * An orthographic fit, given as the center of the box and half the view's width and height, for a viewport
146
+ * whose width over height is `aspect`. A tenth of margin is added. One world unit is as long across the
147
+ * screen as up it, unless the camera has a free aspect. The box is then fitted in each direction separately,
148
+ * and along an axis on which the box is flat the half size is the one of the equal fit.
149
+ */
150
+ export declare function orthoFit(box: THREE.Box3, cam: Camera, aspect: number): {
151
+ center: THREE.Vector3;
152
+ halfWidth: number;
153
+ halfHeight: number;
154
+ };
155
+ /** The opacity of a member at parameter distance `d` from the center of a highlight's kernel (section 2.7). */
156
+ export declare function kernelOpacity(floor: number, kernel: {
157
+ width: number;
158
+ opacity: number;
159
+ }, extent: number, d: number): number;
160
+ /** The part of the display plane a 2d camera shows, and the steps of its ticks. */
161
+ export interface PlaneView {
162
+ /** The visible rectangle along the camera's right and up axes, in display-frame units. */
163
+ x0: number;
164
+ x1: number;
165
+ y0: number;
166
+ y1: number;
167
+ /** The panel's size in CSS pixels. */
168
+ w: number;
169
+ h: number;
170
+ stepX: number;
171
+ stepY: number;
172
+ }
173
+ /** What an orthographic camera under a 2d camera shows, with a tick about every 110 pixels across and 70 up. */
174
+ export declare function planeView(camera: THREE.OrthographicCamera, cam: Camera & {
175
+ kind: '2d';
176
+ }, w: number, h: number): PlaneView;
177
+ /**
178
+ * A label's box in CSS pixels from the panel's corner, as [left, top, right, bottom]. Its length is estimated from its text as
179
+ * `tickWidth` estimates a tick number, scaled to 13 px for a title and kept at 12 px for any other label, and its height is
180
+ * the font size. The box is estimated rather than measured, so that the same titles are hidden in a page and in a video frame,
181
+ * although their text is set in different fonts.
182
+ */
183
+ export declare function labelBox(l: PanelLabel): [number, number, number, number];
184
+ /** True when the boxes of two labels are overlapping, as `labelBox` estimates them, and false when they are only touching. */
185
+ export declare function labelsOverlap(a: PanelLabel, b: PanelLabel): boolean;
186
+ /**
187
+ * What covers a panel's drawing besides its labels, measured by the viewer: the height of the panel's header, and the box of its
188
+ * colorbars, given by its distance from the panel's right edge, its top, its width, and its height, in CSS pixels.
189
+ */
190
+ export interface Clearance {
191
+ header: number;
192
+ bars: {
193
+ right: number;
194
+ top: number;
195
+ width: number;
196
+ height: number;
197
+ } | null;
198
+ }
199
+ /** The colorbars' box of `c` in a panel `w` pixels wide, as [left, top, right, bottom], grown by 2 px on each side. */
200
+ export declare function barsBox(c: Clearance, w: number): [number, number, number, number] | null;
201
+ /** True when the box of label `l`, as tall as its line of text, overlaps `box`, given as [left, top, right, bottom]. */
202
+ export declare function labelOver(l: PanelLabel, box: [number, number, number, number]): boolean;
203
+ /**
204
+ * The labels of a plane view. Tick numbers run along the bottom and the left edges, clear of the corners
205
+ * and below `top`, the bottom of the panel's header. The two axis titles sit at the bottom center and the left center, the second reading upward, each in a
206
+ * separate row outside the tick numbers. The tick row is centered 28 px above the bottom edge and the x
207
+ * title 10 px above it. The y title sits 10 px from the left edge, and the y tick column is right-aligned
208
+ * clear of it at its widest number. A panel too short or too narrow for a title keeps its ticks.
209
+ */
210
+ export declare function planeLabels(v: PlaneView, ticks: boolean, titles: [string, string] | null, top?: number): PanelLabel[];
211
+ interface Draw {
212
+ readonly key: string;
213
+ readonly group: THREE.Group;
214
+ extend(box: THREE.Box3): void;
215
+ resize?(w: number, h: number): void;
216
+ dispose(): void;
217
+ }
218
+ /**
219
+ * Where the dash pattern of each segment of a trajectory starts (section 2.11), as an arclength along the trajectory, written to `out` from
220
+ * `at` on, one value per segment: where the trajectory last entered the rectangle `[x0, x1] x [y0, y1]` at or before the segment, or its
221
+ * first sample when that lies in the rectangle, as matplotlib clips a line to its figure before it dashes it, which starts the
222
+ * pattern again at each entry. `xy` holds the screen position of each of the `count` samples from `from`, two numbers per sample,
223
+ * and `dist` the arclength of each. Before the trajectory first enters the rectangle, its segments start at its first sample.
224
+ */
225
+ export declare function dashRestarts(xy: ArrayLike<number>, dist: ArrayLike<number>, from: number, count: number, x0: number, y0: number, x1: number, y1: number, out: {
226
+ [i: number]: number;
227
+ }, at: number): void;
228
+ /** The sprites of a marker (section 2.11), drawn from a texture of its shape, in one color or tinted per point. */
229
+ export declare class MarkerSprites {
230
+ readonly points: THREE.Points;
231
+ private readonly material;
232
+ private readonly marker;
233
+ private readonly tinted;
234
+ private texSize;
235
+ /** The width of the stroke the texture was drawn with, which may move with the timeline as the size does. */
236
+ private texEdge;
237
+ private edgeWidth;
238
+ constructor(marker: Marker, size: number, tinted: boolean);
239
+ /**
240
+ * Sets the size of the sprites' shape in CSS pixels, and the width of its stroke when given, drawing the texture again when either
241
+ * moves, since the stroke is in CSS pixels and does not scale with the marker.
242
+ */
243
+ setSize(size: number, edgeWidth?: number | undefined): void;
244
+ setOpacity(opacity: number): void;
245
+ /** Room for `n` points. */
246
+ grow(n: number): void;
247
+ get position(): THREE.BufferAttribute;
248
+ get color(): THREE.BufferAttribute;
249
+ /** Draws the first `n` points. */
250
+ show(n: number): void;
251
+ dispose(): void;
252
+ }
253
+ export declare class TrajectoryDraw implements Draw {
254
+ readonly key: string;
255
+ readonly group: THREE.Group<THREE.Object3DEventMap>;
256
+ private readonly src;
257
+ private readonly layer;
258
+ private readonly set;
259
+ private readonly geo;
260
+ private readonly clocks;
261
+ private readonly clock;
262
+ private readonly spec;
263
+ private readonly color;
264
+ private readonly width;
265
+ private readonly hiWidth;
266
+ private readonly opacity;
267
+ private readonly hiOpacity;
268
+ /** Along a trail, the loop readings over which the taper falls, else 0, and the width and opacity it falls to. */
269
+ private readonly fraction;
270
+ private readonly taperWidth;
271
+ private readonly taperOpacity;
272
+ private readonly kernel;
273
+ private readonly ranges;
274
+ private readonly alphas;
275
+ /** For a dashed layer, the arclength at which each segment's dash pattern starts on the panel area (section 2.11), else null. */
276
+ private readonly dashFrom;
277
+ private dashScreen;
278
+ private restartOut;
279
+ private readonly resolution;
280
+ private readonly uniforms;
281
+ private readonly baseHolder;
282
+ private readonly hiHolder;
283
+ /** The passes built so far, by revolution and kind, each built the first time its revolution shows anything. */
284
+ private readonly passes;
285
+ private readonly pieces;
286
+ private heads;
287
+ private glow;
288
+ private readonly headSize;
289
+ private readonly headColor;
290
+ private fill;
291
+ private fillBuffer;
292
+ /** False for a layer that draws its heads alone (section 2.11). */
293
+ private readonly line;
294
+ /** The stencil mark of a flat layer, whose lines blend each pixel once (section 2.11), else 0. */
295
+ private readonly flatMark;
296
+ /** True when the layer's opacity or its head's size or opacity moves with the timeline, hence it is drawn every frame. */
297
+ private readonly keyframed;
298
+ private members;
299
+ private highlight;
300
+ private selected;
301
+ private baseWhat;
302
+ private skip;
303
+ private filled;
304
+ /** True for a layer in the reference trajectory's context (rule `read-from`), whose buffers are in the frame of its set and whose group's matrix moves them. */
305
+ readonly referenceContext: boolean;
306
+ private readonly geometry;
307
+ constructor(ctx: DrawContext, plan: TrajectoryPlan & {
308
+ set: SetData;
309
+ }, display: string, key: string);
310
+ resize(w: number, h: number): void;
311
+ /** The ratio of the pixels per unit up the screen to those across it, for which the arclengths of a dash were computed. */
312
+ private dashRatio;
313
+ /**
314
+ * Sets the pixels per unit of the display frame across and up the screen, which a dash is measured in. Under a free aspect the two
315
+ * differ, and the arclengths are computed again, and the passes built again, when their ratio changes.
316
+ */
317
+ setPixels(across: number, up: number): void;
318
+ /** The color of a vertex of trajectory `t`, which is the layer's color or a blend of the colors of two samples. */
319
+ private colorAt;
320
+ /** The arclength of a vertex of trajectory `t` for a dash, from where the trajectory's pattern starts. */
321
+ private distAt;
322
+ /**
323
+ * Starts the dash pattern of each trajectory where it enters the panel area, of `width` by `height` CSS pixels widened by `margin`, as
324
+ * matplotlib clips a line to its figure before it dashes it (section 2.11). The panel draws with `camera` in `rect` of the panel area.
325
+ * The dashes of a line that the camera follows then stay where they are on the screen rather than crawl along it.
326
+ */
327
+ placeDash(camera: THREE.Camera, rect: {
328
+ x: number;
329
+ y: number;
330
+ w: number;
331
+ h: number;
332
+ }, width: number, height: number, margin: number): void;
333
+ /** Each trajectory's opacity under the highlight's kernel, around the selected trajectory's parameter value. */
334
+ private fillKernel;
335
+ private showPass;
336
+ private pass;
337
+ /** Shows the passes of the revolutions that draw a segment, building the ones not built yet, and hides the others. */
338
+ private syncPasses;
339
+ /**
340
+ * True when the layer does not take a reading, is not in the reference trajectory's context, and does not move with the timeline, so that
341
+ * what it draws changes only with its members, its highlight, and its selection.
342
+ */
343
+ get isStatic(): boolean;
344
+ /** Moves a layer in the reference trajectory's context into the display frame at the reference trajectory's reading, or hides it when the reference does not match a set (rule `read-from`). */
345
+ place(env: LayerEnv, reference: Reference): void;
346
+ /** Fades the layer as a whole by the keyframes of its opacity at time `s` (section 2.11), and returns the factor, 1 for an opacity that is a number. */
347
+ private fade;
348
+ /** Returns whether the picture changed through new members, a new highlight or selection, or a first fill. */
349
+ update(plan: TrajectoryPlan, scene: Scene, q: number): boolean;
350
+ /** The vertices of the drawn polyline of trajectory `t`, as rules `polyline`, `trail-wrap`, and `revolutions` give them, for a fill. */
351
+ private fillTrajectory;
352
+ /** The two axes of the plane the fill is laid out in, set by the panel's camera. */
353
+ planeAxes: [number, number];
354
+ private setFill;
355
+ extend(): void;
356
+ /** The colorbar of a colormapped layer, with the highlighted or single member marked on it, and the kernel's band. */
357
+ colorbar(): Colorbar | null;
358
+ dispose(): void;
359
+ }
360
+ /** Appends the triangles that shade the part of the segment from `a` to `b` above the line y = base, as x, y pairs. */
361
+ export declare function fillSegment(a: [number, number], b: [number, number], base: number, out: number[]): void;
362
+ /**
363
+ * The corners, in CSS pixels from the host panel's top left corner, of what a 2d camera shows in the target panel, i.e. the rectangle `view` in
364
+ * the target panel's display frame, mapped by `map` into the host's display frame, stretched as the host camera stretches it, and projected by the
365
+ * host camera onto a panel of `w` by `h` pixels. Null when a corner is behind a perspective camera.
366
+ */
367
+ export declare function outlineCorners(map: InsetBoxLayerResult & {
368
+ origin: Vec3;
369
+ axes: [Vec3, Vec3, Vec3];
370
+ }, view: PlaneView, target: Camera & {
371
+ kind: '2d';
372
+ }, camera: THREE.OrthographicCamera | THREE.PerspectiveCamera, host: Camera, w: number, h: number): [[number, number], [number, number], [number, number], [number, number]] | null;
373
+ /**
374
+ * An inset box, the outline of what another panel shows (rule `inset-box`). Its map from the target frame is evaluated at the clock in `update`, and the ring is laid out
375
+ * in `place` from the target camera's visible rectangle at the same frame, after every camera of the panel area has moved.
376
+ */
377
+ /** The id of the shown panel whose window an inset box outlines, or null when the layout does not show its declared panel or the reference does not resolve. */
378
+ export declare function insetBoxShownPanel(map: InsetBoxLayerResult | null): string | null;
379
+ /**
380
+ * Whether a camera's world or projection matrix differs from `seen`, which then holds both. The test
381
+ * covers any pan, zoom, rotation, fit, or change of aspect, however the camera was moved.
382
+ */
383
+ export declare function cameraMoved(camera: THREE.Camera, seen: Float64Array): boolean;
384
+ /** Whether two regions (x, y, width, height) of the underlay share a pixel. A region that was never set, at -1, shares none. */
385
+ export declare function overlaps(a: THREE.Vector4, b: THREE.Vector4): boolean;
386
+ export declare class PanelAreaRenderer {
387
+ readonly canvas: HTMLCanvasElement;
388
+ /** Called when the user moves a camera, so that the page redraws. */
389
+ onChange: () => void;
390
+ private readonly gl;
391
+ private readonly ctx;
392
+ private readonly panels;
393
+ private lastState;
394
+ private size;
395
+ private readonly background;
396
+ /**
397
+ * Draws each panel's bottom run of layers that do not take a reading once, and copies it back every
398
+ * frame. When it is off, every layer is drawn every frame, as the reference the cache is compared with.
399
+ */
400
+ cacheStatic: boolean;
401
+ /**
402
+ * Draws an underlay without antialiasing when it was drawn again less than DRAG_MS before, as
403
+ * every frame of a slider or camera drag does, and with antialiasing REFINE_MS after the drag stops.
404
+ * It is off for a video export, whose frames must all be finished.
405
+ */
406
+ coarseDrags: boolean;
407
+ private refineTimer;
408
+ private readonly blit;
409
+ /** Every panel's static layers, each panel in a separate region at the same pixels as on the canvas. */
410
+ private underlay;
411
+ /**
412
+ * Where a panel's static layers are drawn with antialiasing before they are copied into the
413
+ * underlay, as large as the largest panel. Reading the antialiased canvas back instead gives, in
414
+ * Chrome, the right pixels only for the last panel drawn in a frame, and stale pixels for the others.
415
+ */
416
+ private scratch;
417
+ private readonly viewport;
418
+ /** The canvas's viewport and scissor in CSS pixels, as they were set for the panel being drawn. */
419
+ private readonly cssViewport;
420
+ private readonly cssScissor;
421
+ private readonly buffer;
422
+ private readonly region;
423
+ private readonly corner;
424
+ /**
425
+ * The option `preserveDrawingBuffer` is set for a canvas that is read back after the frame, as in a
426
+ * video export. It is left off for a page, which spares the compositor a copy of the canvas every frame.
427
+ */
428
+ constructor(canvas: HTMLCanvasElement, scene: Scene, geometry: GeometryCache, options?: {
429
+ preserveDrawingBuffer?: boolean;
430
+ cacheStatic?: boolean;
431
+ coarseDrags?: boolean;
432
+ theme?: Theme;
433
+ });
434
+ /** Draws with `theme` from the next frame on. The cameras stay, and the next plan rebuilds only the draws that take a color from the theme. */
435
+ setTheme(theme: Theme): void;
436
+ private panel;
437
+ /** Gives a panel the element its camera controls listen on and its labels are written into, or takes it away. */
438
+ bind(pid: string, element: HTMLElement | null): void;
439
+ /** Sets the header and the colorbars over a panel, as the viewer measured them, for the labels drawn from the next frame on. */
440
+ setClearance(pid: string, clearance: Clearance): void;
441
+ /** Fits a panel's camera to what it draws at the next frame, forgetting how the user moved the camera. */
442
+ refit(pid: string): void;
443
+ refitAll(): void;
444
+ /**
445
+ * Whether the viewer has panned or zoomed a panel whose camera has keyframes (rule `camera-keyframes`), so that the panel no longer follows them. A
446
+ * refit hands the camera back to its keyframes.
447
+ */
448
+ offKeys(pid: string): boolean;
449
+ /** The panels with a 3d camera and its controls, i.e. those that the keys of a 3d camera move. */
450
+ orbitPanels(): string[];
451
+ /**
452
+ * Shows a panel of a 3d camera from the side `sign` of the axis `axis` of its display frame, at the distance of the camera
453
+ * from its target, with the up axis of the camera up the screen. Seen along the up axis, the second axis of the camera's basis
454
+ * runs up the screen and the first to the right, as in a plot of them, e.g. y and x under the up axis z: the camera then stands
455
+ * off the axis by a hair, where three's lookAt is undefined.
456
+ */
457
+ viewFrom(pid: string, axis: 'x' | 'y' | 'z', sign: 1 | -1): void;
458
+ /** Turns a panel of a 3d camera about its up axis through its target by `degrees`, as a drag to the right turns it. */
459
+ turnBy(pid: string, degrees: number): void;
460
+ private makeControls;
461
+ private setCamera;
462
+ /**
463
+ * Draws a panel's static layers into the viewport just set, copied back from the underlay, which
464
+ * is drawn again first when anything they depend on changed.
465
+ */
466
+ private drawStatic;
467
+ /** Draws a panel's static layers straight into its region of `target`, which is not multisampled. */
468
+ private drawCoarse;
469
+ /** Draws every coarse underlay again with antialiasing once REFINE_MS pass without a coarse one. */
470
+ private scheduleRefine;
471
+ /**
472
+ * Draws a panel's static layers with antialiasing into the scratch target, which three resolves
473
+ * after the draw, and copies them into the panel's region `r` of `target`.
474
+ */
475
+ private drawFine;
476
+ private disposePanel;
477
+ /** Re-resolves a panel against a new state, rebuilding only the draws whose inputs changed. */
478
+ private replan;
479
+ /** Updates a panel's draws for progress `q`. */
480
+ private advance;
481
+ /** Fits the camera to every trajectory layer's members (fitBox), or to the bodies when the trajectory layers do not draw anything. */
482
+ private fit;
483
+ /**
484
+ * Keeps one world unit the same length across and up the screen in an orthographic view. Under a free
485
+ * aspect the visible rectangle is kept instead, and it is stretched with the panel.
486
+ */
487
+ private aspect;
488
+ /**
489
+ * Turns a 3d camera about its up axis through its target to its `auto_rotate` in degrees times the
490
+ * progress `q` of the loop. The turn adds to where the viewer moved the camera.
491
+ */
492
+ private autoRotate;
493
+ /** What a 2d camera shows now, and the marks that follow it laid out across it. */
494
+ private follow;
495
+ /**
496
+ * Draws every panel of `state` at progress `q` in [0, 1) on a panel area of `width` by `height` CSS
497
+ * pixels. A frame index i sits at q = i / frame_count, and playback draws between two of them. Returns the
498
+ * message of every panel that could not be drawn.
499
+ */
500
+ renderAt(state: State, q: number, width: number, height: number, pixelRatio: number): Map<string, string>;
501
+ /**
502
+ * The labels of a panel at the last frame, in CSS pixels from the panel's corner. They are the tick
503
+ * numbers and axis titles of a 2d camera, the axis titles at the tips of axes laid out from the
504
+ * box, and the body labels beside their discs. An axis title under a shown body label is hidden,
505
+ * since the body label is the name of the disc beside it. A body label that would cover the colorbars
506
+ * moves to the other side of its disc, and a label still over them is hidden, since neither text could be read.
507
+ */
508
+ private labelItems;
509
+ /** The labels a panel shows at the last frame, for a page or a video frame to write as text. */
510
+ labels(pid: string): PanelLabel[];
511
+ /** The colorbars a panel shows, the identical ones merged. */
512
+ colorbars(pid: string): Colorbar[];
513
+ private placeLabels;
514
+ /**
515
+ * Moves a 2d camera with keyframes to its window at progress `q` (rule `camera-keyframes`), or back to its fit when the keyframes do not give a window
516
+ * then, unless the viewer has moved the camera since its last fit. The window's height is its own under a free aspect, and
517
+ * the width over the panel's aspect ratio otherwise.
518
+ */
519
+ private keyed;
520
+ /** Resolves once every body image of the drawn panels is decoded, so that a video does not start without them. */
521
+ ready(): Promise<void>;
522
+ /** What the panel area paints over a panel at the last frame (section 2.11), in pixels of the panel area, or null for a panel that is not drawn. */
523
+ paintInfo(pid: string): PanelPaint | null;
524
+ dispose(): void;
525
+ }
526
+ /** What the panel area paints over a panel (section 2.11): its labels at their anchors, the box of an axes layer, and the panel's opacity. */
527
+ export interface PanelPaint {
528
+ outer: Rect;
529
+ rect: Rect;
530
+ opacity: Panel['opacity'];
531
+ /** The titles of the box's axes layer, when it gives its own (section 2.11). */
532
+ boxTitles?: MarkLayer extends never ? never : Extract<MarkLayer, {
533
+ kind: 'axes';
534
+ }>['titles'];
535
+ /** The labels at their anchors, `clip` for an anchor at a point, which is hidden outside the plot. */
536
+ labels: {
537
+ layer: LabelLayer;
538
+ x: number;
539
+ y: number;
540
+ clip: boolean;
541
+ }[];
542
+ /** The box of an axes layer, with the opacity of the layer, which the panel area reads at the time of the timeline. */
543
+ box: (Omit<BoxPaint, 'opacity'> & {
544
+ opacity: MarkLayer['opacity'];
545
+ }) | null;
546
+ }
547
+ /** A rectangle less a panel's margin, given as fractions of its height and width (section 2.11). */
548
+ export declare function inset(r: Rect, margin: Panel['margin']): Rect;
549
+ /** The layout at time `s` of the timeline, each split with keyframes at the ratio its keyframes gives then, clamped into [0, 1] (section 2.11). */
550
+ export declare function layoutAt(layout: Layout, s: number): Layout;
551
+ export {};
@@ -0,0 +1,104 @@
1
+ import { type Layout, type ShownPanel, type Scene, type State, type InputValue } from '../scene.js';
2
+ import { type DropZone } from './layout.js';
3
+ /** Which of the snapshot, the frame index, and the playing flag changed. */
4
+ export type Change = 'state' | 'frame' | 'playing';
5
+ export type Listener = (change: Change) => void;
6
+ /** A dictionary without a prototype, so that an id like "__proto__" is an own key. */
7
+ export declare function dict<T>(): Record<string, T>;
8
+ export declare class Store {
9
+ private snap;
10
+ private index;
11
+ private play;
12
+ private readonly frameCount;
13
+ private readonly listeners;
14
+ constructor(state: State, frameCount: number);
15
+ get state(): State;
16
+ /** The frame index, kept in [0, frameCount), since the indices i and i + frameCount are the same frame (section 2.6). */
17
+ get frame(): number;
18
+ get playing(): boolean;
19
+ subscribe(listener: Listener): () => void;
20
+ private emit;
21
+ set(next: State): void;
22
+ update(f: (s: State) => State): void;
23
+ setFrame(i: number): void;
24
+ setPlaying(on: boolean): void;
25
+ }
26
+ /**
27
+ * Sets an input in the shown panel when the input is per-panel, and in the state's shared inputs otherwise
28
+ * (rule `input-scope`). A value that does not fit the input leaves the state as it is.
29
+ */
30
+ export declare function withInput(scene: Scene, state: State, id: string, value: InputValue, panel?: string): State;
31
+ export declare function withChannel(state: State, channel: string): State;
32
+ export declare function withPanel(state: State, id: string, panel: ShownPanel): State;
33
+ export declare function withLayout(state: State, layout: Layout): State;
34
+ /** Removes a panel and its layout leaf, collapsing its split. The last panel stays. */
35
+ export declare function withoutPanel(state: State, id: string): State;
36
+ /** A panel id of the form p1, p2, and so on that the state does not use yet. */
37
+ export declare function newPanelId(state: State): string;
38
+ /** The layout with two leaves exchanged. */
39
+ export declare function swapLeaves(node: Layout, a: string, b: string): Layout;
40
+ /** What can be dropped on a shown panel: a declared panel, or another shown panel. */
41
+ export type DropPayload = {
42
+ kind: 'declared';
43
+ panel: string;
44
+ } | {
45
+ kind: 'panel';
46
+ id: string;
47
+ };
48
+ /**
49
+ * The state after a drop on the shown panel `target`. On an edge, a declared panel makes a new shown
50
+ * panel there, and a shown panel moves there. On the center, a declared panel replaces the declared
51
+ * panel that the target shows, which keeps its inputs, and a shown panel swaps places with it. A new
52
+ * shown panel is not made once the state has `maxPanels` shown panels.
53
+ */
54
+ export declare function withDrop(scene: Scene, state: State, target: string, zone: DropZone, payload: DropPayload, maxPanels?: number): State;
55
+ /**
56
+ * The state after adding a panel with `payload` where there is most room. The largest panel by
57
+ * area is split along its longer side, below it when `tall` returns true (taller than wide) and
58
+ * to its right otherwise. A new panel is not made once the state has `maxPanels` panels.
59
+ */
60
+ export declare function withAdd(scene: Scene, state: State, payload: Extract<DropPayload, {
61
+ kind: 'declared';
62
+ }>, maxPanels: number, tall: (id: string) => boolean): State;
63
+ /** Where a chip's menu puts a panel, either where there is most room or where a drop on a panel would. */
64
+ export type Placement = {
65
+ kind: 'add';
66
+ } | {
67
+ kind: 'drop';
68
+ target: string;
69
+ zone: DropZone;
70
+ };
71
+ export interface MenuItem {
72
+ label: string;
73
+ placement: Placement;
74
+ disabled: boolean;
75
+ /** The item opens a new group of the menu. */
76
+ group: boolean;
77
+ }
78
+ /**
79
+ * The menu of a chip in the Add panel group, which offers from the keyboard what dragging does. It
80
+ * lists Add panel, then for each panel in layout order Split it right, Split it below, and Replace
81
+ * it. The function `name` gives a panel's name, which is numbered where two panels share one. An
82
+ * item that would add a panel beyond `maxPanels` is disabled.
83
+ */
84
+ export declare function chipMenu(state: State, name: (id: string) => string, maxPanels: number): MenuItem[];
85
+ /** The state after a chip's menu item: `withAdd` or `withDrop` with the chip's payload. */
86
+ export declare function withPlacement(scene: Scene, state: State, placement: Placement, payload: Extract<DropPayload, {
87
+ kind: 'declared';
88
+ }>, maxPanels: number, tall: (id: string) => boolean): State;
89
+ /** The 32-bit FNV-1a hash (Fowler-Noll-Vo) of the UTF-8 bytes of `text`, as eight hex digits. */
90
+ export declare function fnv1a(text: string): string;
91
+ /** The key under which a stored state is kept, built from a hash of scene.tys and its length (section 2.8). */
92
+ export declare function storageKey(sceneText: string): string;
93
+ /**
94
+ * Repairs a stored state against a scene, as described in section 2.8. A shown panel whose declared
95
+ * panel the scene lacks is dropped together with its layout leaf, and a value that does not fit its
96
+ * input is dropped, as is a value of a shared input in a shown panel. A split keeps its keyframes, the
97
+ * keyframes of its ratio (section 2.11), when they are valid, so that a restored layout still moves with
98
+ * the timeline, and loses them otherwise. The repair falls back to `initial` once every panel is
99
+ * dropped or when the clock channel is unknown. Beyond section 2.8,
100
+ * it also drops values that are never read (undeclared ids, and a shared value of a per-panel input),
101
+ * a shown panel that the layout does not show or whose id is not an identifier, and a repeated leaf. It falls
102
+ * back to `initial` as well on input that is not a state at all. It is pure and does not modify `stored`.
103
+ */
104
+ export declare function repair(scene: Scene, stored: unknown): State;