@pacem/pacem-numerical 1.0.0-bessel → 1.0.0-dirac

package/typings/index.d.ts

@@ -1,23 +1,80 @@
 import { Point } from '@pacem/pacem-foundation';
 import { Rect } from '@pacem/pacem-foundation';
 
+/** Represents a complex number as an immutable pair of real and imaginary components. */
 declare interface Complex {
+    /** Real part. */
     readonly real: number;
+    /** Imaginary part. */
     readonly img: number;
 }
 
+/** Utility tools to build and operate on {@link Complex} numbers. */
 declare class Complex {
+    /**
+     * Returns the provided value unchanged if it is already a {@link Complex} number.
+     * @param z A complex number (or a real number, treated as having a zero imaginary part).
+     */
     static build(z: Complex | number): Complex;
+    /**
+     * Builds a new {@link Complex} number from its real and imaginary components.
+     * @param real Real part.
+     * @param img Imaginary part.
+     */
     static build(real: number, img: number): Complex;
+    /**
+     * Adds two complex numbers (real numbers are treated as having a zero imaginary part).
+     * @param a First addend.
+     * @param b Second addend.
+     */
     static add(a: Complex | number, b: Complex | number): Complex;
+    /**
+     * Subtracts one complex number from another.
+     * @param from Minuend.
+     * @param what Subtrahend.
+     */
     static subtract(from: Complex | number, what: Complex | number): Complex;
+    /**
+     * Multiplies two complex numbers.
+     * @param a First factor.
+     * @param b Second factor.
+     */
     static multiply(a: Complex | number, b: Complex | number): Complex;
+    /**
+     * Divides one complex number by another.
+     * @param a Dividend.
+     * @param b Divisor.
+     * @returns The quotient, or {@link Complex.NaC} if the divisor is (close to) zero.
+     */
     static divide(a: Complex | number, b: Complex | number): Complex;
+    /**
+     * Returns the squared modulus (|z|²) of the complex number, i.e. real² + img².
+     * Cheaper than {@link modulus} since it avoids the square root.
+     * @param c
+     */
     static absSquare(c: Complex | number): number;
+    /**
+     * Returns the modulus (magnitude) of the complex number.
+     * @param c
+     */
     static modulus(c: Complex | number): number;
+    /**
+     * Type guard checking whether the provided value is a {@link Complex} number.
+     * @param c
+     */
     static isComplex(c: any): c is Complex;
+    /**
+     * Returns the complex conjugate: same real part, negated imaginary part.
+     * @param a
+     */
     static conjugate(a: Complex | number): Complex;
+    /**
+     * Checks whether two complex numbers have the same real and imaginary parts.
+     * @param c1
+     * @param c2
+     */
     static equals(c1: Complex | number, c2: Complex | number): boolean;
+    /** The "Not a Complex" sentinel value (`NaN + NaNi`), returned by operations on invalid input. */
     static get NaC(): Complex;
 }
 
@@ -36,6 +93,7 @@ export declare namespace DataAnalysis {
     }
 }
 
+/** Discrete Fourier Transform (DFT) utilities, including a Cooley-Tukey FFT fast path for power-of-two inputs. */
 declare class Fourier {
     /**
      * Checks the input vector and outputs a frequency vector using the best performing algo.
@@ -66,11 +124,21 @@ declare class Fourier {
     static fft(data: (Complex | number)[], normalize?: boolean): Complex[];
 }
 
+/** Represents a Gaussian (normal) distribution and exposes its density and cumulative probability functions. */
 declare class Gaussian {
+    /**
+     * Creates a new {@link Gaussian} distribution with the given mean and standard deviation.
+     * @param mean Mean (μ) of the distribution.
+     * @param stdev Standard deviation (σ) of the distribution (its absolute value is used).
+     */
     constructor(mean: number, stdev: number);
+    /** Mean (μ) of the distribution. */
     readonly mean: number;
+    /** Standard deviation (σ) of the distribution. */
     readonly stdev: number;
+    /** Variance (σ²) of the distribution. */
     readonly variance: number;
+    /** The standard normal distribution (mean 0, standard deviation 1). */
     static get normal(): Gaussian;
     /**
      * Un-normalized probability density function.
@@ -102,19 +170,52 @@ export declare namespace Geometry {
     }
 }
 
+/** Common contract for the interpolation strategies of this module: given an x, returns the estimated y. */
 declare interface Interpolator {
+    /**
+     * Evaluates the interpolated function at the given x.
+     * @param x Input value.
+     * @returns The interpolated y value.
+     */
     interpolate(x: number): number;
 }
 
+/**
+ * Lagrange polynomial interpolation, evaluated using the numerically stable barycentric form.
+ * Given a set of `(x, y)` points, builds the unique polynomial of minimal degree passing through
+ * all of them and evaluates it at arbitrary x values.
+ */
 declare class Lagrange implements Interpolator {
     #private;
+    /** Use {@link Lagrange.create} to build an instance. */
     protected constructor(points: Point[]);
     private _prepareBarycentric;
     private _computeBarycentric;
+    /**
+     * Evaluates the Lagrange interpolating polynomial at the given x, using barycentric weights.
+     * @param x Input value.
+     * @returns The interpolated y value (the exact node y if x coincides with a node).
+     */
     interpolate(x: number): number;
+    /**
+     * Builds a {@link Lagrange} interpolator from a set of y values, using their array index as x.
+     * @param values y values, implicitly located at x = 0, 1, 2, ...
+     */
     static create(...values: number[]): Lagrange;
+    /**
+     * Builds a {@link Lagrange} interpolator from a set of points.
+     * @param points Points to interpolate through.
+     */
     static create(...points: Point[]): Lagrange;
+    /**
+     * Builds a {@link Lagrange} interpolator from a set of points.
+     * @param points Points to interpolate through.
+     */
     static create(points: Point[]): Lagrange;
+    /**
+     * Builds a {@link Lagrange} interpolator from a set of y values, using their array index as x.
+     * @param values y values, implicitly located at x = 0, 1, 2, ...
+     */
     static create(values: number[]): Lagrange;
 }
 
@@ -144,6 +245,10 @@ export declare namespace Mathematics {
     }
 }
 
+/**
+ * Represents a 4x4 transformation matrix in 3D space, in row-major layout (`m{row}{col}`, with the
+ * 4th column split out as `offsetX`/`offsetY`/`offsetZ`/`m44` for the translation and perspective terms).
+ */
 declare interface Matrix3D {
     m11: number;
     m12: number;
@@ -163,24 +268,87 @@ declare interface Matrix3D {
     m44: number;
 }
 
+/** Utilities to build, combine and invert 4x4 transformation matrices ({@link Matrix3D}) in 3D space. */
 declare class Matrix3D {
     /**
      * Identity 4x4 matrix.
      * @returns
      */
     static identity(): Matrix3D;
+    /**
+     * Builds a {@link Matrix3D} from its 16 components, in row-major order.
+     * @param args Exactly 16 numbers.
+     * @throws If the number of arguments is not exactly 16.
+     */
     static from(...args: number[]): Matrix3D;
+    /**
+     * Returns the transpose of the given matrix (rows and columns swapped).
+     * @param m
+     */
     static transpose(m: Matrix3D): Matrix3D;
+    /**
+     * Flattens the matrix into a 16-number array, in row-major order (the same order accepted by {@link from}).
+     * @param m
+     */
     static toArray(m: Matrix3D): number[];
+    /**
+     * Returns a copy of the given matrix.
+     * @param m
+     */
     static clone(m: Matrix3D): Matrix3D;
+    /**
+     * Returns a copy of the given matrix, after applying an in-place modification callback to it.
+     * @param m
+     * @param modifier Callback invoked on the cloned matrix to alter its content.
+     */
     static clone(m: Matrix3D, modifier: (m: Matrix3D) => void): Matrix3D;
+    /**
+     * Returns a copy of the matrix scaled by the components of a vector.
+     * @param m
+     * @param v Per-axis scale factors.
+     */
     static scale(m: Matrix3D, v: Vector3D): Matrix3D;
+    /**
+     * Returns a copy of the matrix uniformly scaled by a single factor.
+     * @param m
+     * @param scale
+     */
     static scale(m: Matrix3D, scale: number): Matrix3D;
+    /**
+     * Returns a copy of the matrix scaled by independent per-axis factors.
+     * @param m
+     * @param sx
+     * @param sy
+     * @param sz
+     */
     static scale(m: Matrix3D, sx: number, sy: number, sz: number): Matrix3D;
+    /**
+     * Returns a copy of the matrix translated (offset) by the given vector.
+     * @param m
+     * @param offset
+     */
     static translate(m: Matrix3D, offset: Vector3D): Matrix3D;
+    /**
+     * Parses a string representation of a matrix (16 numbers) into a {@link Matrix3D}.
+     * @param input String to parse.
+     * @throws If the input cannot be parsed as exactly 16 numbers.
+     */
     static parse(input: string): Matrix3D;
+    /**
+     * Checks whether the matrix is the identity matrix.
+     * @param m
+     */
     static isIdentity(m: Matrix3D): boolean;
+    /**
+     * Checks whether the matrix represents a pure affine transform, i.e. it has no perspective
+     * component (its 4th column is `(0, 0, 0, 1)`).
+     * @param m
+     */
     static isAffine(m: Matrix3D): boolean;
+    /**
+     * Computes the determinant of the matrix.
+     * @param m
+     */
     static determinant(m: Matrix3D): number;
     /**
      * Multiplies two matrices in the provided order (i.e.: applies {@link m2} to {@link m1}).
@@ -188,6 +356,12 @@ declare class Matrix3D {
      * @returns Combination matrix.
      */
     static multiply(...matrices: Matrix3D[]): Matrix3D;
+    /**
+     * Computes the inverse of the matrix, using the cofactor/adjugate method (with a specialized,
+     * cheaper path for affine matrices).
+     * @param m
+     * @returns The inverse matrix, or `null` if the matrix is singular (determinant is 0).
+     */
     static invert(m: Matrix3D): Matrix3D;
     /**
      * Moves a given point in 3D space given the transformation matrix.
@@ -201,14 +375,42 @@ declare interface Mesh extends Polygon {
     triangleIndices: number[];
 }
 
+/**
+ * Newton's divided-difference polynomial interpolation.
+ * Builds the same interpolating polynomial as {@link Lagrange} but represents it in Newton form
+ * (a nested/Horner-like product of divided differences), which is efficient to evaluate and to
+ * extend incrementally as new points are added.
+ */
 declare class Newton implements Interpolator {
     private xs;
     private coeffs;
+    /** Use {@link Newton.create} to build an instance. */
     private constructor();
+    /**
+     * Evaluates the Newton form of the interpolating polynomial at the given x, via nested multiplication.
+     * @param x Input value.
+     * @returns The interpolated y value (`NaN` if the interpolator has no points).
+     */
     interpolate(x: number): number;
+    /**
+     * Builds a {@link Newton} interpolator from a set of y values, using their array index as x.
+     * @param values y values, implicitly located at x = 0, 1, 2, ...
+     */
     static create(...values: number[]): Newton;
+    /**
+     * Builds a {@link Newton} interpolator from a set of points.
+     * @param points Points to interpolate through.
+     */
     static create(...points: Point[]): Newton;
+    /**
+     * Builds a {@link Newton} interpolator from a set of points.
+     * @param points Points to interpolate through.
+     */
     static create(points: Point[]): Newton;
+    /**
+     * Builds a {@link Newton} interpolator from a set of y values, using their array index as x.
+     * @param values y values, implicitly located at x = 0, 1, 2, ...
+     */
     static create(values: number[]): Newton;
 }
 
@@ -220,37 +422,100 @@ export declare namespace NumberTheory {
 
 declare type NumericKeySelector<T> = (item: T, index?: number) => number;
 
+/**
+ * Piecewise Cubic Hermite Interpolating Polynomial (PCHIP).
+ * Builds a shape-preserving (monotonicity-respecting) piecewise-cubic curve through a set of
+ * `(x, y)` points: unlike {@link Lagrange}, it does not overshoot between nodes, at the cost of
+ * only being C¹ (continuous first derivative, not second).
+ */
 declare class Pchip implements Interpolator {
     private xs;
     private ys;
     private ms;
+    /** Use {@link Pchip.create} to build an instance. */
     private constructor();
     private computeDerivatives;
+    /**
+     * Evaluates the PCHIP curve at the given x, using cubic Hermite interpolation on the enclosing segment.
+     * Values outside the node range are linearly extrapolated using the boundary derivative.
+     * @param x Input value.
+     * @returns The interpolated y value.
+     */
     interpolate(x: number): number;
+    /**
+     * Builds a {@link Pchip} interpolator from a set of y values, using their array index as x.
+     * @param values y values, implicitly located at x = 0, 1, 2, ...
+     */
     static create(...values: number[]): Pchip;
+    /**
+     * Builds a {@link Pchip} interpolator from a set of points (at least 2).
+     * @param points Points to interpolate through.
+     */
     static create(...points: Point[]): Pchip;
+    /**
+     * Builds a {@link Pchip} interpolator from a set of points (at least 2).
+     * @param points Points to interpolate through.
+     */
     static create(points: Point[]): Pchip;
+    /**
+     * Builds a {@link Pchip} interpolator from a set of y values, using their array index as x.
+     * @param values y values, implicitly located at x = 0, 1, 2, ...
+     */
     static create(values: number[]): Pchip;
 }
 
+/** A point (or free vector) in 3D space. */
 declare interface Point3D {
     x: number;
     y: number;
     z: number;
 }
 
+/** A (2D) polygon, represented as its ordered list of vertices. */
 declare interface Polygon {
     vertices: Point[];
 }
 
+/** Utility tools to build and inspect {@link Polygon}s. */
 declare class Polygon {
     private static readonly _eps;
+    /**
+     * Type guard checking whether the provided value is a valid {@link Polygon} (has at least 3 point vertices).
+     * @param obj
+     */
     static isPolygon(obj: any): obj is Polygon;
+    /**
+     * Builds a polygon from the provided vertices, in order.
+     * @param points Vertices of the polygon.
+     */
     static from(...points: Point[]): Polygon;
+    /**
+     * Checks whether a point lies inside the polygon.
+     * @param polygon
+     * @param p Point to test.
+     */
     static contains(polygon: Polygon, p: Point): any;
+    /**
+     * Returns the center of the polygon's bounding box.
+     * Note: this is not the geometric centroid (center of mass) for non-symmetric polygons.
+     * @param polygon
+     */
     static centroid(polygon: Polygon): Point;
+    /**
+     * Computes the axis-aligned bounding box of the polygon.
+     * @param polygon
+     */
     static boundingBox(polygon: Polygon): Rect;
+    /**
+     * Returns the polygon's edges as an ordered list of segments, each joining a vertex to the next
+     * (the last one wrapping back to the first).
+     * @param polygon
+     */
     static sides(polygon: Polygon): Segment[];
+    /**
+     * Checks whether the polygon is convex, i.e. all its interior angles turn in the same rotational direction.
+     * @param polygon
+     */
     static isConvex(polygon: Polygon): boolean;
     /**
      * Check whether a polygon is a self-intersecting one.
@@ -278,6 +543,12 @@ declare class Polygon {
      * @returns
      */
     static area(polygon: Polygon): number;
+    /**
+     * Computes the intersection area(s) between two polygons.
+     * @param polygon1
+     * @param polygon2
+     * @returns The overlapping area(s) as one or more polygons.
+     */
     static intersect(polygon1: Polygon, polygon2: Polygon): Polygon[];
     /**
      * Returns the convex hull of a polygon.
@@ -289,6 +560,10 @@ declare class Polygon {
 
 declare type PolygonCompound = 'union' | 'intersect' | 'difference';
 
+/**
+ * Represents a rotation in 3D space as a unit quaternion `x·i + y·j + z·k + w`, avoiding the gimbal-lock
+ * issues of Euler angles and allowing smooth interpolation between orientations.
+ */
 declare interface Quaternion {
     x: number;
     y: number;
@@ -296,10 +571,28 @@ declare interface Quaternion {
     w: number;
 }
 
+/** Utilities to build, combine and convert {@link Quaternion} rotations. */
 declare class Quaternion {
+    /** Returns the identity quaternion (no rotation). */
     static identity(): Quaternion;
+    /**
+     * Builds a {@link Quaternion} from its x, y, z, w components, in that order.
+     * @param args Exactly 4 numbers: x, y, z, w.
+     * @throws If the number of arguments is not exactly 4.
+     */
     static from(...args: number[]): Quaternion;
+    /**
+     * Parses a string representation of a quaternion (4 numbers) into a {@link Quaternion}.
+     * @param input String to parse.
+     * @throws If the input cannot be parsed as exactly 4 numbers.
+     */
     static parse(input: string): Quaternion;
+    /**
+     * Builds the (shortest-arc) quaternion representing the rotation that takes one unit vector onto another.
+     * Normalizes both input vectors in place as a side effect.
+     * @param from Source direction.
+     * @param to Target direction.
+     */
     static fromVectors(from: Vector3D, to: Vector3D): Quaternion;
     /**
      * In-place normalizarion of the provided quaternion
@@ -322,21 +615,48 @@ declare class Quaternion {
      * @param rotationMatrix
      */
     static fromRotationMatrix(rotationMatrix: Matrix3D): Quaternion;
+    /**
+     * Returns the conjugate of the quaternion (vector part negated). For a unit quaternion, this
+     * represents the inverse rotation.
+     * @param q
+     */
     static conjugate(q: Quaternion): Quaternion;
     /**
      * Returns the magnitude/length of the provided quaternion.
      * @param q {Quaternion}
      */
     static mag(q: Quaternion): number;
+    /**
+     * Returns the squared magnitude of the vector (imaginary) part of the quaternion.
+     * @param q
+     */
     static norm(q: Quaternion): number;
+    /**
+     * Returns the (unit) rotation axis represented by the quaternion, defaulting to the y axis
+     * when the quaternion has no vector part (i.e. represents no rotation).
+     * @param q
+     */
     static axis(q: Quaternion): Vector3D;
+    /**
+     * Rotates a vector by the given quaternion (normalizes the quaternion in place as a side effect).
+     * @param v Vector to rotate.
+     * @param q Rotation quaternion.
+     */
     static transform(v: Vector3D, q: Quaternion): Vector3D;
     /**
      * Returns the rotation angle (in degrees) of the provided quaternion.
      * @param q
      */
     static angle(q: Quaternion): number;
+    /**
+     * Builds the rotation matrix equivalent to the given quaternion.
+     * @param q
+     */
     static toRotationMatrix(q: Quaternion): Matrix3D;
+    /**
+     * Returns the inverse rotation of the given quaternion (the conjugate of its normalized form).
+     * @param q
+     */
     static invert(q: Quaternion): Quaternion;
     /**
      * Combines two quaternions.
@@ -352,10 +672,16 @@ declare class Quaternion {
     static dot(q1: Quaternion, q2: Quaternion): number;
 }
 
+/** A ray in 3D space, represented as its start and end points (direction goes from the first to the second). */
 declare type Ray = [Point3D, Point3D];
 
+/**
+ * A search function that finds (approximately) the value in `[min, max]` minimizing the given weight function,
+ * within the given tolerance. See {@link SearchFunctions} for ready-made implementations.
+ */
 declare type SearchFunction = (min: number, max: number, weight: (v: number) => number, tolerance?: number) => number;
 
+/** Ready-made {@link SearchFunction} implementations for unimodal minimum-search over an interval. */
 declare const SearchFunctions: {
     /**
      * Creates a linear search function.
@@ -368,8 +694,10 @@ declare const SearchFunctions: {
     gaussian: SearchFunction;
 };
 
+/** A line segment, represented as its two endpoints. */
 declare type Segment = [Point, Point];
 
+/** Represents a point in 3D space using spherical coordinates (radial distance and two angles). */
 declare interface Spherical {
     /** Azimuthal angle in degrees. */
     theta: number;
@@ -379,6 +707,10 @@ declare interface Spherical {
     rho: number;
 }
 
+/**
+ * Utilities to convert between spherical coordinates (radial distance `rho`, azimuth `theta` and
+ * polar angle `phi`) and their cartesian ({@link Vector3D}) or rotation-matrix ({@link Matrix3D}) equivalents.
+ */
 declare class Spherical {
     /**
      * Creates a new {@link Spherical} object.
@@ -388,16 +720,39 @@ declare class Spherical {
      * @returns
      */
     static from(rho: number, theta: number, phi: number): Spherical;
+    /**
+     * Computes the {@link Spherical} coordinates equivalent to the given cartesian x, y, z components.
+     * @param x
+     * @param y
+     * @param z
+     */
     static fromVector(x: number, y: number, z: any): Spherical;
+    /**
+     * Computes the {@link Spherical} coordinates equivalent to the given 3D vector.
+     * @param v
+     */
     static fromVector(v: Vector3D): Spherical;
+    /**
+     * Converts {@link Spherical} coordinates back into cartesian {@link Vector3D} coordinates.
+     * @param coords
+     */
     static toVector(coords: Spherical): Vector3D;
+    /**
+     * Builds the rotation matrix corresponding to the given azimuth (`theta`) and polar (`phi`) angles.
+     * @param coords
+     */
     static toRotationMatrix(coords: Spherical): Matrix3D;
+    /**
+     * Builds the rotation matrix corresponding to the given azimuth (`theta`) and polar (`phi`) angles.
+     * @param coords
+     */
     static toRotationMatrix(coords: {
         theta: number;
         phi: number;
     }): Matrix3D;
 }
 
+/** Utility tools for 2D geometry: points, segments, polygons and their interactions. */
 declare class Utils {
     /**
      * Computes the slope (in radians) of the segment joining two points.
@@ -428,6 +783,12 @@ declare class Utils {
      * @param rects Rects to intersect
      */
     static intersect(...rects: Rect[]): Rect;
+    /**
+     * Computes the intersection polygon(s) between two polygons.
+     * @param polygon1 First polygon.
+     * @param polygon2 Second polygon.
+     * @returns The overlapping area(s) as one or more polygons.
+     */
     static intersect(polygon1: Polygon, polygon2: Polygon): Polygon[];
     /**
      * Computes the intersection point between two segments, if any.
@@ -435,7 +796,21 @@ declare class Utils {
      * @param segment2
      */
     static intersect(segment1: Segment, segment2: Segment): Point;
+    /**
+     * Computes the axis-aligned bounding box of a set of points.
+     * @param vertices Points to enclose.
+     * @returns The smallest rect containing all provided points.
+     */
     static boundingBox(vertices: Point[]): Rect;
+    /**
+     * Combines two polygons using a boolean set operator (union, intersection or difference).
+     * Internally triangulates the merged vertex set (via {@link mesh}) and filters the resulting
+     * triangles by whether their barycenter falls inside either source polygon.
+     * @param polygon1 First polygon.
+     * @param polygon2 Second polygon.
+     * @param operator Boolean operator to apply.
+     * @returns The resulting polygon(s), plus the underlying triangulation mesh and triangles used to compute them; or `null` if the operation yields no polygon.
+     */
     static combinePolygons(polygon1: Polygon, polygon2: Polygon, operator: PolygonCompound): {
         polygons: Polygon[];
         mesh?: Mesh;
@@ -502,6 +877,13 @@ declare class Utils {
     private static _intersectSegments;
     private static _intersectRects;
     private static _areClose;
+    /**
+     * Checks if the two points are effectively the same location.
+     * @param p1 The first point.
+     * @param p2 The second point.
+     * @param precision Optional precision roundoff for the proximity check.
+     * @returns True if the points are considered coincident within tolerance; otherwise, false.
+     */
     static areClose(p1: Point, p2: Point): boolean;
     static areClose(p1: Point, p2: Point, precision: number): boolean;
     /**
@@ -528,16 +910,54 @@ declare class Utils {
      * @param mq Line identified by a two-number array (slope and y-intercept).
      */
     static distance(p: Point, mq: [number, number]): number;
+    /**
+     * Returns the length of a segment.
+     * @param segment
+     */
     static distance(segment: Segment): number;
     private static _pointSegmentDistance;
+    /**
+     * Checks whether a point lies on the given side (clockwise or counter-clockwise) of the line
+     * through a segment, strictly off the line.
+     * @param p Point to test.
+     * @param segment Segment identifying the reference line and its direction.
+     * @param clockwise Side to test for: `true` for the clockwise side, `false` for counter-clockwise.
+     * @param precision Optional precision roundoff used to consider the point "on the line" (and thus not "within" either side).
+     */
     static isWithin(p: Point, segment: Segment, clockwise: boolean): boolean;
     static isWithin(p: Point, segment: Segment, clockwise: boolean, precision: number): boolean;
+    /**
+     * Checks whether a point lies on the opposite side (clockwise or counter-clockwise) of the line
+     * through a segment, strictly off the line. Complementary to {@link isWithin}.
+     * @param p Point to test.
+     * @param segment Segment identifying the reference line and its direction.
+     * @param clockwise Side to test *against*: `true` tests for the counter-clockwise side, `false` for clockwise.
+     * @param precision Optional precision roundoff used to consider the point "on the line".
+     */
     static isBeyond(p: Point, segment: Segment, clockwise: boolean): boolean;
     static isBeyond(p: Point, segment: Segment, clockwise: boolean, precision: number): boolean;
+    /**
+     * Checks whether a point lies on the (infinite) line through a segment.
+     * @param p Point to test.
+     * @param segment Segment identifying the reference line.
+     * @param precision Optional precision roundoff for the proximity check.
+     */
     static inLine(p: Point, segment: Segment): boolean;
     static inLine(p: Point, segment: Segment, precision: number): boolean;
+    /**
+     * Checks whether a point lies on the segment itself (on its line, and within its bounding box).
+     * @param p Point to test.
+     * @param segment Segment to test against.
+     * @param precision Optional precision roundoff for the proximity check.
+     */
     static inSegment(p: Point, segment: Segment): boolean;
     static inSegment(p: Point, segment: Segment, precision: number): boolean;
+    /**
+     * Checks whether a point lies inside (or on the boundary of) a triangle, by verifying that it
+     * is on the same rotational side of all three edges.
+     * @param p Point to test.
+     * @param triangle Triangle vertices.
+     */
     static inTriangle(p: Point, triangle: [Point, Point, Point]): boolean;
     /**
      * Checks whether a given point lies inside a polygon in the 2d plane.
@@ -567,6 +987,7 @@ declare class Utils {
     static convexHull(points: Point[]): Point[];
 }
 
+/** Utility tools for 3D geometry: rays, triangles and their interactions. */
 declare class Utils3D {
     /**
      * Computes the intersection between a ray and a triangle in the 3D space - if any - using the Möller–Trumbore algorithm.
@@ -579,12 +1000,32 @@ declare class Utils3D {
 
 /** Utility tools about statistics, probability, data analysis... */
 declare class Utils_2 {
+    /**
+     * Sums the (selected) values of a set.
+     * @param set Input set.
+     * @param selector Optional projection from item (and index) to the numeric value to sum. Defaults to the identity.
+     */
     static sum<T>(set: T[], selector: NumericKeySelector<T>): number;
     static sum(set: number[]): number;
+    /**
+     * Arithmetic mean (average) of the (selected) values of a set.
+     * @param set Input set.
+     * @param selector Optional projection from item (and index) to the numeric value to average. Defaults to the identity.
+     */
     static mean<T>(set: T[], selector: NumericKeySelector<T>): number;
     static mean(set: number[]): number;
+    /**
+     * Median (middle value, or average of the two middle values) of the (selected) values of a set.
+     * @param set Input set.
+     * @param selector Optional projection from item (and index) to the numeric value. Defaults to the identity.
+     */
     static median<T>(set: T[], selector: NumericKeySelector<T>): number;
     static median(set: number[]): number;
+    /**
+     * Mode (most frequently occurring value) of the (selected) values of a set.
+     * @param set Input set.
+     * @param selector Optional projection from item (and index) to the numeric value. Defaults to the identity.
+     */
     static mode<T>(set: T[], selector: NumericKeySelector<T>): number;
     static mode(set: number[]): number;
     /**
@@ -630,12 +1071,65 @@ declare class Utils_2 {
 
 /** Utility tools about number theory, 'diophantine' stuff... */
 declare class Utils_3 {
+    /**
+     * Computes the least common multiple (LCM) of the given numbers (each rounded to the nearest integer).
+     * @param args Two or more numbers.
+     * @returns The least common multiple.
+     * @throws If fewer than two numbers are provided.
+     */
     static lcd(...args: number[]): number;
+    /**
+     * Computes the greatest common divisor (GCD) of two numbers (each rounded to the nearest integer)
+     * using the Euclidean algorithm.
+     * @param a
+     * @param b
+     */
     static gcd(a: number, b: number): any;
+    /**
+     * Converts an integer value from one numeric base (radix) to another.
+     * @param v Value to convert, in the source radix.
+     * @param from Source radix.
+     * @param to Target radix.
+     * @returns The value re-expressed in the target radix, as a string.
+     */
     static rebaseInt(v: number | string, from: number, to: number): string;
+    /**
+     * Converts a (possibly fractional) numeric value from one radix to another, dispatching to the
+     * appropriate specialized conversion routine depending on whether base-10 is the source, the
+     * target, or neither.
+     * @param v Value to convert, in the source radix.
+     * @param fromRadix Source radix.
+     * @param toRadix Target radix.
+     * @param precision Maximum number of digits to compute for the fractional part (default 12).
+     * @returns The converted value: a number when converting to base 10, otherwise a string.
+     */
     static rebaseFloat(v: number | string, fromRadix: number, toRadix: number, precision?: number): string | number;
+    /**
+     * Converts a numeric string expressed in the given radix into its base-10 (decimal) value.
+     * @param v Value to convert, expressed in the source radix (digits from `0-9a-z`).
+     * @param radix Source radix (must be greater than 1 and no larger than the size of the digit alphabet).
+     * @param precision Unused for the integer part; reserved for symmetry with the sibling conversion methods.
+     * @returns The base-10 numeric value, or `NaN` if the input contains invalid digits.
+     * @throws If radix is out of range.
+     */
     static rebaseFloatNTo10(v: string, radix: number, precision?: number): number;
+    /**
+     * Converts a base-10 number into its representation in another **integer** radix.
+     * @param v Base-10 value to convert.
+     * @param radix Target integer radix (must be greater than 1 and no larger than the size of the digit alphabet).
+     * @param precision Maximum number of digits to compute for the fractional part (default 12).
+     * @returns The value re-expressed in the target radix, as a string.
+     * @throws If radix is out of range.
+     */
     static rebaseFloat10ToNIntBase(v: number, radix: number, precision?: number): string;
+    /**
+     * Converts a base-10 number into its representation in another (possibly non-integer) radix.
+     * @param v Base-10 value to convert.
+     * @param radix Target radix, possibly fractional (must be greater than 1 and no larger than the size of the digit alphabet).
+     * @param precision Maximum number of digits to compute for the fractional part (default 12).
+     * @returns The value re-expressed in the target radix, as a string.
+     * @throws If radix is out of range.
+     */
     static rebaseFloat10ToN(v: number, radix: number, precision?: number): string;
 }
 
@@ -650,7 +1144,15 @@ declare class Vector {
      * @param v
      */
     static unit(v: Vector): Vector;
+    /**
+     * Returns the squared magnitude (length) of the vector. Cheaper than {@link mag} since it avoids the square root.
+     * @param v
+     */
     static magSqr(v: Vector): number;
+    /**
+     * Returns the magnitude (length) of the vector.
+     * @param v
+     */
     static mag(v: Vector): number;
     /**
      * Normalizes the provided vector in place.
@@ -688,12 +1190,27 @@ declare class Vector {
 declare interface Vector3D extends Point3D {
 }
 
+/** 3D vector utils. */
 declare class Vector3D {
+    /**
+     * Builds a {@link Vector3D} from its x, y, z components, in that order.
+     * @param args Exactly 3 numbers: x, y, z.
+     * @throws If the number of arguments is not exactly 3.
+     */
     static from(...args: number[]): Vector3D;
+    /**
+     * Parses a string representation (e.g. `"1 2 3"` or `"1,2,3"`) into a {@link Vector3D}.
+     * @param input String to parse.
+     * @throws If the input cannot be parsed as exactly 3 numbers.
+     */
     static parse(input: string): Vector3D;
+    /** Returns the unit vector along the x axis: `(1, 0, 0)`. */
     static i(): Vector3D;
+    /** Returns the unit vector along the y axis: `(0, 1, 0)`. */
     static j(): Vector3D;
+    /** Returns the unit vector along the z axis: `(0, 0, 1)`. */
     static k(): Vector3D;
+    /** Returns the zero vector: `(0, 0, 0)`. */
     static zero(): Vector3D;
     /**
      * Subtracts a point p from another and returns the resulting vector.
@@ -718,8 +1235,24 @@ declare class Vector3D {
      * @param v2
      */
     static cross(v1: Point3D, v2: Point3D): Vector3D;
+    /**
+     * Scales a vector by a single factor applied uniformly to all axes.
+     * @param v Vector to scale.
+     * @param f Scale factor for x, y and z.
+     */
     static scale(v: Vector3D, f: number): Vector3D;
+    /**
+     * Scales a vector by independent per-axis factors.
+     * @param v Vector to scale.
+     * @param fx Scale factor for x.
+     * @param fy Scale factor for y.
+     * @param fz Scale factor for z.
+     */
     static scale(v: Vector3D, fx: number, fy: number, fz: number): Vector3D;
+    /**
+     * Returns the squared magnitude (length) of the vector. Cheaper than {@link mag} since it avoids the square root.
+     * @param v
+     */
     static magSqr(v: Point3D): number;
     /**
      * Checks if the two points are effectively the same location.
@@ -728,7 +1261,15 @@ declare class Vector3D {
      * @returns True if the points are considered coincident within tolerance; otherwise, false.
      */
     static areClose(v1: Point3D, v2: Point3D): boolean;
+    /**
+     * Returns the magnitude (length) of the vector.
+     * @param v
+     */
     static mag(v: Point3D): number;
+    /**
+     * Returns the opposite vector (each component negated).
+     * @param v
+     */
     static negate(v: Vector3D): Vector3D;
     /**
      * Returns the unit (normalized) vector having the same direction and sense of the provided one.