@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,45 +1,45 @@
1
1
  export type Dtype = 'int8' | 'uint8' | 'int16' | 'uint16' | 'int32' | 'uint32' | 'float32' | 'float64';
2
2
  export type TypedArray = Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array;
3
- /** One named array, with its elements flat in C order (rule D4), its shape, and its dtype. */
4
- export interface ArrayView {
3
+ /** One named array, with its elements flat in C order (rule `c-order`), its shape, and its dtype. */
4
+ export interface DataArray {
5
5
  readonly name: string;
6
6
  readonly dtype: Dtype;
7
7
  readonly shape: readonly number[];
8
8
  readonly data: TypedArray;
9
9
  }
10
- /** The interface through which the evaluator reads arrays. `view` throws for a name that is missing. */
10
+ /** The interface through which the evaluator reads arrays. `array` throws for a name that is missing. */
11
11
  export interface DataStore {
12
12
  has(name: string): boolean;
13
- view(name: string): ArrayView;
13
+ array(name: string): DataArray;
14
14
  }
15
- /** A view stored as its little-endian bytes in C order, at `offset` in the payload. */
16
- export interface RawViewInfo {
15
+ /** An array stored as its little-endian bytes in C order, at `offset` in the payload. */
16
+ export interface RawArrayInfo {
17
17
  dtype: Dtype;
18
18
  shape: number[];
19
19
  encoding: 'raw';
20
20
  offset: number;
21
21
  length: number;
22
22
  }
23
- /** A view stored in chunks of `chunk_rows` rows, each an `[offset, length]` in the payload (rule D5). */
24
- export interface EncodedViewInfo {
23
+ /** An array stored in chunks of `chunk_rows` rows, each an `[offset, length]` in the payload (rule `shuffle-delta-deflate`). */
24
+ export interface EncodedArrayInfo {
25
25
  dtype: Dtype;
26
26
  shape: number[];
27
27
  encoding: 'shuffle-delta-deflate';
28
28
  chunk_rows: number;
29
29
  chunks: [number, number][];
30
30
  }
31
- export type ViewInfo = RawViewInfo | EncodedViewInfo;
31
+ export type ArrayInfo = RawArrayInfo | EncodedArrayInfo;
32
32
  export interface DataHeader {
33
33
  format: 'tycho-data';
34
- version: 1;
34
+ version: 2;
35
35
  generator?: string;
36
36
  meta?: Record<string, unknown>;
37
- views: Record<string, ViewInfo>;
37
+ arrays: Record<string, ArrayInfo>;
38
38
  }
39
- export declare const DATA_VERSION = 1;
39
+ export declare const DATA_VERSION = 2;
40
40
  export declare function isDtype(s: unknown): s is Dtype;
41
41
  export declare function itemSize(dtype: Dtype): number;
42
- /** A parsed data.tyd. Raw views are built once, on first access, and encoded views by `parse`. */
42
+ /** A parsed data.tyd. Raw arrays are built once, on first access, and encoded arrays by `parse`. */
43
43
  export declare class Container implements DataStore {
44
44
  readonly header: DataHeader;
45
45
  private readonly bytes;
@@ -47,13 +47,13 @@ export declare class Container implements DataStore {
47
47
  private readonly cache;
48
48
  private constructor();
49
49
  /**
50
- * Parses a data container, checks rules D1 to D3 and D5 for every view, and decodes every encoded
51
- * view. The decoding rejects a chunk that does not inflate to the byte length of its rows (rule D5).
50
+ * Parses a data container, checks rules `array-dtype`, `array-keys`, `container-version`, and
51
+ * `shuffle-delta-deflate` for every array, and decodes every encoded array. The decoding rejects a chunk that does not inflate to the byte length of its rows (rule `shuffle-delta-deflate`).
52
52
  */
53
53
  static parse(input: ArrayBufferLike | ArrayBufferView): Promise<Container>;
54
54
  has(name: string): boolean;
55
55
  names(): string[];
56
- view(name: string): ArrayView;
56
+ array(name: string): DataArray;
57
57
  }
58
58
  /** Decodes base64 text, ignoring whitespace. */
59
59
  export declare function base64ToBytes(text: string): Uint8Array<ArrayBuffer>;
@@ -1,7 +1,6 @@
1
1
  /**
2
- * The one error type a reader throws. `rule` is the rule of spec/tycho-scene.md that the
3
- * input breaks (`D2`, `F5`, ...), or the section number for a requirement stated without a
4
- * rule number (`2.3`).
2
+ * The one error type a reader throws. `rule` is the name of the rule of spec/tycho-scene.md that the
3
+ * input breaks, such as `array-keys`, `transform-channels`, or the section-level rule `frame`.
5
4
  */
6
5
  export declare class TychoError extends Error {
7
6
  readonly rule: string;
@@ -1,30 +1,36 @@
1
- import { type Clock } from '../scene.js';
1
+ import { type Clock, type LayerClock } from '../scene.js';
2
2
  import type { SetData } from './sets.js';
3
- /** Progress q in [0, 1) for a frame index, taken modulo `steps` (section 2.6). */
4
- export declare function progress(steps: number, frameIndex: number): number;
5
- /** The clock along one track, which holds the sample readings u_i of rule C1 and gives the reading of rule C2. */
6
- export declare class TrackClock {
3
+ /** Progress q in [0, 1) for a frame index, taken modulo the frame count (section 2.6). */
4
+ export declare function progress(frameCount: number, frameIndex: number): number;
5
+ /** The clock along one trajectory, which holds the sample readings u_i of rule `sample-fraction` and gives the reading of rule `clock-mode`. */
6
+ export declare class TrajectoryClock {
7
7
  readonly m: number;
8
8
  private readonly c0;
9
9
  private readonly c1;
10
10
  private readonly u;
11
- constructor(set: SetData, track: number, channel: string);
12
- /** The reading u_i at which sample `i` sits along the track (rule C1). */
11
+ constructor(set: SetData, trajectory: number, channel: string);
12
+ /** The reading u_i at which sample `i` sits along the trajectory (rule `sample-fraction`). */
13
13
  at(i: number): number;
14
- /** The track's reading at progress q (rule C2), possibly outside [0, 1] in value mode. */
14
+ /** The trajectory's reading at progress q (rule `clock-mode`), possibly outside [0, 1] in epoch mode. */
15
15
  reading(clock: Clock, q: number): number;
16
- /** The segment k and weight w of the point at reading u in [0, 1] (rule C4). */
16
+ /** The segment k and weight w of the point at reading u in [0, 1] (rule `segment`). */
17
17
  locate(u: number): {
18
18
  k: number;
19
19
  w: number;
20
20
  };
21
21
  }
22
- /** The number of laps of rule C6, 1 when absent. Only a clock in fraction mode has laps. */
23
- export declare function clockLaps(clock: Clock): number;
24
- /** The lap of a loop reading and the within-lap reading there (rule C6). */
25
- export declare function lapOf(loopReading: number, laps: number): {
26
- lap: number;
22
+ /** The number of revolutions of rule `revolutions`, 1 when absent. Only a clock in fraction mode has revolutions. */
23
+ export declare function clockRevolutions(clock: Clock): number;
24
+ /** The revolution of a loop reading and the within-revolution reading there (rule `revolutions`). */
25
+ export declare function revolutionOf(loopReading: number, revolutions: number): {
26
+ revolution: number;
27
27
  u: number;
28
28
  };
29
- /** Applies `before` and `after` (rule C3) to a reading. Null means the track is hidden. */
29
+ /** Applies `before` and `after` (rule `before-after`) to a reading. Null means the trajectory is hidden. */
30
30
  export declare function bound(u: number, before?: 'clamp' | 'hidden', after?: 'clamp' | 'hidden'): number | null;
31
+ /**
32
+ * The clock of a layer with a clock of its own (rule `layer-clock`), as a clock in epoch mode on the layer's channel, whose loop lasts as
33
+ * long as the scene's, so that its keyframes read the same timeline. It does not have revolutions. The clock is checked and built once
34
+ * and returned again while the scene's clock keeps its frame count and its loop length, hence a caller must not change it.
35
+ */
36
+ export declare function layerClock(scene: Clock, own: LayerClock): Clock;
@@ -3,12 +3,12 @@ import type { SetData } from './sets.js';
3
3
  import type { Vec3 } from './types.js';
4
4
  export interface Context {
5
5
  set: SetData;
6
- track: number;
6
+ trajectory: number;
7
7
  sample: number;
8
- /** One lap lower than `lap` (rule L2). */
8
+ /** One revolution lower than `revolution` (rule `trail-wrap`). */
9
9
  shifted: boolean;
10
- /** The lap of rule C6, 0 when absent. */
11
- lap?: number;
10
+ /** The revolution of rule `revolutions`, 0 when absent. */
11
+ revolution?: number;
12
12
  }
13
13
  /** The value of a number, an attribute, or a channel in a context (section 2.2). */
14
14
  export declare function scalarValue(s: Scalar | ConstantScalar, ctx: Context): number;
@@ -24,7 +24,7 @@ export declare class FrameTree {
24
24
  /** True when `id` is `ancestor` or below it. */
25
25
  inSubtree(id: string, ancestor: string): boolean;
26
26
  /**
27
- * The edges from `a` to `b` (rule F3), each identified by its child frame. The edges in `up` are in the
27
+ * The edges from `a` to `b` (rule `frame-path`), each identified by its child frame. The edges in `up` are in the
28
28
  * order taken inversely from `a`, and those in `down` in the order taken forward toward `b`.
29
29
  */
30
30
  path(a: string, b: string): {
@@ -45,18 +45,18 @@ export declare class Frames {
45
45
  constructor(scene: Scene);
46
46
  private body;
47
47
  private edgeOf;
48
- /** Takes `p` from frame `from` to frame `to` in one context (rule F3). */
48
+ /** Takes `p` from frame `from` to frame `to` in one context (rule `frame-path`). */
49
49
  transform(p: Vec3, from: string, to: string, ctx: Context): Vec3;
50
- /** A body's position in `frame` (section 2.4), with its attributes read from the context's track set. */
50
+ /** A body's position in `frame` (section 2.4), with its attributes read from the context's trajectory set. */
51
51
  bodyPosition(bodyId: string, frame: string, ctx: Context): Vec3;
52
52
  /**
53
- * Applies the edge from `child`'s parent to `child` (rule F1), or its inverse. Only an origin at
54
- * a body evaluates further edges, hence only there can an edge meet itself (rule F6).
53
+ * Applies the edge from `child`'s parent to `child` (rule `transform`), or its inverse. Only an origin at
54
+ * a body evaluates further edges, hence only there can an edge meet itself (rule `body-origin-cycle`).
55
55
  */
56
56
  private edge;
57
57
  /**
58
- * The channels and attributes a context's track set must carry to take a position from `from`
59
- * to `to` (rule F5), through body origins too. It fails with rule F6 on an origin that depends on itself.
58
+ * The channels and attributes a context's trajectory set must carry to take a position from `from`
59
+ * to `to` (rule `transform-channels`), through body origins too. It fails with rule `body-origin-cycle` on an origin that depends on itself.
60
60
  */
61
61
  requirements(from: string, to: string, req?: Requirements): Requirements;
62
62
  bodyRequirements(bodyId: string, frame: string, req?: Requirements): Requirements;
@@ -4,11 +4,18 @@
4
4
  * for a scene it cannot evaluate. It does not run every check of validate().
5
5
  */
6
6
  import type { DataStore } from '../container.js';
7
- import type { Scene, State } from '../scene.js';
8
- import type { EvaluateResult } from './types.js';
7
+ import type { Panel, Scene, State } from '../scene.js';
8
+ import { type Reference, type LayerEnv } from './layers.js';
9
+ import { SetCache } from './sets.js';
10
+ import type { CameraResult, EvaluateResult } from './types.js';
9
11
  export type * from './types.js';
10
12
  /**
11
13
  * Evaluates `state` at frame index `frameIndex` and returns, for every panel, the display frame and one entry per layer,
12
14
  * the same answer as pytycho.evaluate. It throws a TychoError that gives the broken rule.
13
15
  */
14
16
  export declare function evaluate(scene: Scene, data: DataStore, state: State, frameIndex: number): EvaluateResult;
17
+ /**
18
+ * The window of a 2d camera with keyframes at the environment's progress (rule `camera-keyframes`). A follow key's center is the mean of its targets'
19
+ * points, projected onto the plane, plus its offset, and its `center` when every target's set query fails to match.
20
+ */
21
+ export declare function cameraAt(env: LayerEnv, panel: Panel, sets: SetCache, reference: Reference): CameraResult | null;
@@ -1,36 +1,37 @@
1
- import type { BodyLayer, Clock, TrackLayer } from '../scene.js';
2
- import { TrackClock } from './clock.js';
3
- import type { Context, Frames } from './frames.js';
1
+ import { type ArrowLayer, type BodyLayer, type Clock, type LabelLayer, type InsetBoxLayer, type PointsLayer, type TrajectoriesLayer } from '../scene.js';
2
+ import { TrajectoryClock } from './clock.js';
3
+ import { type Context, type Frames } from './frames.js';
4
4
  import type { PanelScope } from './resolve.js';
5
5
  import type { SetData } from './sets.js';
6
- import type { BodyLayerResult, TrackLayerResult, Vec3 } from './types.js';
6
+ import type { ArrowLayerResult, BodyLayerResult, LabelLayerResult, InsetBoxLayerResult, PointsLayerResult, TrajectoriesLayerResult, Vec3 } from './types.js';
7
7
  /**
8
8
  * A vertex is a stored sample or a point blended between samples k and k + 1, in the context of
9
- * its lap of rule C6 (0 when absent). `shifted` puts it one lap lower (rule L2).
9
+ * its revolution of rule `revolutions` (0 when absent). `shifted` puts it one revolution lower (rule `trail-wrap`).
10
10
  */
11
11
  export type Vertex = {
12
12
  sample: number;
13
13
  shifted: boolean;
14
- lap?: number;
15
- } | {
14
+ revolution?: number;
15
+ } | BlendVertex;
16
+ export type BlendVertex = {
16
17
  k: number;
17
18
  w: number;
18
19
  shifted: boolean;
19
- lap?: number;
20
+ revolution?: number;
20
21
  };
21
- export declare function point(tc: TrackClock, u: number, shifted: boolean, lap?: number): Vertex;
22
- /** The polyline of a track between readings `ua` and `ub` within one lap (rule L1). */
23
- export declare function polyline(tc: TrackClock, ua: number, ub: number, lap?: number): Vertex[];
24
- /** The polyline between loop readings `ua <= ub` across laps (rule C6). Each joint keeps the first sample of the higher lap. */
25
- export declare function loopPolyline(tc: TrackClock, ua: number, ub: number, laps: number): Vertex[];
26
- /** Every sample of every lap, joined (rule C6). A track set that is not periodic has one lap. */
27
- export declare function whole(m: number, laps: number, periodic: boolean): Vertex[];
28
- /** The trail from loop reading `loopReading - laps * fraction` to `loopReading`, cut at 0 unless the track set is periodic (rules L2 and C6). */
29
- export declare function trail(tc: TrackClock, loopReading: number, laps: number, fraction: number, periodic: boolean): Vertex[];
30
- /** Whether a track layer gives a head (rule L3), i.e. whether its `head` is `true` or an object. */
31
- export declare function hasHead(layer: TrackLayer): boolean;
32
- /** Evaluates a vertex with `f`, which gives the position of a sample in a context (rule C4). */
33
- export declare function vertexPosition(v: Vertex, set: SetData, track: number, f: (ctx: Context) => Vec3): Vec3;
22
+ export declare function point(tc: TrajectoryClock, u: number, shifted: boolean, revolution?: number): BlendVertex;
23
+ /** The polyline of a trajectory between readings `ua` and `ub` within one revolution (rule `polyline`). */
24
+ export declare function polyline(tc: TrajectoryClock, ua: number, ub: number, revolution?: number): Vertex[];
25
+ /** The polyline between loop readings `ua <= ub` across revolutions (rule `revolutions`). Each joint keeps the first sample of the higher revolution. */
26
+ export declare function loopPolyline(tc: TrajectoryClock, ua: number, ub: number, revolutions: number): Vertex[];
27
+ /** Every sample of every revolution, joined (rule `revolutions`). A trajectory set that is not periodic has one revolution. */
28
+ export declare function whole(m: number, revolutions: number, periodic: boolean): Vertex[];
29
+ /** The trail from loop reading `loopReading - revolutions * fraction` to `loopReading`, cut at 0 unless the trajectory set is periodic (rules `trail-wrap` and `revolutions`). */
30
+ export declare function trail(tc: TrajectoryClock, loopReading: number, revolutions: number, fraction: number, periodic: boolean): Vertex[];
31
+ /** Whether a trajectories layer gives a head (rule `head`), i.e. whether its `head` is `true` or an object. */
32
+ export declare function hasHead(layer: TrajectoriesLayer): boolean;
33
+ /** Evaluates a vertex with `f`, which gives the position of a sample in a context (rule `segment`). */
34
+ export declare function vertexPosition(v: Vertex, set: SetData, trajectory: number, f: (ctx: Context) => Vec3): Vec3;
34
35
  export interface LayerEnv {
35
36
  scope: PanelScope;
36
37
  frames: Frames;
@@ -38,10 +39,70 @@ export interface LayerEnv {
38
39
  channel: string;
39
40
  q: number;
40
41
  display: string;
42
+ /** The environment of the scene's clock, for a layer with a clock of its own (rule `layer-clock`), whose reference still reads the scene's clock. */
43
+ base?: LayerEnv;
41
44
  }
42
- export declare function trackLayer(env: LayerEnv, layer: TrackLayer, set: SetData | null): TrackLayerResult;
43
- /** The position and trail of a body layer (rule L4). The driver's reading is clamped to [0, 1], since a body layer does not have `before` or `after`. */
44
- export declare function bodyLayer(env: LayerEnv, layer: BodyLayer, driver: {
45
+ /** The environment in which a layer takes its readings: the scene's, or one on the layer's own clock (rule `layer-clock`). */
46
+ export declare function layerEnv(env: LayerEnv, layer: {
47
+ clock?: TrajectoriesLayer['clock'];
48
+ }): LayerEnv;
49
+ /** The reference's trajectory, as a panel resolves it, or null when its set query does not match any set. */
50
+ export type Reference = {
45
51
  set: SetData;
46
- track: number;
47
- } | null): BodyLayerResult;
52
+ trajectory: number;
53
+ } | null;
54
+ /**
55
+ * The reference's clock and loop reading, and the point at the reading in its revolution. A body layer and a layer that reads from the reference lack `before` and `after`,
56
+ * thus the reading is clamped (rules `body-layer` and `read-from`). A caller that keeps the reference trajectory's clock on `env.channel` passes it as `tc`, which is otherwise built here.
57
+ */
58
+ export declare function referencePoint(env: LayerEnv, reference: NonNullable<Reference>, tc?: TrajectoryClock): {
59
+ tc: TrajectoryClock;
60
+ loopReading: number;
61
+ at: BlendVertex;
62
+ };
63
+ /** The contexts of the reference trajectory's samples k and k + 1 at its point `at`, and the weight that blends them (rules `body-layer` and `read-from`). */
64
+ export declare function referenceContexts(reference: NonNullable<Reference>, at: BlendVertex): {
65
+ a: Context;
66
+ b: Context;
67
+ w: number;
68
+ };
69
+ export declare function trajectoriesLayer(env: LayerEnv, layer: TrajectoriesLayer, set: SetData | null, reference?: Reference): TrajectoriesLayerResult;
70
+ /** Checks the keys of an arrow layer that rule `arrow` restricts, and returns its vector channels and its scale. */
71
+ export declare function arrowParts(layer: ArrowLayer): {
72
+ vector: string[];
73
+ scale: ArrowLayer['scale'] & {};
74
+ };
75
+ /**
76
+ * The base and the tip of each member's arrow at the reading (rule `arrow`). A caller that keeps the clocks of the set's trajectories on `env.channel` passes them as
77
+ * `clocks`, which are otherwise built here.
78
+ */
79
+ export declare function arrowLayer(env: LayerEnv, layer: ArrowLayer, set: SetData | null, clocks?: (t: number) => TrajectoryClock): ArrowLayerResult;
80
+ /**
81
+ * Checks that the panel of an inset_box layer is declared, is not the declared panel `host` that holds the layer, and has a 2d camera
82
+ * (rule `inset-box`).
83
+ */
84
+ export declare function checkInsetBoxPanel(scene: {
85
+ panels: Record<string, {
86
+ camera?: {
87
+ kind: string;
88
+ };
89
+ } | undefined>;
90
+ }, host: string, layer: InsetBoxLayer): void;
91
+ /**
92
+ * The target panel and frame of an inset_box layer, and the affine map from the target frame into the display frame at the reading of
93
+ * the reference trajectory (rule `inset-box`).
94
+ */
95
+ export declare function insetBoxLayer(env: LayerEnv, layer: InsetBoxLayer, reference: Reference): InsetBoxLayerResult;
96
+ /** The position and trail of a body layer (rule `body-layer`). The reference's reading is clamped to [0, 1], since a body layer does not have `before` or `after`. */
97
+ export declare function bodyLayer(env: LayerEnv, layer: BodyLayer, reference: Reference): BodyLayerResult;
98
+ /**
99
+ * The point at the reading of member `k` of a set, clamped to [0, 1] as for a body (rule `body-layer`), in its revolution of rule `revolutions`, under the clock
100
+ * of `env`, transformed by `f`. This is the anchor of a label at a member (rule `label`) and the target of a camera keyframe (rule `camera-keyframes`).
101
+ */
102
+ export declare function memberPoint(env: LayerEnv, set: SetData, k: number, f: (ctx: Context) => Vec3): Vec3;
103
+ /** The target of a camera keyframe (rule `camera-keyframes`): the point at the reading of member `k` of a trajectories layer, in the layer's context, or null when its set query does not match any set. */
104
+ export declare function targetPoint(env: LayerEnv, layer: TrajectoriesLayer, set: SetData | null, k: number, reference: Reference): Vec3 | null;
105
+ /** The position of a label's anchor (rule `label`), or null on the screen or when the anchor does not resolve. */
106
+ export declare function labelLayer(env: LayerEnv, layer: LabelLayer, set: SetData | null, reference: Reference): LabelLayerResult;
107
+ /** The drawn samples of each member of a points layer (rule `points`). */
108
+ export declare function pointsLayer(env: LayerEnv, layer: PointsLayer, set: SetData | null): PointsLayerResult;
@@ -1,39 +1,50 @@
1
- import type { Layer, Layout, MemberRef, PanelState, Scene, SetQuery, State, StringValue, VarRef, Variable, VariableValue, View } from '../scene.js';
1
+ import type { Layer, Layout, MemberRef, ShownPanel, Scene, Panel, SetQuery, State, StringValue, InputRef, Input, InputValue } from '../scene.js';
2
2
  import type { SetData } from './sets.js';
3
3
  /** One panel of one state, where a value is read. */
4
4
  export interface PanelScope {
5
5
  scene: Scene;
6
6
  state: State;
7
- panel: PanelState;
7
+ panel: ShownPanel;
8
8
  }
9
- /** The definition of variable `id`, looked up by own property only, so that an id like "constructor" is not declared. */
10
- export declare function variableDef(scene: Scene, id: string): Variable | undefined;
11
- /** The value of variable `id` in a panel (rule V1). A panel-scoped variable takes the panel's value, and any other variable the scene's. */
12
- export declare function variableValue(scope: PanelScope, id: string): VariableValue;
13
- /** Whether a value fits its variable's kind (section 2.5). */
14
- export declare function fits(v: Variable, value: unknown): boolean;
9
+ /** The definition of input `id`, looked up by own property only, so that an id like "constructor" is not declared. */
10
+ export declare function inputDef(scene: Scene, id: string): Input | undefined;
11
+ /** The value of input `id` in a panel (rule `input-scope`). A per-panel input takes the panel's value, and any other input the scene's. */
12
+ export declare function inputValue(scope: PanelScope, id: string): InputValue;
13
+ /** Whether a value fits its input's kind (section 2.5). */
14
+ export declare function fits(v: Input, value: unknown): boolean;
15
15
  /**
16
- * Checks that a state is valid as section 2.8 defines it. Every panel shows a declared view, the layout
16
+ * Checks that a state is valid as section 2.8 defines it. Every shown panel names a declared panel, the layout
17
17
  * shows every panel once and does not repeat any, the clock channel is one of the scene's, and every
18
- * value fits its variable. Undeclared variable ids are ignored.
18
+ * value fits its input. Undeclared input ids are ignored.
19
19
  */
20
20
  export declare function checkState(scene: Scene, state: State): void;
21
21
  export declare function layoutIds(node: Layout, out?: string[]): string[];
22
- export declare function stringValue(scope: PanelScope, s: StringValue): VariableValue;
23
- /** Every track set a query matches, in the order of `track_sets` (rule V2). */
22
+ export declare function stringValue(scope: PanelScope, s: StringValue): InputValue;
23
+ /** Every trajectory set a query matches, in the order of `trajectory_sets` (rule `set-query`). */
24
24
  export declare function querySets(scope: PanelScope, q: SetQuery): string[];
25
- /** The one track set that the query of a layer or a driver matches (rule V2), null when the query does not match any and an error when it matches several. */
25
+ /** The one trajectory set that the query of a layer or a reference matches (rule `set-query`), null when the query does not match any and an error when it matches several. */
26
26
  export declare function oneSet(scope: PanelScope, q: SetQuery): string | null;
27
- /** The track a selector picks in the track set where the member reference or highlight that refers to the selector is resolved (section 2.5). */
28
- export declare function selectorTrack(scope: PanelScope, ref: VarRef, set: SetData): number;
29
- /** The tracks of `{"count": n}` (rule V3), i.e. every `step`-th track from 0, and the last track. */
30
- export declare function sparse(tracks: number, n: number): number[];
31
- /** The tracks that a member reference selects in a track set (rule V3), i.e. all of them, one by index, an evenly spaced subset, or a selector's track. */
27
+ /**
28
+ * The member that an input of kind parameter picks in the trajectory set where the member reference or highlight that refers
29
+ * to the input is resolved, i.e. the member whose value of the parameter is nearest, the lowest index on a tie (section 2.5).
30
+ */
31
+ export declare function parameterMember(scope: PanelScope, ref: InputRef, set: SetData): number;
32
+ /** The members of `{"evenly_spaced": n}` (rule `members`), i.e. every `step`-th trajectory from 0, and the last trajectory. */
33
+ export declare function sparse(trajectories: number, n: number): number[];
34
+ /** The trajectories that a member reference selects in a trajectory set (rule `members`), i.e. all of them, one by index, an evenly spaced subset, or the member of an input of kind parameter. */
32
35
  export declare function members(scope: PanelScope, ref: MemberRef, set: SetData): number[];
33
- export declare function driverMember(scope: PanelScope, ref: {
36
+ export declare function referenceMember(scope: PanelScope, ref: {
34
37
  index: number;
35
- } | VarRef, set: SetData): number;
36
- /** The display frame of a view in a panel (section 2.7). */
37
- export declare function displayFrame(scope: PanelScope, view: View): string;
38
- /** Whether a layer is drawn, i.e. false while its `visible` toggle is off (rule L5). */
38
+ } | InputRef, set: SetData): number;
39
+ /**
40
+ * The target of an inset_box layer, i.e. the first shown panel in layout order that names declared panel `panelId`, and its display
41
+ * frame read with its own values of the inputs (rule `inset-box`), or null when the layout does not show the declared panel.
42
+ */
43
+ export declare function insetBoxTarget(scope: PanelScope, panelId: string): {
44
+ shown: string;
45
+ frame: string;
46
+ } | null;
47
+ /** The display frame of a declared panel where it is shown (section 2.7). */
48
+ export declare function displayFrame(scope: PanelScope, panel: Panel): string;
49
+ /** Whether a layer is drawn, i.e. false while its `visible` toggle is off (rule `visible`). */
39
50
  export declare function layerVisible(scope: PanelScope, layer: Layer): boolean;
@@ -1,15 +1,15 @@
1
1
  /**
2
- * Read access to one track set's arrays (spec section 2.1), checked against the shapes given in
2
+ * Read access to one trajectory set's arrays (spec section 2.1), checked against the shapes given in
3
3
  * the same section. Every value is returned as a float64 number, whatever the stored dtype.
4
4
  */
5
5
  import type { DataStore, TypedArray } from '../container.js';
6
- import { type Scene, type TrackSet } from '../scene.js';
6
+ import { type Scene, type TrajectorySet } from '../scene.js';
7
7
  import type { Vec3 } from './types.js';
8
8
  export declare class SetData {
9
9
  readonly id: string;
10
- readonly def: TrackSet;
11
- readonly tracks: number;
12
- /** The number S of samples over all tracks. */
10
+ readonly def: TrajectorySet;
11
+ readonly trajectories: number;
12
+ /** The number S of samples over all trajectories. */
13
13
  readonly samples: number;
14
14
  readonly dim: 2 | 3;
15
15
  private readonly data;
@@ -17,29 +17,30 @@ export declare class SetData {
17
17
  private readonly positions;
18
18
  private readonly channels;
19
19
  private readonly parameters;
20
- constructor(id: string, def: TrackSet, data: DataStore);
20
+ constructor(id: string, def: TrajectorySet, data: DataStore);
21
21
  get periodic(): boolean;
22
- /** Index of the first sample of track `t` in the concatenated arrays. */
22
+ /** Index of the first sample of trajectory `t` in the concatenated arrays. */
23
23
  start(t: number): number;
24
- /** The number m of samples of track `t`. */
24
+ /** The number m of samples of trajectory `t`. */
25
25
  count(t: number): number;
26
- /** Sample `i` of track `t`, in the track set's frame. A two-component position has z = 0. */
26
+ /** Sample `i` of trajectory `t`, in the trajectory set's frame. A two-component position has z = 0. */
27
27
  position(t: number, i: number): Vec3;
28
28
  hasChannel(name: string): boolean;
29
29
  /** The stored values of a channel, of shape (S,). `@index` does not have stored values. */
30
30
  channel(name: string, rule?: string): TypedArray;
31
31
  /**
32
- * The value of a channel at sample `i` of track `t` (rule T4 for `@index`), raised by the
33
- * channel's advance over the track once per lap (rules T2 and C6). A shifted context is one
34
- * lap lower (rule L2).
32
+ * The value of a channel at sample `i` of trajectory `t` (rule `index-channel` for `@index`), raised by the
33
+ * channel's advance over the trajectory once per revolution (rules `periodic` and `revolutions`). A shifted context is one
34
+ * revolution lower (rule `trail-wrap`).
35
35
  */
36
- channelAt(name: string, t: number, i: number, shifted: boolean, lap?: number): number;
37
- /** The per-track values of a parameter, of shape (tracks,). */
36
+ channelAt(name: string, t: number, i: number, shifted: boolean, revolution?: number): number;
37
+ hasParameter(name: string): boolean;
38
+ /** The values of a parameter, one per member, of shape (trajectories,). The built-in parameter `@index` has the value `t` for member `t`. */
38
39
  parameter(name: string, rule?: string): TypedArray;
39
40
  hasAttr(name: string): boolean;
40
41
  attr(name: string): number;
41
42
  }
42
- /** One SetData per track set, built on first use. */
43
+ /** One SetData per trajectory set, built on first use. */
43
44
  export declare class SetCache {
44
45
  private readonly scene;
45
46
  private readonly data;
@@ -0,0 +1,60 @@
1
+ import type { Camera, Clock, Opacity, Size } from '../scene.js';
2
+ /** Seconds one revolution of the clock lasts at speed 1, whatever its frame count. */
3
+ export declare const REVOLUTION_SECONDS = 8;
4
+ export declare const EASES: readonly string[];
5
+ /** A keyframe as the scene gives it, `[t, v]` or `[t, v, ease]`. */
6
+ export type Keyframe = readonly unknown[];
7
+ /** The seconds that one loop of the clock lasts at speed 1: its `seconds` when given, else REVOLUTION_SECONDS for each of its revolutions (rule `revolutions`). */
8
+ export declare function loopSeconds(clock: Pick<Clock, 'seconds' | 'revolutions'> & Partial<Clock>): number;
9
+ /** The time of the timeline at progress `q`, `s = q * L` (section 2.11). */
10
+ export declare function timeAt(clock: Pick<Clock, 'seconds' | 'revolutions'> & Partial<Clock>, q: number): number;
11
+ /** The ease E(x) of rule `ease`. */
12
+ export declare function ease(name: unknown, x: number): number;
13
+ /** Checks a list of keyframes (rules `keyframes` and `ease`), with numbers for values unless `values` says otherwise, and returns it. */
14
+ export declare function checkKeyframes(keys: unknown, what: string, values?: (v: unknown) => boolean): Keyframe[];
15
+ /**
16
+ * The segment of a list of keyframes at time `s` (rule `keyframes`): the index `i` of the last keyframe at or before `s`, and the eased
17
+ * weight `e` toward keyframe `i + 1`, or `e = null` when `s` lies before the first keyframe (i = 0) or at or after the last.
18
+ */
19
+ export declare function segmentAt(times: (i: number) => number, count: number, s: number, easeOf: (i: number) => unknown): {
20
+ i: number;
21
+ e: number | null;
22
+ };
23
+ /** The value of a list of keyframes at time `s` (rule `keyframes`). */
24
+ export declare function keyframesValue(keys: readonly Keyframe[], s: number): number;
25
+ /** A number that may be keyframed, at time `s`, or `fallback` when it is absent. */
26
+ export declare function numberAt(value: number | {
27
+ keyframes: unknown;
28
+ } | undefined, s: number, fallback: number): number;
29
+ /** An opacity that may be keyframed, at time `s`, clamped into [0, 1]. */
30
+ export declare function opacityAt(value: Opacity | undefined, s: number, fallback?: number): number;
31
+ /** A size that may be keyframed, at time `s`, never below zero. */
32
+ export declare function sizeAt(value: Size | undefined, s: number, fallback: number): number;
33
+ /** Checks a number that may be keyframed, whose values `ok` accepts, e.g. an opacity in [0, 1]. */
34
+ export declare function checkKeyframed(value: unknown, what: string, ok: (v: unknown) => boolean, rule?: string): void;
35
+ export declare const isOpacity: (v: unknown) => boolean;
36
+ /** A value of the keyframes of a split (section 2.11), the share of its first side, in [0, 1]. */
37
+ export declare const isShare: (v: unknown) => boolean;
38
+ export declare const isPositive: (v: unknown) => boolean;
39
+ /** The shared value of a clock in epoch mode at progress `q`, by its range (rule `clock-mode`) or its keyframes (rule `clock-keyframes`). */
40
+ export declare function clockValue(clock: Clock, q: number): number;
41
+ /** The two axes of a 2d camera's plane, as indices of x, y, and z. */
42
+ export declare function planeAxes(cam: {
43
+ plane?: 'xy' | 'xz' | 'yz';
44
+ }): [number, number];
45
+ export type CameraKeyframe = NonNullable<Extract<Camera, {
46
+ kind: '2d';
47
+ }>['keyframes']>[number];
48
+ /** The window of a camera at a time (rule `camera-keyframes`), with `height` null when the panel's aspect ratio gives it. */
49
+ export interface CameraWindow {
50
+ center: [number, number];
51
+ width: number;
52
+ height: number | null;
53
+ }
54
+ /**
55
+ * The window of a camera with keyframes at time `s` (rule `camera-keyframes`). `center(i)` gives the center of keyframe `i` at `s`, a follow keyframe's
56
+ * mean of its targets plus its offset, or null when the keyframe does not have a center then.
57
+ */
58
+ export declare function cameraWindow(keys: readonly CameraKeyframe[], s: number, center: (i: number) => [number, number] | null): CameraWindow | null;
59
+ /** Checks the keyframes of a 2d camera (rule `camera-keyframes`), apart from the targets of its follow keyframes, which need the layers of the panel. */
60
+ export declare function checkCameraKeyframes(keys: unknown, free: boolean, what: string): void;