@altpsyche/maths 0.2.0 → 0.3.0

package/README.md

@@ -42,6 +42,14 @@ marks onto a two-dimensional canvas, which is what a recording needs, because an
 one surface. A test holds the two to emitting the same geometry and the same style for every
 mark.
 
+## The way in
+
+`pathFromData` reads an SVG `d` attribute as a path, which is the inverse of what the SVG painter
+writes. Without it the only shapes that exist are the ones the builders here make, so a glyph from
+a typesetter or an outline from a drawing program could not be trimmed, aligned or walked into
+another shape, and those are the operations this package is for. Every command is read, elliptical
+arcs included, and a command it does not know stops the read rather than being skipped.
+
 ## The line through the package
 
 **Values and timing** are below it: vectors, a transform, the four curves a change can travel

package/dist/figure/path-data.d.ts

@@ -0,0 +1,29 @@
+/**
+ * An SVG path string read as geometry, which is the way in to everything above.
+ *
+ * `pathData` writes a path out and this reads one back. Without it the only
+ * paths that exist are the ones the builders beside this file make, so a glyph
+ * from a typesetter, an icon from a designer or anything else a drawing program
+ * exported cannot be trimmed, aligned or walked into another shape, and those
+ * are the operations this package is for.
+ *
+ * Everything becomes a cubic, the way it does everywhere here. A straight run
+ * takes the controls a third and two thirds along, a quadratic elevates exactly,
+ * and an elliptical arc is cut into pieces of at most a quarter turn each. So no
+ * segment read here is an approximation of the one the string described, apart
+ * from the arc, which no Bézier can be exactly.
+ *
+ * A command it does not know stops the read rather than being skipped. Skipping
+ * leaves a shape with a piece missing, and a piece missing from a letter or an
+ * outline reads as a mistake in the drawing rather than in the reading of it.
+ */
+import { type Path } from './path.js';
+/**
+ * The path a `d` attribute describes.
+ *
+ * Both cases of every command are read, so a relative run is resolved against
+ * where the last one ended. A command letter followed by more numbers than it
+ * takes repeats, which is the shorthand the grammar allows and which a moveto
+ * repeats as a lineto.
+ */
+export declare function pathFromData(d: string): Path;

package/dist/figure/path-data.js

@@ -0,0 +1,283 @@
+/**
+ * An SVG path string read as geometry, which is the way in to everything above.
+ *
+ * `pathData` writes a path out and this reads one back. Without it the only
+ * paths that exist are the ones the builders beside this file make, so a glyph
+ * from a typesetter, an icon from a designer or anything else a drawing program
+ * exported cannot be trimmed, aligned or walked into another shape, and those
+ * are the operations this package is for.
+ *
+ * Everything becomes a cubic, the way it does everywhere here. A straight run
+ * takes the controls a third and two thirds along, a quadratic elevates exactly,
+ * and an elliptical arc is cut into pieces of at most a quarter turn each. So no
+ * segment read here is an approximation of the one the string described, apart
+ * from the arc, which no Bézier can be exactly.
+ *
+ * A command it does not know stops the read rather than being skipped. Skipping
+ * leaves a shape with a piece missing, and a piece missing from a letter or an
+ * outline reads as a mistake in the drawing rather than in the reading of it.
+ */
+import { vec2 } from '../values/vec2.js';
+import { mat3 } from '../values/mat3.js';
+import { straight } from './path.js';
+/** Every command in the path grammar. */
+const DRAWN = 'MLHVCSQTAZ';
+/** A letter, a number, a run of separators, or one character that is none of
+ * those. The last group is what turns an unexpected character into a refusal
+ * rather than leaving it in the string unread. */
+const SCANNER = /([A-Za-z])|([+-]?(?:\d*\.\d+|\d+\.?)(?:[eE][+-]?\d+)?)|([,\s]+)|([\s\S])/g;
+function tokenize(d) {
+    const tokens = [];
+    SCANNER.lastIndex = 0;
+    for (let match = SCANNER.exec(d); match; match = SCANNER.exec(d)) {
+        if (match[1])
+            tokens.push({ command: match[1] });
+        else if (match[2] !== undefined)
+            tokens.push({ number: Number(match[2]) });
+        else if (match[3] === undefined)
+            throw new Error(`path data holds "${match[4]}", which is neither a command nor a number`);
+    }
+    return tokens;
+}
+/** A quadratic written as a cubic, both controls two thirds of the way from an
+ * end towards the single control. The two describe the same curve. */
+const elevate = (from, control, to) => ({
+    control1: vec2.lerp(from, control, 2 / 3),
+    control2: vec2.lerp(to, control, 2 / 3),
+    to,
+});
+/** The control a smooth segment uses, which is the previous one turned through
+ * the point the two segments share. */
+const reflect = (control, about) => vec2.sub(vec2.scale(about, 2), control);
+/** How far a cubic's controls sit from the ends of a piece of a unit arc, along
+ * the tangent. It is the same derivation `arc` uses and it holds for any sweep
+ * short enough, which is why the sweep is cut into quarters first. */
+const reachFor = (sweep) => (4 / 3) * Math.tan(sweep / 4);
+/**
+ * An SVG elliptical arc as cubics, from the endpoint form the string carries.
+ *
+ * SVG gives an arc as where it ends plus two radii, a rotation and two flags,
+ * and every one of the four arcs that fit those endpoints is selected by the
+ * flags. The centre and the two angles are recovered first, which is the
+ * conversion in the SVG specification, and then the sweep is walked in pieces
+ * of at most a quarter turn on a unit circle. The ellipse is an affine map of
+ * that circle, and an affine map takes a cubic to a cubic, so the control
+ * points can be mapped straight through rather than derived again.
+ */
+function arcCurves(from, radii, rotation, largeArc, sweep, to) {
+    // A radius of zero is a straight line by the specification, and so is an arc
+    // whose endpoints are the same point, which the specification drops entirely.
+    if (radii.x === 0 || radii.y === 0)
+        return [straight(from, to)];
+    const angle = (rotation * Math.PI) / 180;
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+    const half = vec2.scale(vec2.sub(from, to), 0.5);
+    const turned = vec2(cos * half.x + sin * half.y, -sin * half.x + cos * half.y);
+    // Radii too small to reach both endpoints are scaled up until they just do,
+    // which the specification asks for rather than treating as an error.
+    let rx = Math.abs(radii.x);
+    let ry = Math.abs(radii.y);
+    const short = (turned.x * turned.x) / (rx * rx) + (turned.y * turned.y) / (ry * ry);
+    if (short > 1) {
+        rx *= Math.sqrt(short);
+        ry *= Math.sqrt(short);
+    }
+    const denominator = rx * rx * turned.y * turned.y + ry * ry * turned.x * turned.x;
+    const numerator = Math.max(0, rx * rx * ry * ry - denominator);
+    const spread = (largeArc === sweep ? -1 : 1) * Math.sqrt(numerator / denominator);
+    const centreTurned = vec2((spread * rx * turned.y) / ry, (-spread * ry * turned.x) / rx);
+    const centre = vec2.add(vec2(cos * centreTurned.x - sin * centreTurned.y, sin * centreTurned.x + cos * centreTurned.y), vec2.scale(vec2.add(from, to), 0.5));
+    const at = (point) => vec2((point.x - centreTurned.x) / rx, (point.y - centreTurned.y) / ry);
+    const opening = at(turned);
+    const closing = at(vec2.scale(turned, -1));
+    const first = vec2.angle(opening);
+    let swept = vec2.angle(closing) - first;
+    if (!sweep && swept > 0)
+        swept -= 2 * Math.PI;
+    if (sweep && swept < 0)
+        swept += 2 * Math.PI;
+    // The whole ellipse, placed and turned, as one matrix. Every point of the
+    // unit arc goes through it, controls included.
+    const place = mat3.multiply(mat3.translation(centre), mat3.multiply(mat3.rotation(angle), mat3.scaling(vec2(rx, ry))));
+    const pieces = Math.max(1, Math.ceil(Math.abs(swept) / (Math.PI / 2)));
+    const step = swept / pieces;
+    const reach = reachFor(step);
+    const curves = [];
+    for (let piece = 0; piece < pieces; piece++) {
+        const a0 = first + step * piece;
+        const a1 = a0 + step;
+        const p0 = vec2(Math.cos(a0), Math.sin(a0));
+        const p1 = vec2(Math.cos(a1), Math.sin(a1));
+        const t0 = vec2(-Math.sin(a0), Math.cos(a0));
+        const t1 = vec2(-Math.sin(a1), Math.cos(a1));
+        curves.push({
+            control1: mat3.transformPoint(place, vec2.add(p0, vec2.scale(t0, reach))),
+            control2: mat3.transformPoint(place, vec2.sub(p1, vec2.scale(t1, reach))),
+            // The endpoint the string named rather than the one the angles give back,
+            // so a run of arcs cannot drift away from where it said it ends.
+            to: piece === pieces - 1 ? to : mat3.transformPoint(place, p1),
+        });
+    }
+    return curves;
+}
+/**
+ * The path a `d` attribute describes.
+ *
+ * Both cases of every command are read, so a relative run is resolved against
+ * where the last one ended. A command letter followed by more numbers than it
+ * takes repeats, which is the shorthand the grammar allows and which a moveto
+ * repeats as a lineto.
+ */
+export function pathFromData(d) {
+    const tokens = tokenize(d);
+    const subpaths = [];
+    let curves = [];
+    let start = vec2.ZERO;
+    let at = vec2.ZERO;
+    let open = false;
+    let moved = false;
+    let command = '';
+    let index = 0;
+    // Held per kind because an S reflects a cubic's second control and a T a
+    // quadratic's only one, and either falls back to the current point when the
+    // segment before it was neither.
+    let lastCubic;
+    let lastQuadratic;
+    const take = (count) => {
+        const values = [];
+        while (values.length < count) {
+            const token = tokens[index++];
+            if (!token || !('number' in token))
+                throw new Error(`path command "${command}" wants ${count} numbers and the run ends short`);
+            values.push(token.number);
+        }
+        return values;
+    };
+    const flush = (closed) => {
+        if (open)
+            subpaths.push({ start, curves, closed });
+        open = false;
+    };
+    const segment = (...added) => {
+        if (!moved)
+            throw new Error('path data draws before it moves to a starting point');
+        // A segment after a close begins again where the closed subpath began,
+        // which is the point the close left as the current one.
+        if (!open) {
+            start = at;
+            curves = [];
+            open = true;
+        }
+        curves.push(...added);
+        at = added[added.length - 1]?.to ?? at;
+    };
+    while (index < tokens.length) {
+        const token = tokens[index];
+        if (token && 'command' in token) {
+            command = token.command;
+            index++;
+            if (!DRAWN.includes(command.toUpperCase()))
+                throw new Error(`path data holds command "${command}", which is not one of "${DRAWN}"`);
+        }
+        else if (!command) {
+            throw new Error('path data opens on a number rather than a command');
+        }
+        const relative = command === command.toLowerCase();
+        const absolute = (x, y) => (relative ? vec2(at.x + x, at.y + y) : vec2(x, y));
+        switch (command.toUpperCase()) {
+            case 'M': {
+                const [x = 0, y = 0] = take(2);
+                flush(false);
+                at = absolute(x, y);
+                start = at;
+                curves = [];
+                open = true;
+                moved = true;
+                lastCubic = undefined;
+                lastQuadratic = undefined;
+                // A second pair under one moveto is a line rather than a second move,
+                // and the repetition carries the case the moveto was written in.
+                command = relative ? 'l' : 'L';
+                break;
+            }
+            case 'L': {
+                const [x = 0, y = 0] = take(2);
+                segment(straight(at, absolute(x, y)));
+                lastCubic = undefined;
+                lastQuadratic = undefined;
+                break;
+            }
+            case 'H': {
+                const [x = 0] = take(1);
+                segment(straight(at, relative ? vec2(at.x + x, at.y) : vec2(x, at.y)));
+                lastCubic = undefined;
+                lastQuadratic = undefined;
+                break;
+            }
+            case 'V': {
+                const [y = 0] = take(1);
+                segment(straight(at, relative ? vec2(at.x, at.y + y) : vec2(at.x, y)));
+                lastCubic = undefined;
+                lastQuadratic = undefined;
+                break;
+            }
+            case 'C': {
+                const [x1 = 0, y1 = 0, x2 = 0, y2 = 0, x = 0, y = 0] = take(6);
+                const control2 = absolute(x2, y2);
+                segment({ control1: absolute(x1, y1), control2, to: absolute(x, y) });
+                lastCubic = control2;
+                lastQuadratic = undefined;
+                break;
+            }
+            case 'S': {
+                const [x2 = 0, y2 = 0, x = 0, y = 0] = take(4);
+                const control1 = lastCubic ? reflect(lastCubic, at) : at;
+                const control2 = absolute(x2, y2);
+                segment({ control1, control2, to: absolute(x, y) });
+                lastCubic = control2;
+                lastQuadratic = undefined;
+                break;
+            }
+            case 'Q': {
+                const [qx = 0, qy = 0, x = 0, y = 0] = take(4);
+                const control = absolute(qx, qy);
+                segment(elevate(at, control, absolute(x, y)));
+                lastCubic = undefined;
+                lastQuadratic = control;
+                break;
+            }
+            case 'T': {
+                const [x = 0, y = 0] = take(2);
+                const control = lastQuadratic ? reflect(lastQuadratic, at) : at;
+                segment(elevate(at, control, absolute(x, y)));
+                lastCubic = undefined;
+                lastQuadratic = control;
+                break;
+            }
+            case 'A': {
+                const [rx = 0, ry = 0, turn = 0, large = 0, sweep = 0, x = 0, y = 0] = take(7);
+                const to = absolute(x, y);
+                // An arc that ends where it began is dropped rather than drawn, which
+                // is the specification's own wording: there is no such ellipse to pick.
+                if (to.x !== at.x || to.y !== at.y)
+                    segment(...arcCurves(at, vec2(rx, ry), turn, large !== 0, sweep !== 0, to));
+                lastCubic = undefined;
+                lastQuadratic = undefined;
+                break;
+            }
+            case 'Z': {
+                flush(true);
+                at = start;
+                lastCubic = undefined;
+                lastQuadratic = undefined;
+                // A close ends the run of one command, so a number after it has nothing
+                // to repeat and is refused rather than read as a line.
+                command = '';
+                break;
+            }
+        }
+    }
+    flush(false);
+    return subpaths;
+}

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export { SAME_TIME, keyAt, sampleTrack, sampleTracks, withKey, withoutKey } from
 export type { Key, Track, TrackValue, Tracks } from './timing/track.js';
 export { arc, circle, line, polygon, polyline, pointCount, pointOn, rect, straight, transformPath } from './figure/path.js';
 export type { Cubic, Path, Subpath } from './figure/path.js';
+export { pathFromData } from './figure/path-data.js';
 export type { Colour, Fill, Mark, PathMark, Stroke, TextMark } from './figure/mark.js';
 export { byAspect, fractionOf, matchingAspect, resolveExtent, viewMatrix } from './figure/extent.js';
 export type { Extent, ExtentChoice, Fit } from './figure/extent.js';

package/dist/index.js

@@ -14,6 +14,7 @@ export { vec3 } from './values/vec3.js';
 export { mat3 } from './values/mat3.js';
 export { SAME_TIME, keyAt, sampleTrack, sampleTracks, withKey, withoutKey } from './timing/track.js';
 export { arc, circle, line, polygon, polyline, pointCount, pointOn, rect, straight, transformPath } from './figure/path.js';
+export { pathFromData } from './figure/path-data.js';
 export { byAspect, fractionOf, matchingAspect, resolveExtent, viewMatrix } from './figure/extent.js';
 export { flatten, group, shape, text } from './figure/node.js';
 export { fadeIn, fadeOut, fadeTo, draw, morph, moveBy } from './figure/animation.js';

package/dist/paint/svg.d.ts

@@ -37,21 +37,26 @@ export declare function svgElements(marks: readonly Mark[], view: Mat3): SvgElem
 export declare function svgMarkup(marks: readonly Mark[], view: Mat3, width: number, height: number): string;
 /**
  * Only what a painter needs from a document, named here rather than taken from
- * the DOM types.
+ * the DOM types, so this package declares no browser library at all: it can be
+ * checked and tested without one, and a caller can hand in a stand-in.
  *
- * A real `SVGElement` and a real `Document` both satisfy these already, and
- * writing them out means this package declares no browser library at all: it can
- * be checked and tested without one, and a caller can hand in a stand-in.
+ * The element a maker makes is the element the target is handed, and that type
+ * travels through rather than being flattened to the two members named below. An
+ * element in a real document takes whole nodes and text where the painter's own
+ * type takes neither, so a target written in terms of the painter's type is a
+ * target no real element can be: what a document offers and what the painter
+ * would ask for are each missing something the other has, and neither signature
+ * is assignable to the other in either direction.
  */
 export interface PaintNode {
     setAttribute(name: string, value: string): void;
     textContent: string | null;
 }
-export interface PaintTarget {
-    replaceChildren(...nodes: PaintNode[]): void;
+export interface PaintTarget<Made extends PaintNode = PaintNode> {
+    replaceChildren(...nodes: Made[]): void;
 }
-export interface ElementMaker {
-    createElementNS(namespace: string, tag: string): PaintNode;
+export interface ElementMaker<Made extends PaintNode = PaintNode> {
+    createElementNS(namespace: string, tag: string): Made;
 }
 /**
  * The marks put into an element that is already on the page.
@@ -61,4 +66,4 @@ export interface ElementMaker {
  * and matching them up first would cost more than it saved while adding a way for
  * two frames to disagree.
  */
-export declare function paintSvg(into: PaintTarget, marks: readonly Mark[], view: Mat3, maker: ElementMaker): void;
+export declare function paintSvg<Made extends PaintNode>(into: PaintTarget<NoInfer<Made>>, marks: readonly Mark[], view: Mat3, maker: ElementMaker<Made>): void;

package/dist/paint/svg.js

@@ -114,7 +114,11 @@ const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
  * and matching them up first would cost more than it saved while adding a way for
  * two frames to disagree.
  */
-export function paintSvg(into, marks, view, maker) {
+export function paintSvg(
+// The maker alone says what kind of element this is. Read from the target as
+// well, a real element would offer the whole union its own call accepts, text
+// included, and that union is not a thing this painter can set an attribute on.
+into, marks, view, maker) {
     const elements = svgElements(marks, view);
     into.replaceChildren(...elements.map((element) => {
         const node = maker.createElementNS(SVG_NAMESPACE, element.tag);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@altpsyche/maths",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The mathematics AltPsyche's figures are drawn from: vectors, matrices, curves, and a value walked over time.",
   "license": "MIT",
   "author": "Siva",