@fimbul-works/vec
Version:
A comprehensive TypeScript vector math library providing 2D, 3D, and 4D vector operations with a focus on performance and type safety.
556 lines (555 loc) • 19 kB
TypeScript
/**
* Represents a 3D vector with various operations.
*/
export declare class Vec3 {
#private;
/**
* Creates a new Vec3 instance.
* @param x - The x-coordinate of the vector.
* @param y - The y-coordinate of the vector.
* @param z - The z-coordinate of the vector.
*/
constructor(x?: number, y?: number, z?: number);
/**
* Adds two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @returns A new Vec3 instance representing the sum.
*/
static add(v: Vec3, w: Vec3): Vec3;
/**
* Subtracts one vector from another.
* @param v - The vector to subtract from.
* @param w - The vector to subtract.
* @returns A new Vec2 instance representing the difference.
*/
static subtract(v: Vec3, w: Vec3): Vec3;
/**
* Multiplies one vector with another.
* @param v - The first vector.
* @param w - The second vector.
* @returns A new Vec3 instance representing the multiplied value.
*/
static multiply(v: Vec3, w: Vec3): Vec3;
/**
* Divides one vector with another.
* @param v - Divident.
* @param w - Divisor.
* @returns A new Vec3 instance representing the divided value.
*/
static divide(v: Vec3, w: Vec3): Vec3;
/**
* Calculates the angle between two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @returns The angle between the vectors in radians.
*/
static angleBetween(v: Vec3, w: Vec3): number;
/**
* Calculates the cross product of two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @returns The cross product of the two vectors.
*/
static cross(v: Vec3, w: Vec3): Vec3;
/**
* Reflects a vector across a normal vector.
* The normal vector should be normalized (unit length).
* @param v - The vector to reflect.
* @param normal - The normal vector to reflect across (must be normalized).
* @returns A new Vec3 instance representing the reflected vector.
*/
static reflect(v: Vec3, normal: Vec3): Vec3;
/**
* Calculates the Euclidean distance between two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @returns The distance between the vectors.
*/
static distance(v: Vec3, w: Vec3): number;
/**
* Calculates the Chebyshev distance between two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @returns The Chebyshev distance between the vectors.
*/
static distanceChebyshev(v: Vec3, w: Vec3): number;
/**
* Calculates the Manhattan distance between two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @returns The Manhattan distance between the vectors.
*/
static distanceManhattan(v: Vec3, w: Vec3): number;
/**
* Calculates the Minkowski distance between two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @param p - The order of the Minkowski distance.
* @returns The Minkowski distance between the vectors.
*/
static distanceMinkowski(v: Vec3, w: Vec3, p: number): number;
/**
* Calculates the squared Euclidean distance between two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @returns The squared distance between the vectors.
*/
static distanceSq(v: Vec3, w: Vec3): number;
/**
* Calculates the dot product of two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @returns The dot product of the two vectors.
*/
static dot(v: Vec3, w: Vec3): number;
/**
* Creates a Vec3 from cylindrical coordinates.
* @param r - Radial distance from the z-axis
* @param phi - Azimuthal angle in the x-y plane from the x-axis
* @param z - Height above the x-y plane
* @returns New Vec3 instance
*/
static fromCylindricalCoords(r: number, phi: number, z: number): Vec3;
/**
* Creates a Vec3 from spherical coordinates.
* @param r - Radial distance from origin
* @param theta - Polar angle from the z-axis
* @param phi - Azimuthal angle in the x-y plane from the x-axis
* @returns New Vec3 instance
*/
static fromSphericalCoords(r: number, theta: number, phi: number): Vec3;
/**
* Creates an immutable Vec3-like object.
* @param x - The x-coordinate of the vector.
* @param y - The y-coordinate of the vector.
* @returns An immutable object with Vec3-like properties.
*/
static immutable(x?: number, y?: number, z?: number): {
readonly x: number;
readonly y: number;
readonly z: number;
readonly xyz: readonly number[];
readonly magnitude: number;
readonly magnitudeSq: number;
readonly angleX: number;
readonly angleY: number;
readonly angleZ: number;
readonly isInfinite: boolean;
readonly isNaN: boolean;
readonly isZero: boolean;
};
/**
* Checks if a vector has infinite components.
* @param v - The vector to check.
* @returns True if the vector has infinite components, false otherwise.
*/
static isInfinite(v: Vec3): boolean;
/**
* Checks if a vector has NaN components.
* @param v - The vector to check.
* @returns True if the vector has NaN components, false otherwise.
*/
static isNaN(v: Vec3): boolean;
/**
* Checks if a vector is zero.
* @param v - The vector to check.
* @returns True if the vector is zero, false otherwise.
*/
static isZero(v: Vec3): boolean;
/**
* Performs linear interpolation between two vectors.
* @param v - The first vector.
* @param w - The second vector.
* @param t - The interpolation parameter (0 to 1).
* @returns A new Vec2 instance representing the interpolated vector.
*/
static lerp(v: Vec3, w: Vec3, t: number): Vec3;
/**
* Negates a vector.
* @param v - The vector to negate.
* @returns A new Vec2 instance representing the negated vector.
*/
static negate(v: Vec3): Vec3;
/**
* Normalizes a vector.
* @param v - The vector to normalize.
* @returns A new Vec2 instance representing the normalized vector.
*/
static normalize(v: Vec3): Vec3;
/**
* Projects one vector onto another.
* @param v - The vector to project.
* @param w - The vector to project onto.
* @returns A new Vec2 instance representing the projected vector.
*/
static project(v: Vec3, w: Vec3): Vec3;
/**
* Creates a random unit vector.
* @param random - A function that returns a random number between 0 and 1.
* @returns A new Vec3 instance representing a random unit vector.
*/
static random(random?: () => number): Vec3;
/**
* Checks if two vectors are equal.
* @param v - The first vector.
* @param w - The second vector.
* @returns True if the vectors are equal, false otherwise.
*/
static satisfyEquality(v: Vec3, w: Vec3): boolean;
/**
* Checks if two vectors are opposite.
* @param v - The first vector.
* @param w - The second vector.
* @returns True if the vectors are opposite, false otherwise.
*/
static satisfyOpposition(v: Vec3, w: Vec3): boolean;
/**
* Compares a vector with another vector using an epsilon value for floating-point comparison.
* @param v - The first vector.
* @param w - The second vector.
* @param epsilon - The maximum difference between components to consider them equal.
* @returns True if the vectors are equal within epsilon, false otherwise.
*/
static equals(v: Vec3, w: Vec3, epsilon?: number): boolean;
/**
* Scales a vector by a scalar value.
* @param v - The vector to scale.
* @param c - The scalar value.
* @returns A new Vec3 instance representing the scaled vector.
*/
static scale(v: Vec3, c: number): Vec3;
/**
* Creates a zero vector.
* @returns A new Vec3 instance representing a zero vector.
*/
static zero(): Vec3;
/**
* Creates a vector with all components set to 1.0.
* @returns A new Vec3 instance representing a vector with all components set to 1.0.
*/
static one(): Vec3;
/**
* Creates a Vec3 from an array.
* @returns A new Vec3 instance.
*/
static fromArray(arr: [number, number, number] | number[]): Vec3;
/**
* Creates a Vec3 from an object with x, y and z properties.
* @returns A new Vec3 instance.
*/
static fromObject(obj: {
x: number;
y: number;
z: number;
}): Vec3;
/**
* Creates a Vec3 instance from a JSON-parsed object.
* @param json - The JSON-parsed object containing x and y properties.
* @returns A new Vec3 instance.
*/
static fromJSON(json: {
x: number;
y: number;
z: number;
}): Vec3;
/**
* Gets the x-component of the vector.
* @returns The x-component.
*/
get x(): number;
/**
* Sets the x-component of the vector.
* @param x - The new x-component.
*/
set x(x: number);
/**
* Gets the y-component of the vector.
* @returns The y-component.
*/
get y(): number;
/**
* Sets the y-component of the vector.
* @param y - The new y-component.
*/
set y(y: number);
/**
* Gets the z-component of the vector.
* @returns The z-component.
*/
get z(): number;
/**
* Sets the z-component of the vector.
* @param z - The new z-component.
*/
set z(z: number);
/**
* Gets a copy of the vector's components as an array.
* @returns An array containing the x, y and z components of the vector.
*/
get xyz(): [number, number, number];
/**
* Sets both components of the vector at once.
* @param xyz - An array containing the new x, y and z components.
*/
set xyz(xyz: [number, number, number] | number[]);
/**
* Gets the angle between the vector and the positive x-axis in radians.
* @returns The angle in radians, always in the range [0, 2π).
*/
get angleX(): number;
/**
* Gets the angle between the vector and the positive y-axis in radians.
* @returns The angle in radians, always in the range [0, 2π).
*/
get angleY(): number;
/**
* Gets the angle between the vector and the positive z-axis in radians.
* @returns The angle in radians, always in the range [0, 2π).
*/
get angleZ(): number;
/**
* Sets the magnitude (length) of the vector, maintaining its direction.
* @param m - The new magnitude.
*/
get magnitude(): number;
/**
* Gets the squared magnitude of the vector.
* This is faster to compute than the actual magnitude and is useful for comparisons.
* @returns The squared magnitude of the vector.
*/
get magnitudeSq(): number;
/**
* Sets the magnitude (length) of the vector, maintaining its direction.
* @param m - The new magnitude.
*/
set magnitude(m: number);
/**
* Adds another vector to this vector.
* @param v - The vector to add.
* @returns This Vec3 instance for method chaining.
*/
add(v: Vec3): this;
/**
* Subtracts another vector from this vector.
* @param v - The vector to subtract.
* @returns This Vec3 instance for method chaining.
*/
subtract(v: Vec3): this;
/**
* Multiplies this vector with another vector.
* @param v - The vector to multiply with.
* @returns This Vec3 instance for method chaining.
*/
multiply(v: Vec3): this;
/**
* Divides this vector with another vector.
* @param v - The vector to divide with.
* @returns This Vec3 instance for method chaining.
*/
divide(v: Vec3): this;
/**
* Calculates the angle between this vector and another vector.
* @param v - The other vector.
* @returns The angle between the vectors in radians.
*/
angleBetween(v: Vec3): number;
/**
* Clamps the magnitude of this vector between a minimum and maximum value.
* @param min - The minimum magnitude.
* @param max - The maximum magnitude.
* @returns This Vec3 instance for method chaining.
*/
clamp(min: number, max: number): this;
/**
* Creates a copy of this vector.
* @returns A new Vec3 instance with the same components.
*/
clone(): Vec3;
/**
* Copies the components of another vector to this vector.
* @param v - The vector to copy from.
* @returns This Vec3 instance for method chaining.
*/
copy(v: Vec3): this;
/**
* Calculates the dot product of this vector with another vector.
* @param v - The other vector.
* @returns The dot product of the vectors.
*/
dot(v: Vec3): number;
/**
* Calculates cross product between this vector and another vector.
* @param v - The other vector.
* @returns The distance between the vectors.
*/
cross(v: Vec3): this;
/**
* Reflects this vector across a normal vector.
* The normal vector should be normalized (unit length).
* @param normal - The normal vector to reflect across (must be normalized).
* @returns This Vec3 instance for method chaining.
*/
reflect(normal: Vec3): this;
/**
* Calculates the distance between this vector and another vector.
* @param v - The other vector.
* @returns The distance between the vectors.
*/
distance(v: Vec3): number;
/**
* Calculates the Chebyshev distance between vector and another vector.
* @param v - The other vector.
* @returns The Chebyshev distance between the vectors.
*/
distanceChebyshev(v: Vec3): number;
/**
* Calculates the Manhattan distance between vector and another vector.
* @param v - The other vector.
* @returns The Manhattan distance between the vectors.
*/
distanceManhattan(v: Vec3): number;
/**
* Calculates the Minkowski distance between this vector and another vector.
* @param v - The other vector.
* @param p - The order of the Minkowski distance.
* @returns The Minkowski distance between the vectors.
*/
distanceMinkowski(v: Vec3, p: number): number;
/**
* Calculates the squared distance between this vector and another vector.
* @param v - The other vector.
* @returns The squared distance between the vectors.
*/
distanceSq(v: Vec3): number;
/**
* Checks if this vector has infinite components.
* @returns True if the vector has infinite components, false otherwise.
*/
isInfinite(): boolean;
/**
* Checks if this vector has NaN components.
* @returns True if the vector has NaN components, false otherwise.
*/
isNaN(): boolean;
/**
* Checks if this vector is zero.
* @returns True if the vector is zero, false otherwise.
*/
isZero(): boolean;
/**
* Limits the maximum magnitude of this vector.
* @param max - The maximum magnitude.
* @returns This Vec3 instance for method chaining.
*/
limitMax(max: number): this;
/**
* Limits the minimum magnitude of this vector.
* @param min - The minimum magnitude.
* @returns This Vec3 instance for method chaining.
*/
limitMin(min: number): this;
/**
* Sets this vector to point towards another vector.
* @param v - The vector to look at.
* @returns This Vec3 instance for method chaining.
*/
lookAt(v: Vec3): this;
/**
* Negates this vector.
* @returns This Vec3 instance for method chaining.
*/
negate(): this;
/**
* Normalizes this vector.
* @returns This Vec3 instance for method chaining.
*/
normalize(): this;
/**
* Projects this vector onto another vector.
* @param v - The vector to project onto.
* @returns This Vec3 instance for method chaining.
*/
project(v: Vec3): this;
/**
* Sets this vector to a random direction with the same magnitude.
* @param random - A function that returns a random number between 0 and 1.
* @returns This Vec3 instance for method chaining.
*/
random(random?: () => number): this;
/**
* Rotates this vector around the X-axis.
* @param phi - The angle of rotation in radians.
* @returns This Vec3 instance for method chaining.
*/
rotateX(phi: number): this;
/**
* Rotates this vector around the Y-axis.
* @param phi - The angle of rotation in radians.
* @returns This Vec3 instance for method chaining.
*/
rotateY(phi: number): this;
/**
* Rotates this vector around the Z-axis.
* @param phi - The angle of rotation in radians.
* @returns This Vec3 instance for method chaining.
*/
rotateZ(phi: number): this;
/**
* Checks if this vector is equal to another vector.
* @param v - The other vector.
* @returns True if the vectors are equal, false otherwise.
*/
satisfyEquality(v: Vec3): boolean;
/**
* Checks if this vector is opposite to another vector.
* @param v - The other vector.
* @returns True if the vectors are opposite, false otherwise.
*/
satisfyOpposition(v: Vec3): boolean;
/**
* Compares this vector with another vector using an epsilon value for floating-point comparison.
* @param v - The vector to compare with.
* @param epsilon - The maximum difference between components to consider them equal.
* @returns True if the vectors are equal within epsilon, false otherwise.
*/
equals(v: Vec3, epsilon?: number): boolean;
/**
* Scales this vector by a scalar value.
* @param c - The scalar value.
* @returns This Vec3 instance for method chaining.
*/
scale(c: number): this;
/**
* Sets this vector to zero.
* @returns This Vec3 instance for method chaining.
*/
zero(): this;
/**
* Makes the Vec3 instance iterable.
* @yields The x, y and z components of the vector.
*/
[Symbol.iterator](): IterableIterator<number>;
/**
* Returns a string representation of the vector.
* @returns A string in the format "Vec3(x, y, z)".
*/
toString(): string;
/**
* Converts the vector to a plain object.
* @returns An object with x, y and z properties.
*/
toObject(): {
x: number;
y: number;
z: number;
};
/**
* Serializes the vector to a JSON-friendly format.
* @returns A JSON-friendly object representation of the vector.
*/
toJSON(): {
x: number;
y: number;
};
}