inkplot 0.0.0-stage → 1.0.0-beta.1

package/dist/data.js

@@ -0,0 +1,276 @@
+/**
+ * The data contract and the base of data sources (the sources themselves are in sources.ts): always delivered domain-sorted, read in place when already sorted.
+ *
+ * The data contract, and why it is shaped this way
+ * ─────────────────────────────────────────────────
+ * A *point* is a row of numbers: `[domain, value, ...channels]`. The domain is the position along the independent
+ * axis; the channels are extra named columns (size, colour, the x of an XY plot) that a series asks for by name.
+ *
+ * Everything downstream (windowing to the visible range, decimation to the pixel width, path generation) wants the
+ * domain *ascending*: it can then binary-search a window and sweep pixel columns in one pass. So the contract is that
+ * every stage **delivers** ascending points. How a source achieves that is its own business:
+ *   - Already sorted (`isSorted`, a regular domain, generated data): read where it is stored, no copy ("in place").
+ *   - Otherwise: copied once per change into a buffer the source owns ("managed"), NaN domains dropped, sorted if needed.
+ * Callers see the same interface either way, which is what lets a million sorted points cost nothing to set up while
+ * unsorted object data still just works.
+ *
+ * Stages form a pipeline (`DataStage`): a source, optionally wrapped by transforms (a Decimator). Each stage answers
+ * `plan(context)` with a capacity and a `fill` that writes points into a caller-supplied buffer — the caller owns the
+ * memory, so a series can reuse one allocation across redraws. `version` increases on every change and keys all
+ * caches (fills, extents). `view()` is the optional zero-copy path used by decimators and extent scans.
+ *
+ * Extents are tracked per column and reported by `fill`, because the loop that writes a value is the cheapest place
+ * to see it. `valueExtent`/`channelExtent` additionally report the extent of *all* the data regardless of the window,
+ * which zoom limits and mapped scales need.
+ */
+/* oxlint-disable typescript/no-non-null-assertion -- numeric kernels over flat typed-array buffers (stride-addressed rows): every index is bounded by the row count, which `noUncheckedIndexedAccess` cannot see */
+import { BOOLEAN } from './attrs.js';
+import { ChartElement, fail } from './element.js';
+/** What a source's loader is given: nothing about the plot, since loading from storage does not depend on it. */
+const LOAD_CONTEXT = { width: 0, height: 0, domainRange: { min: -Infinity, max: Infinity }, channels: [] };
+const identity = (i) => i;
+/** The extent of an empty column: min above max, so any real value replaces it and `min <= max` tests emptiness. */
+export const NO_POINTS = { min: Infinity, max: -Infinity };
+/** Shared with sources.ts. Missing values become NaN, which every stage treats as a gap. */
+// oxlint-disable-next-line typescript/consistent-type-assertions -- `+v` is how any value is coerced to a number, whatever its type
+export const num = (v) => (v === null || v === undefined ? NaN : +v);
+/** The first and last finite values of `n` readings, which for an ascending domain are its extent. */
+export function endsOf(n, at) {
+    let min = Infinity, max = -Infinity;
+    for (let i = 0; i < n; i++) {
+        const x = at(i);
+        if (Number.isFinite(x)) {
+            min = x;
+            break;
+        }
+    }
+    for (let i = n - 1; i >= 0; i--) {
+        const x = at(i);
+        if (Number.isFinite(x)) {
+            max = x;
+            break;
+        }
+    }
+    return min <= max ? { min, max } : null;
+}
+/** The extent of every column of `count` rows of `stride` numbers, NaN skipped. The domain column is ascending, so only its ends matter. */
+function columnExtents(buf, count, stride) {
+    const out = [count > 0 ? { min: buf[0], max: buf[stride * (count - 1)] } : NO_POINTS];
+    for (let c = 1; c < stride; c++) {
+        let min = Infinity, max = -Infinity;
+        for (let i = 0, j = c; i < count; i++, j += stride) {
+            const v = buf[j];
+            if (v < min)
+                min = v;
+            if (v > max)
+                max = v;
+        }
+        out.push(count > 0 && min <= max ? { min, max } : NO_POINTS);
+    }
+    return out;
+}
+/**
+ * Everything the contract needs that does not depend on where the numbers are stored: ordering, the managed buffer,
+ * wrapping, extents and caching. A concrete source supplies only `fill`, `scanDomain` and (if it can) `orderedView`.
+ */
+export class DataSource extends ChartElement {
+    static attrTypes = { ...ChartElement.attrTypes, isSorted: BOOLEAN };
+    #version = 0;
+    domainCache = null;
+    valueCache = null;
+    channelCache = null;
+    /** Increases whenever the data changes. Cached fills are keyed on it. */
+    get version() { return this.#version; }
+    /**
+     * True when `fill` already writes ascending points, so nothing needs arranging: the data is flagged sorted,
+     * or the source generates it in order. A generated source overrides this.
+     */
+    get ordered() { return this.attrs.isSorted === true; }
+    /** Ordered, and so read where it is stored: not when wrapped, since the extra point has to live somewhere. */
+    get inPlace() { return this.ordered && this.attrs.wrap === undefined; }
+    /** The channels this source can deliver, in the order `managed` stores them. Default none. */
+    get channelNames() { return []; }
+    /** An `ordered` source that can be read in place offers its storage here. Default: nothing to offer. */
+    orderedView() { return null; }
+    // The managed copy is rebuilt lazily, at most once per version, and only for sources that need arranging.
+    #managed = null;
+    #loadBuffer = new Float64Array(0);
+    /**
+     * The points in a buffer this source owns, ascending, rebuilt lazily after each change. An ordered source is
+     * only copied; any other has NaN-domain points dropped and is sorted (stably) unless it happens to be in order.
+     */
+    managed() {
+        const cached = this.#managed;
+        if (cached && cached.version === this.version)
+            return cached;
+        const names = this.channelNames, stride = 2 + names.length, n = this.pointCount;
+        if (this.#loadBuffer.length < stride * (n + 1))
+            this.#loadBuffer = new Float64Array(stride * (n + 1));
+        const loaded = this.fill(this.#loadBuffer, { ...LOAD_CONTEXT, channels: names });
+        let buf = this.#loadBuffer, count = loaded.count, extents = loaded.extents;
+        let rows = null;
+        if (!this.inPlace) {
+            // One pass: close the gaps left by NaN domains (compacting in place) and notice whether the order is already right.
+            // `origin` (made at the first gap) remembers which stored row each kept point came from.
+            let kept = 0, ascending = true, prev = -Infinity, origin = null;
+            for (let i = 0; i < count; i++) {
+                const x = buf[stride * i];
+                if (!Number.isFinite(x)) {
+                    if (!origin) {
+                        origin = new Uint32Array(count);
+                        for (let k = 0; k < kept; k++)
+                            origin[k] = k;
+                    }
+                    continue;
+                }
+                if (x < prev)
+                    ascending = false;
+                prev = x;
+                if (kept !== i)
+                    for (let c = 0; c < stride; c++)
+                        buf[stride * kept + c] = buf[stride * i + c];
+                if (origin)
+                    origin[kept] = i;
+                kept++;
+            }
+            rows = origin;
+            count = kept;
+            if (!ascending) {
+                // Sort an index rather than the rows, with the index as tie-break so equal domains keep their original order.
+                const order = new Uint32Array(count);
+                for (let i = 0; i < count; i++)
+                    order[i] = i;
+                order.sort((a, b) => buf[stride * a] - buf[stride * b] || a - b);
+                const sorted = new Float64Array(stride * (count + 1));
+                for (let i = 0; i < count; i++)
+                    for (let c = 0; c < stride; c++)
+                        sorted[stride * i + c] = buf[stride * order[i] + c];
+                buf = sorted;
+                rows = order.map((o) => (origin ? origin[o] : o));
+            }
+            // The closing point is a copy of the first one period on; the loader allocated one spare row for it.
+            const wrap = this.attrs.wrap;
+            if (wrap !== undefined && count > 0) {
+                if (buf[0] + wrap < buf[stride * (count - 1)])
+                    fail('the wrap period is shorter than the domain of the data');
+                for (let c = 1; c < stride; c++)
+                    buf[stride * count + c] = buf[c];
+                buf[stride * count] = buf[0] + wrap;
+                // The copy is the first point again, so an edit to it lands on the first point's row.
+                const longer = new Uint32Array(count + 1);
+                if (rows)
+                    longer.set(rows.subarray(0, count));
+                else
+                    for (let k = 0; k < count; k++)
+                        longer[k] = k;
+                longer[count] = longer[0];
+                rows = longer;
+                count++;
+            }
+            extents = columnExtents(buf, count, stride);
+        }
+        return (this.#managed = { version: this.version, data: buf, count, stride, extents, rows });
+    }
+    /** The managed buffer as a view. */
+    managedView() {
+        const m = this.managed();
+        return { data: m.data, count: m.count, stride: m.stride, domainOffset: 0, valueOffset: 1, regularDomain: null };
+    }
+    /** The points ascending in the domain, to read in place; valid until the next change. Null: use `plan`. */
+    view() { return this.inPlace ? this.orderedView() : this.managedView(); }
+    /** Any change to the data bumps the version, which is what discards cached fills. */
+    invalidate() {
+        this.#version++;
+        super.invalidate();
+    }
+    /** Cached per version; an in-place source only looks at its two ends, a managed one already knows. */
+    domain() {
+        const c = this.domainCache;
+        if (c && c.version === this.version)
+            return c.extent;
+        const extent = this.inPlace ? this.scanDomain() : (this.managed().extents[0] ?? null);
+        const result = extent && extent.min <= extent.max ? extent : null;
+        this.domainCache = { version: this.version, extent: result };
+        return result;
+    }
+    /**
+     * The extent of all the values, gaps skipped. A scan of the stored points, made once per change and only when asked,
+     * for anything that needs the whole range while drawing only part of it (the limits of a zoom).
+     */
+    valueExtent() {
+        const c = this.valueCache;
+        if (c && c.version === this.version)
+            return c.extent;
+        let min = Infinity, max = -Infinity;
+        const v = this.view();
+        if (v) {
+            const d = v.data, s = v.stride, n = v.count;
+            for (let i = 0, j = v.valueOffset; i < n; i++, j += s) {
+                const y = d[j];
+                if (y < min)
+                    min = y;
+                if (y > max)
+                    max = y;
+            }
+        }
+        else {
+            const plan = this.plan(LOAD_CONTEXT), extent = plan.fill(new Float64Array(2 * plan.capacity)).extents[1];
+            if (extent) {
+                min = extent.min;
+                max = extent.max;
+            }
+        }
+        const extent = min <= max ? { min, max } : null;
+        this.valueCache = { version: this.version, extent };
+        return extent;
+    }
+    /** Like `valueExtent` for one channel: a scan made once per change and name, for anything that needs the whole range. */
+    channelExtent(name) {
+        let c = this.channelCache;
+        if (!c || c.version !== this.version)
+            c = this.channelCache = { version: this.version, byName: new Map() };
+        const known = c.byName.get(name);
+        if (known !== undefined)
+            return known;
+        const plan = this.plan({ ...LOAD_CONTEXT, channels: [name] }), column = plan.fill(new Float64Array(3 * plan.capacity)).extents[2];
+        const extent = column && column.min <= column.max ? column : null;
+        c.byName.set(name, extent);
+        return extent;
+    }
+    /**
+     * In place: fill straight from storage in the requested column order. Managed: copy the sorted buffer, repacking rows
+     * only when the series wants a different selection of channels than the source stores.
+     */
+    plan(context) {
+        if (this.inPlace)
+            return { capacity: this.pointCount, fill: (out) => ({ ...this.fill(out, context), rowOf: identity }) };
+        const m = this.managed(), want = context.channels, have = this.channelNames;
+        const rows = m.rows, rowOf = rows ? (i) => rows[i] : identity;
+        if (want.length === have.length && want.every((w, i) => w === have[i])) {
+            return {
+                capacity: m.count,
+                fill: (out) => { out.set(m.data.subarray(0, m.stride * m.count)); return { count: m.count, extents: m.extents, rowOf }; },
+            };
+        }
+        // A different selection of channels: repack each row.
+        const columns = want.map((name) => { const i = have.indexOf(name); return i < 0 ? fail(`the data has no channel "${name}"`) : 2 + i; });
+        const out2 = 2 + want.length;
+        return {
+            capacity: m.count,
+            fill: (out) => {
+                for (let i = 0; i < m.count; i++) {
+                    out[out2 * i] = m.data[m.stride * i];
+                    out[out2 * i + 1] = m.data[m.stride * i + 1];
+                    for (let c = 0; c < columns.length; c++)
+                        out[out2 * i + 2 + c] = m.data[m.stride * i + columns[c]];
+                }
+                return { count: m.count, extents: [m.extents[0], m.extents[1], ...columns.map((c) => m.extents[c])], rowOf };
+            },
+        };
+    }
+}
+/** A stage that takes another stage as input: a decimator, a filter, a resampler. It has no storage of its own, so it implements the stage interface directly. */
+export class DataTransform extends ChartElement {
+    /** The channels it delivers by name. Default none; a transform that passes its source's through, or makes its own, says so. */
+    get channelNames() { return []; }
+}

package/dist/decimation.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Decimation: reducing many points to the few a plot can show, by pixel column.
+ *
+ * Why: a line over a million points cannot show more than about one distinct value per pixel column, yet generating,
+ * normalising and stringifying a million points is the dominant cost of a redraw. Reducing to the extremes of each
+ * column first keeps the picture (to within a pixel) at a cost proportional to the plot's width, not the data's size.
+ *
+ * Structure: a `Decimator` (a data transform) owns a `DecimationKernel` (the reduction rule, swappable) and a source.
+ * It windows the source to the visible domain, hands the kernel a zero-copy `PointView`, and reports extents of what the
+ * kernel *saw* so the value axis fits the visible data rather than the whole of it.
+ */
+import { type DataNode, DataTransform, type FillPlan, type PlanContext, type PointView } from './data.ts';
+import { type BaseAttributes, ChartElement } from './element.ts';
+import type { Extent } from './geometry.ts';
+/** Tuning for the reduction. */
+export interface DecimatorAttributes extends BaseAttributes {
+    /** Pixel columns reduced to per pixel of plot width. Default 1; raise it for high-DPI output. */
+    resolution?: number;
+    /** Turn it off without removing it. Default true. */
+    enabled?: boolean;
+}
+/** What a kernel reports besides the points it wrote: the value extent of the data it looked at. */
+export interface ReduceResult {
+    readonly count: number;
+    readonly yMin: number;
+    readonly yMax: number;
+}
+/**
+ * The reduction itself. A kernel is an element so its parameters serialize and a new one is just a class.
+ * Kernels read the source's storage in place; sources always deliver the domain ascending.
+ */
+export declare abstract class DecimationKernel<A extends BaseAttributes = BaseAttributes> extends ChartElement<Decimator, [], A> {
+    /** The most points `reduce` can write for this many columns. */
+    abstract capacity(columns: number): number;
+    /**
+     * Reduce `view` to at most `capacity` points over `domainRange`, writing (domain, value) pairs into `out`.
+     * Points outside the range land in the edge columns. A gap (NaN value) is kept as one NaN point if the kernel handles gaps.
+     */
+    abstract reduce(view: PointView, domainRange: Extent, columns: number, out: Float64Array, capacity: number): ReduceResult;
+}
+/**
+ * The lowest and highest value in each pixel column, in the order they occur. Every extreme survives, so the
+ * drawn line covers what the full data would to within a pixel. Keeps gaps. At most 2 points per column.
+ */
+export declare class MinMaxKernel extends DecimationKernel {
+    capacity(columns: number): number;
+    reduce(view: PointView, range: Extent, columns: number, out: Float64Array, capacity: number): ReduceResult;
+}
+/** Min/max plus the first and last value in each column, which keeps joins between columns exact. At most 4 per column. */
+export declare class M4Kernel extends DecimationKernel {
+    capacity(columns: number): number;
+    reduce(view: PointView, range: Extent, columns: number, out: Float64Array, capacity: number): ReduceResult;
+}
+/**
+ * Largest Triangle Three Buckets: one point per column, chosen to keep the line's shape. It does not keep extremes,
+ * so spikes can vanish, and it does not handle gaps (a NaN value poisons its bucket). Prefer MinMaxKernel.
+ */
+export declare class LttbKernel extends DecimationKernel {
+    capacity(columns: number): number;
+    reduce(v: PointView, _range: Extent, W: number, out: Float64Array, cap: number): ReduceResult;
+}
+/** Every k-th point. The cheapest possible, and it aliases: extremes are lost. For previews and for comparison. */
+export declare class StrideKernel extends DecimationKernel {
+    capacity(columns: number): number;
+    reduce(v: PointView, _range: Extent, columns: number, out: Float64Array, cap: number): ReduceResult;
+}
+/**
+ * Sits between a series and its source and reduces the source to what the plot can show:
+ * `new Series(new Decimator({}, new MinMaxKernel(), source), new LinePath(new LinearCurve()))`.
+ * Only the visible part of the domain is read, so zooming in refills from the full data again.
+ * Sources always deliver points ascending in the domain, so any source works; one flagged `isSorted` is read in place.
+ */
+export declare class Decimator extends DataTransform<DecimatorAttributes, [kernel: DecimationKernel, source: DataNode]> {
+    #private;
+    get kernel(): DecimationKernel;
+    get source(): DataNode;
+    get channelNames(): readonly string[];
+    /** Anything beneath bubbles an invalidation up through here, so one counter covers source, kernel and attributes. */
+    invalidate(): void;
+    get version(): number;
+    get pointCount(): number;
+    domain(): Extent | null;
+    valueExtent(): Extent | null;
+    channelExtent(name: string): Extent | null;
+    plan(context: PlanContext): FillPlan;
+}