inkplot 0.0.0-stage → 1.0.0-beta.1

package/dist/radial.js

@@ -0,0 +1,336 @@
+/**
+ * Radial planes: the domain goes round a circle (the angle axis), the value out from the middle (the radius axis).
+ *
+ * A radial plane is three decisions. Where a point goes (`locate`), what a line of constant value looks like (`ring`),
+ * and what to do once the circle is settled (`prepare`). Everything else, from layout to axes to gridlines to the
+ * clip, is shared, and series and renderers know nothing of it. `PolarPlane` is the continuous one: rings are arcs.
+ * `RadarPlane` has a spoke at every tick of the angle axis and joins them with chords, rings and data alike.
+ */
+/* 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 { NUMBER } from './attrs.js';
+import { Axis, polarSide } from './axis.js';
+import { writeAria } from './aria.js';
+import { fail } from './element.js';
+import { EVENT_ARRANGE, EVENT_ATTACH, EVENT_PAINT } from './events.js';
+import { f2 } from './geometry.js';
+import { MIN_INSET, Plane, nextClipId } from './plane.js';
+const SIDES = ['angle', 'radius'];
+const TAU = 2 * Math.PI;
+/** An arc of a circle as path data, in pieces of at most half a turn so that any sweep is drawn the right way round. */
+function arc(cx, cy, r, start, sweep) {
+    const pieces = Math.max(1, Math.ceil(Math.abs(sweep) / Math.PI - 1e-9)), step = sweep / pieces;
+    const at = (a) => `${f2(cx + r * Math.sin(a))} ${f2(cy - r * Math.cos(a))}`;
+    let d = `M${at(start)}`;
+    for (let k = 1; k <= pieces; k++)
+        d += `A${f2(r)} ${f2(r)} 0 0 ${sweep > 0 ? 1 : 0} ${at(start + k * step)}`;
+    return d;
+}
+/**
+ * The shared machinery of radial planes: layout in a circle, rulers for both axes, clip, gridlines, and `place`.
+ * Subclasses supply only the geometry (`locate`, `ring`, `outerRadius`, `prepare`).
+ */
+export class RadialPlane extends Plane {
+    static attrTypes = { ...Plane.attrTypes, innerRadius: NUMBER, startAngle: NUMBER };
+    clipId = nextClipId();
+    #cx = 0;
+    #cy = 0;
+    #radius = 1;
+    #xy = new Float64Array(2);
+    #rulers = new Map();
+    get clipUrl() { return this.attrs.clip === false ? null : `url(#${this.clipId})`; }
+    get curved() { return true; }
+    get startAngle() { return this.attrs.startAngle ?? 0; }
+    get sweep() { return this.attrs.sweep ?? TAU; }
+    get innerRadius() { return this.attrs.innerRadius ?? 0; }
+    /** The outer radius in plot pixels. Valid after arrange. */
+    get radius() { return this.#radius; }
+    get cx() { return this.#cx; }
+    get cy() { return this.#cy; }
+    /** Called when the circle is settled, before any series is projected. */
+    prepare() { }
+    cyclic(axis) { return axis.orientation === 'angle' && Math.abs(this.sweep) >= TAU - 1e-9; }
+    /** On the plot when inside the rim in that direction, outside the hole, and (for a part of a turn) within the sweep. */
+    covers(x, y) {
+        const dx = x - this.#cx, dy = y - this.#cy, len = Math.hypot(dx, dy);
+        if (len > this.outerRadius(dx, dy) + 1e-9 || len < this.#radius * this.innerRadius - 1e-9)
+            return false;
+        const first = this.defaultAxis('first');
+        if (len === 0 || !first || this.cyclic(first))
+            return true;
+        const f = this.angleFraction(dx, dy);
+        return f >= 0 && f <= 1;
+    }
+    /** A radius is a ring (round, or a polygon on a radar); an angle is a spoke, which the plane's own way of placing gives. */
+    guide(role, value) {
+        const axis = this.defaultAxis(role);
+        if (axis?.orientation !== 'radius')
+            return super.guide(role, value);
+        const f = axis.fractionOf(value);
+        return Number.isFinite(f) ? this.ring(this.#radius * (this.innerRadius + (1 - this.innerRadius) * Math.max(0, f))) : '';
+    }
+    /** The first coordinate is the angle, the second the radius. */
+    defaultAxis(role) {
+        return this.axes.find((a) => a.orientation === (role === 'first' ? 'angle' : 'radius'));
+    }
+    /** Pixels along an axis: what its ticks have to fit into. */
+    lengthOf(axis) { return this.#rulers.get(axis)?.length ?? 1; }
+    /** The fractions 0..1 of an axis' ticks that fall inside its range. */
+    tickFractions(axis) {
+        const out = [];
+        if (!axis)
+            return out;
+        for (const t of axis.getTicks(this.lengthOf(axis))) {
+            const f = axis.fractionOf(t.value);
+            if (f >= -1e-9 && f <= 1 + 1e-9)
+                out.push(f);
+        }
+        return out;
+    }
+    unplace(x, y, first, second) {
+        const dx = x - this.#cx, dy = y - this.#cy, inner = this.innerRadius;
+        const around = this.angleFraction(dx, dy);
+        const out = (Math.hypot(dx, dy) / this.outerRadius(dx, dy) - inner) / (1 - inner);
+        return first.orientation === 'angle' ? [first.denormalize(around), second.denormalize(out)] : [first.denormalize(out), second.denormalize(around)];
+    }
+    place(points, first, second) {
+        const angleIsDomain = first.orientation === 'angle';
+        if ((first.orientation !== 'angle' && first.orientation !== 'radius') || (second.orientation === 'angle') === angleIsDomain) {
+            fail('a series needs one angle axis and one radius axis');
+        }
+        const { data, count, stride } = points;
+        const R = this.#radius, inner = this.innerRadius, xy = this.#xy;
+        const a0 = angleIsDomain ? 0 : 1, r0 = 1 - a0;
+        for (let k = 0, i = 0; k < count; k++, i += stride) {
+            // Below the middle would come out on the far side. Above the edge is left for the clip.
+            this.locate(data[i + a0], R * (inner + (1 - inner) * Math.max(0, data[i + r0])), xy);
+            data[i] = xy[0];
+            data[i + 1] = xy[1];
+        }
+    }
+    onEvent(ev) {
+        switch (ev.type) {
+            case EVENT_ATTACH:
+                this.surface.wrapper();
+                break;
+            case EVENT_ARRANGE:
+                this.arrange(ev.rect);
+                break;
+            case EVENT_PAINT:
+                this.paint();
+                break;
+        }
+    }
+    /**
+     * Every axis gets the curve it runs along: the rim for the angle, a spoke at the start angle for the radius. The line
+     * is worked out when it is drawn, since a radar's depends on ticks that are only settled by then.
+     */
+    setRulers() {
+        const start = this.startAngle, sweep = this.sweep, R = this.#radius, r0 = R * this.innerRadius, xy = this.#xy;
+        const ring = (r) => this.ring(r);
+        const at0 = (r) => {
+            this.locate(0, r, xy);
+            return `${f2(xy[0])} ${f2(xy[1])}`;
+        };
+        const angleAt = (f) => {
+            this.locate(f, R, xy);
+            const a = start + f * sweep;
+            return [xy[0], xy[1], Math.sin(a), -Math.cos(a)];
+        };
+        const radiusAt = (f) => {
+            this.locate(0, r0 + f * (R - r0), xy);
+            return [xy[0], xy[1], -Math.cos(start), -Math.sin(start)];
+        };
+        // A radial axis' title is always on its own line, past its labels: there is no edge of a circle to put it at.
+        const spot = (mid) => ({ x: mid[0], y: mid[1], nx: mid[2], ny: mid[3], beyond: true });
+        for (const axis of this.axes) {
+            const ruler = axis.orientation === 'angle'
+                ? {
+                    length: Math.max(1, Math.abs(sweep) * R), tickSpacing: 70, horizontal: false,
+                    get line() { return ring(R); },
+                    at: angleAt,
+                    title: () => spot(angleAt(0.5)),
+                }
+                : {
+                    length: Math.max(1, R - r0), tickSpacing: 36, horizontal: false,
+                    get line() { return `M${at0(r0)}L${at0(R)}`; },
+                    at: radiusAt,
+                    title: () => spot(radiusAt(0.5)),
+                    // However far round the pointer is, it is as far along the radius as it is out from the middle, measured
+                    // against the edge in its own direction (a radar's edge is nearer between spokes).
+                    fractionAt: (x, y) => {
+                        const dx = x - this.#cx, dy = y - this.#cy, inner = this.innerRadius;
+                        return (Math.hypot(dx, dy) / this.outerRadius(dx, dy) - inner) / (1 - inner);
+                    },
+                };
+            this.#rulers.set(axis, ruler);
+            axis.setRuler(ruler);
+        }
+    }
+    /**
+     * Same three passes as a Cartesian plane (estimate → fit → measure → final size → project), except that the plot is
+     * the largest circle in what is left, and the only margin that matters is what the angle axis' labels need around it.
+     */
+    arrange(available) {
+        const axes = this.axes, series = this.series;
+        this.assignAxes(SIDES, polarSide);
+        // A first guess at the circle sizes the fills and the tick counts; the labels then say how much room they take.
+        this.#radius = Math.max(1, Math.min(available.width, available.height) / 2 - 24);
+        this.#cx = this.#cy = 0;
+        this.setRulers();
+        const estimate = { width: Math.max(1, Math.abs(this.sweep) * this.#radius), height: this.#radius };
+        this.fit(estimate);
+        let margin = 0;
+        for (const a of axes) {
+            this.measureChild(a, estimate);
+            if (a.orientation === 'angle')
+                margin = Math.max(margin, a.thickness, Math.ceil(a.labelOverhang));
+        }
+        const o = this.attrs.insets ?? {};
+        const insets = {
+            top: o.top ?? Math.max(MIN_INSET, margin), bottom: o.bottom ?? Math.max(MIN_INSET, margin),
+            left: o.left ?? Math.max(MIN_INSET, margin), right: o.right ?? Math.max(MIN_INSET, margin),
+        };
+        const rect = {
+            x: available.x + insets.left, y: available.y + insets.top,
+            width: Math.max(1, available.width - insets.left - insets.right),
+            height: Math.max(1, available.height - insets.top - insets.bottom),
+        };
+        this.setRect(rect);
+        this.#cx = rect.width / 2;
+        this.#cy = rect.height / 2;
+        this.#radius = Math.max(1, Math.min(rect.width, rect.height) / 2);
+        this.setRulers();
+        this.prepare();
+        for (const s of series)
+            s.project(this);
+    }
+    /** What the plot covers: the whole outline for a full turn (less the hole), a sector for part of one. */
+    region() {
+        const R = this.#radius, r0 = R * this.innerRadius;
+        if (Math.abs(this.sweep) >= TAU - 1e-9)
+            return this.ring(R) + 'Z' + (r0 > 0 ? this.ring(r0) + 'Z' : '');
+        return this.ring(R) + 'L' + this.ring(r0, true).slice(1) + 'Z';
+    }
+    /** Clip region, then spokes at the angle axis' ticks and rings at the radius axis' ticks. */
+    paint() {
+        const s = this.surface, r = this.rect, a = this.attrs;
+        const R = this.#radius, inner = this.innerRadius, xy = this.#xy;
+        s.set(s.wrapper(), 'transform', `translate(${f2(r.x)} ${f2(r.y)})`);
+        writeAria(s, s.wrapper(), a.meta, { role: 'group' });
+        if (a.clip !== false) {
+            const clip = s.node('clip', 'clipPath', { parent: s.node('defs', 'defs') });
+            s.set(clip, 'id', this.clipId);
+            const shape = s.node('clip-shape', 'path', { parent: clip });
+            s.set(shape, 'd', this.region());
+            s.set(shape, 'clip-rule', 'evenodd');
+        }
+        if (a.gridlines !== false) {
+            let d = '';
+            const angle = this.axes.find((x) => x.orientation === 'angle'), radius = this.axes.find((x) => x.orientation === 'radius');
+            for (const f of this.tickFractions(angle)) {
+                this.locate(f, R * inner, xy);
+                d += `M${f2(xy[0])} ${f2(xy[1])}`;
+                this.locate(f, R, xy);
+                d += `L${f2(xy[0])} ${f2(xy[1])}`;
+            }
+            for (const f of this.tickFractions(radius))
+                d += this.ring(R * (inner + (1 - inner) * f));
+            const grid = s.node('grid', 'path');
+            s.set(grid, 'd', d);
+            s.set(grid, 'fill', 'none');
+            this.strokeWith(grid, this.styleFor(['gridline', 'line']));
+        }
+        else {
+            s.remove('grid');
+        }
+    }
+}
+/** A continuous plane: the angle is an angle, so lines of constant value are circles. */
+export class PolarPlane extends RadialPlane {
+    locate(fraction, r, out) {
+        const a = this.startAngle + fraction * this.sweep;
+        out[0] = this.cx + r * Math.sin(a);
+        out[1] = this.cy - r * Math.cos(a);
+    }
+    outerRadius() { return this.radius; }
+    angleFraction(dx, dy) {
+        const f = (Math.atan2(dx, -dy) - this.startAngle) / this.sweep;
+        return Math.abs(this.sweep) >= TAU - 1e-9 ? f - Math.floor(f) : f;
+    }
+    ring(r, reverse = false) {
+        return reverse ? arc(this.cx, this.cy, r, this.startAngle + this.sweep, -this.sweep) : arc(this.cx, this.cy, r, this.startAngle, this.sweep);
+    }
+}
+/**
+ * A plane with a spoke at every tick of the angle axis, the ends of the sweep too, and straight lines between them.
+ * Between two spokes a point is on the chord between where its radius is on each, so a ring is a polygon, a line
+ * through dense data follows the same chords, and an `AreaPath` fills a polygon without being told it is one.
+ *
+ * Give the angle axis a fixed `min` and `max` and a `tickCount` that puts a tick on each category (and `nice` off,
+ * or on only for integers); auto-ranging works, but the spokes move as the data does. A full turn ends where it began,
+ * so a closed shape needs the first point repeated at the end of the domain.
+ */
+export class RadarPlane extends RadialPlane {
+    /** Fractions of the angle axis that have a spoke, ascending, and the direction of each. */
+    #at = [0, 1];
+    #sin = [0, 0];
+    #cos = [1, 1];
+    prepare() {
+        const set = new Set([0, 1]);
+        for (const f of this.tickFractions(this.axes.find((a) => a.orientation === 'angle')))
+            set.add(Math.round(f * 1e9) / 1e9);
+        this.#at = [...set].sort((p, q) => p - q);
+        this.#sin = this.#at.map((f) => Math.sin(this.startAngle + f * this.sweep));
+        this.#cos = this.#at.map((f) => Math.cos(this.startAngle + f * this.sweep));
+    }
+    /** The spokes: a line along the angle axis bends at each. */
+    breaks(axis) { return axis.orientation === 'angle' ? this.#at : []; }
+    locate(fraction, r, out) {
+        const at = this.#at;
+        let k = 0;
+        while (k < at.length - 2 && fraction > at[k + 1])
+            k++;
+        const t = (fraction - at[k]) / (at[k + 1] - at[k]);
+        const x0 = r * this.#sin[k], y0 = -r * this.#cos[k];
+        out[0] = this.cx + x0 + t * (r * this.#sin[k + 1] - x0);
+        out[1] = this.cy + y0 + t * (-r * this.#cos[k + 1] - y0);
+    }
+    /** The wedge between two spokes that the direction (dx, dy) points into: the spoke before it, and how far round the sweep it is. */
+    wedge(dx, dy) {
+        const at = this.#at;
+        let f = (Math.atan2(dx, -dy) - this.startAngle) / this.sweep;
+        f = Math.abs(this.sweep) >= TAU - 1e-9 ? f - Math.floor(f) : Math.min(1, Math.max(0, f));
+        let k = 0;
+        while (k < at.length - 2 && f > at[k + 1])
+            k++;
+        return { k, f };
+    }
+    outerRadius(dx, dy) {
+        // The chord of the wedge the pointer is in: a ray meets it where the chord's distance from the middle, over the
+        // cosine of the angle to the chord's normal, says.
+        const { k } = this.wedge(dx, dy);
+        const nx = this.#sin[k] + this.#sin[k + 1], ny = -(this.#cos[k] + this.#cos[k + 1]), norm = Math.hypot(nx, ny);
+        const chord = (this.#sin[k] * nx - this.#cos[k] * ny) / norm, along = (dx * nx + dy * ny) / norm / Math.hypot(dx, dy);
+        const t = (chord / along) * this.radius;
+        return t > 0 && Number.isFinite(t) ? t : this.radius;
+    }
+    /** Where along the chord the pointer's ray crosses it, mapped to the fractions of the two spokes (not linear in the angle). */
+    angleFraction(dx, dy) {
+        const at = this.#at, { k, f } = this.wedge(dx, dy), R = this.radius;
+        const len = Math.hypot(dx, dy);
+        if (len === 0)
+            return f;
+        const reach = this.outerRadius(dx, dy), px = (dx / len) * reach, py = (dy / len) * reach;
+        const ax = R * this.#sin[k], ay = -R * this.#cos[k], sx = R * this.#sin[k + 1] - ax, sy = -R * this.#cos[k + 1] - ay;
+        const t = ((px - ax) * sx + (py - ay) * sy) / (sx * sx + sy * sy);
+        return at[k] + Math.min(1, Math.max(0, t)) * (at[k + 1] - at[k]);
+    }
+    ring(r, reverse = false) {
+        let d = '';
+        for (let j = 0; j < this.#at.length; j++) {
+            const k = reverse ? this.#at.length - 1 - j : j;
+            d += (j === 0 ? 'M' : 'L') + f2(this.cx + r * this.#sin[k]) + ' ' + f2(this.cy - r * this.#cos[k]);
+        }
+        return d;
+    }
+}