@altpsyche/maths 0.7.0 → 0.9.0

package/README.md

@@ -24,9 +24,10 @@ svgMarkup(at(figure, 0.5), viewMatrix(figure.extent, 'contain', 640, 360), 640,
 
 The picture arrives rather than appearing. The grid fades, the axes draw on, their labels come in one
 after another, the curve draws, the dot grows out of the origin, and the dot is pointed at where the
-slope is nothing. Then it walks the curve at one speed and flashes at the top. The number in the
-corner is a value of the typeset rule under it, and that rule reads no slope while the dot is held at
-the stationary point and walks into the one that depends on x as the dot leaves.
+slope is nothing. Then it walks the curve at one speed and flashes at the top, and a brace measures
+how far it climbed with its number counting up to the rise. The number in the corner is a value of
+the typeset rule under it, and that rule reads no slope while the dot is held at the stationary point
+and walks into the one that depends on x as the dot leaves.
 
 ```ts
 import { axes, coordsOf, group, interval, numberPlane, plot, scaleOf, shape } from '@altpsyche/maths';
@@ -59,7 +60,7 @@ region is the limit of at the left edge, the right edge or the middle of each on
 lays the tangent along the curve, cut where it leaves the graph. `slopeOf` reads the slope itself,
 which is what the number in the corner is.
 
-<img src="docs/tangent-strip.svg" width="960" alt="Four frames of the same figure side by side, the point walking up the curve, the shaded region growing behind it, and the typeset rule in the corner changing from a slope of nothing to one that depends on x.">
+<img src="docs/tangent-strip.svg" width="960" alt="Four frames of the same figure side by side, the point walking up the curve, the shaded region growing behind it, the typeset rule in the corner changing from a slope of nothing to one that depends on x, and a brace measuring the rise in the last frame.">
 
 Four times of one figure, side by side: the picture arrived, the beat at the stationary point, half
 way up, and the top. A moving picture in a README needs a GIF and this package has no encoder, so the
@@ -126,10 +127,87 @@ which would draw with whatever font a browser had and draw nothing at all in a r
 undefined macro is not an error at all, because MathJax draws the macro's own name in red, so a typo
 would otherwise ship as a red word inside the picture.
 
+## Braces and a number that counts
+
+`bracePath` draws a curly brace from one point to another with its tip standing off the line between
+them, and `brace` is that path with a word beyond the tip. It is one open subpath of six pieces: a
+curl out of each end, a run along at the curl's own height, and two curls meeting at the tip. The tip
+is a corner rather than a smooth turn, which is what a brace has and what says which point of it is
+doing the pointing. The tip stands at the depth asked for whatever the span, and only the curl
+narrows when the span is short, so two close points get a shallower brace rather than one whose
+halves cross.
+
+The label is anchored and never measured, because nothing about a figure's layout may depend on how
+wide some text is.
+
+`countTo` writes the value a count has reached into a text mark. How the value is written is the
+caller's, so a count of a length and a count of a population can round differently and this holds no
+opinion about either.
+
+```ts
+import { brace, countTo, labelFor, pointOf, vec2 } from '@altpsyche/maths';
+
+brace('rise', pointOf(coords, 3, 9), pointOf(coords, 3, 0), labelFor(9, 0.01), {
+  depth: 0.3,
+  padding: 0.28,
+  stroke: pen,
+  fill: ink,
+  size: 0.3,
+});
+
+countTo('rise/word', 0, 9, (value) => labelFor(value, 0.01));
+```
+
+A number driven by the clock is not the same as a reading driven by a track, and the difference
+matters. The slope in the demo is a value of the walk, so it is worked out by the scene from the
+track and cannot drift from the dot. The rise is counted by the clock, which is honest only because
+the dot has stopped by the time it counts: two clocks running at once would be free to disagree.
+
+## Two shapes combined
+
+<img src="docs/boolean.svg" width="720" alt="Two discs drawn three times side by side: everything either one covers, only what both cover, and the first with the second taken out of it.">
+
+`unionOf` is everything either path covers, `intersectionOf` is only what both cover, and
+`differenceOf` is the first with the second taken out of it. Each input is closed loops that do not
+cross themselves, and a loop left open is closed by a straight run back to where it started before
+anything else happens.
+
+```ts
+import { circle, differenceOf, intersectionOf, unionOf, vec2 } from '@altpsyche/maths';
+
+const first = circle(vec2(0, 0), 0.9);
+const second = circle(vec2(-0.6, 0), 0.36);
+
+unionOf(first, second);
+intersectionOf(first, second);
+differenceOf(first, second);
+```
+
+A result may have a hole even though an input may not. A disc with a smaller disc taken out of it is
+a ring, which is an outer loop and an inner loop wound the opposite way, and the nonzero rule the
+mark already carries leaves the middle empty.
+
+The work happens in four steps, and each of them is a call of its own. `curveCrossings` says where
+two cubics cross, by halving both curves and following only the halves whose boxes still overlap,
+then sharpening what it finds by Newton's method. `cutPath` puts a cut wherever something crosses,
+so that afterwards every piece is wholly inside the other path or wholly outside it. `containsPoint`
+decides which of those a piece is, by counting how many times the other path winds round its middle.
+`areaOf` says how much a path encloses, in closed form rather than by sampling, which is what every
+claim above is checked against.
+
+<img src="docs/boolean-strip.svg" width="960" alt="Four frames side by side, each showing the three panels, as the small disc walks from clear of the large one, through touching it at one point, through overlapping it, to sitting wholly inside it.">
+
+Four times of one figure. A small disc walks across a larger one: clear of it, touching it at one
+point, crossing it at two, and wholly inside it. Those are the four cases this kind of code gets
+silently wrong, which is why the demo walks through all of them rather than drawing one.
+
+Two edges that lie on top of each other for a stretch have no one answer, and what comes back for
+them is decided by the tolerance rather than by the geometry.
+
 ## The animations
 
-`fadeIn`, `fadeOut`, `fadeTo`, `draw`, `morph`, `morphEquation`, `moveBy`, `rotate`, `scale`,
-`growFrom`, `moveAlong`, `indicate`, `flash` and `circumscribe`. A `Timeline` plays them in order, plays several `together`, or
+`fadeIn`, `fadeOut`, `fadeTo`, `draw`, `morph`, `morphEquation`, `countTo`, `moveBy`, `rotate`,
+`scale`, `growFrom`, `moveAlong`, `indicate`, `flash` and `circumscribe`. A `Timeline` plays them in order, plays several `together`, or
 `stagger`s a row so its parts arrive one after another.
 
 A turn and a growth happen about a point the marks decide for themselves, which is the middle of the

package/dist/figure/animation.d.ts

@@ -43,6 +43,17 @@ export declare function morph(target: string, into: Path): Animation;
  * expression still fading in when a morph starts does not jump to solid.
  */
 export declare function morphEquation(from: string, to: string): Animation;
+/**
+ * A number ticking from one value to another, written into a text mark.
+ *
+ * How the value is written is the caller's, so this holds no opinion about
+ * decimal places: a count of a length and a count of a population want different
+ * rounding and neither is this function's to choose.
+ *
+ * The scene writes the value the count ends at, which is what this writes at the
+ * end of its span, so the two never disagree about what the number settles on.
+ */
+export declare function countTo(target: string, from: number, to: number, write: (value: number) => string): Animation;
 /** A mark's own opacity walked to a value, for a figure that wants a thing dimmed
  * rather than gone. */
 export declare function fadeTo(target: string, opacity: number): Animation;

package/dist/figure/animation.js

@@ -119,6 +119,19 @@ export function morphEquation(from, to) {
         return marks.map((mark) => changed.get(mark.id) ?? mark);
     };
 }
+/**
+ * A number ticking from one value to another, written into a text mark.
+ *
+ * How the value is written is the caller's, so this holds no opinion about
+ * decimal places: a count of a length and a count of a population want different
+ * rounding and neither is this function's to choose.
+ *
+ * The scene writes the value the count ends at, which is what this writes at the
+ * end of its span, so the two never disagree about what the number settles on.
+ */
+export function countTo(target, from, to, write) {
+    return over(target, (mark, along) => (mark.kind === 'text' ? { ...mark, text: write(lerp(from, to, along)) } : mark));
+}
 /** A mark's own opacity walked to a value, for a figure that wants a thing dimmed
  * rather than gone. */
 export function fadeTo(target, opacity) {

package/dist/figure/annotate.d.ts

@@ -8,6 +8,7 @@
  * filled at its head, and no mark can be both.
  */
 import { type Vec2 } from '../values/vec2.js';
+import { type Path } from './path.js';
 import { type GroupNode, type TextOptions } from './node.js';
 import type { Fill, Stroke } from './mark.js';
 export interface ArrowOptions {
@@ -32,6 +33,52 @@ export interface ArrowOptions {
 export declare function arrow(name: string, from: Vec2, to: Vec2, options: ArrowOptions): GroupNode;
 /** A filled disc, which is what marks a place a line is pointing at. */
 export declare function dot(name: string, at: Vec2, radius: number, fill: Fill): GroupNode;
+export interface BraceOptions {
+    /** How far the tip stands off the line between the two points, in figure
+     * units. A negative depth puts the brace on the other side of that line. */
+    depth: number;
+    /**
+     * How wide the curl at each end and at the tip is, in figure units. Half the
+     * depth unless named, which is the curl a quarter circle gives, and never more
+     * than a quarter of the span, since two curls wider than that would cross.
+     */
+    curl?: number;
+}
+/**
+ * A curly brace from one point to the other, with its tip standing off the line
+ * between them.
+ *
+ * It is one open subpath of six pieces: a curl out of each end, a run along at
+ * the curl's own height, and two curls meeting at the tip. The tip is a corner
+ * rather than a smooth turn, which is what a brace has and what says which point
+ * of it is being pointed at.
+ *
+ * The tip stands at the depth asked for whatever the span, and only the curl
+ * narrows when the span is short, so a brace between two close points is a
+ * shallower shape rather than one whose halves cross.
+ */
+export declare function bracePath(from: Vec2, to: Vec2, options: BraceOptions): Path;
+export interface BracedOptions extends BraceOptions {
+    stroke: Stroke;
+    fill: Fill;
+    size: number;
+    /** How far beyond the tip the label's anchor sits, in figure units. */
+    padding?: number;
+    align?: TextOptions['align'];
+    baseline?: TextOptions['baseline'];
+    family?: string;
+    weight?: number;
+}
+/**
+ * A brace with a word on it, placed beyond the tip on the far side from the two
+ * points.
+ *
+ * The label is anchored and never measured. Nothing about a figure's layout may
+ * depend on how wide some text is, because the width depends on which fonts the
+ * machine has and a box sized to fit a label would be a different box on two
+ * machines.
+ */
+export declare function brace(name: string, from: Vec2, to: Vec2, content: string, options: BracedOptions): GroupNode;
 export interface CalloutOptions {
     stroke: Stroke;
     fill: Fill;

package/dist/figure/annotate.js

@@ -8,7 +8,7 @@
  * filled at its head, and no mark can be both.
  */
 import { vec2 } from '../values/vec2.js';
-import { circle, line, polygon } from './path.js';
+import { circle, line, polygon, straight } from './path.js';
 import { group, shape, text } from './node.js';
 /**
  * A line with a head at the far end.
@@ -32,6 +32,80 @@ export function arrow(name, from, to, options) {
 export function dot(name, at, radius, fill) {
     return group(name, [shape('disc', circle(at, radius), { fill })]);
 }
+/** The control distance a quarter circle wants, which is what makes each curl of
+ * a brace an arc rather than a corner rounded by eye. */
+const QUARTER = (4 / 3) * (Math.SQRT2 - 1);
+/**
+ * A curly brace from one point to the other, with its tip standing off the line
+ * between them.
+ *
+ * It is one open subpath of six pieces: a curl out of each end, a run along at
+ * the curl's own height, and two curls meeting at the tip. The tip is a corner
+ * rather than a smooth turn, which is what a brace has and what says which point
+ * of it is being pointed at.
+ *
+ * The tip stands at the depth asked for whatever the span, and only the curl
+ * narrows when the span is short, so a brace between two close points is a
+ * shallower shape rather than one whose halves cross.
+ */
+export function bracePath(from, to, options) {
+    const span = vec2.distance(from, to);
+    if (span === 0)
+        return [];
+    const along = vec2.normalize(vec2.sub(to, from));
+    const out = vec2.perpendicular(along);
+    const depth = options.depth;
+    const curl = Math.min(Math.abs(options.curl ?? depth / 2), span / 4);
+    const rise = Math.sign(depth || 1) * curl;
+    const at = (forward, off) => vec2.add(from, vec2.add(vec2.scale(along, forward), vec2.scale(out, off)));
+    const shoulder = at(curl, rise);
+    const beforeTip = at(span / 2 - curl, rise);
+    const tip = at(span / 2, depth);
+    const afterTip = at(span / 2 + curl, rise);
+    const beyond = at(span - curl, rise);
+    const reach = QUARTER * curl;
+    const lift = QUARTER * (depth - rise);
+    const piece = (control1, control2, end) => ({ control1, control2, to: end });
+    return [
+        {
+            start: from,
+            curves: [
+                piece(vec2.add(from, vec2.scale(out, rise * QUARTER)), vec2.sub(shoulder, vec2.scale(along, reach)), shoulder),
+                straight(shoulder, beforeTip),
+                piece(vec2.add(beforeTip, vec2.scale(along, reach)), vec2.sub(tip, vec2.scale(out, lift)), tip),
+                piece(vec2.sub(tip, vec2.scale(out, lift)), vec2.sub(afterTip, vec2.scale(along, reach)), afterTip),
+                straight(afterTip, beyond),
+                piece(vec2.add(beyond, vec2.scale(along, reach)), vec2.add(to, vec2.scale(out, rise * QUARTER)), to),
+            ],
+            closed: false,
+        },
+    ];
+}
+/**
+ * A brace with a word on it, placed beyond the tip on the far side from the two
+ * points.
+ *
+ * The label is anchored and never measured. Nothing about a figure's layout may
+ * depend on how wide some text is, because the width depends on which fonts the
+ * machine has and a box sized to fit a label would be a different box on two
+ * machines.
+ */
+export function brace(name, from, to, content, options) {
+    const path = bracePath(from, to, options);
+    const padding = options.padding ?? Math.abs(options.depth) / 2;
+    const out = vec2.perpendicular(vec2.normalize(vec2.sub(to, from)));
+    const middle = vec2.lerp(from, to, 0.5);
+    const at = vec2.add(middle, vec2.scale(out, options.depth + Math.sign(options.depth || 1) * padding));
+    const style = { fill: options.fill, family: options.family, weight: options.weight };
+    return group(name, [
+        shape('brace', path, { stroke: options.stroke }),
+        text('word', at, content, options.size, {
+            ...style,
+            align: options.align ?? 'middle',
+            baseline: options.baseline ?? 'middle',
+        }),
+    ]);
+}
 /**
  * A word attached to a place: a disc on the place, a line out to where there is
  * room, and the word at the end of it.

package/dist/figure/area.d.ts

@@ -0,0 +1,22 @@
+/**
+ * How much a path encloses.
+ *
+ * This is Green's theorem, which turns the area inside a closed loop into an
+ * integral round its edge, and for a cubic that integral has a closed form. So
+ * the answer is worked out rather than sampled, and it is exact for the shape
+ * the cubics actually draw.
+ *
+ * The sign is the direction the loop is wound in, positive anticlockwise. That
+ * is what makes a hole subtract: a loop wound the other way inside another one
+ * encloses a negative amount, and the two added together are the ring.
+ */
+import type { Path } from './path.js';
+/**
+ * How much a path encloses, positive where it is wound anticlockwise.
+ *
+ * A subpath left open is closed by the straight run back to where it started,
+ * since an open loop encloses nothing on its own. Every subpath is added, so a
+ * ring written as an outer loop and an inner loop wound the other way comes
+ * back as the difference between the two discs.
+ */
+export declare function areaOf(path: Path): number;

package/dist/figure/area.js

@@ -0,0 +1,45 @@
+/** Twice the area of the triangle two points make with the origin, positive
+ * anticlockwise. */
+function wedge(a, b) {
+    return a.x * b.y - b.x * a.y;
+}
+/**
+ * What one piece contributes to the integral round the loop.
+ *
+ * Each pair of the piece's four points contributes the triangle it makes with
+ * the origin, and the weights are what integrating a cubic against its own
+ * derivative leaves: six, three, one, three, three and six twentieths, in the
+ * order the pairs are taken.
+ */
+function pieceArea(from, curve) {
+    const { control1, control2, to } = curve;
+    return ((6 * wedge(from, control1) +
+        3 * wedge(from, control2) +
+        wedge(from, to) +
+        3 * wedge(control1, control2) +
+        3 * wedge(control1, to) +
+        6 * wedge(control2, to)) /
+        20);
+}
+/**
+ * How much a path encloses, positive where it is wound anticlockwise.
+ *
+ * A subpath left open is closed by the straight run back to where it started,
+ * since an open loop encloses nothing on its own. Every subpath is added, so a
+ * ring written as an outer loop and an inner loop wound the other way comes
+ * back as the difference between the two discs.
+ */
+export function areaOf(path) {
+    let total = 0;
+    for (const subpath of path) {
+        if (subpath.curves.length === 0)
+            continue;
+        let from = subpath.start;
+        for (const curve of subpath.curves) {
+            total += pieceArea(from, curve);
+            from = curve.to;
+        }
+        total += wedge(from, subpath.start) / 2;
+    }
+    return total;
+}

package/dist/figure/boolean.d.ts

@@ -0,0 +1,13 @@
+import { type Path } from './path.js';
+export interface BooleanOptions {
+    /** How close two things come before they count as the same place, in the
+     * picture's own units. It decides where two paths are read as crossing and
+     * which ends are read as meeting. */
+    readonly tolerance?: number;
+}
+/** Everything either path covers. */
+export declare function unionOf(first: Path, second: Path, options?: BooleanOptions): Path;
+/** Only what both paths cover. */
+export declare function intersectionOf(first: Path, second: Path, options?: BooleanOptions): Path;
+/** The first path with the second taken out of it. */
+export declare function differenceOf(first: Path, second: Path, options?: BooleanOptions): Path;

package/dist/figure/boolean.js

@@ -0,0 +1,173 @@
+/**
+ * Union, intersection and difference on paths.
+ *
+ * Both paths are cut at every place they cross, so that after the cutting every
+ * piece is wholly inside the other path or wholly outside it. Each piece is
+ * then decided one way or the other, the operation says which pieces it wants,
+ * and what is kept is stitched back into loops by joining ends that meet.
+ *
+ * The difference takes the second path's kept pieces the other way round, which
+ * is what turns a disc taken out of the middle of another disc into a ring: the
+ * inner loop is wound against the outer one and the nonzero rule the mark
+ * carries leaves it empty.
+ */
+import { vec2 } from '../values/vec2.js';
+import { pointOn } from './path.js';
+import { cutPath } from './cut.js';
+import { curveCrossings } from './intersect.js';
+import { flattenPath, windingAt } from './inside.js';
+const TOLERANCE = 1e-6;
+/** A subpath left open closed by the straight run back to where it started,
+ * since a path with an open loop has no inside for any of this to ask about. */
+function closedLoops(path) {
+    return path.map((subpath) => {
+        if (subpath.curves.length === 0)
+            return subpath;
+        const end = subpath.curves[subpath.curves.length - 1].to;
+        if (subpath.closed && end.x === subpath.start.x && end.y === subpath.start.y) {
+            return subpath;
+        }
+        const curves = end.x === subpath.start.x && end.y === subpath.start.y
+            ? subpath.curves
+            : [
+                ...subpath.curves,
+                {
+                    control1: vec2.lerp(end, subpath.start, 1 / 3),
+                    control2: vec2.lerp(end, subpath.start, 2 / 3),
+                    to: subpath.start,
+                },
+            ];
+        return { start: subpath.start, curves, closed: true };
+    });
+}
+function piecesOf(path) {
+    const pieces = [];
+    for (const subpath of path) {
+        let from = subpath.start;
+        for (const curve of subpath.curves) {
+            pieces.push({ from, curve });
+            from = curve.to;
+        }
+    }
+    return pieces;
+}
+/** A piece walked the other way, which is what puts a hole the opposite way
+ * round from the loop it sits in. */
+function reversed(piece) {
+    return {
+        from: piece.curve.to,
+        curve: { control1: piece.curve.control2, control2: piece.curve.control1, to: piece.from },
+    };
+}
+/** Where the two paths cross, as the cuts each of them needs. */
+function cutsBetween(first, second, tolerance) {
+    const forFirst = [];
+    const forSecond = [];
+    for (let left = 0; left < first.length; left++) {
+        let leftFrom = first[left].start;
+        for (let leftPiece = 0; leftPiece < first[left].curves.length; leftPiece++) {
+            const leftCurve = first[left].curves[leftPiece];
+            for (let right = 0; right < second.length; right++) {
+                let rightFrom = second[right].start;
+                for (let rightPiece = 0; rightPiece < second[right].curves.length; rightPiece++) {
+                    const rightCurve = second[right].curves[rightPiece];
+                    for (const crossing of curveCrossings(leftFrom, leftCurve, rightFrom, rightCurve, { tolerance })) {
+                        forFirst.push({ subpath: left, curve: leftPiece, along: crossing.alongFirst });
+                        forSecond.push({ subpath: right, curve: rightPiece, along: crossing.alongSecond });
+                    }
+                    rightFrom = rightCurve.to;
+                }
+            }
+            leftFrom = leftCurve.to;
+        }
+    }
+    return [forFirst, forSecond];
+}
+/**
+ * The kept pieces joined into loops, by taking each end to the piece that
+ * starts where it finishes.
+ *
+ * A piece carries its two controls and where it ends, so the loop takes where
+ * each piece begins from where the piece before it ended. The two paths put
+ * their cut at a place they each worked out on their own, so the two ends of a
+ * join differ by whatever the crossing was out by, and that difference is
+ * absorbed here rather than left as a gap.
+ */
+function stitch(pieces, tolerance) {
+    const used = pieces.map(() => false);
+    const loops = [];
+    for (let seed = 0; seed < pieces.length; seed++) {
+        if (used[seed])
+            continue;
+        used[seed] = true;
+        const start = pieces[seed].from;
+        const curves = [pieces[seed].curve];
+        let end = pieces[seed].curve.to;
+        while (vec2.distance(end, start) > tolerance) {
+            let next = -1;
+            let nearest = tolerance;
+            for (let at = 0; at < pieces.length; at++) {
+                if (used[at])
+                    continue;
+                const gap = vec2.distance(pieces[at].from, end);
+                if (gap <= nearest) {
+                    nearest = gap;
+                    next = at;
+                }
+            }
+            if (next < 0)
+                break;
+            used[next] = true;
+            curves.push(pieces[next].curve);
+            end = pieces[next].curve.to;
+        }
+        loops.push({ start, curves, closed: true });
+    }
+    return loops;
+}
+/** Which side of the other path each piece falls on, taken at its middle, which
+ * after the cutting stands for the whole piece. */
+function insideOther(pieces, other) {
+    return pieces.map((piece) => windingAt(other, pointOn(piece.from, piece.curve, 0.5)) !== 0);
+}
+function combine(first, second, keep, options) {
+    const tolerance = options.tolerance ?? TOLERANCE;
+    const left = closedLoops(first);
+    const right = closedLoops(second);
+    if (left.length === 0)
+        return keep === 'union' ? right : [];
+    if (right.length === 0)
+        return keep === 'intersection' ? [] : left;
+    const [leftCuts, rightCuts] = cutsBetween(left, right, tolerance);
+    const leftPieces = piecesOf(cutPath(left, leftCuts, { tolerance }));
+    const rightPieces = piecesOf(cutPath(right, rightCuts, { tolerance }));
+    const leftInside = insideOther(leftPieces, flattenPath(right, { tolerance }));
+    const rightInside = insideOther(rightPieces, flattenPath(left, { tolerance }));
+    const kept = [];
+    for (let at = 0; at < leftPieces.length; at++) {
+        if (leftInside[at] === (keep === 'intersection'))
+            kept.push(leftPieces[at]);
+    }
+    for (let at = 0; at < rightPieces.length; at++) {
+        if (keep === 'difference') {
+            if (rightInside[at])
+                kept.push(reversed(rightPieces[at]));
+            continue;
+        }
+        if (rightInside[at] === (keep === 'intersection'))
+            kept.push(rightPieces[at]);
+    }
+    return stitch(kept, tolerance);
+}
+/** Everything either path covers. */
+export function unionOf(first, second, options = {}) {
+    return combine(first, second, 'union', options);
+}
+/** Only what both paths cover. */
+export function intersectionOf(first, second, options = {}) {
+    return combine(first, second, 'intersection', options);
+}
+/** The first path with the second taken out of it. */
+export function differenceOf(first, second, options = {}) {
+    return combine(first, second, 'difference', options);
+}

package/dist/figure/cut.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A path cut where something crosses it.
+ *
+ * Each cut names a piece and how far along it the cut falls, and the pieces
+ * that come back draw exactly what the pieces they replace drew, because de
+ * Casteljau's construction gives both halves of a cubic as cubics. Several cuts
+ * in one piece are taken in order, and each one after the first is measured
+ * against what is left rather than against the piece it started as.
+ */
+import { type Path } from './path.js';
+/** Where one cut falls: which subpath, which piece of it, and how far along
+ * that piece. */
+export interface Cut {
+    readonly subpath: number;
+    readonly curve: number;
+    readonly along: number;
+}
+export interface CutOptions {
+    /** How close two cuts, or a cut and the end of a piece, are before they count
+     * as the same place, in the picture's own units. */
+    readonly tolerance?: number;
+}
+/**
+ * A path with every cut put in, drawing what it drew and holding one more piece
+ * for each cut.
+ *
+ * The tolerance is a distance rather than a fraction, so it is read against
+ * each piece's own length: a cut is worth making only where the piece it would
+ * leave behind is long enough to see, and a piece of nothing is one the stitch
+ * that follows would have to know to skip.
+ *
+ * A cut naming a piece the path does not have is ignored, since a caller that
+ * has already thrown one subpath away should not have to renumber the cuts it
+ * gathered before it did.
+ */
+export declare function cutPath(path: Path, cuts: readonly Cut[], options?: CutOptions): Path;