@beeson-group/tycho 0.2.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.
@@ -1,28 +1,37 @@
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, TrajectoriesLayer, Panel } from '../scene.js';
23
30
  import { type Theme } from './colors.js';
31
+ import { type BoxPaint } from './paint.js';
24
32
  import { GeometryCache } from './geometry.js';
25
33
  import { type Colorbar, type PanelLabel } from './overlay.js';
34
+ import { type Rect } from './tiles.js';
26
35
  /** Width of the gutter between two panels, in CSS pixels. */
27
36
  export declare const GUTTER = 6;
28
37
  /** A pleasant round step near `range / target`, which is 1, 2 or 5 times a power of ten. */
@@ -39,21 +48,25 @@ interface DrawContext {
39
48
  theme: Theme;
40
49
  disc: THREE.Texture;
41
50
  }
42
- export interface TrackPlan {
43
- kind: 'track';
51
+ export interface TrajectoryPlan {
52
+ kind: 'trajectories';
44
53
  index: number;
45
- layer: TrackLayer;
54
+ layer: TrajectoriesLayer;
46
55
  set: SetData | null;
47
- /** The members of rule V3, in increasing order. */
56
+ /** The members of rule `members`, in increasing order. */
48
57
  members: number[];
49
- /** The highlighted member, when the highlight's selector resolves to one of the members. */
58
+ /** The highlighted member, when the highlight's parameter input resolves to one of the members. */
50
59
  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. */
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. */
52
61
  selected: number | null;
53
62
  /** The clock channel the layer reads, or null when it does not take a reading. */
54
63
  channel: string | null;
55
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). */
56
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;
57
70
  }
58
71
  export interface BodyPlan {
59
72
  kind: 'body';
@@ -65,38 +78,78 @@ export interface MarkPlan {
65
78
  index: number;
66
79
  layer: MarkLayer;
67
80
  }
68
- export type LayerPlan = TrackPlan | BodyPlan | MarkPlan;
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;
69
112
  export interface PanelPlan {
70
- viewId: string;
71
- view: View;
113
+ /** The id of the declared panel that the shown panel shows. */
114
+ declaredId: string;
115
+ declared: Panel;
72
116
  display: string;
73
117
  scope: PanelScope;
74
- driver: {
75
- set: SetData;
76
- track: number;
77
- } | null;
118
+ reference: Reference;
78
119
  layers: LayerPlan[];
79
120
  }
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). */
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`). */
81
122
  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. */
123
+ /** What a panel of a state draws: its display frame, its reference, and its visible layers resolved. */
83
124
  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. */
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. */
85
126
  export declare function contentKey(plan: PanelPlan): string;
86
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;
87
137
  /**
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.
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.
91
142
  */
92
- export declare function fitBox(plan: PanelPlan, geometry: GeometryCache): Box6 | null;
143
+ export declare function fitBox(plan: PanelPlan, geometry: GeometryCache, budget?: number): Box6 | null;
93
144
  /**
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.
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.
97
149
  */
98
150
  export declare function orthoFit(box: THREE.Box3, cam: Camera, aspect: number): {
99
151
  center: THREE.Vector3;
152
+ halfWidth: number;
100
153
  halfHeight: number;
101
154
  };
102
155
  /** The opacity of a member at parameter distance `d` from the center of a highlight's kernel (section 2.7). */
@@ -104,7 +157,7 @@ export declare function kernelOpacity(floor: number, kernel: {
104
157
  width: number;
105
158
  opacity: number;
106
159
  }, extent: number, d: number): number;
107
- /** The part of the display plane a plane camera shows, and the steps of its ticks. */
160
+ /** The part of the display plane a 2d camera shows, and the steps of its ticks. */
108
161
  export interface PlaneView {
109
162
  /** The visible rectangle along the camera's right and up axes, in display-frame units. */
110
163
  x0: number;
@@ -117,18 +170,44 @@ export interface PlaneView {
117
170
  stepX: number;
118
171
  stepY: number;
119
172
  }
120
- /** What an orthographic camera under a plane camera shows, with a tick about every 110 pixels across and 70 up. */
173
+ /** What an orthographic camera under a 2d camera shows, with a tick about every 110 pixels across and 70 up. */
121
174
  export declare function planeView(camera: THREE.OrthographicCamera, cam: Camera & {
122
- kind: 'plane';
175
+ kind: '2d';
123
176
  }, w: number, h: number): PlaneView;
124
177
  /**
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
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
127
206
  * separate row outside the tick numbers. The tick row is centered 28 px above the bottom edge and the x
128
207
  * title 10 px above it. The y title sits 10 px from the left edge, and the y tick column is right-aligned
129
208
  * clear of it at its widest number. A panel too short or too narrow for a title keeps its ticks.
130
209
  */
131
- export declare function planeLabels(v: PlaneView, ticks: boolean, titles: [string, string] | null): PanelLabel[];
210
+ export declare function planeLabels(v: PlaneView, ticks: boolean, titles: [string, string] | null, top?: number): PanelLabel[];
132
211
  interface Draw {
133
212
  readonly key: string;
134
213
  readonly group: THREE.Group;
@@ -136,7 +215,42 @@ interface Draw {
136
215
  resize?(w: number, h: number): void;
137
216
  dispose(): void;
138
217
  }
139
- export declare class TrackDraw implements Draw {
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 {
140
254
  readonly key: string;
141
255
  readonly group: THREE.Group<THREE.Object3DEventMap>;
142
256
  private readonly src;
@@ -144,6 +258,7 @@ export declare class TrackDraw implements Draw {
144
258
  private readonly set;
145
259
  private readonly geo;
146
260
  private readonly clocks;
261
+ private readonly clock;
147
262
  private readonly spec;
148
263
  private readonly color;
149
264
  private readonly width;
@@ -157,51 +272,118 @@ export declare class TrackDraw implements Draw {
157
272
  private readonly kernel;
158
273
  private readonly ranges;
159
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;
160
279
  private readonly resolution;
161
280
  private readonly uniforms;
162
281
  private readonly baseHolder;
163
282
  private readonly hiHolder;
164
- /** The passes built so far, by lap and kind, each built the first time its lap shows anything. */
283
+ /** The passes built so far, by revolution and kind, each built the first time its revolution shows anything. */
165
284
  private readonly passes;
166
285
  private readonly pieces;
167
286
  private heads;
287
+ private glow;
168
288
  private readonly headSize;
169
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;
170
298
  private members;
171
299
  private highlight;
172
300
  private selected;
173
301
  private baseWhat;
174
302
  private skip;
175
303
  private filled;
176
- constructor(ctx: DrawContext, plan: TrackPlan & {
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 & {
177
308
  set: SetData;
178
309
  }, display: string, key: string);
179
- /** Room for `n` heads in the heads' buffers. */
180
- private growHeads;
181
310
  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. */
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. */
183
319
  private colorAt;
184
- /** Each track's opacity under the highlight's kernel, around the selected track's parameter value. */
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. */
185
334
  private fillKernel;
186
335
  private showPass;
187
336
  private pass;
188
- /** Shows the passes of the laps that draw a segment, building the ones not built yet, and hides the others. */
337
+ /** Shows the passes of the revolutions that draw a segment, building the ones not built yet, and hides the others. */
189
338
  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. */
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
+ */
191
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;
192
348
  /** 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;
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;
194
355
  extend(): void;
195
356
  /** The colorbar of a colormapped layer, with the highlighted or single member marked on it, and the kernel's band. */
196
357
  colorbar(): Colorbar | null;
197
358
  dispose(): void;
198
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;
199
379
  /**
200
380
  * Whether a camera's world or projection matrix differs from `seen`, which then holds both. The test
201
381
  * covers any pan, zoom, rotation, fit, or change of aspect, however the camera was moved.
202
382
  */
203
383
  export declare function cameraMoved(camera: THREE.Camera, seen: Float64Array): boolean;
204
- export declare class StageRenderer {
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 {
205
387
  readonly canvas: HTMLCanvasElement;
206
388
  /** Called when the user moves a camera, so that the page redraws. */
207
389
  onChange: () => void;
@@ -233,6 +415,9 @@ export declare class StageRenderer {
233
415
  */
234
416
  private scratch;
235
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;
236
421
  private readonly buffer;
237
422
  private readonly region;
238
423
  private readonly corner;
@@ -251,9 +436,27 @@ export declare class StageRenderer {
251
436
  private panel;
252
437
  /** Gives a panel the element its camera controls listen on and its labels are written into, or takes it away. */
253
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;
254
441
  /** Fits a panel's camera to what it draws at the next frame, forgetting how the user moved the camera. */
255
442
  refit(pid: string): void;
256
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;
257
460
  private makeControls;
258
461
  private setCamera;
259
462
  /**
@@ -275,22 +478,32 @@ export declare class StageRenderer {
275
478
  private replan;
276
479
  /** Updates a panel's draws for progress `q`. */
277
480
  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. */
481
+ /** Fits the camera to every trajectory layer's members (fitBox), or to the bodies when the trajectory layers do not draw anything. */
279
482
  private fit;
280
- /** Keeps one world unit the same length across and up the screen in an orthographic view. */
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
+ */
281
487
  private aspect;
282
- /** What a plane camera shows now, and the marks that follow it laid out across it. */
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. */
283
494
  private follow;
284
495
  /**
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
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
287
498
  * message of every panel that could not be drawn.
288
499
  */
289
500
  renderAt(state: State, q: number, width: number, height: number, pixelRatio: number): Map<string, string>;
290
501
  /**
291
502
  * 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.
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.
294
507
  */
295
508
  private labelItems;
296
509
  /** The labels a panel shows at the last frame, for a page or a video frame to write as text. */
@@ -298,6 +511,41 @@ export declare class StageRenderer {
298
511
  /** The colorbars a panel shows, the identical ones merged. */
299
512
  colorbars(pid: string): Colorbar[];
300
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;
301
524
  dispose(): void;
302
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;
303
551
  export {};