@js-draw/math 1.9.0 → 1.10.0

package/dist/cjs/lib.d.ts

@@ -20,6 +20,7 @@ export { LineSegment2 } from './shapes/LineSegment2';
 export { Path, PathCommandType, PathCommand, LinePathCommand, MoveToPathCommand, QuadraticBezierPathCommand, CubicBezierPathCommand, } from './shapes/Path';
 export { Rect2 } from './shapes/Rect2';
 export { QuadraticBezier } from './shapes/QuadraticBezier';
+export { Abstract2DShape } from './shapes/Abstract2DShape';
 export { Mat33, Mat33Array } from './Mat33';
 export { Point2, Vec2 } from './Vec2';
 export { Vec3 } from './Vec3';

package/dist/cjs/lib.js

@@ -18,7 +18,7 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toRoundedString = exports.Color4 = exports.Vec3 = exports.Vec2 = exports.Mat33 = exports.QuadraticBezier = exports.Rect2 = exports.PathCommandType = exports.Path = exports.LineSegment2 = void 0;
+exports.toRoundedString = exports.Color4 = exports.Vec3 = exports.Vec2 = exports.Mat33 = exports.Abstract2DShape = exports.QuadraticBezier = exports.Rect2 = exports.PathCommandType = exports.Path = exports.LineSegment2 = void 0;
 var LineSegment2_1 = require("./shapes/LineSegment2");
 Object.defineProperty(exports, "LineSegment2", { enumerable: true, get: function () { return LineSegment2_1.LineSegment2; } });
 var Path_1 = require("./shapes/Path");
@@ -28,6 +28,8 @@ var Rect2_1 = require("./shapes/Rect2");
 Object.defineProperty(exports, "Rect2", { enumerable: true, get: function () { return Rect2_1.Rect2; } });
 var QuadraticBezier_1 = require("./shapes/QuadraticBezier");
 Object.defineProperty(exports, "QuadraticBezier", { enumerable: true, get: function () { return QuadraticBezier_1.QuadraticBezier; } });
+var Abstract2DShape_1 = require("./shapes/Abstract2DShape");
+Object.defineProperty(exports, "Abstract2DShape", { enumerable: true, get: function () { return Abstract2DShape_1.Abstract2DShape; } });
 var Mat33_1 = require("./Mat33");
 Object.defineProperty(exports, "Mat33", { enumerable: true, get: function () { return Mat33_1.Mat33; } });
 var Vec2_1 = require("./Vec2");

package/dist/cjs/shapes/Abstract2DShape.d.ts

@@ -1,7 +1,10 @@
 import LineSegment2 from './LineSegment2';
 import { Point2 } from '../Vec2';
 import Rect2 from './Rect2';
-declare abstract class Abstract2DShape {
+/**
+ * An abstract base class for 2D shapes.
+ */
+export declare abstract class Abstract2DShape {
     protected static readonly smallValue = 1e-12;
     /**
      * @returns the distance from `point` to this shape. If `point` is within this shape,

package/dist/cjs/shapes/Abstract2DShape.js

@@ -1,5 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Abstract2DShape = void 0;
+/**
+ * An abstract base class for 2D shapes.
+ */
 class Abstract2DShape {
     /**
      * @returns the distance from `point` to this shape. If `point` is within this shape,
@@ -34,5 +38,7 @@ class Abstract2DShape {
         return this.getTightBoundingBox();
     }
 }
+exports.Abstract2DShape = Abstract2DShape;
+// @internal
 Abstract2DShape.smallValue = 1e-12;
 exports.default = Abstract2DShape;

package/dist/cjs/shapes/Path.d.ts

@@ -35,24 +35,29 @@ interface IntersectionResult {
     parameterValue?: number;
     point: Point2;
 }
-type GeometryType = Abstract2DShape;
-type GeometryArrayType = Array<GeometryType>;
 /**
  * Represents a union of lines and curves.
  */
 export declare class Path {
     readonly startPoint: Point2;
-    readonly parts: PathCommand[];
     /**
      * A rough estimate of the bounding box of the path.
      * A slight overestimate.
      * See {@link getExactBBox}
      */
     readonly bbox: Rect2;
-    constructor(startPoint: Point2, parts: PathCommand[]);
+    /** The individual shapes that make up this path. */
+    readonly parts: Readonly<PathCommand>[];
+    /**
+     * Creates a new `Path` that starts at `startPoint` and is made up of the path commands,
+     * `parts`.
+     *
+     * See also {@link fromString}
+     */
+    constructor(startPoint: Point2, parts: Readonly<PathCommand>[]);
     getExactBBox(): Rect2;
     private cachedGeometry;
-    get geometry(): GeometryArrayType;
+    get geometry(): Abstract2DShape[];
     /**
      * Iterates through the start/end points of each component in this path.
      *
@@ -77,6 +82,8 @@ export declare class Path {
      * intersections are approximated with the surface `strokeRadius` away from this.
      *
      * If `strokeRadius > 0`, the resultant `parameterValue` has no defined value.
+     *
+     * **Note**: `strokeRadius` is half of a stroke's width.
      */
     intersection(line: LineSegment2, strokeRadius?: number): IntersectionResult[];
     private static mapPathCommand;
@@ -84,6 +91,16 @@ export declare class Path {
     transformedBy(affineTransfm: Mat33): Path;
     union(other: Path | null): Path;
     private getEndPoint;
+    /**
+     * Like {@link closedRoughlyIntersects} except takes stroke width into account.
+     *
+     * This is intended to be a very fast and rough approximation. Use {@link intersection}
+     * and {@link signedDistance} for more accurate (but much slower) intersection calculations.
+     *
+     * **Note**: Unlike other methods, this accepts `strokeWidth` (and not `strokeRadius`).
+     *
+     * `strokeRadius` is half of `strokeWidth`.
+     */
     roughlyIntersects(rect: Rect2, strokeWidth?: number): boolean;
     closedRoughlyIntersects(rect: Rect2): boolean;
     /**
@@ -95,16 +112,32 @@ export declare class Path {
      */
     static fromRect(rect: Rect2, lineWidth?: number | null): Path;
     private cachedStringVersion;
-    toString(useNonAbsCommands?: boolean): string;
+    /**
+     * Convert to an [SVG path representation](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths).
+     *
+     * If `useNonAbsCommands` is given, relative path commands (e.g. `l10,0`) are to be used instead of
+     * absolute commands (e.g. `L10,0`).
+     *
+     * See also {@link fromString}.
+     */
+    toString(useNonAbsCommands?: boolean, ignoreCache?: boolean): string;
     serialize(): string;
     static toString(startPoint: Point2, parts: PathCommand[], onlyAbsCommands?: boolean): string;
     /**
-     * Create a Path from a SVG path specification.
+     * Create a `Path` from a subset of the SVG path specification.
      *
      * ## To-do
      * - TODO: Support a larger subset of SVG paths
      *   - Elliptical arcs are currently unsupported.
      * - TODO: Support `s`,`t` commands shorthands.
+     *
+     * @example
+     * ```ts,runnable,console
+     * import { Path } from '@js-draw/math';
+     *
+     * const path = Path.fromString('m0,0l100,100');
+     * console.log(path.toString(true)); // true: Prefer relative to absolute path commands
+     * ```
      */
     static fromString(pathString: string): Path;
     static empty: Path;

package/dist/cjs/shapes/Path.js

@@ -22,17 +22,23 @@ var PathCommandType;
  * Represents a union of lines and curves.
  */
 class Path {
+    /**
+     * Creates a new `Path` that starts at `startPoint` and is made up of the path commands,
+     * `parts`.
+     *
+     * See also {@link fromString}
+     */
     constructor(startPoint, parts) {
         this.startPoint = startPoint;
-        this.parts = parts;
         this.cachedGeometry = null;
         this.cachedPolylineApproximation = null;
         this.cachedStringVersion = null;
+        this.parts = parts;
         // Initial bounding box contains one point: the start point.
         this.bbox = Rect2_1.default.bboxOf([startPoint]);
         // Convert into a representation of the geometry (cache for faster intersection
         // calculation)
-        for (const part of parts) {
+        for (const part of this.parts) {
             this.bbox = this.bbox.union(Path.computeBBoxForSegment(startPoint, part));
         }
     }
@@ -337,6 +343,8 @@ class Path {
      * intersections are approximated with the surface `strokeRadius` away from this.
      *
      * If `strokeRadius > 0`, the resultant `parameterValue` has no defined value.
+     *
+     * **Note**: `strokeRadius` is half of a stroke's width.
      */
     intersection(line, strokeRadius) {
         let result = [];
@@ -432,6 +440,16 @@ class Path {
             return lastPart.point;
         }
     }
+    /**
+     * Like {@link closedRoughlyIntersects} except takes stroke width into account.
+     *
+     * This is intended to be a very fast and rough approximation. Use {@link intersection}
+     * and {@link signedDistance} for more accurate (but much slower) intersection calculations.
+     *
+     * **Note**: Unlike other methods, this accepts `strokeWidth` (and not `strokeRadius`).
+     *
+     * `strokeRadius` is half of `strokeWidth`.
+     */
     roughlyIntersects(rect, strokeWidth = 0) {
         if (this.parts.length === 0) {
             return rect.containsPoint(this.startPoint);
@@ -459,7 +477,7 @@ class Path {
         }
         return false;
     }
-    // Treats this as a closed path and returns true if part of `rect` is roughly within
+    // Treats this as a closed path and returns true if part of `rect` is *roughly* within
     // this path's interior.
     //
     // Note: Assumes that this is a closed, non-self-intersecting path.
@@ -541,8 +559,16 @@ class Path {
         });
         return new Path(startPoint, commands);
     }
-    toString(useNonAbsCommands) {
-        if (this.cachedStringVersion) {
+    /**
+     * Convert to an [SVG path representation](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths).
+     *
+     * If `useNonAbsCommands` is given, relative path commands (e.g. `l10,0`) are to be used instead of
+     * absolute commands (e.g. `L10,0`).
+     *
+     * See also {@link fromString}.
+     */
+    toString(useNonAbsCommands, ignoreCache = false) {
+        if (this.cachedStringVersion && !ignoreCache) {
             return this.cachedStringVersion;
         }
         if (useNonAbsCommands === undefined) {
@@ -632,12 +658,20 @@ class Path {
         return result.join('');
     }
     /**
-     * Create a Path from a SVG path specification.
+     * Create a `Path` from a subset of the SVG path specification.
      *
      * ## To-do
      * - TODO: Support a larger subset of SVG paths
      *   - Elliptical arcs are currently unsupported.
      * - TODO: Support `s`,`t` commands shorthands.
+     *
+     * @example
+     * ```ts,runnable,console
+     * import { Path } from '@js-draw/math';
+     *
+     * const path = Path.fromString('m0,0l100,100');
+     * console.log(path.toString(true)); // true: Prefer relative to absolute path commands
+     * ```
      */
     static fromString(pathString) {
         // See the MDN reference:

package/dist/mjs/lib.d.ts

@@ -20,6 +20,7 @@ export { LineSegment2 } from './shapes/LineSegment2';
 export { Path, PathCommandType, PathCommand, LinePathCommand, MoveToPathCommand, QuadraticBezierPathCommand, CubicBezierPathCommand, } from './shapes/Path';
 export { Rect2 } from './shapes/Rect2';
 export { QuadraticBezier } from './shapes/QuadraticBezier';
+export { Abstract2DShape } from './shapes/Abstract2DShape';
 export { Mat33, Mat33Array } from './Mat33';
 export { Point2, Vec2 } from './Vec2';
 export { Vec3 } from './Vec3';

package/dist/mjs/lib.mjs

@@ -20,6 +20,7 @@ export  { LineSegment2 }  from './shapes/LineSegment2.mjs';
 export  { Path, PathCommandType, }  from './shapes/Path.mjs';
 export  { Rect2 }  from './shapes/Rect2.mjs';
 export  { QuadraticBezier }  from './shapes/QuadraticBezier.mjs';
+export  { Abstract2DShape }  from './shapes/Abstract2DShape.mjs';
 export  { Mat33 }  from './Mat33.mjs';
 export  { Vec2 }  from './Vec2.mjs';
 export  { Vec3 }  from './Vec3.mjs';

package/dist/mjs/shapes/Abstract2DShape.d.ts

@@ -1,7 +1,10 @@
 import LineSegment2 from './LineSegment2';
 import { Point2 } from '../Vec2';
 import Rect2 from './Rect2';
-declare abstract class Abstract2DShape {
+/**
+ * An abstract base class for 2D shapes.
+ */
+export declare abstract class Abstract2DShape {
     protected static readonly smallValue = 1e-12;
     /**
      * @returns the distance from `point` to this shape. If `point` is within this shape,

package/dist/mjs/shapes/Abstract2DShape.mjs

@@ -1,4 +1,7 @@
-class Abstract2DShape {
+/**
+ * An abstract base class for 2D shapes.
+ */
+export class Abstract2DShape {
     /**
      * @returns the distance from `point` to this shape. If `point` is within this shape,
      * this returns the distance from `point` to the edge of this shape.
@@ -32,5 +35,6 @@ class Abstract2DShape {
         return this.getTightBoundingBox();
     }
 }
+// @internal
 Abstract2DShape.smallValue = 1e-12;
 export default Abstract2DShape;

package/dist/mjs/shapes/Path.d.ts

@@ -35,24 +35,29 @@ interface IntersectionResult {
     parameterValue?: number;
     point: Point2;
 }
-type GeometryType = Abstract2DShape;
-type GeometryArrayType = Array<GeometryType>;
 /**
  * Represents a union of lines and curves.
  */
 export declare class Path {
     readonly startPoint: Point2;
-    readonly parts: PathCommand[];
     /**
      * A rough estimate of the bounding box of the path.
      * A slight overestimate.
      * See {@link getExactBBox}
      */
     readonly bbox: Rect2;
-    constructor(startPoint: Point2, parts: PathCommand[]);
+    /** The individual shapes that make up this path. */
+    readonly parts: Readonly<PathCommand>[];
+    /**
+     * Creates a new `Path` that starts at `startPoint` and is made up of the path commands,
+     * `parts`.
+     *
+     * See also {@link fromString}
+     */
+    constructor(startPoint: Point2, parts: Readonly<PathCommand>[]);
     getExactBBox(): Rect2;
     private cachedGeometry;
-    get geometry(): GeometryArrayType;
+    get geometry(): Abstract2DShape[];
     /**
      * Iterates through the start/end points of each component in this path.
      *
@@ -77,6 +82,8 @@ export declare class Path {
      * intersections are approximated with the surface `strokeRadius` away from this.
      *
      * If `strokeRadius > 0`, the resultant `parameterValue` has no defined value.
+     *
+     * **Note**: `strokeRadius` is half of a stroke's width.
      */
     intersection(line: LineSegment2, strokeRadius?: number): IntersectionResult[];
     private static mapPathCommand;
@@ -84,6 +91,16 @@ export declare class Path {
     transformedBy(affineTransfm: Mat33): Path;
     union(other: Path | null): Path;
     private getEndPoint;
+    /**
+     * Like {@link closedRoughlyIntersects} except takes stroke width into account.
+     *
+     * This is intended to be a very fast and rough approximation. Use {@link intersection}
+     * and {@link signedDistance} for more accurate (but much slower) intersection calculations.
+     *
+     * **Note**: Unlike other methods, this accepts `strokeWidth` (and not `strokeRadius`).
+     *
+     * `strokeRadius` is half of `strokeWidth`.
+     */
     roughlyIntersects(rect: Rect2, strokeWidth?: number): boolean;
     closedRoughlyIntersects(rect: Rect2): boolean;
     /**
@@ -95,16 +112,32 @@ export declare class Path {
      */
     static fromRect(rect: Rect2, lineWidth?: number | null): Path;
     private cachedStringVersion;
-    toString(useNonAbsCommands?: boolean): string;
+    /**
+     * Convert to an [SVG path representation](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths).
+     *
+     * If `useNonAbsCommands` is given, relative path commands (e.g. `l10,0`) are to be used instead of
+     * absolute commands (e.g. `L10,0`).
+     *
+     * See also {@link fromString}.
+     */
+    toString(useNonAbsCommands?: boolean, ignoreCache?: boolean): string;
     serialize(): string;
     static toString(startPoint: Point2, parts: PathCommand[], onlyAbsCommands?: boolean): string;
     /**
-     * Create a Path from a SVG path specification.
+     * Create a `Path` from a subset of the SVG path specification.
      *
      * ## To-do
      * - TODO: Support a larger subset of SVG paths
      *   - Elliptical arcs are currently unsupported.
      * - TODO: Support `s`,`t` commands shorthands.
+     *
+     * @example
+     * ```ts,runnable,console
+     * import { Path } from '@js-draw/math';
+     *
+     * const path = Path.fromString('m0,0l100,100');
+     * console.log(path.toString(true)); // true: Prefer relative to absolute path commands
+     * ```
      */
     static fromString(pathString: string): Path;
     static empty: Path;

package/dist/mjs/shapes/Path.mjs

@@ -16,17 +16,23 @@ export var PathCommandType;
  * Represents a union of lines and curves.
  */
 export class Path {
+    /**
+     * Creates a new `Path` that starts at `startPoint` and is made up of the path commands,
+     * `parts`.
+     *
+     * See also {@link fromString}
+     */
     constructor(startPoint, parts) {
         this.startPoint = startPoint;
-        this.parts = parts;
         this.cachedGeometry = null;
         this.cachedPolylineApproximation = null;
         this.cachedStringVersion = null;
+        this.parts = parts;
         // Initial bounding box contains one point: the start point.
         this.bbox = Rect2.bboxOf([startPoint]);
         // Convert into a representation of the geometry (cache for faster intersection
         // calculation)
-        for (const part of parts) {
+        for (const part of this.parts) {
             this.bbox = this.bbox.union(Path.computeBBoxForSegment(startPoint, part));
         }
     }
@@ -331,6 +337,8 @@ export class Path {
      * intersections are approximated with the surface `strokeRadius` away from this.
      *
      * If `strokeRadius > 0`, the resultant `parameterValue` has no defined value.
+     *
+     * **Note**: `strokeRadius` is half of a stroke's width.
      */
     intersection(line, strokeRadius) {
         let result = [];
@@ -426,6 +434,16 @@ export class Path {
             return lastPart.point;
         }
     }
+    /**
+     * Like {@link closedRoughlyIntersects} except takes stroke width into account.
+     *
+     * This is intended to be a very fast and rough approximation. Use {@link intersection}
+     * and {@link signedDistance} for more accurate (but much slower) intersection calculations.
+     *
+     * **Note**: Unlike other methods, this accepts `strokeWidth` (and not `strokeRadius`).
+     *
+     * `strokeRadius` is half of `strokeWidth`.
+     */
     roughlyIntersects(rect, strokeWidth = 0) {
         if (this.parts.length === 0) {
             return rect.containsPoint(this.startPoint);
@@ -453,7 +471,7 @@ export class Path {
         }
         return false;
     }
-    // Treats this as a closed path and returns true if part of `rect` is roughly within
+    // Treats this as a closed path and returns true if part of `rect` is *roughly* within
     // this path's interior.
     //
     // Note: Assumes that this is a closed, non-self-intersecting path.
@@ -535,8 +553,16 @@ export class Path {
         });
         return new Path(startPoint, commands);
     }
-    toString(useNonAbsCommands) {
-        if (this.cachedStringVersion) {
+    /**
+     * Convert to an [SVG path representation](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths).
+     *
+     * If `useNonAbsCommands` is given, relative path commands (e.g. `l10,0`) are to be used instead of
+     * absolute commands (e.g. `L10,0`).
+     *
+     * See also {@link fromString}.
+     */
+    toString(useNonAbsCommands, ignoreCache = false) {
+        if (this.cachedStringVersion && !ignoreCache) {
             return this.cachedStringVersion;
         }
         if (useNonAbsCommands === undefined) {
@@ -626,12 +652,20 @@ export class Path {
         return result.join('');
     }
     /**
-     * Create a Path from a SVG path specification.
+     * Create a `Path` from a subset of the SVG path specification.
      *
      * ## To-do
      * - TODO: Support a larger subset of SVG paths
      *   - Elliptical arcs are currently unsupported.
      * - TODO: Support `s`,`t` commands shorthands.
+     *
+     * @example
+     * ```ts,runnable,console
+     * import { Path } from '@js-draw/math';
+     *
+     * const path = Path.fromString('m0,0l100,100');
+     * console.log(path.toString(true)); // true: Prefer relative to absolute path commands
+     * ```
      */
     static fromString(pathString) {
         // See the MDN reference:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@js-draw/math",
-	"version": "1.9.0",
+	"version": "1.10.0",
 	"description": "A math library for js-draw. ",
 	"types": "./dist/mjs/lib.d.ts",
 	"main": "./dist/cjs/lib.js",
@@ -45,5 +45,5 @@
 		"svg",
 		"math"
 	],
-	"gitHead": "e824c37e9f216852cf096976e3a74fb4f177ead3"
+	"gitHead": "ccf1d0634e902c731fcd794df11cd001c3a30585"
 }

package/src/lib.ts

@@ -30,6 +30,7 @@ export {
 } from './shapes/Path';
 export { Rect2 } from './shapes/Rect2';
 export { QuadraticBezier } from './shapes/QuadraticBezier';
+export { Abstract2DShape } from './shapes/Abstract2DShape';
 
 export { Mat33, Mat33Array } from './Mat33';
 export { Point2, Vec2 } from './Vec2';

package/src/shapes/Abstract2DShape.ts

@@ -2,7 +2,11 @@ import LineSegment2 from './LineSegment2';
 import { Point2 } from '../Vec2';
 import Rect2 from './Rect2';
 
-abstract class Abstract2DShape {
+/**
+ * An abstract base class for 2D shapes.
+ */
+export abstract class Abstract2DShape {
+	// @internal
 	protected static readonly smallValue = 1e-12;
 
 	/**

package/src/shapes/Path.toString.test.ts

@@ -47,9 +47,9 @@ describe('Path.toString', () => {
 
 	it('deserialized path should serialize to the same/similar path, but with rounded components', () => {
 		const path1 = Path.fromString('M100,100 L101,101 Q102,102 90.000000001,89.99999999 Z');
-		path1['cachedStringVersion'] = null; // Clear the cache.
+		const ignoreCache = true;
 
-		expect(path1.toString()).toBe([
+		expect(path1.toString(undefined, ignoreCache)).toBe([
 			'M100,100', 'l1,1', 'q1,1 -11-11', 'l10,10'
 		].join(''));
 	});
@@ -58,9 +58,9 @@ describe('Path.toString', () => {
 		const pathStr = 'M184.2,52.3l-.2-.2q-2.7,2.4 -3.2,3.5q-2.8,7 -.9,6.1q4.3-2.6 4.8-6.1q1.2-8.8 .4-8.3q-4.2,5.2 -3.9,3.9q.2-1.6 .3-2.1q.2-1.3 -.2-1q-3.8,6.5 -3.2,3.3q.6-4.1 1.1-5.3q4.1-10 3.3-8.3q-5.3,13.1 -6.6,14.1q-3.3,2.8 -1.8-1.5q2.8-9.7 2.7-8.4q0,.3 0,.4q-1.4,7.1 -2.7,8.5q-2.6,3.2 -2.5,2.9q-.3-1.9 -.7-1.9q-4.1,4.4 -2.9,1.9q1.1-3 .3-2.6q-1.8,2 -2.5,2.4q-4.5,2.8 -4.2,1.9q.3-1.6 .2-1.4q1.5,2.2 1.3,2.9q-.8,3.9 -.5,3.3q.8-7.6 2.5-13.3q2.6-9.2 2.9-6.9q.3,1.4 .3,1.2q-.7-.4 -.9,0q-2.2,11.6 -7.6,13.6q-3.9,1.6 -2.1-1.3q3-5.5 2.6-3.4q-.2,1.8 -.5,1.8q-3.2,.5 -4.1,1.2q-2.6,2.6 -1.9,2.5q4.7-4.4 3.7-5.5q-1.1-.9 -1.6-.6q-7.2,7.5 -3.9,6.5q.3-.1 .4-.4q.6-5.3 -.2-4.9q-2.8,2.3 -3.1,2.4q-3.7,1.5 -3.5,.5q.3-3.6 1.4-3.3q3.5,.7 1.9,2.4q-1.7,2.3 -1.6,.8q0-3.5 -.9-3.1q-5.1,3.3 -4.9,2.8q.1-4 -.8-3.5q-4.3,3.4 -4.6,2.5q-1-2.1 .5-8.7l-.2,0q-1.6,6.6 -.7,8.9q.7,1.2 5.2-2.3q.4-.5 .2,3.1q.1,1 5.5-2.4q.4-.4 .3,2.7q.1,2 2.4-.4q1.7-2.3 -2.1-3.2q-1.7-.3 -2,3.7q0,1.4 4.1-.1q.3-.1 3.1-2.4q.3-.5 -.4,4.5q0-.1 -.2,0q-2.6,1.2 4.5-5.7q0-.2 .8,.6q.9,.6 -3.7,4.7q-.5,1 2.7-1.7q.6-.7 3.7-1.2q.7-.2 .9-2.2q.1-2.7 -3.4,3.2q-1.8,3.4 2.7,1.9q5.6-2.1 7.8-14q-.1,.1 .3,.4q.6,.1 .3-1.6q-.7-2.8 -3.7,6.7q-1.8,5.8 -2.5,13.5q.1,1.1 1.3-3.1q.2-1 -1.3-3.3q-.5-.5 -1,1.6q-.1,1.3 4.8-1.5q1-1 3-2q.1-.4 -1.1,2q-1.1,3.1 3.7-1.3q-.4,0 -.1,1.5q.3,.8 3.3-2.5q1.3-1.6 2.7-8.9q0-.1 0-.4q-.3-1.9 -3.5,8.2q-1.3,4.9 2.4,2.1q1.4-1.2 6.6-14.3q.8-2.4 -3.9,7.9q-.6,1.3 -1.1,5.5q-.3,3.7 4-3.1q-.2,0 -.6,.6q-.2,.6 -.3,2.3q0,1.8 4.7-3.5q.1-.5 -1.2,7.9q-.5,3.2 -4.6,5.7q-1.3,1 1.5-5.5q.4-1.1 3.01-3.5';
 
 		const path1 = Path.fromString(pathStr);
-		path1['cachedStringVersion'] = null; // Clear the cache.
-		const path = Path.fromString(path1.toString(true));
-		path1['cachedStringVersion'] = null; // Clear the cache.
+		const ignoreCache = true;
+		const path = Path.fromString(path1.toString(true, ignoreCache));
+		path1['cachedStringVersion'] = null; // Clear the cache manually
 
 		expect(path.toString(true)).toBe(path1.toString(true));
 	});

package/src/shapes/Path.ts

@@ -51,9 +51,6 @@ interface IntersectionResult {
 	point: Point2;
 }
 
-type GeometryType = Abstract2DShape;
-type GeometryArrayType = Array<GeometryType>;
-
 /**
  * Represents a union of lines and curves.
  */
@@ -65,13 +62,27 @@ export class Path {
 	 */
 	public readonly bbox: Rect2;
 
-	public constructor(public readonly startPoint: Point2, public readonly parts: PathCommand[]) {
+	/** The individual shapes that make up this path. */
+	public readonly parts: Readonly<PathCommand>[];
+
+	/**
+	 * Creates a new `Path` that starts at `startPoint` and is made up of the path commands,
+	 * `parts`.
+	 *
+	 * See also {@link fromString}
+	 */
+	public constructor(
+		public readonly startPoint: Point2,
+		parts: Readonly<PathCommand>[],
+	) {
+		this.parts = parts;
+
 		// Initial bounding box contains one point: the start point.
 		this.bbox = Rect2.bboxOf([startPoint]);
 
 		// Convert into a representation of the geometry (cache for faster intersection
 		// calculation)
-		for (const part of parts) {
+		for (const part of this.parts) {
 			this.bbox = this.bbox.union(Path.computeBBoxForSegment(startPoint, part));
 		}
 	}
@@ -85,16 +96,16 @@ export class Path {
 		return Rect2.union(...bboxes);
 	}
 
-	private cachedGeometry: GeometryArrayType|null = null;
+	private cachedGeometry: Abstract2DShape[]|null = null;
 
 	// Lazy-loads and returns this path's geometry
-	public get geometry(): GeometryArrayType {
+	public get geometry(): Abstract2DShape[] {
 		if (this.cachedGeometry) {
 			return this.cachedGeometry;
 		}
 
 		let startPoint = this.startPoint;
-		const geometry: GeometryArrayType = [];
+		const geometry: Abstract2DShape[] = [];
 
 		for (const part of this.parts) {
 			let exhaustivenessCheck: never;
@@ -258,7 +269,7 @@ export class Path {
 
 		type DistanceFunction = (point: Point2) => number;
 		type DistanceFunctionRecord = {
-			part: GeometryType,
+			part: Abstract2DShape,
 			bbox: Rect2,
 			distFn: DistanceFunction,
 		};
@@ -297,7 +308,7 @@ export class Path {
 
 		// Returns the minimum distance to a part in this stroke, where only parts that the given
 		// line could intersect are considered.
-		const sdf = (point: Point2): [GeometryType|null, number] => {
+		const sdf = (point: Point2): [Abstract2DShape|null, number] => {
 			let minDist = Infinity;
 			let minDistPart: Abstract2DShape|null = null;
 
@@ -466,6 +477,8 @@ export class Path {
 	 * intersections are approximated with the surface `strokeRadius` away from this.
 	 *
 	 * If `strokeRadius > 0`, the resultant `parameterValue` has no defined value.
+	 *
+	 * **Note**: `strokeRadius` is half of a stroke's width.
 	 */
 	public intersection(line: LineSegment2, strokeRadius?: number): IntersectionResult[] {
 		let result: IntersectionResult[] = [];
@@ -576,6 +589,16 @@ export class Path {
 		}
 	}
 
+	/**
+	 * Like {@link closedRoughlyIntersects} except takes stroke width into account.
+	 *
+	 * This is intended to be a very fast and rough approximation. Use {@link intersection}
+	 * and {@link signedDistance} for more accurate (but much slower) intersection calculations.
+	 *
+	 * **Note**: Unlike other methods, this accepts `strokeWidth` (and not `strokeRadius`).
+	 *
+	 * `strokeRadius` is half of `strokeWidth`.
+	 */
 	public roughlyIntersects(rect: Rect2, strokeWidth: number = 0) {
 		if (this.parts.length === 0) {
 			return rect.containsPoint(this.startPoint);
@@ -609,7 +632,7 @@ export class Path {
 		return false;
 	}
 
-	// Treats this as a closed path and returns true if part of `rect` is roughly within
+	// Treats this as a closed path and returns true if part of `rect` is *roughly* within
 	// this path's interior.
 	//
 	// Note: Assumes that this is a closed, non-self-intersecting path.
@@ -713,8 +736,16 @@ export class Path {
 
 	private cachedStringVersion: string|null = null;
 
-	public toString(useNonAbsCommands?: boolean): string {
-		if (this.cachedStringVersion) {
+	/**
+	 * Convert to an [SVG path representation](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths).
+	 *
+	 * If `useNonAbsCommands` is given, relative path commands (e.g. `l10,0`) are to be used instead of
+	 * absolute commands (e.g. `L10,0`).
+	 *
+	 * See also {@link fromString}.
+	 */
+	public toString(useNonAbsCommands?: boolean, ignoreCache: boolean = false): string {
+		if (this.cachedStringVersion && !ignoreCache) {
 			return this.cachedStringVersion;
 		}
 
@@ -817,12 +848,20 @@ export class Path {
 	}
 
 	/**
-	 * Create a Path from a SVG path specification.
+	 * Create a `Path` from a subset of the SVG path specification.
 	 *
 	 * ## To-do
 	 * - TODO: Support a larger subset of SVG paths
 	 *   - Elliptical arcs are currently unsupported.
 	 * - TODO: Support `s`,`t` commands shorthands.
+	 *
+	 * @example
+	 * ```ts,runnable,console
+	 * import { Path } from '@js-draw/math';
+	 *
+	 * const path = Path.fromString('m0,0l100,100');
+	 * console.log(path.toString(true)); // true: Prefer relative to absolute path commands
+	 * ```
 	 */
 	public static fromString(pathString: string): Path {
 		// See the MDN reference: