@altpsyche/maths 0.9.2 → 0.9.4

package/README.md

@@ -195,14 +195,22 @@ decides which of those a piece is, by counting how many times the other path win
 `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.
+<img src="docs/boolean-strip.svg" width="820" alt="Four moments in two rows, 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, in two rows. 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 shapes that share an edge are combined by which way each of them runs over it. Two paths walking
+a shared stretch the same way have their solid on the same side of it, so the stretch is on the edge
+of a union and of an overlap and is kept once. Walking it opposite ways puts their solids on opposite
+sides, so the stretch is inside a union and outside an overlap, and a difference keeps the first
+path's copy of it. Two rectangles sharing an edge unite into one rectangle, and a shape combined with
+itself gives itself back.
+
+When the pieces kept will not join into a loop, the operation stops and says how far apart the two
+ends of the run it had are. That happens when an input crosses itself, which these do not take. A
+shape drawn with a gap in it and nothing said about it is the one failure a caller cannot see.
 
 ## The animations
 

package/dist/figure/animation.js

@@ -141,9 +141,9 @@ export function fadeTo(target, opacity) {
  * A mark carried through a transform, geometry and weight together.
  *
  * A transform that scales makes the lines inside it thicker and the words
- * bigger, the way it makes everything else bigger, which is what `flatten`
- * already does for a group that scales. Doing less here would leave a shrinking
- * mark with the stroke it started at.
+ * bigger, the way it makes everything else bigger, which is what a group that
+ * scales already does to the marks under it. Doing less here would leave a
+ * shrinking mark with the stroke it started at.
  */
 function carried(mark, through) {
     const scale = mat3.scaleFactor(through);

package/dist/figure/axis.d.ts

@@ -28,6 +28,10 @@ export interface NumberLineOptions {
     /** Leaves the label at zero out, which is what a second axis crossing here
      * wants, since both would otherwise write the same number in the same place. */
     skipZero?: boolean;
+    /** The number on this line another line crosses it at. The label there is
+     * written below and to the left of the crossing rather than under it, since
+     * under it is where the other line and its head already are. */
+    crossedAt?: number;
 }
 /**
  * One axis as a group: the line, the ticks under `ticks`, the labels under
@@ -61,6 +65,10 @@ export interface NumberPlaneOptions {
     /** How much of the stroke a minor line is drawn with, since a grid a reader
      * notices is a grid competing with the curve on top of it. */
     minorOpacity?: number;
+    /** How wide a minor line is against a major one. A minor line that differs
+     * only in how strong its ink is reads as the same line, so the grid comes out
+     * flat and busy. */
+    minorWidth?: number;
     ticks?: number;
 }
 /**

package/dist/figure/axis.js

@@ -37,14 +37,17 @@ export function numberLine(name, scale, options) {
     const gap = options.gap ?? size * 0.35;
     const { from: low, to: high } = interval.ordered(scale.units);
     const at = (along, off) => (across ? vec2(along, seat + off) : vec2(seat + off, along));
-    // The line stops where a head begins rather than running under it, because a
-    // line drawn to the point shows through a head that is not fully opaque.
-    const parts = [shape('line', line(at(low + tip, 0), at(high - tip, 0)), { stroke: options.stroke })];
+    // The line runs the whole of the axis and each head stands beyond its end,
+    // rather than the heads eating into the line. Eating in leaves the outermost
+    // tick standing under a head instead of on the line, and the line still stops
+    // where a head begins, so a head that is not fully opaque has nothing showing
+    // through it.
+    const parts = [shape('line', line(at(low, 0), at(high, 0)), { stroke: options.stroke })];
     if (tip > 0 && options.fill) {
         const spread = options.spread ?? 0.6;
         parts.push(group('tips', [
-            shape('low', head(at(low, 0), at(low + tip, 0), spread), { fill: options.fill }),
-            shape('high', head(at(high, 0), at(high - tip, 0), spread), { fill: options.fill }),
+            shape('low', head(at(low - tip, 0), at(low, 0), spread), { fill: options.fill }),
+            shape('high', head(at(high + tip, 0), at(high, 0), spread), { fill: options.fill }),
         ]));
     }
     const step = tickStep(scale.graph, options.ticks);
@@ -57,17 +60,22 @@ export function numberLine(name, scale, options) {
     if (options.fill && size > 0) {
         // Placed by an anchor and an alignment and never by how wide the text is,
         // so a long label moves nothing else in the figure.
-        const align = across ? 'middle' : 'end';
-        const baseline = across ? 'hanging' : 'middle';
         const written = marked.filter((tick) => !(options.skipZero && tick.value === 0));
+        const off = half + gap;
         parts.push(group('labels', written.map((tick) => {
             const along = interval.remap(tick.value, scale.graph, scale.units);
-            return text(tick.label, at(along, -(half + gap)), tick.label, size, {
+            const crossed = options.crossedAt !== undefined && tick.value === options.crossedAt;
+            const anchor = crossed
+                ? across
+                    ? vec2(along - off, seat - off)
+                    : vec2(seat - off, along - off)
+                : at(along, -off);
+            return text(tick.label, anchor, tick.label, size, {
                 fill: options.fill,
                 family: options.family,
                 weight: options.weight,
-                align,
-                baseline,
+                align: crossed || !across ? 'end' : 'middle',
+                baseline: crossed || across ? 'hanging' : 'middle',
             });
         })));
     }
@@ -85,7 +93,12 @@ export function axes(name, coords, options) {
     const holdsOrigin = interval.holds(coords.x.graph, 0) && interval.holds(coords.y.graph, 0);
     const seat = (scale) => scaled(scale, interval.clampTo(scale.graph, 0));
     return group(name, [
-        numberLine('x', coords.x, { ...options, at: seat(coords.y), direction: 'across' }),
+        numberLine('x', coords.x, {
+            ...options,
+            at: seat(coords.y),
+            direction: 'across',
+            crossedAt: holdsOrigin ? 0 : undefined,
+        }),
         numberLine('y', coords.y, { ...options, at: seat(coords.x), direction: 'up', skipZero: holdsOrigin }),
     ]);
 }
@@ -124,7 +137,12 @@ export function numberPlane(name, coords, options) {
         parts.push(group('minors', [
             group('x', gridLines(coords, step.x / minors, 'x', step.x)),
             group('y', gridLines(coords, step.y / minors, 'y', step.y)),
-        ], { style: { stroke: options.stroke, opacity: options.minorOpacity ?? 0.4 } }));
+        ], {
+            style: {
+                stroke: { ...options.stroke, width: options.stroke.width * (options.minorWidth ?? 0.6) },
+                opacity: options.minorOpacity ?? 0.4,
+            },
+        }));
     }
     parts.push(group('majors', [group('x', gridLines(coords, step.x, 'x')), group('y', gridLines(coords, step.y, 'y'))], {
         style: { stroke: options.stroke },

package/dist/figure/boolean.js

@@ -24,7 +24,7 @@ import { pointOn, slopeOn } from './path.js';
 import { cutPath } from './cut.js';
 import { curveCrossings } from './intersect.js';
 import { flattenPath, nearestEdge, windingAt } from './inside.js';
-const TOLERANCE = 1e-6;
+import { TOLERANCE } from './tolerance.js';
 /** 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) {

package/dist/figure/cut.js

@@ -9,7 +9,7 @@
  */
 import { splitCurve } from './path.js';
 import { measurePath } from './length.js';
-const TOLERANCE = 1e-9;
+import { TOLERANCE } from './tolerance.js';
 /** The fractions for one piece, in order, with the ones that would leave a
  * piece of nothing dropped. */
 function wanted(fractions, tolerance) {

package/dist/figure/equation.js

@@ -22,7 +22,8 @@
  * expressions has to be made on.
  *
  * Three things stop the walk instead of being drawn, and each names what it
- * found. They are written up on `refuse` below.
+ * found: a TeX error, a character the font has no outline for, and a macro the
+ * typesetter does not know.
  */
 import { mat3 } from '../values/mat3.js';
 import { vec2 } from '../values/vec2.js';

package/dist/figure/inside.d.ts

@@ -49,5 +49,9 @@ export declare function nearestEdge(loops: readonly (readonly Vec2[])[], point:
  *
  * A point sitting on the edge itself has no answer this can be right about, and
  * what comes back for one is whichever side the tolerance put it on.
+ *
+ * The path is flattened again on every call, which is a millisecond every three
+ * points against a path of a hundred pieces. Asking about many points wants the
+ * flattening made once and the count taken against it.
  */
 export declare function containsPoint(path: Path, point: Vec2, options?: FlattenOptions): boolean;

package/dist/figure/inside.js

@@ -14,7 +14,7 @@
  * ray answers.
  */
 import { vec2 } from '../values/vec2.js';
-const TOLERANCE = 1e-6;
+import { TOLERANCE } from './tolerance.js';
 /** How many times a piece may be halved, which a tolerance of zero would
  * otherwise leave unbounded. */
 const DEPTH = 24;
@@ -136,6 +136,10 @@ export function nearestEdge(loops, point) {
  *
  * A point sitting on the edge itself has no answer this can be right about, and
  * what comes back for one is whichever side the tolerance put it on.
+ *
+ * The path is flattened again on every call, which is a millisecond every three
+ * points against a path of a hundred pieces. Asking about many points wants the
+ * flattening made once and the count taken against it.
  */
 export function containsPoint(path, point, options = {}) {
     return windingAt(flattenPath(path, options), point) !== 0;

package/dist/figure/intersect.d.ts

@@ -13,8 +13,14 @@
  */
 import { type Vec2 } from '../values/vec2.js';
 import type { Cubic } from './path.js';
-/** One place two curves meet, as a fraction along each of them and the point
- * itself. */
+/**
+ * One place two curves meet, as a fraction along each of them and the point.
+ *
+ * The point is read off the first curve. Where the two cross cleanly the second
+ * curve's own fraction lands on the same point to the last few bits, and where
+ * they meet without crossing it can land as far off as the tolerance, since
+ * Newton has no step to take when the two are heading the same way.
+ */
 export interface Crossing {
     readonly alongFirst: number;
     readonly alongSecond: number;
@@ -22,7 +28,8 @@ export interface Crossing {
 }
 export interface CrossingOptions {
     /** How close two pieces come before they count as meeting, in the picture's
-     * own units. */
+     * own units. It decides which meetings are told apart rather than how sharp
+     * one is, since Newton's method supplies the sharpness afterwards. */
     readonly tolerance?: number;
 }
 /**

package/dist/figure/intersect.js

@@ -12,10 +12,7 @@
  * tolerance to the last few bits.
  */
 import { vec2 } from '../values/vec2.js';
-/** How close two pieces come before they count as meeting. It decides which
- * meetings are told apart rather than how sharp one is, since Newton's method
- * supplies the sharpness afterwards. */
-const TOLERANCE = 1e-6;
+import { TOLERANCE } from './tolerance.js';
 /**
  * How many pairs the search may make before it answers with where it had got to.
  *

package/dist/figure/tolerance.d.ts

@@ -0,0 +1,15 @@
+/**
+ * How close two things come before this package reads them as the same place.
+ *
+ * It is a distance in the picture's own units rather than a share of anything,
+ * so a figure drawn in units of thousands wants its own number passed in. Every
+ * call that takes a tolerance takes it as a distance and defaults to this one,
+ * so a crossing, a cut, a flattening and a stitch all agree about what counts as
+ * one place without a caller having to line four numbers up.
+ *
+ * A millionth of a figure unit is a ten thousandth of a pixel at the hundred
+ * pixels to the unit the demos draw at, so nothing this decides is visible. What
+ * it decides is which meetings are told apart, since two crossings closer than
+ * this come back as one.
+ */
+export declare const TOLERANCE = 0.000001;

package/dist/figure/tolerance.js

@@ -0,0 +1,15 @@
+/**
+ * How close two things come before this package reads them as the same place.
+ *
+ * It is a distance in the picture's own units rather than a share of anything,
+ * so a figure drawn in units of thousands wants its own number passed in. Every
+ * call that takes a tolerance takes it as a distance and defaults to this one,
+ * so a crossing, a cut, a flattening and a stitch all agree about what counts as
+ * one place without a caller having to line four numbers up.
+ *
+ * A millionth of a figure unit is a ten thousandth of a pixel at the hundred
+ * pixels to the unit the demos draw at, so nothing this decides is visible. What
+ * it decides is which meetings are told apart, since two crossings closer than
+ * this come back as one.
+ */
+export const TOLERANCE = 1e-6;

package/dist/index.d.ts

@@ -23,6 +23,7 @@ export type { Key, Track, TrackValue, Tracks } from './timing/track.js';
 export { arc, circle, line, polygon, polyline, pointCount, pointOn, rect, slopeOn, splitCurve, straight, transformPath } from './figure/path.js';
 export type { Cubic, Path, Subpath } from './figure/path.js';
 export { pathFromData } from './figure/path-data.js';
+export { TOLERANCE } from './figure/tolerance.js';
 export { areaOf } from './figure/area.js';
 export { differenceOf, intersectionOf, unionOf } from './figure/boolean.js';
 export type { BooleanOptions } from './figure/boolean.js';

package/dist/index.js

@@ -16,6 +16,7 @@ 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, slopeOn, splitCurve, straight, transformPath } from './figure/path.js';
 export { pathFromData } from './figure/path-data.js';
+export { TOLERANCE } from './figure/tolerance.js';
 export { areaOf } from './figure/area.js';
 export { differenceOf, intersectionOf, unionOf } from './figure/boolean.js';
 export { containsPoint, flattenPath, nearestEdge, windingAt } from './figure/inside.js';

package/package.json

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