animouse/dist/mescellaneous/math.d.ts

lightweight animation state machine for three js

import type { Vector2Like } from "three";
/** The number of vertices in a triangle. */
export declare const TRIANGLE_VERTEX_COUNT = 3;
/**
 * Precomputed data for efficient triangle operations.
 */
export interface TriangleCache {
    /** A vertex of the triangle. */
    readonly origin: Vector2Like;
    /** The circumcenter of the triangle. */
    readonly circumcenter: Vector2Like;
    /** The squared circumradius of the triangle. */
    readonly circumradiusSquared: number;
    /** Vector from vertex A to vertex B. */
    readonly u: Vector2Like;
    /** Vector from vertex A to vertex C. */
    readonly v: Vector2Like;
    /** Pseudo dot product of u with itself (u·u). */
    readonly d00: number;
    /** Pseudo dot product of u with v (u·v). */
    readonly d01: number;
    /** Pseudo dot product of v with itself (v·v). */
    readonly d11: number;
    /** Inverse of the determinant used in barycentric calculations. */
    readonly invDenom: number;
    /** Minimum bounds of the triangle's axis-aligned bounding box. */
    readonly min: Vector2Like;
    /** Maximum bounds of the triangle's axis-aligned bounding box. */
    readonly max: Vector2Like;
}
/**
 * Precomputes triangle data for efficient subsequent operations.
 * Calculates circumcenter, bounding box, and barycentric coordinate helpers.
 *
 * @param a - First vertex of the triangle (Vector2Like coordinates)
 * @param b - Second vertex of the triangle (Vector2Like coordinates)
 * @param c - Third vertex of the triangle (Vector2Like coordinates)
 * @returns Precomputed triangle data cache for efficient operations
 * @throws {Error} When triangle is degenerate or coordinates are invalid
 * @see {@link assertValidNumber} for coordinate validation details
 */
export declare function precomputeTriangle(a: Vector2Like, b: Vector2Like, c: Vector2Like): TriangleCache;
/**
 * Calculates barycentric coordinates for a point relative to a triangle.
 * Returns undefined if the point lies outside the triangle boundaries.
 *
 * @param point - The point to calculate barycentric coordinates for (Vector2Like coordinates)
 * @param cache - Precomputed triangle data containing vectors and determinants
 * @returns Barycentric weights {aW, bW, cW} if point is inside triangle, undefined otherwise
 * @throws {Error} When point coordinates or cache data are invalid
 * @see {@link assertValidNumber} for coordinate validation details
 */
export declare function calculateBarycentricWeights(point: Vector2Like, cache: {
    origin: Vector2Like;
    u: Vector2Like;
    v: Vector2Like;
    d00: number;
    d01: number;
    d11: number;
    invDenom: number;
    min: Vector2Like;
    max: Vector2Like;
}): {
    aW: number;
    bW: number;
    cW: number;
} | undefined;
/**
 * Calculates the centroid (geometric center) of a triangle.
 * The centroid is the point where all three medians of the triangle intersect.
 *
 * @param a - First vertex of the triangle (Vector2Like coordinates)
 * @param b - Second vertex of the triangle (Vector2Like coordinates)
 * @param c - Third vertex of the triangle (Vector2Like coordinates)
 * @returns The centroid point of the triangle (Vector2Like coordinates)
 * @throws {Error} When any coordinate value is invalid
 * @see {@link assertValidNumber} for coordinate validation details
 */
export declare function calculateTriangleCentroid(a: Vector2Like, b: Vector2Like, c: Vector2Like): Vector2Like;
/**
 * Determines if a point is strictly inside a circle (excluding the boundary).
 * Uses squared distance comparison to avoid expensive square root operations.
 *
 * @param origin - The center point of the circle (Vector2Like coordinates)
 * @param radiusSquared - The squared radius of the circle (positive number)
 * @param point - The point to test (Vector2Like coordinates)
 * @returns True if the point is strictly inside the circle, false otherwise
 * @throws {Error} When coordinates are invalid or radius is not positive
 * @see {@link assertValidNumber} for coordinate validation details
 * @see {@link assertValidPositiveNumber} for radius validation details
 */
export declare function isPointInsideCircle(origin: Vector2Like, radiusSquared: number, point: Vector2Like): boolean;
/**
 * Normalizes an azimuth angle to the range [0, 2π).
 * Handles negative angles by adding 2π to bring them into the valid range.
 *
 * @param azimuth - The azimuth angle in radians (any finite number)
 * @returns The normalized azimuth in the range [0, 2π) radians
 * @throws {Error} When the azimuth value is not a valid number
 * @see {@link assertValidNumber} for validation details
 */
export declare function calculateNormalizedAzimuth(azimuth: number): number;
/**
 * Calculates the forward angular distance between two azimuth angles.
 * Always measures distance in the positive direction, even if a shorter path exists in the backward direction.
 *
 * @param from - The starting azimuth angle in radians (normalized to [0, 2π))
 * @param to - The target azimuth angle in radians (normalized to [0, 2π))
 * @returns The forward angular distance in radians [0, 2π)
 * @throws {Error} When either azimuth value is invalid
 * @see {@link assertValidAzimuth} for azimuth validation details
 */
export declare function calculateAngularDistanceForward(from: number, to: number): number;
/**
 * Determines if an azimuth angle falls within a specified angular range.
 * Handles ranges that wrap around the 0/2π boundary correctly.
 *
 * @param value - The azimuth angle to test in radians (normalized to [0, 2π))
 * @param from - The start of the angular range in radians (normalized to [0, 2π))
 * @param to - The end of the angular range in radians (normalized to [0, 2π))
 * @returns True if the azimuth is within the range (inclusive), false otherwise
 * @throws {Error} When any azimuth value is invalid
 * @see {@link assertValidAzimuth} for azimuth validation details
 */
export declare function isAzimuthBetween(value: number, from: number, to: number): boolean;
/**
 * Calculates the squared Euclidean distance between two points.
 * Using squared distance avoids the expensive square root operation.
 *
 * @param x1 - X coordinate of the first point (finite number)
 * @param y1 - Y coordinate of the first point (finite number)
 * @param x2 - X coordinate of the second point (finite number)
 * @param y2 - Y coordinate of the second point (finite number)
 * @returns The squared distance between the two points (non-negative number)
 * @throws {Error} When any coordinate value is invalid
 * @see {@link assertValidNumber} for coordinate validation details
 */
export declare function calculateDistanceSquared(x1: number, y1: number, x2: number, y2: number): number;
/**
 * Calculates the squared distance from a point to a line segment (edge).
 * Projects the point onto the line segment and clamps to the segment boundaries.
 *
 * @param edge - A tuple containing the two endpoints of the edge (Vector2Like coordinates)
 * @param x - X coordinate of the point (finite number)
 * @param y - Y coordinate of the point (finite number)
 * @returns The squared distance from the point to the closest point on the edge (non-negative number)
 * @throws {Error} When any coordinate value is invalid
 * @see {@link assertValidNumber} for coordinate validation details
 */
export declare function calculateDistanceToEdgeSquared([p1, p2]: [Vector2Like, Vector2Like], x: number, y: number): number;