@sachitv/safe-math-ts 0.1.0

package/esm/src/geometry3d/vector3.js

@@ -0,0 +1,361 @@
+import { quantity, } from '../units.js';
+/**
+ * Casts a raw number into a branded quantity.
+ *
+ * @param value Raw numeric scalar.
+ * @returns Branded quantity.
+ */
+const asQuantity = (value) => value;
+/**
+ * Casts xyz components to a branded displacement tuple.
+ *
+ * @param x X component.
+ * @param y Y component.
+ * @param z Z component.
+ * @returns Branded displacement.
+ */
+const asDelta3 = (x, y, z) => [x, y, z];
+/**
+ * Casts xyz components to a branded point tuple.
+ *
+ * @param x X component.
+ * @param y Y component.
+ * @param z Z component.
+ * @returns Branded point.
+ */
+const asPoint3 = (x, y, z) => [x, y, z];
+/**
+ * Casts xyz components to a branded direction tuple.
+ *
+ * @param x X component.
+ * @param y Y component.
+ * @param z Z component.
+ * @returns Branded direction.
+ */
+const asDir3 = (x, y, z) => [x, y, z];
+/**
+ * Constructs a frame-aware displacement vector.
+ *
+ * @param frameTag Frame token for the resulting displacement.
+ * @param x X component.
+ * @param y Y component.
+ * @param z Z component.
+ * @returns Displacement in `frameTag`.
+ */
+export const delta3 = (frameTag, x, y, z) => {
+    void frameTag;
+    return asDelta3(x, y, z);
+};
+/**
+ * Constructs a frame-aware point.
+ *
+ * @param frameTag Frame token for the resulting point.
+ * @param x X component.
+ * @param y Y component.
+ * @param z Z component.
+ * @returns Point in `frameTag`.
+ */
+export const point3 = (frameTag, x, y, z) => {
+    void frameTag;
+    return asPoint3(x, y, z);
+};
+/**
+ * Constructs a frame-aware direction (dimensionless).
+ *
+ * @param frameTag Frame token for the resulting direction.
+ * @param x X component.
+ * @param y Y component.
+ * @param z Z component.
+ * @returns Direction in `frameTag`.
+ */
+export const dir3 = (frameTag, x, y, z) => {
+    void frameTag;
+    return asDir3(x, y, z);
+};
+/**
+ * Constructs a zero displacement for an explicit unit and frame.
+ *
+ * @param unitTag Unit token for the displacement components.
+ * @param frameTag Frame token for the displacement.
+ * @returns Zero displacement in the provided unit and frame.
+ */
+export const zeroVec3 = (unitTag, frameTag) => delta3(frameTag, quantity(unitTag, 0), quantity(unitTag, 0), quantity(unitTag, 0));
+/**
+ * Adds two displacements with matching unit and frame.
+ *
+ * @param left Left displacement.
+ * @param right Right displacement in the same unit/frame.
+ * @returns Component-wise sum.
+ */
+export const addVec3 = (left, right) => {
+    const x = asQuantity(left[0] + right[0]);
+    const y = asQuantity(left[1] + right[1]);
+    const z = asQuantity(left[2] + right[2]);
+    return asDelta3(x, y, z);
+};
+/**
+ * Subtracts two displacements with matching unit and frame.
+ *
+ * @param left Left displacement.
+ * @param right Right displacement in the same unit/frame.
+ * @returns Component-wise difference.
+ */
+export const subVec3 = (left, right) => {
+    const x = asQuantity(left[0] - right[0]);
+    const y = asQuantity(left[1] - right[1]);
+    const z = asQuantity(left[2] - right[2]);
+    return asDelta3(x, y, z);
+};
+/**
+ * Negates each displacement component.
+ *
+ * @param value Displacement to negate.
+ * @returns Negated displacement.
+ */
+export const negVec3 = (value) => asDelta3(asQuantity(-value[0]), asQuantity(-value[1]), asQuantity(-value[2]));
+/**
+ * Multiplies each displacement component by a unitless scalar.
+ *
+ * @param value Displacement to scale.
+ * @param scalar Unitless multiplier.
+ * @returns Scaled displacement.
+ */
+export const scaleVec3 = (value, scalar) => {
+    const x = asQuantity(value[0] * scalar);
+    const y = asQuantity(value[1] * scalar);
+    const z = asQuantity(value[2] * scalar);
+    return asDelta3(x, y, z);
+};
+/**
+ * Scales a unitless direction by a unitful magnitude.
+ *
+ * @param value Direction vector.
+ * @param magnitude Unitful scalar magnitude.
+ * @returns Displacement with unit derived from `magnitude`.
+ */
+export const scaleDir3 = (value, magnitude) => asDelta3(asQuantity(value[0] * magnitude), asQuantity(value[1] * magnitude), asQuantity(value[2] * magnitude));
+/**
+ * Translates a point by a displacement.
+ *
+ * @param point Input point.
+ * @param delta Translation displacement in the same frame/unit.
+ * @returns Translated point.
+ */
+export const addPoint3 = (point, delta) => asPoint3(asQuantity(point[0] + delta[0]), asQuantity(point[1] + delta[1]), asQuantity(point[2] + delta[2]));
+/**
+ * Offsets a point by subtracting a displacement.
+ *
+ * @param point Input point.
+ * @param delta Displacement to subtract.
+ * @returns Offset point.
+ */
+export const subPoint3Delta3 = (point, delta) => asPoint3(asQuantity(point[0] - delta[0]), asQuantity(point[1] - delta[1]), asQuantity(point[2] - delta[2]));
+/**
+ * Computes the displacement from `right` point to `left` point.
+ *
+ * @param left Destination point.
+ * @param right Source point.
+ * @returns Displacement that moves `right` to `left`.
+ */
+export const subPoint3 = (left, right) => asDelta3(asQuantity(left[0] - right[0]), asQuantity(left[1] - right[1]), asQuantity(left[2] - right[2]));
+/**
+ * Computes dot product for two displacements/directions in the same frame.
+ *
+ * @param left Left vector.
+ * @param right Right vector in the same frame.
+ * @returns Scalar product with multiplied unit.
+ */
+export const dotVec3 = (left, right) => {
+    const xx = left[0] * right[0];
+    const yy = left[1] * right[1];
+    const zz = left[2] * right[2];
+    const dot = xx + yy + zz;
+    return asQuantity(dot);
+};
+/**
+ * Computes cross product for two displacements/directions in the same frame.
+ *
+ * @param left Left vector.
+ * @param right Right vector in the same frame.
+ * @returns Cross-product vector with multiplied unit.
+ */
+export const crossVec3 = (left, right) => {
+    const x = asQuantity(left[1] * right[2] - left[2] * right[1]);
+    const y = asQuantity(left[2] * right[0] - left[0] * right[2]);
+    const z = asQuantity(left[0] * right[1] - left[1] * right[0]);
+    return asDelta3(x, y, z);
+};
+/**
+ * Computes squared Euclidean length of a displacement/direction.
+ *
+ * @param value Input vector.
+ * @returns Squared length.
+ */
+export const lengthSquaredVec3 = (value) => dotVec3(value, value);
+/**
+ * Computes Euclidean length of a displacement/direction.
+ *
+ * @param value Input vector.
+ * @returns Vector length.
+ */
+export const lengthVec3 = (value) => asQuantity(Math.hypot(value[0], value[1], value[2]));
+export function distanceVec3(left, right) {
+    const dx = left[0] - right[0];
+    const dy = left[1] - right[1];
+    const dz = left[2] - right[2];
+    const distance = Math.hypot(dx, dy, dz);
+    return asQuantity(distance);
+}
+/**
+ * Computes Euclidean distance between two points.
+ *
+ * @param left Left point.
+ * @param right Right point in the same unit/frame.
+ * @returns Distance magnitude.
+ */
+export const distancePoint3 = (left, right) => distanceVec3(left, right);
+const NEAR_ZERO = 1e-14;
+/**
+ * Normalizes displacement length to 1.
+ *
+ * Unsafe variant: performs no zero-length guard.
+ * Degenerate inputs can yield `NaN`/`Infinity`.
+ *
+ * @param value Vector to normalize.
+ * @returns Unit-length direction in the same frame.
+ */
+export const normalizeVec3Unsafe = (value) => {
+    const magnitude = lengthVec3(value);
+    return asDir3(asQuantity(value[0] / magnitude), asQuantity(value[1] / magnitude), asQuantity(value[2] / magnitude));
+};
+/**
+ * Normalizes displacement length to 1.
+ *
+ * Throws when vector length is at or below `1e-14`.
+ *
+ * @param value Vector to normalize.
+ * @returns Unit-length direction in the same frame.
+ * @throws {Error} When the vector is near zero length.
+ */
+export const normalizeVec3 = (value) => {
+    const magnitude = lengthVec3(value);
+    if (magnitude <= NEAR_ZERO) {
+        throw new Error('Cannot normalize a zero-length vector');
+    }
+    return normalizeVec3Unsafe(value);
+};
+export function lerpVec3(start, end, t) {
+    const inverseT = 1 - t;
+    const x = start[0] * inverseT +
+        end[0] * t;
+    const y = start[1] * inverseT +
+        end[1] * t;
+    const z = start[2] * inverseT +
+        end[2] * t;
+    return [
+        asQuantity(x),
+        asQuantity(y),
+        asQuantity(z),
+    ];
+}
+/**
+ * Projects a displacement onto another displacement in the same frame.
+ *
+ * Unsafe variant: performs no zero-length guard for `onto`.
+ *
+ * @param value Vector being projected.
+ * @param onto Target direction for projection.
+ * @returns Projection of `value` onto `onto`.
+ */
+export const projectVec3Unsafe = (value, onto) => {
+    const ontoLengthSquared = onto[0] * onto[0] +
+        onto[1] * onto[1] +
+        onto[2] * onto[2];
+    const dotValueOnto = value[0] * onto[0] +
+        value[1] * onto[1] +
+        value[2] * onto[2];
+    const scalar = dotValueOnto / ontoLengthSquared;
+    return asDelta3(asQuantity(onto[0] * scalar), asQuantity(onto[1] * scalar), asQuantity(onto[2] * scalar));
+};
+/**
+ * Projects a displacement onto another displacement in the same frame.
+ *
+ * @param value Vector being projected.
+ * @param onto Target direction for projection.
+ * @returns Projection of `value` onto `onto`.
+ * @throws {Error} When `onto` is near zero length.
+ */
+export const projectVec3 = (value, onto) => {
+    const ontoLengthSquared = onto[0] * onto[0] +
+        onto[1] * onto[1] +
+        onto[2] * onto[2];
+    if (ontoLengthSquared <= NEAR_ZERO * NEAR_ZERO) {
+        throw new Error('Cannot project onto a zero-length vector');
+    }
+    return projectVec3Unsafe(value, onto);
+};
+/**
+ * Reflects a displacement around a normal direction.
+ *
+ * Unsafe variant: performs no zero-length guard for `normal`.
+ *
+ * @param incident Incident displacement.
+ * @param normal Reflection normal direction.
+ * @returns Reflected displacement.
+ */
+export const reflectVec3Unsafe = (incident, normal) => {
+    const dir_normalized = normalizeVec3Unsafe(normal);
+    const dotIncidentNormal = incident[0] * dir_normalized[0] +
+        incident[1] * dir_normalized[1] +
+        incident[2] * dir_normalized[2];
+    const scale = 2 * dotIncidentNormal;
+    return asDelta3(asQuantity(incident[0] - dir_normalized[0] * scale), asQuantity(incident[1] - dir_normalized[1] * scale), asQuantity(incident[2] - dir_normalized[2] * scale));
+};
+/**
+ * Reflects a displacement around a normal direction.
+ *
+ * @param incident Incident displacement.
+ * @param normal Reflection normal direction.
+ * @returns Reflected displacement.
+ * @throws {Error} When `normal` is near zero length.
+ */
+export const reflectVec3 = (incident, normal) => {
+    normalizeVec3(normal);
+    return reflectVec3Unsafe(incident, normal);
+};
+/**
+ * Computes the angle in radians between two displacements.
+ *
+ * Unsafe variant: performs no zero-length guards.
+ *
+ * @param left Left vector.
+ * @param right Right vector.
+ * @returns Angle in radians.
+ */
+export const angleBetweenVec3Unsafe = (left, right) => {
+    const leftLength = Math.hypot(left[0], left[1], left[2]);
+    const rightLength = Math.hypot(right[0], right[1], right[2]);
+    const dotLeftRight = left[0] * right[0] +
+        left[1] * right[1] +
+        left[2] * right[2];
+    const lengthProduct = leftLength * rightLength;
+    const cosine = dotLeftRight / lengthProduct;
+    const clamped = Math.max(-1, Math.min(1, cosine));
+    return Math.acos(clamped);
+};
+/**
+ * Computes the angle in radians between two non-zero displacements.
+ *
+ * @param left Left vector.
+ * @param right Right vector.
+ * @returns Angle in radians.
+ * @throws {Error} When either vector is near zero length.
+ */
+export const angleBetweenVec3 = (left, right) => {
+    const leftLength = Math.hypot(left[0], left[1], left[2]);
+    const rightLength = Math.hypot(right[0], right[1], right[2]);
+    if (leftLength <= NEAR_ZERO || rightLength <= NEAR_ZERO) {
+        throw new Error('Cannot compute angle with a zero-length vector');
+    }
+    return angleBetweenVec3Unsafe(left, right);
+};