@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,217 @@
1
+ /**
2
+ * Static geometry of a trajectory set in a display frame, and the revealed part of one trajectory at a
3
+ * reading. A set's samples are transformed once per display frame and revolution, each in its context
4
+ * (rules `sample-context` and `revolutions`). Their readings u_i are computed once per clock channel (rule `sample-fraction`), so that
5
+ * drawing a frame only compares readings and blends two transformed samples (rule `segment`). Every
6
+ * panel showing the same frame shares the same buffers, and a revolution is transformed the first time
7
+ * something draws it.
8
+ *
9
+ * The GPU draws the stored segments of one revolution per pass. Within a revolution below the top one, the
10
+ * closing sample of a trajectory is replaced by the first sample of the next revolution, which is the joint
11
+ * of rule `revolutions`, so that the passes of consecutive revolutions draw one polyline. A segment is drawn when
12
+ * both its ends lie strictly inside the revealed range of loop readings U = n u, where n is the
13
+ * number of revolutions and u the reading. The range is stored as the revolution and the within-revolution reading of
14
+ * each end, and compared revolution by revolution, so that the GPU compares the float32 readings as stored and
15
+ * does not add a revolution to any of them. The CPU draws the pieces at the two ends of the range, thus
16
+ * the GPU and the CPU together draw the polyline of rules `polyline`, `trail-wrap` and `revolutions`.
17
+ */
18
+ import type { DataStore } from '../container.js';
19
+ import { TrajectoryClock } from '../evaluate/clock.js';
20
+ import { Frames } from '../evaluate/frames.js';
21
+ import { type Vertex } from '../evaluate/layers.js';
22
+ import { SetCache, type SetData } from '../evaluate/sets.js';
23
+ import type { Clock, Scene, TrajectoriesLayer } from '../scene.js';
24
+ type Box6 = [number, number, number, number, number, number];
25
+ /** The revolution a vertex is evaluated in, which is its revolution of rule `revolutions`, or one lower when it is shifted (rule `trail-wrap`). */
26
+ export declare function vertexRevolution(v: Vertex): number;
27
+ /**
28
+ * Every sample of a set in one display frame, per revolution, as x, y, z per sample in storage order.
29
+ * A trajectory is transformed in a revolution the first time it is needed, so that drawing one member of a
30
+ * large set costs one trajectory, and the revolutions of rule `revolutions` do not cost anything until something draws them.
31
+ */
32
+ export declare class TrajectoryGeometry {
33
+ readonly set: SetData;
34
+ readonly frame: string;
35
+ /** The number of revolutions of rule `revolutions` on the set. It is taken from the clock for a periodic set, and is one otherwise. */
36
+ readonly revolutions: number;
37
+ /** The highest revolution, the only one that keeps its closing sample when the revolutions are joined. */
38
+ readonly top: number;
39
+ /** True when the edges into the display frame do not read any channel, meaning that every revolution has the positions of revolution 0. */
40
+ readonly invariant: boolean;
41
+ private readonly frames;
42
+ private readonly stores;
43
+ private box;
44
+ constructor(set: SetData, frame: string, frames: Frames, revolutions?: number);
45
+ /** The revolution whose positions revolution `j` has. */
46
+ private storeRevolution;
47
+ /** A name for the GPU's segments of revolution `j`, the same for every revolution whose segments are the same. */
48
+ revolutionKey(j: number): string;
49
+ private store;
50
+ /** Transforms trajectory `t` in revolution `revolution` (true stands for revolution -1 and false for revolution 0), unless it is already transformed. */
51
+ ensure(t: number, revolution: number | boolean): Float64Array;
52
+ /** Every sample of revolution `j`, each in its context. */
53
+ revolutionPositions(j: number): Float64Array;
54
+ /** Every sample of revolution 0, each in its context (rule `sample-context`). */
55
+ get positions(): Float64Array;
56
+ /** Every sample of revolution -1, the shifted contexts of rule `trail-wrap`, for a periodic set only. */
57
+ get shifted(): Float64Array | null;
58
+ /** The samples of trajectory `t` alone in a revolution, as x, y, z per sample. */
59
+ trajectory(t: number, revolution: number | boolean): Float64Array;
60
+ /**
61
+ * Sample `i` of trajectory `t` as the GPU draws revolution `revolution`, written at `out[o..o+2]`. It is the sample
62
+ * of revolution `revolution` itself, except for the closing sample of a revolution below the top, which is the first
63
+ * sample of the next revolution (rule `revolutions`).
64
+ */
65
+ gpuSample(t: number, revolution: number, i: number, out: {
66
+ [i: number]: number;
67
+ }, o?: number): void;
68
+ /**
69
+ * The bounding box of trajectory `t`, or of the whole set, over every revolution from 0 to the top, as
70
+ * minimum then maximum x, y, z.
71
+ */
72
+ bounds(t?: number): Box6;
73
+ /** The position of a vertex of trajectory `t` (rule `segment`) in its revolution, written at `out[o..o+2]`. */
74
+ vertex(t: number, v: Vertex, out: {
75
+ [i: number]: number;
76
+ }, o?: number): void;
77
+ }
78
+ /** The clock along every trajectory of a set for one channel, with the reading u_i of every sample and one TrajectoryClock per trajectory. */
79
+ export declare class TrajectoryReadings {
80
+ readonly channel: string;
81
+ readonly clocks: TrajectoryClock[];
82
+ readonly u: Float64Array;
83
+ constructor(set: SetData, channel: string);
84
+ }
85
+ /** Geometry and readings, built on first use and kept for the life of the page. */
86
+ export declare class GeometryCache {
87
+ readonly scene: Scene;
88
+ readonly sets: SetCache;
89
+ readonly frames: Frames;
90
+ private readonly geometries;
91
+ private readonly readingsBy;
92
+ private readonly bodyTrails;
93
+ private readonly data;
94
+ constructor(scene: Scene, data: DataStore);
95
+ /** The bytes of an array of `uint8` elements, e.g. the image file of a body. */
96
+ bytes(name: string): Uint8Array;
97
+ /** Throws an error of rule `revolutions` when the clock is in epoch mode but has revolutions. */
98
+ geometry(setId: string, frame: string): TrajectoryGeometry;
99
+ hasChannel(setId: string, channel: string): boolean;
100
+ /** Throws an error of rule `clock-channel-carried` when the set lacks the channel. */
101
+ readings(setId: string, channel: string): TrajectoryReadings;
102
+ /** The positions of a body along one reference trajectory in one display frame, kept per revolution. */
103
+ bodyTrail(bodyId: string, display: string, setId: string, trajectory: number): BodyTrailTable;
104
+ }
105
+ /**
106
+ * A channel of the reference trajectory's trajectory at progress `q`, as a readout shows it (section 2.9). The
107
+ * reading is clamped to [0, 1], and the channel is blended between the samples of rule `segment` in the
108
+ * context of the reference trajectory's revolution of rule `revolutions`.
109
+ */
110
+ export declare function channelAtReading(set: SetData, tc: TrajectoryClock, trajectory: number, channel: string, clock: Clock, q: number, hold?: boolean): number;
111
+ /** A range that does not contain any vertex, as [revolution, reading, revolution, reading] of its two ends. */
112
+ export declare const EMPTY_RANGE: readonly [number, number, number, number];
113
+ /** The range every sample of every revolution from 0 to `top` lies inside, closing samples included. */
114
+ export declare const fullRange: (top: number) => [number, number, number, number];
115
+ /** The part of a polyline the GPU draws and the pieces the CPU draws at its two ends. */
116
+ export interface LoopSpan {
117
+ /** The revolution and the within-revolution reading of each end for the GPU, [jA, uA, jB, uB], rounded as the GPU stores readings. */
118
+ range: [number, number, number, number];
119
+ /** The lowest and the highest revolution whose pass draws a segment, or null when the GPU does not draw any segment. */
120
+ revolutions: [number, number] | null;
121
+ /** Segments the CPU draws, at the ends of the range. */
122
+ pieces: [Vertex, Vertex][];
123
+ }
124
+ /**
125
+ * Whether the GPU draws, in revolution `revolution`, a segment whose samples read `ui` and `uj` (as stored),
126
+ * against a range of `LoopSpan.range`. Both ends must lie strictly inside the range in loop
127
+ * readings, compared revolution first and reading second.
128
+ */
129
+ export declare function segmentShown(range: readonly [number, number, number, number], revolution: number, ui: number, uj: number): boolean;
130
+ /**
131
+ * The polyline of rules `polyline` and `revolutions` between loop readings `ua <= ub`, on a set of `revolutions` revolutions. A
132
+ * vertex is inside when its rounded reading in its revolution lies strictly inside the rounded range, as
133
+ * segmentShown tests it. With `round` the identity, the test selects the vertices of the
134
+ * evaluator's polyline. With Math.fround, it is the comparison a float32 GPU makes, so that the
135
+ * CPU's end pieces meet the GPU's segments at the same samples.
136
+ */
137
+ export declare function loopSpan(tc: TrajectoryClock, ua: number, ub: number, revolutions: number, round?: (x: number) => number): LoopSpan;
138
+ export interface Reveal extends LoopSpan {
139
+ /** The trajectory is not drawn at this reading (rule `before-after`). */
140
+ hidden: boolean;
141
+ /** The trajectory's reading u, bounded by rule `before-after`, or null when the layer does not take a reading or the trajectory is hidden. */
142
+ reading: number | null;
143
+ /** The loop reading U = n u of rule `revolutions`, null when `reading` is null. */
144
+ loop: number | null;
145
+ /** The point at the reading, i.e. the head of rule `head`, when the layer draws a head and the trajectory is shown. */
146
+ head: Vertex | null;
147
+ }
148
+ export interface RevealSpec {
149
+ reveal: 'none' | 'grow' | 'trail';
150
+ fraction: number;
151
+ before?: 'clamp' | 'hidden';
152
+ after?: 'clamp' | 'hidden';
153
+ head: boolean;
154
+ periodic: boolean;
155
+ /** The number of revolutions n of rule `revolutions` on this set, taken from the clock for a periodic set and one otherwise. */
156
+ revolutions: number;
157
+ }
158
+ /** Whether a layer takes a reading on its trajectories (rule `clock-channel-carried`), by the same test as the evaluator. */
159
+ export declare function needsReading(layer: TrajectoriesLayer, clock: Clock): boolean;
160
+ export declare function revealSpec(layer: TrajectoriesLayer, periodic: boolean, revolutions?: number): RevealSpec;
161
+ /**
162
+ * The revealed part of one trajectory at progress `q` (rules `clock-mode`, `before-after`, `revolutions`, `polyline`, `trail-wrap` and `head`). The trajectory clock
163
+ * `tc` is null only for a layer that does not take a reading, which shows every sample of every revolution.
164
+ */
165
+ export declare function revealTrajectory(tc: TrajectoryClock | null, clock: Clock, q: number, spec: RevealSpec, round?: (x: number) => number): Reveal;
166
+ /** The number of stored segments of a set, i.e. its number of samples minus its number of trajectories. */
167
+ export declare function segmentCount(set: SetData): number;
168
+ /** The index of the first segment of trajectory `t`. */
169
+ export declare function firstSegment(set: SetData, t: number): number;
170
+ /** Per-sample values of width `k`, as two vertices per segment. */
171
+ export declare function pairs(set: SetData, values: ArrayLike<number>, k: number): Float32Array;
172
+ /** Per-sample values of width `k` of the `m` samples from `s` on, as two vertices per segment. */
173
+ export declare function slicePairs(values: ArrayLike<number>, k: number, s: number, m: number): Float32Array;
174
+ /** The positions of every segment of a set in revolution `revolution`, as two vertices per segment, joined to the next revolution below the top. */
175
+ export declare function revolutionPairs(g: TrajectoryGeometry, revolution: number): Float32Array;
176
+ /** The positions of the segments of trajectory `t` in revolution `revolution`, as revolutionPairs lays them out. */
177
+ export declare function trajectoryRevolutionPairs(g: TrajectoryGeometry, t: number, revolution: number): Float32Array;
178
+ /** The loop reading of a vertex, which is the reading u_i at a sample or the blended reading at a point, plus its revolution. */
179
+ export declare function vertexReading(tc: TrajectoryClock, v: Vertex): number;
180
+ /** The readings of a segment's two samples, (u_i, u_(i+1)), on both its vertices. */
181
+ export declare function pairReadings(set: SetData, u: Float64Array): Float32Array;
182
+ /** The readings of the `m` samples from `s` on, as pairReadings lays them out. */
183
+ export declare function readingPairs(u: ArrayLike<number>, s: number, m: number): Float32Array;
184
+ /** The trajectory index of every vertex. */
185
+ export declare function pairTrajectories(set: SetData): Float32Array;
186
+ /**
187
+ * A body's position in one display frame in the context of each sample of one reference trajectory,
188
+ * per revolution of rule `revolutions`, as x, y, z per sample. A revolution is filled the first time it is drawn and kept,
189
+ * so that a frame copies a trail instead of evaluating it. When neither the body's position nor an
190
+ * edge into the display frame reads a channel, every revolution has the positions of revolution 0.
191
+ */
192
+ export declare class BodyTrailTable {
193
+ private readonly frames;
194
+ private readonly body;
195
+ private readonly display;
196
+ private readonly set;
197
+ private readonly trajectory;
198
+ readonly m: number;
199
+ readonly invariant: boolean;
200
+ private readonly revolutions;
201
+ constructor(frames: Frames, body: string, display: string, set: SetData, trajectory: number);
202
+ /** The body's positions at every sample of revolution `j`, each in the context of its sample. */
203
+ revolution(j: number): Float64Array;
204
+ /** The position of a vertex (rule `segment`) in its revolution, written at `out[o..o+2]`. */
205
+ vertex(v: Vertex, out: {
206
+ [i: number]: number;
207
+ }, o?: number): void;
208
+ /**
209
+ * The polyline of rules `polyline` and `revolutions` between loop readings `ua <= ub`, with the same vertices as the
210
+ * evaluator's `loopPolyline`, written as x, y, z per vertex from `out[0]`. Returns the vertex
211
+ * count. The samples of a revolution are copied as runs, and only the two ends are blended.
212
+ */
213
+ polyline(tc: TrajectoryClock, ua: number, ub: number, revolutions: number, out: Float32Array): number;
214
+ }
215
+ /** The most vertices a trail of `fraction` of a loop of `revolutions` revolutions over `m` samples can have. */
216
+ export declare function trailCapacity(m: number, revolutions: number, fraction: number): number;
217
+ export {};
@@ -0,0 +1,66 @@
1
+ /**
2
+ * The icons of the viewer's controls, as inline SVG built with createElementNS from path strings, so that
3
+ * the browser neither parses markup nor fetches a file. The icons house, chevron-down, grip-vertical, x,
4
+ * rotate-ccw, undo and redo (here turnLeft and turnRight), plus, and download are taken from Lucide, on its 24 px grid with a 2 px
5
+ * stroke (the dots of grip-vertical are written as paths). The icons play and pause are drawn here on a 16 px grid and filled.
6
+ */
7
+ export declare const GLYPHS: {
8
+ readonly house: {
9
+ readonly grid: 24;
10
+ readonly fill: false;
11
+ readonly d: readonly ["M15 21v-8a1 1 0 0 0-1-1h-4a1 1 0 0 0-1 1v8", "M3 10a2 2 0 0 1 .709-1.528l7-5.999a2 2 0 0 1 2.582 0l7 5.999A2 2 0 0 1 21 10v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"];
12
+ };
13
+ readonly chevronDown: {
14
+ readonly grid: 24;
15
+ readonly fill: false;
16
+ readonly d: readonly ["m6 9 6 6 6-6"];
17
+ };
18
+ readonly grip: {
19
+ readonly grid: 24;
20
+ readonly fill: false;
21
+ readonly d: readonly [string, string];
22
+ };
23
+ readonly x: {
24
+ readonly grid: 24;
25
+ readonly fill: false;
26
+ readonly d: readonly ["M18 6 6 18", "m6 6 12 12"];
27
+ };
28
+ readonly rotateCcw: {
29
+ readonly grid: 24;
30
+ readonly fill: false;
31
+ readonly d: readonly ["M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8", "M3 3v5h5"];
32
+ };
33
+ readonly turnLeft: {
34
+ readonly grid: 24;
35
+ readonly fill: false;
36
+ readonly d: readonly ["M3 7v6h6", "M21 17a9 9 0 0 0-9-9 9 9 0 0 0-6 2.3L3 13"];
37
+ };
38
+ readonly turnRight: {
39
+ readonly grid: 24;
40
+ readonly fill: false;
41
+ readonly d: readonly ["M21 7v6h-6", "M3 17a9 9 0 0 1 9-9 9 9 0 0 1 6 2.3l3 2.7"];
42
+ };
43
+ readonly plus: {
44
+ readonly grid: 24;
45
+ readonly fill: false;
46
+ readonly d: readonly ["M5 12h14", "M12 5v14"];
47
+ };
48
+ readonly download: {
49
+ readonly grid: 24;
50
+ readonly fill: false;
51
+ readonly d: readonly ["M12 15V3", "M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4", "m7 10 5 5 5-5"];
52
+ };
53
+ readonly play: {
54
+ readonly grid: 16;
55
+ readonly fill: true;
56
+ readonly d: readonly ["M5 3.5v9l7.5-4.5z"];
57
+ };
58
+ readonly pause: {
59
+ readonly grid: 16;
60
+ readonly fill: true;
61
+ readonly d: readonly ["M4.5 3H7v10H4.5zM9 3h2.5v10H9z"];
62
+ };
63
+ };
64
+ export type IconName = keyof typeof GLYPHS;
65
+ /** An icon as an `<svg>` that takes the text color. It is hidden from assistive technology, since its button carries the label. */
66
+ export declare function icon(name: IconName, cls?: string): SVGSVGElement;
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Tiling layout: a binary tree of splits whose leaves are panels.
3
+ *
4
+ * A new panel dropped on an edge of an existing panel splits the existing panel along the same
5
+ * edge, and one dropped on its center replaces it. Removing a panel collapses its parent split.
6
+ * The tree is plain JSON, thus it can be stored and put into an export.
7
+ */
8
+ export type SplitDir = 'row' | 'col';
9
+ export type DropZone = 'left' | 'right' | 'top' | 'bottom' | 'centre';
10
+ export type LayoutNode = {
11
+ kind: 'panel';
12
+ id: string;
13
+ } | {
14
+ kind: 'split';
15
+ dir: SplitDir;
16
+ ratio: number;
17
+ a: LayoutNode;
18
+ b: LayoutNode;
19
+ };
20
+ export declare function panelIds(node: LayoutNode | null): string[];
21
+ export declare function hasPanel(node: LayoutNode | null, id: string): boolean;
22
+ /** Returns a new tree with `newId` placed relative to `targetId` in `zone`. */
23
+ export declare function splitAt(node: LayoutNode, targetId: string, newId: string, zone: DropZone): LayoutNode;
24
+ /** Returns the tree without `id`, or null if it was the only panel. */
25
+ export declare function removePanel(node: LayoutNode, id: string): LayoutNode | null;
26
+ export declare function setRatio(node: LayoutNode, split: LayoutNode, ratio: number): LayoutNode;
27
+ /** Panel ids with the area fraction each one occupies, for picking a split target. */
28
+ export declare function panelAreas(node: LayoutNode, area?: number): {
29
+ id: string;
30
+ area: number;
31
+ }[];
32
+ /** The drop zone for a pointer at (x, y) inside a rectangle of size (w, h), i.e. the nearest edge within 28% of the side, or else the center. */
33
+ export declare function zoneFor(x: number, y: number, w: number, h: number): DropZone;
34
+ export declare function isLayoutNode(v: unknown): v is LayoutNode;
@@ -0,0 +1,29 @@
1
+ /**
2
+ * The screen geometry of an inset box layer (rule `inset-box`), i.e. the corners of the target panel's visible rectangle on the host panel, widened to a
3
+ * minimum size, cut into dashes across the visible part of the panel, and laid out as triangles with mitered corners.
4
+ */
5
+ type Vec2 = [number, number];
6
+ /**
7
+ * Corners in the order of a ring, stretched about their center along each screen axis on which they span less than `min` CSS pixels. The corners
8
+ * are those of a parallelogram, which is the image of a rectangle under the affine map from the target frame.
9
+ */
10
+ export declare function widen(corners: [Vec2, Vec2, Vec2, Vec2], min: number): [Vec2, Vec2, Vec2, Vec2];
11
+ /**
12
+ * The polylines of a ring with the given corners in CSS pixels that are drawn on a panel of `w` by `h` pixels. They are one closed polyline when
13
+ * the whole ring is solid and within reach of the panel, and open polylines otherwise. A dash pattern of `dash` [on, off] pixels starts at the
14
+ * first corner and runs along the ring. Only the parts of the ring within a margin of the panel are laid out, hence a ring far larger than the
15
+ * panel is not cut into more dashes than the panel can show.
16
+ */
17
+ export declare function outlinePaths(corners: Vec2[], w: number, h: number, dash?: [number, number]): {
18
+ closed: boolean;
19
+ paths: Vec2[][];
20
+ };
21
+ /** Appends to `out` the triangles, as x, y pairs in CSS pixels, of a line `width` pixels wide along `path`, with mitered joins and butt ends. */
22
+ export declare function strokeTriangles(path: Vec2[], closed: boolean, width: number, out?: number[]): number[];
23
+ /** The triangles, as x, y pairs in CSS pixels, of an outline with the given corners in pixels on a panel of `w` by `h` pixels. */
24
+ export declare function outlineTriangles(corners: [Vec2, Vec2, Vec2, Vec2], w: number, h: number, look: {
25
+ width: number;
26
+ minSize: number;
27
+ dash?: [number, number];
28
+ }): number[];
29
+ export {};
@@ -0,0 +1,33 @@
1
+ /**
2
+ * What a panel shows over its drawing, as data: its text labels and its colorbars. The renderer
3
+ * computes them, the element writes them as DOM, and the video export draws them on a canvas.
4
+ */
5
+ /**
6
+ * A text label over a panel, centered vertically on (x, y) in CSS pixels from the panel's corner.
7
+ * Its start sits at (x, y) by default, and its center or its end with `align` set to 'center' or
8
+ * 'end'. A rotated label reads upward, turned a quarter turn about (x, y).
9
+ */
10
+ export interface PanelLabel {
11
+ text: string;
12
+ x: number;
13
+ y: number;
14
+ align?: 'start' | 'center' | 'end';
15
+ rotate?: boolean;
16
+ /** Marks a tick number of the axes or the grid, or an axis title, and is left undefined for a body label or an axis tip. */
17
+ kind?: 'tick' | 'title';
18
+ }
19
+ /** What a panel's overlay shows for a colormapped layer. */
20
+ export interface Colorbar {
21
+ label: string;
22
+ gradient: string;
23
+ /** The same colors as stops from 0 at the low end to 1 at the high end, for a canvas. */
24
+ stops: [number, string][];
25
+ lo: number;
26
+ hi: number;
27
+ /** Where the highlighted or single member sits on the bar, in [0, 1], for a parameter colormap. */
28
+ marker: number | null;
29
+ /** The part of the bar a highlight's kernel lights, 1.5 kernel widths either side of the marker, in [0, 1]. */
30
+ band: [number, number] | null;
31
+ }
32
+ /** The bars of a panel with the identical ones merged, keeping the first marker and band any of them has. */
33
+ export declare function mergeColorbars(bars: readonly Colorbar[]): Colorbar[];
@@ -0,0 +1,110 @@
1
+ /**
2
+ * The 2D painting of markers, labels, the box of an axes layer, and the overlays. The page
3
+ * paints them onto a canvas over the panel area, and a video export onto each of its frames, with the same functions, so that a frame of a
4
+ * video shows what the page shows. Every text is canvas text, never markup (rule `plain-text`).
5
+ */
6
+ import type { Box, LabelLayer, Marker, Overlay, Readout, Scene, State } from '../scene.js';
7
+ import type { PanelAreaRenderer } from './renderer.js';
8
+ import { type Theme } from './colors.js';
9
+ import type { Rect } from './tiles.js';
10
+ export declare const FONT = "\"Helvetica Neue\", Arial, sans-serif";
11
+ export declare const LABEL_SIZE = 13;
12
+ export declare const TICK_SIZE = 12;
13
+ type G = CanvasRenderingContext2D;
14
+ /** Draws a marker of `shape`, `d` CSS pixels across, centered at (x, y). A ring, a cross, and a plus are stroked in `fill`. */
15
+ export declare function drawMarker(g: G, shape: string, x: number, y: number, d: number, fill: string | null, edge: string | null, edgeWidth: number): void;
16
+ /** The width of the stroke of a marker: its outline, or the line of a ring, a cross, or a plus. */
17
+ export declare function markerStroke(marker: Marker, size: number): number;
18
+ /**
19
+ * A square canvas holding a marker for the texture of a sprite of `size` plus its stroke CSS pixels across, drawn at `scale` texture
20
+ * pixels per CSS pixel. The shape is `size` across, and its stroke is centered on its outline, as matplotlib draws a marker's edge.
21
+ * Without a fill color, the shape is white, so that a sprite's vertex color tints it.
22
+ */
23
+ export declare function markerCanvas(marker: Marker, size: number, scale?: number): HTMLCanvasElement;
24
+ /**
25
+ * The text metrics of matplotlib's layout, in units of the font size, which the labels, the overlays, the legends, and the boxes
26
+ * follow: a line's box is 0.984 tall with its baseline 0.227 above its bottom, and the lines of a text are 1.15 apart.
27
+ */
28
+ export declare const TEXT_HEIGHT = 0.984;
29
+ export declare const TEXT_DESCENT = 0.227;
30
+ export declare const TEXT_ASCENT: number;
31
+ export declare const LINE_PITCH = 1.15;
32
+ export interface TextStyle {
33
+ size: number;
34
+ color: string;
35
+ weight: 'normal' | 'bold';
36
+ font: string;
37
+ align: 'start' | 'center' | 'end';
38
+ /** `alphabetic` puts the baseline of the last line at the anchor, as matplotlib's `va="baseline"` does. */
39
+ baseline: 'top' | 'middle' | 'bottom' | 'alphabetic';
40
+ opacity: number;
41
+ box?: Box;
42
+ /** The spacing of the lines, as matplotlib's `linespacing`, 1.2 by default. */
43
+ linespacing?: number;
44
+ }
45
+ /**
46
+ * The distance between the baselines of two lines of a text, in units of its size. Matplotlib puts each line's baseline its
47
+ * ascent times `linespacing` below the descent of the line before, hence the default pitch grows by the ascent per unit.
48
+ */
49
+ export declare function linePitch(linespacing?: number): number;
50
+ /** A run of a text, set lowered and smaller as a subscript, raised and smaller as a superscript, or on the baseline (rule `timeline-parts`). */
51
+ export interface TextRun {
52
+ text: string;
53
+ shift?: 'sub' | 'sup';
54
+ }
55
+ /** The plain text of a text of runs. */
56
+ export declare const plainText: (text: string | TextRun[]) => string;
57
+ /** The rectangle a text of possibly several lines covers when drawn at (x, y) in `style`, as [left, top, width, height]. */
58
+ export declare function textRect(g: G, text: string | TextRun[], x: number, y: number, style: TextStyle): [number, number, number, number];
59
+ /** Draws a text of possibly several lines at (x, y), aligned by `style`, on its box when it has one. */
60
+ export declare function drawText(g: G, text: string | TextRun[], x: number, y: number, style: TextStyle): void;
61
+ /** The style of a label or a text overlay at time `s` of the timeline. */
62
+ export declare function styleOf(spec: Pick<LabelLayer, 'size' | 'color' | 'weight' | 'align' | 'baseline' | 'opacity' | 'box' | 'linespacing'>, theme: Theme, s: number): TextStyle;
63
+ /**
64
+ * Draws a label (rule `label`) whose anchor lies at (ax, ay), with its text `offset` pixels away and the leader between them. The leader
65
+ * runs from the anchor to the nearest point of the text's rectangle, and stops 3 pixels short of it.
66
+ */
67
+ export declare function drawLabel(g: G, layer: LabelLayer, text: string | TextRun[], ax: number, ay: number, theme: Theme, s: number): void;
68
+ /** Ticks across [lo, hi] at the smallest round step of at least (hi - lo) / bins, as matplotlib's MaxNLocator picks them. */
69
+ export declare function boxTicks(lo: number, hi: number, bins: number): {
70
+ values: number[];
71
+ step: number;
72
+ };
73
+ /** A tick number with the decimals its step needs, and a true minus. */
74
+ export declare function tickLabel(v: number, step: number): string;
75
+ export interface BoxPaint {
76
+ /** The part of the panel the camera draws, in pixels of the panel area. */
77
+ rect: Rect;
78
+ /** The visible window along the camera's right and up axes. */
79
+ x0: number;
80
+ x1: number;
81
+ y0: number;
82
+ y1: number;
83
+ /** The axes that carry tick numbers. */
84
+ ticks: {
85
+ x: boolean;
86
+ y: boolean;
87
+ };
88
+ size: number;
89
+ /** The axis titles, the frame's or the axes layer's own, as text or as runs with subscripts. */
90
+ titles: [string | TextRun[], string | TextRun[]];
91
+ opacity: number;
92
+ }
93
+ /** Draws the box of an axes layer with `"span": "box"` around its rectangle, with ticks pointing out, tick numbers, and the axis titles. */
94
+ export declare function drawBox(g: G, b: BoxPaint, theme: Theme): void;
95
+ /** Draws a legend overlay on a panel area of `w` by `h` pixels. */
96
+ export declare function drawLegend(g: G, legend: Extract<Overlay, {
97
+ kind: 'legend';
98
+ }>, w: number, h: number, theme: Theme, s: number): void;
99
+ /** Covers a panel with the background at `1 - opacity`, which fades it as a whole. */
100
+ export declare function coverPanel(g: G, r: Rect, opacity: number, theme: Theme): void;
101
+ /** The gutter color of a video, the theme's or a blend of its foreground and background. */
102
+ export declare const gutterColor: (theme: Theme) => string;
103
+ /**
104
+ * Paints, for every panel of `state`, the cover of its opacity, the box of its axes layer, and its labels, and then the
105
+ * overlays of the scene, onto `g`, a 2D context in pixels of the panel area. `text` gives the text of a list of parts in a panel.
106
+ */
107
+ export declare function paintPanelArea(g: CanvasRenderingContext2D, renderer: PanelAreaRenderer, scene: Scene, state: State, theme: Theme, q: number, w: number, h: number, text: (pid: string, parts: Readout['parts']) => string[]): void;
108
+ /** The runs of a text from its parts and the text of each part, a `sub` or a `sup` part set as a script (rule `timeline-parts`). */
109
+ export declare function runsOf(parts: Readout['parts'], pieces: string[]): TextRun[];
110
+ export {};
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Paints a laid-out element tree onto a 2D canvas, for a video frame that shows what the page shows. The browser lays the tree out,
3
+ * and `rasterize` draws every box, text run, and canvas where the layout put it, in the colors, fonts, and shadows of its computed
4
+ * style. The painter covers the CSS that the viewer uses over its panel area: background colors and linear gradients, solid borders (also
5
+ * a triangle made of borders), box and text shadows, opacity, overflow clipping, 2D transforms, absolutely positioned `::before` and
6
+ * `::after` boxes without text, and canvases. Boxes are painted in tree order, which is the order of their z-index in the viewer.
7
+ * Visibility is not read, since the tree is hidden while it is painted.
8
+ */
9
+ type G = CanvasRenderingContext2D;
10
+ interface Shadow {
11
+ color: string;
12
+ x: number;
13
+ y: number;
14
+ blur: number;
15
+ spread: number;
16
+ inset: boolean;
17
+ }
18
+ /** The shadows of a computed `text-shadow` or `box-shadow`, whose color Chrome writes first. Exported for the tests. */
19
+ export declare function parseShadows(s: string): Shadow[];
20
+ /**
21
+ * The direction and the stops of a computed `linear-gradient(...)`, or null for any other image. The direction is a unit vector in
22
+ * CSS pixels with y down, and each stop is a position in [0, 1] and a color. Exported for the tests.
23
+ */
24
+ export declare function parseGradient(s: string): {
25
+ dir: [number, number];
26
+ stops: [number, string][];
27
+ } | null;
28
+ /**
29
+ * Paints `root` and its descendants, inside its open shadow root too, onto `g`. The transform of `g` maps the CSS pixels of the
30
+ * root, from its top left corner, to the canvas.
31
+ */
32
+ export declare function rasterize(g: G, root: HTMLElement): void;
33
+ export {};