@beeson-group/tycho 0.2.0 → 0.3.1

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 (35) hide show
  1. package/AUTHORS +1 -0
  2. package/NOTICE +1 -1
  3. package/THIRD_PARTY_NOTICES.md +4 -4
  4. package/dist/tycho.esm.js +1231 -728
  5. package/dist/tycho.js +1231 -728
  6. package/dist/types/container.d.ts +16 -16
  7. package/dist/types/errors.d.ts +2 -3
  8. package/dist/types/evaluate/clock.d.ts +21 -15
  9. package/dist/types/evaluate/frames.d.ts +11 -11
  10. package/dist/types/evaluate/index.d.ts +9 -2
  11. package/dist/types/evaluate/layers.d.ts +87 -26
  12. package/dist/types/evaluate/resolve.d.ts +34 -23
  13. package/dist/types/evaluate/sets.d.ts +16 -15
  14. package/dist/types/evaluate/timeline.d.ts +60 -0
  15. package/dist/types/evaluate/types.d.ts +57 -6
  16. package/dist/types/index.d.ts +2 -2
  17. package/dist/types/runtime/colormaps.d.ts +1 -1
  18. package/dist/types/runtime/colors.d.ts +40 -13
  19. package/dist/types/runtime/contexts.d.ts +40 -0
  20. package/dist/types/runtime/element.d.ts +100 -22
  21. package/dist/types/runtime/export.d.ts +44 -34
  22. package/dist/types/runtime/geometry.d.ts +106 -103
  23. package/dist/types/runtime/icons.d.ts +12 -2
  24. package/dist/types/runtime/outline.d.ts +29 -0
  25. package/dist/types/runtime/overlay.d.ts +3 -1
  26. package/dist/types/runtime/paint.d.ts +116 -0
  27. package/dist/types/runtime/raster.d.ts +33 -0
  28. package/dist/types/runtime/readouts.d.ts +35 -28
  29. package/dist/types/runtime/renderer.d.ts +344 -61
  30. package/dist/types/runtime/state.d.ts +27 -29
  31. package/dist/types/runtime/tiles.d.ts +2 -2
  32. package/dist/types/scene.d.ts +27 -13
  33. package/dist/types/scene.gen.d.ts +1826 -194
  34. package/dist/types/validate.d.ts +1 -1
  35. package/package.json +4 -4
@@ -1,28 +1,38 @@
1
1
  /**
2
- * One WebGL renderer for the whole stage. Every panel is a scissor rectangle of the one canvas,
2
+ * One WebGL renderer for the whole panel area. Every panel is a scissor rectangle of the one canvas,
3
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 stage size, and the pixel scale, plus
4
+ * function of the state snapshot, the frame index, the panel area size, and the pixel scale, plus
5
5
  * whatever the user did to a camera after it was fitted.
6
6
  *
7
- * A track layer draws from the static buffers of geometry.ts, one pass per lap (rule C6 of
7
+ * A trajectory layer draws from the static buffers of geometry.ts, one pass per revolution (rule `revolutions` of
8
8
  * spec/tycho-scene.md). Its shader compares each segment's two readings with the revealed range of
9
- * its track. Each range is read from a small float texture with one texel per track, so that the
10
- * reveals `none`, `grow`, and `trail` differ only in this range (rules L1, L2 and C6). The ranges
11
- * are per track rather than uniforms because in `value` mode every track has a separate reading
12
- * (rule C2). A second texel per track holds the opacity a highlight's kernel gives it. A line 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
13
  * width 1 is a GL line. A wider one is a quad per segment, offset in screen space by half the width
14
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 L3), and the bodies
16
- * and their trails (rule L4) with the evaluator's functions. Under a plane camera the axes and the
17
- * grid follow the visible rectangle and give their tick numbers and titles as panel labels.
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.
18
21
  */
19
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';
20
27
  import { type PanelScope } from '../evaluate/resolve.js';
21
28
  import type { SetData } from '../evaluate/sets.js';
22
- import type { BodyLayer, Camera, ColorSpec, MarkLayer, Scene, State, TrackLayer, View } from '../scene.js';
29
+ import type { ArrowLayer, BodyLayer, Camera, Clock, ColorSpec, LabelLayer, Layout, Marker, MarkLayer, InsetBoxLayer, PointsLayer, Scene, State, StaticText, TrajectoriesLayer, Panel } from '../scene.js';
23
30
  import { type Theme } from './colors.js';
31
+ import type { ContextHolder } from './contexts.js';
32
+ import { type BoxPaint } from './paint.js';
24
33
  import { GeometryCache } from './geometry.js';
25
34
  import { type Colorbar, type PanelLabel } from './overlay.js';
35
+ import { type Rect } from './tiles.js';
26
36
  /** Width of the gutter between two panels, in CSS pixels. */
27
37
  export declare const GUTTER = 6;
28
38
  /** A pleasant round step near `range / target`, which is 1, 2 or 5 times a power of ten. */
@@ -39,21 +49,25 @@ interface DrawContext {
39
49
  theme: Theme;
40
50
  disc: THREE.Texture;
41
51
  }
42
- export interface TrackPlan {
43
- kind: 'track';
52
+ export interface TrajectoryPlan {
53
+ kind: 'trajectories';
44
54
  index: number;
45
- layer: TrackLayer;
55
+ layer: TrajectoriesLayer;
46
56
  set: SetData | null;
47
- /** The members of rule V3, in increasing order. */
57
+ /** The members of rule `members`, in increasing order. */
48
58
  members: number[];
49
- /** The highlighted member, when the highlight's selector resolves to one of the members. */
59
+ /** The highlighted member, when the highlight's parameter input resolves to one of the members. */
50
60
  highlight: number | null;
51
- /** The track that the highlight's selector resolves to in the set, a member or not, which is the center of its kernel. */
61
+ /** The trajectory that the highlight's parameter input resolves to in the set, a member or not, which is the center of its kernel. */
52
62
  selected: number | null;
53
63
  /** The clock channel the layer reads, or null when it does not take a reading. */
54
64
  channel: string | null;
55
65
  /** 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). */
56
66
  color: ColorSpec | undefined;
67
+ /** The context its samples are transformed in (rule `read-from`). */
68
+ readFrom: 'own' | 'reference';
69
+ /** The clock the layer reads, the scene's or its own (rule `layer-clock`). */
70
+ clock: Clock;
57
71
  }
58
72
  export interface BodyPlan {
59
73
  kind: 'body';
@@ -65,38 +79,82 @@ export interface MarkPlan {
65
79
  index: number;
66
80
  layer: MarkLayer;
67
81
  }
68
- export type LayerPlan = TrackPlan | BodyPlan | MarkPlan;
82
+ export interface ArrowPlan {
83
+ kind: 'arrow';
84
+ index: number;
85
+ layer: ArrowLayer;
86
+ /** Null when the set query does not match any trajectory set. */
87
+ set: SetData | null;
88
+ /** The clock channel the layer reads. */
89
+ channel: string;
90
+ /** The clock the layer reads, the scene's or its own (rule `layer-clock`). */
91
+ clock: Clock;
92
+ }
93
+ export interface PointsPlan {
94
+ kind: 'points';
95
+ index: number;
96
+ layer: PointsLayer;
97
+ /** Null when the set query does not match any trajectory set. */
98
+ set: SetData | null;
99
+ /** The members of rule `members`, in increasing order. */
100
+ members: number[];
101
+ /** The marker's color, where a colormap keyed on a choice is resolved as for a trajectories layer. */
102
+ color: ColorSpec | undefined;
103
+ }
104
+ export interface LabelPlan {
105
+ kind: 'label';
106
+ index: number;
107
+ layer: LabelLayer;
108
+ /** The set of an anchor at a member, or null. */
109
+ set: SetData | null;
110
+ }
111
+ export interface InsetBoxPlan {
112
+ kind: 'inset_box';
113
+ index: number;
114
+ layer: InsetBoxLayer;
115
+ }
116
+ export type LayerPlan = TrajectoryPlan | ArrowPlan | InsetBoxPlan | BodyPlan | MarkPlan | PointsPlan | LabelPlan;
69
117
  export interface PanelPlan {
70
- viewId: string;
71
- view: View;
118
+ /** The id of the declared panel that the shown panel shows. */
119
+ declaredId: string;
120
+ declared: Panel;
72
121
  display: string;
73
122
  scope: PanelScope;
74
- driver: {
75
- set: SetData;
76
- track: number;
77
- } | null;
123
+ reference: Reference;
78
124
  layers: LayerPlan[];
79
125
  }
80
- /** A layer's color with a colormap keyed on a choice (section 2.7) resolved by the panel's value of the choice (rule V1). */
126
+ /** 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`). */
81
127
  export declare function resolveColor(scope: PanelScope, spec: ColorSpec | undefined): ColorSpec | undefined;
82
- /** What a panel of a state draws: its display frame, its driver, and its visible layers resolved. */
128
+ /** What a panel of a state draws: its display frame, its reference, and its visible layers resolved. */
83
129
  export declare function planPanel(scene: Scene, geometry: GeometryCache, state: State, pid: string): PanelPlan;
84
- /** What the camera fit depends on: the view, the display frame, the driver's track set, and the track sets of the track layers. */
130
+ /** 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. */
85
131
  export declare function contentKey(plan: PanelPlan): string;
86
132
  type Box6 = [number, number, number, number, number, number];
133
+ /** An affine map p -> A p + b, as the rows of A followed by b. */
134
+ type Affine = Float64Array;
135
+ /** 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. */
136
+ export declare function affineAt(frames: Frames, from: string, to: string, ctx: Context): Affine;
137
+ /**
138
+ * 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
139
+ * contexts of the reference trajectory's samples k and k + 1 blended by the weight w, as a matrix of three.js.
140
+ */
141
+ export declare function referenceMatrix(env: LayerEnv, from: string, reference: NonNullable<Reference>, out?: THREE.Matrix4, clock?: TrajectoryClock): THREE.Matrix4;
87
142
  /**
88
- * The box a panel's camera fits, which holds every member of every track layer, whole, in every lap
89
- * from 0 to the top, in the display frame. It is given as minimum then maximum x, y, z, and is null
90
- * when the track layers do not draw anything.
143
+ * The box a panel's camera fits, which holds every member of every trajectory layer without `fit: false`, whole, in every revolution
144
+ * from 0 to the top, in the display frame. A layer in the reference trajectory's context is held at every sample of
145
+ * the reference trajectory's trajectory. The box is given as minimum then maximum x, y, z, and is null when the trajectory
146
+ * layers do not draw anything. A test passes a small `budget` in place of REFERENCE_FIT_BUDGET, to force the fit by the corners.
91
147
  */
92
- export declare function fitBox(plan: PanelPlan, geometry: GeometryCache): Box6 | null;
148
+ export declare function fitBox(plan: PanelPlan, geometry: GeometryCache, budget?: number): Box6 | null;
93
149
  /**
94
- * An orthographic fit, given as the center of the box and half the view's height, for a viewport whose
95
- * width over height is `aspect`. One world unit is as long across the screen as up it, and a tenth of
96
- * margin is added.
150
+ * An orthographic fit, given as the center of the box and half the view's width and height, for a viewport
151
+ * whose width over height is `aspect`. A tenth of margin is added. One world unit is as long across the
152
+ * screen as up it, unless the camera has a free aspect. The box is then fitted in each direction separately,
153
+ * and along an axis on which the box is flat the half size is the one of the equal fit.
97
154
  */
98
155
  export declare function orthoFit(box: THREE.Box3, cam: Camera, aspect: number): {
99
156
  center: THREE.Vector3;
157
+ halfWidth: number;
100
158
  halfHeight: number;
101
159
  };
102
160
  /** The opacity of a member at parameter distance `d` from the center of a highlight's kernel (section 2.7). */
@@ -104,7 +162,7 @@ export declare function kernelOpacity(floor: number, kernel: {
104
162
  width: number;
105
163
  opacity: number;
106
164
  }, extent: number, d: number): number;
107
- /** The part of the display plane a plane camera shows, and the steps of its ticks. */
165
+ /** The part of the display plane a 2d camera shows, and the steps of its ticks. */
108
166
  export interface PlaneView {
109
167
  /** The visible rectangle along the camera's right and up axes, in display-frame units. */
110
168
  x0: number;
@@ -117,18 +175,51 @@ export interface PlaneView {
117
175
  stepX: number;
118
176
  stepY: number;
119
177
  }
120
- /** What an orthographic camera under a plane camera shows, with a tick about every 110 pixels across and 70 up. */
178
+ /** What an orthographic camera under a 2d camera shows, with a tick about every 110 pixels across and 70 up. */
121
179
  export declare function planeView(camera: THREE.OrthographicCamera, cam: Camera & {
122
- kind: 'plane';
180
+ kind: '2d';
123
181
  }, w: number, h: number): PlaneView;
124
182
  /**
125
- * The labels of a plane view. Tick numbers run along the bottom and the left edges, clear of the corners.
126
- * The two axis titles sit at the bottom center and the left center, the second reading upward, each in a
183
+ * 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
184
+ * `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
185
+ * 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,
186
+ * although their text is set in different fonts.
187
+ */
188
+ export declare function labelBox(l: PanelLabel): [number, number, number, number];
189
+ /** The title of an axis of a frame, from the axis's static text and the frame's unit, which follows a nonempty title in brackets. */
190
+ export declare function axisTitle(name: StaticText | undefined, unit: string | undefined): PanelLabel['text'];
191
+ /**
192
+ * Writes the text of a label into its span. A sub or a sup run becomes a span at the size of a script, lowered or raised as `drawText` sets it on a
193
+ * canvas. Its offset is relative, hence the line box of the label, and with it the label's place, does not change.
194
+ */
195
+ export declare function writeLabel(span: HTMLElement, text: PanelLabel['text']): void;
196
+ /** True when the boxes of two labels are overlapping, as `labelBox` estimates them, and false when they are only touching. */
197
+ export declare function labelsOverlap(a: PanelLabel, b: PanelLabel): boolean;
198
+ /**
199
+ * 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
200
+ * colorbars, given by its distance from the panel's right edge, its top, its width, and its height, in CSS pixels.
201
+ */
202
+ export interface Clearance {
203
+ header: number;
204
+ bars: {
205
+ right: number;
206
+ top: number;
207
+ width: number;
208
+ height: number;
209
+ } | null;
210
+ }
211
+ /** The colorbars' box of `c` in a panel `w` pixels wide, as [left, top, right, bottom], grown by 2 px on each side. */
212
+ export declare function barsBox(c: Clearance, w: number): [number, number, number, number] | null;
213
+ /** True when the box of label `l`, as tall as its line of text, overlaps `box`, given as [left, top, right, bottom]. */
214
+ export declare function labelOver(l: PanelLabel, box: [number, number, number, number]): boolean;
215
+ /**
216
+ * The labels of a plane view. Tick numbers run along the bottom and the left edges, clear of the corners
217
+ * 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
127
218
  * separate row outside the tick numbers. The tick row is centered 28 px above the bottom edge and the x
128
219
  * title 10 px above it. The y title sits 10 px from the left edge, and the y tick column is right-aligned
129
220
  * clear of it at its widest number. A panel too short or too narrow for a title keeps its ticks.
130
221
  */
131
- export declare function planeLabels(v: PlaneView, ticks: boolean, titles: [string, string] | null): PanelLabel[];
222
+ export declare function planeLabels(v: PlaneView, ticks: boolean, titles: [PanelLabel['text'], PanelLabel['text']] | null, top?: number): PanelLabel[];
132
223
  interface Draw {
133
224
  readonly key: string;
134
225
  readonly group: THREE.Group;
@@ -136,7 +227,42 @@ interface Draw {
136
227
  resize?(w: number, h: number): void;
137
228
  dispose(): void;
138
229
  }
139
- export declare class TrackDraw implements Draw {
230
+ /**
231
+ * Where the dash pattern of each segment of a trajectory starts (section 2.11), as an arclength along the trajectory, written to `out` from
232
+ * `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
233
+ * first sample when that lies in the rectangle, as matplotlib clips a line to its figure before it dashes it, which starts the
234
+ * pattern again at each entry. `xy` holds the screen position of each of the `count` samples from `from`, two numbers per sample,
235
+ * and `dist` the arclength of each. Before the trajectory first enters the rectangle, its segments start at its first sample.
236
+ */
237
+ export declare function dashRestarts(xy: ArrayLike<number>, dist: ArrayLike<number>, from: number, count: number, x0: number, y0: number, x1: number, y1: number, out: {
238
+ [i: number]: number;
239
+ }, at: number): void;
240
+ /** The sprites of a marker (section 2.11), drawn from a texture of its shape, in one color or tinted per point. */
241
+ export declare class MarkerSprites {
242
+ readonly points: THREE.Points;
243
+ private readonly material;
244
+ private readonly marker;
245
+ private readonly tinted;
246
+ private texSize;
247
+ /** The width of the stroke the texture was drawn with, which may move with the timeline as the size does. */
248
+ private texEdge;
249
+ private edgeWidth;
250
+ constructor(marker: Marker, size: number, tinted: boolean);
251
+ /**
252
+ * Sets the size of the sprites' shape in CSS pixels, and the width of its stroke when given, drawing the texture again when either
253
+ * moves, since the stroke is in CSS pixels and does not scale with the marker.
254
+ */
255
+ setSize(size: number, edgeWidth?: number | undefined): void;
256
+ setOpacity(opacity: number): void;
257
+ /** Room for `n` points. */
258
+ grow(n: number): void;
259
+ get position(): THREE.BufferAttribute;
260
+ get color(): THREE.BufferAttribute;
261
+ /** Draws the first `n` points. */
262
+ show(n: number): void;
263
+ dispose(): void;
264
+ }
265
+ export declare class TrajectoryDraw implements Draw {
140
266
  readonly key: string;
141
267
  readonly group: THREE.Group<THREE.Object3DEventMap>;
142
268
  private readonly src;
@@ -144,6 +270,7 @@ export declare class TrackDraw implements Draw {
144
270
  private readonly set;
145
271
  private readonly geo;
146
272
  private readonly clocks;
273
+ private readonly clock;
147
274
  private readonly spec;
148
275
  private readonly color;
149
276
  private readonly width;
@@ -157,55 +284,132 @@ export declare class TrackDraw implements Draw {
157
284
  private readonly kernel;
158
285
  private readonly ranges;
159
286
  private readonly alphas;
287
+ /** For a dashed layer, the arclength at which each segment's dash pattern starts on the panel area (section 2.11), else null. */
288
+ private readonly dashFrom;
289
+ private dashScreen;
290
+ private restartOut;
160
291
  private readonly resolution;
161
292
  private readonly uniforms;
162
293
  private readonly baseHolder;
163
294
  private readonly hiHolder;
164
- /** The passes built so far, by lap and kind, each built the first time its lap shows anything. */
295
+ /** The passes built so far, by revolution and kind, each built the first time its revolution shows anything. */
165
296
  private readonly passes;
166
297
  private readonly pieces;
167
298
  private heads;
299
+ private glow;
168
300
  private readonly headSize;
169
301
  private readonly headColor;
302
+ private fill;
303
+ private fillBuffer;
304
+ /** False for a layer that draws its heads alone (section 2.11). */
305
+ private readonly line;
306
+ /** The stencil mark of a flat layer, whose lines blend each pixel once (section 2.11), else 0. */
307
+ private readonly flatMark;
308
+ /** True when the layer's opacity or its head's size or opacity moves with the timeline, hence it is drawn every frame. */
309
+ private readonly keyframed;
170
310
  private members;
171
311
  private highlight;
172
312
  private selected;
173
313
  private baseWhat;
174
314
  private skip;
175
315
  private filled;
176
- constructor(ctx: DrawContext, plan: TrackPlan & {
316
+ /** 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. */
317
+ readonly referenceContext: boolean;
318
+ private readonly geometry;
319
+ constructor(ctx: DrawContext, plan: TrajectoryPlan & {
177
320
  set: SetData;
178
321
  }, display: string, key: string);
179
- /** Room for `n` heads in the heads' buffers. */
180
- private growHeads;
181
322
  resize(w: number, h: number): void;
182
- /** The color of a vertex of track `t`, which is the layer's color or a blend of the colors of two samples. */
323
+ /** The ratio of the pixels per unit up the screen to those across it, for which the arclengths of a dash were computed. */
324
+ private dashRatio;
325
+ /**
326
+ * 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
327
+ * differ, and the arclengths are computed again, and the passes built again, when their ratio changes.
328
+ */
329
+ setPixels(across: number, up: number): void;
330
+ /** The color of a vertex of trajectory `t`, which is the layer's color or a blend of the colors of two samples. */
183
331
  private colorAt;
184
- /** Each track's opacity under the highlight's kernel, around the selected track's parameter value. */
332
+ /** The arclength of a vertex of trajectory `t` for a dash, from where the trajectory's pattern starts. */
333
+ private distAt;
334
+ /**
335
+ * Starts the dash pattern of each trajectory where it enters the panel area, of `width` by `height` CSS pixels widened by `margin`, as
336
+ * 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.
337
+ * The dashes of a line that the camera follows then stay where they are on the screen rather than crawl along it.
338
+ */
339
+ placeDash(camera: THREE.Camera, rect: {
340
+ x: number;
341
+ y: number;
342
+ w: number;
343
+ h: number;
344
+ }, width: number, height: number, margin: number): void;
345
+ /** Each trajectory's opacity under the highlight's kernel, around the selected trajectory's parameter value. */
185
346
  private fillKernel;
186
347
  private showPass;
187
348
  private pass;
188
- /** Shows the passes of the laps that draw a segment, building the ones not built yet, and hides the others. */
349
+ /** Shows the passes of the revolutions that draw a segment, building the ones not built yet, and hides the others. */
189
350
  private syncPasses;
190
- /** True when the layer does not take a reading, so that what it draws changes only with its members, its highlight, and its selection. */
351
+ /**
352
+ * 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
353
+ * what it draws changes only with its members, its highlight, and its selection.
354
+ */
191
355
  get isStatic(): boolean;
356
+ /** 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`). */
357
+ place(env: LayerEnv, reference: Reference): void;
358
+ /** 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. */
359
+ private fade;
192
360
  /** Returns whether the picture changed through new members, a new highlight or selection, or a first fill. */
193
- update(plan: TrackPlan, scene: Scene, q: number): boolean;
361
+ update(plan: TrajectoryPlan, scene: Scene, q: number): boolean;
362
+ /** The vertices of the drawn polyline of trajectory `t`, as rules `polyline`, `trail-wrap`, and `revolutions` give them, for a fill. */
363
+ private fillTrajectory;
364
+ /** The two axes of the plane the fill is laid out in, set by the panel's camera. */
365
+ planeAxes: [number, number];
366
+ private setFill;
194
367
  extend(): void;
195
368
  /** The colorbar of a colormapped layer, with the highlighted or single member marked on it, and the kernel's band. */
196
369
  colorbar(): Colorbar | null;
197
370
  dispose(): void;
198
371
  }
372
+ /** Appends the triangles that shade the part of the segment from `a` to `b` above the line y = base, as x, y pairs. */
373
+ export declare function fillSegment(a: [number, number], b: [number, number], base: number, out: number[]): void;
374
+ /**
375
+ * 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
376
+ * 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
377
+ * host camera onto a panel of `w` by `h` pixels. Null when a corner is behind a perspective camera.
378
+ */
379
+ export declare function outlineCorners(map: InsetBoxLayerResult & {
380
+ origin: Vec3;
381
+ axes: [Vec3, Vec3, Vec3];
382
+ }, view: PlaneView, target: Camera & {
383
+ kind: '2d';
384
+ }, camera: THREE.OrthographicCamera | THREE.PerspectiveCamera, host: Camera, w: number, h: number): [[number, number], [number, number], [number, number], [number, number]] | null;
385
+ /**
386
+ * 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
387
+ * in `place` from the target camera's visible rectangle at the same frame, after every camera of the panel area has moved.
388
+ */
389
+ /** 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. */
390
+ export declare function insetBoxShownPanel(map: InsetBoxLayerResult | null): string | null;
199
391
  /**
200
392
  * Whether a camera's world or projection matrix differs from `seen`, which then holds both. The test
201
393
  * covers any pan, zoom, rotation, fit, or change of aspect, however the camera was moved.
202
394
  */
203
395
  export declare function cameraMoved(camera: THREE.Camera, seen: Float64Array): boolean;
204
- export declare class StageRenderer {
205
- readonly canvas: HTMLCanvasElement;
206
- /** Called when the user moves a camera, so that the page redraws. */
396
+ /** Whether two regions (x, y, width, height) of the underlay share a pixel. A region that was never set, at -1, shares none. */
397
+ export declare function overlaps(a: THREE.Vector4, b: THREE.Vector4): boolean;
398
+ export declare class PanelAreaRenderer implements ContextHolder {
399
+ /**
400
+ * The canvas drawn on. A canvas keeps its first WebGL context for good, hence a later context is made on a new canvas, which
401
+ * takes this one's place in the page.
402
+ */
403
+ canvas: HTMLCanvasElement;
404
+ /** Called when the panel area should be drawn again, e.g. when the user moves a camera. */
207
405
  onChange: () => void;
208
- private readonly gl;
406
+ /** Called when the browser takes the WebGL context, or gives back one that it took. */
407
+ onContext: () => void;
408
+ /** three's renderer on the WebGL context of `canvas`, or null before the first draw and after a release. */
409
+ private gl;
410
+ /** Whether `canvas` was given a WebGL context. */
411
+ private canvasUsed;
412
+ private readonly preserveDrawingBuffer;
209
413
  private readonly ctx;
210
414
  private readonly panels;
211
415
  private lastState;
@@ -233,6 +437,9 @@ export declare class StageRenderer {
233
437
  */
234
438
  private scratch;
235
439
  private readonly viewport;
440
+ /** The canvas's viewport and scissor in CSS pixels, as they were set for the panel being drawn. */
441
+ private readonly cssViewport;
442
+ private readonly cssScissor;
236
443
  private readonly buffer;
237
444
  private readonly region;
238
445
  private readonly corner;
@@ -246,14 +453,45 @@ export declare class StageRenderer {
246
453
  coarseDrags?: boolean;
247
454
  theme?: Theme;
248
455
  });
456
+ /** Whether the renderer holds a WebGL context, which may be lost. */
457
+ get connected(): boolean;
458
+ /** Whether the renderer holds a WebGL context that is not lost, i.e. whether a draw reaches the canvas. */
459
+ get live(): boolean;
460
+ /**
461
+ * Makes a WebGL context to draw on, unless the renderer holds one that is not lost. The panels keep their cameras, their controls,
462
+ * and their draws, which three uploads to the new context at the next draw. Throws when the browser cannot make a WebGL context.
463
+ */
464
+ connect(): void;
465
+ /** Frees the WebGL context, and with it everything the panels hold on the GPU, for `connect` to make a new one. */
466
+ release(): void;
467
+ /** Forgets the underlay and the scratch target, which went with the context, so that the next draw makes them and every panel's static layers again. */
468
+ private dropTargets;
249
469
  /** 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. */
250
470
  setTheme(theme: Theme): void;
251
471
  private panel;
252
472
  /** Gives a panel the element its camera controls listen on and its labels are written into, or takes it away. */
253
473
  bind(pid: string, element: HTMLElement | null): void;
474
+ /** Sets the header and the colorbars over a panel, as the viewer measured them, for the labels drawn from the next frame on. */
475
+ setClearance(pid: string, clearance: Clearance): void;
254
476
  /** Fits a panel's camera to what it draws at the next frame, forgetting how the user moved the camera. */
255
477
  refit(pid: string): void;
256
478
  refitAll(): void;
479
+ /**
480
+ * 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
481
+ * refit hands the camera back to its keyframes.
482
+ */
483
+ offKeys(pid: string): boolean;
484
+ /** The panels with a 3d camera and its controls, i.e. those that the keys of a 3d camera move. */
485
+ orbitPanels(): string[];
486
+ /**
487
+ * 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
488
+ * 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
489
+ * 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
490
+ * off the axis by a hair, where three's lookAt is undefined.
491
+ */
492
+ viewFrom(pid: string, axis: 'x' | 'y' | 'z', sign: 1 | -1): void;
493
+ /** Turns a panel of a 3d camera about its up axis through its target by `degrees`, as a drag to the right turns it. */
494
+ turnBy(pid: string, degrees: number): void;
257
495
  private makeControls;
258
496
  private setCamera;
259
497
  /**
@@ -275,22 +513,32 @@ export declare class StageRenderer {
275
513
  private replan;
276
514
  /** Updates a panel's draws for progress `q`. */
277
515
  private advance;
278
- /** Fits the camera to every track layer's members (fitBox), or to the bodies when the track layers do not draw anything. */
516
+ /** Fits the camera to every trajectory layer's members (fitBox), or to the bodies when the trajectory layers do not draw anything. */
279
517
  private fit;
280
- /** Keeps one world unit the same length across and up the screen in an orthographic view. */
518
+ /**
519
+ * Keeps one world unit the same length across and up the screen in an orthographic view. Under a free
520
+ * aspect the visible rectangle is kept instead, and it is stretched with the panel.
521
+ */
281
522
  private aspect;
282
- /** What a plane camera shows now, and the marks that follow it laid out across it. */
523
+ /**
524
+ * Turns a 3d camera about its up axis through its target to its `auto_rotate` in degrees times the
525
+ * progress `q` of the loop. The turn adds to where the viewer moved the camera.
526
+ */
527
+ private autoRotate;
528
+ /** What a 2d camera shows now, and the marks that follow it laid out across it. */
283
529
  private follow;
284
530
  /**
285
- * Draws every panel of `state` at progress `q` in [0, 1) on a stage of `width` by `height` CSS
286
- * pixels. A frame index i sits at q = i / steps, and playback draws between two of them. Returns the
531
+ * Draws every panel of `state` at progress `q` in [0, 1) on a panel area of `width` by `height` CSS
532
+ * pixels. A frame index i sits at q = i / frame_count, and playback draws between two of them. Returns the
287
533
  * message of every panel that could not be drawn.
288
534
  */
289
535
  renderAt(state: State, q: number, width: number, height: number, pixelRatio: number): Map<string, string>;
290
536
  /**
291
537
  * The labels of a panel at the last frame, in CSS pixels from the panel's corner. They are the tick
292
- * numbers and axis titles of a plane camera, the axis titles at the tips of axes laid out from the
293
- * box, and the body labels beside their discs.
538
+ * numbers and axis titles of a 2d camera, the axis titles at the tips of axes laid out from the
539
+ * box, and the body labels beside their discs. An axis title under a shown body label is hidden,
540
+ * since the body label is the name of the disc beside it. A body label that would cover the colorbars
541
+ * moves to the other side of its disc, and a label still over them is hidden, since neither text could be read.
294
542
  */
295
543
  private labelItems;
296
544
  /** The labels a panel shows at the last frame, for a page or a video frame to write as text. */
@@ -298,6 +546,41 @@ export declare class StageRenderer {
298
546
  /** The colorbars a panel shows, the identical ones merged. */
299
547
  colorbars(pid: string): Colorbar[];
300
548
  private placeLabels;
549
+ /**
550
+ * 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
551
+ * then, unless the viewer has moved the camera since its last fit. The window's height is its own under a free aspect, and
552
+ * the width over the panel's aspect ratio otherwise.
553
+ */
554
+ private keyed;
555
+ /** Resolves once every body image of the drawn panels is decoded, so that a video does not start without them. */
556
+ ready(): Promise<void>;
557
+ /** 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. */
558
+ paintInfo(pid: string): PanelPaint | null;
301
559
  dispose(): void;
302
560
  }
561
+ /** 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. */
562
+ export interface PanelPaint {
563
+ outer: Rect;
564
+ rect: Rect;
565
+ opacity: Panel['opacity'];
566
+ /** The titles of the box's axes layer, when it gives its own (section 2.11). */
567
+ boxTitles?: MarkLayer extends never ? never : Extract<MarkLayer, {
568
+ kind: 'axes';
569
+ }>['titles'];
570
+ /** The labels at their anchors, `clip` for an anchor at a point, which is hidden outside the plot. */
571
+ labels: {
572
+ layer: LabelLayer;
573
+ x: number;
574
+ y: number;
575
+ clip: boolean;
576
+ }[];
577
+ /** The box of an axes layer, with the opacity of the layer, which the panel area reads at the time of the timeline. */
578
+ box: (Omit<BoxPaint, 'opacity'> & {
579
+ opacity: MarkLayer['opacity'];
580
+ }) | null;
581
+ }
582
+ /** A rectangle less a panel's margin, given as fractions of its height and width (section 2.11). */
583
+ export declare function inset(r: Rect, margin: Panel['margin']): Rect;
584
+ /** 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). */
585
+ export declare function layoutAt(layout: Layout, s: number): Layout;
303
586
  export {};