@interstellar-tools/equations 0.17.0 → 0.19.0

package/dist/categories/helpers/mat-mul3.d.ts

@@ -0,0 +1,46 @@
+import { Matrix3x3Type } from '@interstellar-tools/types';
+/**
+ * Multiply two **3×3 matrices** (row-major).
+ *
+ * Computes:
+ * $$
+ * \mathbf{C} = \mathbf{A}\mathbf{B}
+ * $$
+ *
+ * Using standard matrix multiplication:
+ * $$
+ * C_{r,c} = \sum_{k=0}^{2} A_{r,k}\,B_{k,c}
+ * $$
+ *
+ * Layout:
+ * - Matrices are treated as **row-major**: `M[row][col]`.
+ *
+ * Common usage:
+ * - Compose rotations / direction cosine matrices (DCMs), e.g. `R = R3 * R1 * R3`.
+ * - Compose linear transforms in 3D geometry and mapping pipelines.
+ *
+ * @param A - Left matrix (3×3, row-major).
+ * @param B - Right matrix (3×3, row-major).
+ * @returns The product matrix `A * B` (3×3, row-major).
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * const A: Matrix3x3Type = [
+ *   [1, 2, 3],
+ *   [0, 1, 4],
+ *   [5, 6, 0]
+ * ];
+ *
+ * const B: Matrix3x3Type = [
+ *   [-2, 1, 0],
+ *   [3, 0, 0],
+ *   [4, 5, 1]
+ * ];
+ *
+ * const C = matMul3(A, B);
+ * // C is A*B
+ * ```
+ */
+export declare const matMul3: (A: Matrix3x3Type, B: Matrix3x3Type) => Matrix3x3Type;
+//# sourceMappingURL=mat-mul3.d.ts.map

package/dist/categories/helpers/mat-mul3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mat-mul3.d.ts","sourceRoot":"","sources":["../../../src/categories/helpers/mat-mul3.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,OAAO,GAAI,GAAG,aAAa,EAAE,GAAG,aAAa,KAAG,aAS5D,CAAC"}

package/dist/categories/helpers/mat-mul3.js

@@ -0,0 +1,52 @@
+/**
+ * Multiply two **3×3 matrices** (row-major).
+ *
+ * Computes:
+ * $$
+ * \mathbf{C} = \mathbf{A}\mathbf{B}
+ * $$
+ *
+ * Using standard matrix multiplication:
+ * $$
+ * C_{r,c} = \sum_{k=0}^{2} A_{r,k}\,B_{k,c}
+ * $$
+ *
+ * Layout:
+ * - Matrices are treated as **row-major**: `M[row][col]`.
+ *
+ * Common usage:
+ * - Compose rotations / direction cosine matrices (DCMs), e.g. `R = R3 * R1 * R3`.
+ * - Compose linear transforms in 3D geometry and mapping pipelines.
+ *
+ * @param A - Left matrix (3×3, row-major).
+ * @param B - Right matrix (3×3, row-major).
+ * @returns The product matrix `A * B` (3×3, row-major).
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * const A: Matrix3x3Type = [
+ *   [1, 2, 3],
+ *   [0, 1, 4],
+ *   [5, 6, 0]
+ * ];
+ *
+ * const B: Matrix3x3Type = [
+ *   [-2, 1, 0],
+ *   [3, 0, 0],
+ *   [4, 5, 1]
+ * ];
+ *
+ * const C = matMul3(A, B);
+ * // C is A*B
+ * ```
+ */
+export const matMul3 = (A, B) => {
+    const m = (r, c) => A[r][0] * B[0][c] + A[r][1] * B[1][c] + A[r][2] * B[2][c];
+    return [
+        [m(0, 0), m(0, 1), m(0, 2)],
+        [m(1, 0), m(1, 1), m(1, 2)],
+        [m(2, 0), m(2, 1), m(2, 2)]
+    ];
+};
+//# sourceMappingURL=mat-mul3.js.map

package/dist/categories/helpers/mat-mul3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mat-mul3.js","sourceRoot":"","sources":["../../../src/categories/helpers/mat-mul3.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAgB,EAAE,CAAgB,EAAiB,EAAE;IAC3E,MAAM,CAAC,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,EAAE,CACjC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE5D,OAAO;QACL,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC3B,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC3B,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;KACnB,CAAC;AACb,CAAC,CAAC"}

package/dist/categories/helpers/misc.d.ts

@@ -0,0 +1,118 @@
+import type { Vector3DTupleType } from '@interstellar-tools/types';
+/**
+ * Compute the **Euclidean norm** (length / magnitude) of a 3D vector.
+ *
+ * $$
+ * \lVert \mathbf{v} \rVert = \sqrt{x^2 + y^2 + z^2}
+ * $$
+ *
+ * Uses `Math.hypot` for numerical stability.
+ *
+ * @param v - 3D vector `[x, y, z]`.
+ * @returns Vector magnitude (same units as the components of `v`).
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * norm([3, 4, 12]); // 13
+ * ```
+ */
+export declare const norm: (v: Vector3DTupleType) => number;
+/**
+ * Scale a 3D vector by a scalar.
+ *
+ * Computes:
+ * $$
+ * s\mathbf{v} = [sx, sy, sz]
+ * $$
+ *
+ * @param v - 3D vector `[x, y, z]`.
+ * @param s - Scalar multiplier.
+ * @returns Scaled vector `s * v`.
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * scale([1, -2, 3], 10); // [10, -20, 30]
+ * ```
+ */
+export declare const scale: (v: Vector3DTupleType, s: number) => Vector3DTupleType;
+/**
+ * Subtract two 3D vectors (`a - b`).
+ *
+ * @param a - Minuend vector.
+ * @param b - Subtrahend vector.
+ * @returns Difference vector `a - b`.
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * sub([3, 2, 1], [1, 1, 1]); // [2, 1, 0]
+ * ```
+ */
+export declare const sub: (a: Vector3DTupleType, b: Vector3DTupleType) => Vector3DTupleType;
+/**
+ * Compute the **dot product** of two 3D vectors.
+ *
+ * $$
+ * \mathbf{a}\cdot\mathbf{b} = a_x b_x + a_y b_y + a_z b_z
+ * $$
+ *
+ * @param a - First vector.
+ * @param b - Second vector.
+ * @returns Dot product (units: product of the input component units).
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * dot([1, 2, 3], [4, 5, 6]); // 32
+ * ```
+ */
+export declare const dot: (a: Vector3DTupleType, b: Vector3DTupleType) => number;
+/**
+ * Normalize an angle to the range **[0, 2π)**.
+ *
+ * This is commonly used to keep anomalies / angles within a canonical interval.
+ *
+ * @param x - Angle in radians (or any unit, as long as `TWO_PI` matches that unit).
+ * @returns Equivalent angle in the range `[0, 2π)`.
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * norm2pi(7);            // ~0.7168 (if radians)
+ * norm2pi(-Math.PI / 2); // 3π/2
+ * ```
+ */
+export declare const norm2pi: (x: number) => number;
+/**
+ * Compute the **Kepler equation residual** for an elliptical orbit:
+ *
+ * $$
+ * E - e\sin(E) = M
+ * $$
+ *
+ * This function returns:
+ * $$
+ * r(E) = E - e\sin(E) - \mathrm{wrap}_{2\pi}(M)
+ * $$
+ *
+ * where `wrap_{2π}` normalizes `M` into `[0, 2π)` to keep the residual well-behaved.
+ *
+ * Common usage: root-finding / iteration (Newton–Raphson, Halley, etc.) to solve for
+ * eccentric anomaly `E` given eccentricity `e` and mean anomaly `M`.
+ *
+ * @param E - Eccentric anomaly `E` (radians).
+ * @param e - Eccentricity `e` (dimensionless).
+ * @param M - Mean anomaly `M` (radians).
+ * @returns Residual value `E - e*sin(E) - M_wrapped`.
+ * @group Kepler
+ *
+ * @example
+ * ```ts
+ * // If E solves Kepler's equation, residual(E,e,M) ≈ 0
+ * const r = residual(1.0, 0.1, 0.9);
+ * ```
+ */
+export declare const residual: (E: number, e: number, M: number) => number;
+//# sourceMappingURL=misc.d.ts.map

package/dist/categories/helpers/misc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"misc.d.ts","sourceRoot":"","sources":["../../../src/categories/helpers/misc.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,IAAI,GAAI,GAAG,iBAAiB,WAExC,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,KAAK,GAAI,GAAG,iBAAiB,EAAE,GAAG,MAAM,KAAG,iBAEvD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,GAAG,GACd,GAAG,iBAAiB,EACpB,GAAG,iBAAiB,KACnB,iBAEF,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,GAAG,GAAI,GAAG,iBAAiB,EAAE,GAAG,iBAAiB,WAE7D,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,OAAO,GAAI,GAAG,MAAM,KAAG,MAEnC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,QAAQ,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,WAIvD,CAAC"}

package/dist/categories/helpers/misc.js

@@ -0,0 +1,131 @@
+import { TWO_PI } from '@interstellar-tools/constants';
+/**
+ * Compute the **Euclidean norm** (length / magnitude) of a 3D vector.
+ *
+ * $$
+ * \lVert \mathbf{v} \rVert = \sqrt{x^2 + y^2 + z^2}
+ * $$
+ *
+ * Uses `Math.hypot` for numerical stability.
+ *
+ * @param v - 3D vector `[x, y, z]`.
+ * @returns Vector magnitude (same units as the components of `v`).
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * norm([3, 4, 12]); // 13
+ * ```
+ */
+export const norm = (v) => {
+    return Math.hypot(v[0], v[1], v[2]);
+};
+/**
+ * Scale a 3D vector by a scalar.
+ *
+ * Computes:
+ * $$
+ * s\mathbf{v} = [sx, sy, sz]
+ * $$
+ *
+ * @param v - 3D vector `[x, y, z]`.
+ * @param s - Scalar multiplier.
+ * @returns Scaled vector `s * v`.
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * scale([1, -2, 3], 10); // [10, -20, 30]
+ * ```
+ */
+export const scale = (v, s) => {
+    return [v[0] * s, v[1] * s, v[2] * s];
+};
+/**
+ * Subtract two 3D vectors (`a - b`).
+ *
+ * @param a - Minuend vector.
+ * @param b - Subtrahend vector.
+ * @returns Difference vector `a - b`.
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * sub([3, 2, 1], [1, 1, 1]); // [2, 1, 0]
+ * ```
+ */
+export const sub = (a, b) => {
+    return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+};
+/**
+ * Compute the **dot product** of two 3D vectors.
+ *
+ * $$
+ * \mathbf{a}\cdot\mathbf{b} = a_x b_x + a_y b_y + a_z b_z
+ * $$
+ *
+ * @param a - First vector.
+ * @param b - Second vector.
+ * @returns Dot product (units: product of the input component units).
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * dot([1, 2, 3], [4, 5, 6]); // 32
+ * ```
+ */
+export const dot = (a, b) => {
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+};
+/**
+ * Normalize an angle to the range **[0, 2π)**.
+ *
+ * This is commonly used to keep anomalies / angles within a canonical interval.
+ *
+ * @param x - Angle in radians (or any unit, as long as `TWO_PI` matches that unit).
+ * @returns Equivalent angle in the range `[0, 2π)`.
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * norm2pi(7);            // ~0.7168 (if radians)
+ * norm2pi(-Math.PI / 2); // 3π/2
+ * ```
+ */
+export const norm2pi = (x) => {
+    return ((x % TWO_PI) + TWO_PI) % TWO_PI;
+};
+/**
+ * Compute the **Kepler equation residual** for an elliptical orbit:
+ *
+ * $$
+ * E - e\sin(E) = M
+ * $$
+ *
+ * This function returns:
+ * $$
+ * r(E) = E - e\sin(E) - \mathrm{wrap}_{2\pi}(M)
+ * $$
+ *
+ * where `wrap_{2π}` normalizes `M` into `[0, 2π)` to keep the residual well-behaved.
+ *
+ * Common usage: root-finding / iteration (Newton–Raphson, Halley, etc.) to solve for
+ * eccentric anomaly `E` given eccentricity `e` and mean anomaly `M`.
+ *
+ * @param E - Eccentric anomaly `E` (radians).
+ * @param e - Eccentricity `e` (dimensionless).
+ * @param M - Mean anomaly `M` (radians).
+ * @returns Residual value `E - e*sin(E) - M_wrapped`.
+ * @group Kepler
+ *
+ * @example
+ * ```ts
+ * // If E solves Kepler's equation, residual(E,e,M) ≈ 0
+ * const r = residual(1.0, 0.1, 0.9);
+ * ```
+ */
+export const residual = (E, e, M) => {
+    const Mm = norm2pi(M);
+    return E - e * Math.sin(E) - Mm;
+};
+//# sourceMappingURL=misc.js.map

package/dist/categories/helpers/misc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"misc.js","sourceRoot":"","sources":["../../../src/categories/helpers/misc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAGvD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,CAAoB,EAAE,EAAE;IAC3C,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACtC,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,CAAoB,EAAE,CAAS,EAAqB,EAAE;IAC1E,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AACxC,CAAC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,CACjB,CAAoB,EACpB,CAAoB,EACD,EAAE;IACrB,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,CAAoB,EAAE,CAAoB,EAAE,EAAE;IAChE,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAS,EAAU,EAAE;IAC3C,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC;AAC1C,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,CAAS,EAAE,EAAE;IAC1D,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAEtB,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AAClC,CAAC,CAAC"}

package/dist/categories/helpers/radians.d.ts

@@ -0,0 +1,41 @@
+import type { Radians } from '@interstellar-tools/types';
+/**
+ * Convert **degrees → radians**.
+ *
+ * Uses the standard relation:
+ * $$
+ * \pi\ \text{rad} = 180^\circ
+ * $$
+ *
+ * @param deg - Angle in **degrees**.
+ * @returns Angle in **radians** (branded as {@link Radians}).
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * const halfTurn = toRad(180); // π (Radians)
+ * const rightAngle = toRad(90); // π/2 (Radians)
+ * ```
+ */
+export declare const toRad: (deg: number) => Radians;
+/**
+ * Brand a numeric value as {@link Radians}.
+ *
+ * This is a **type-level** helper only: it does not change the runtime value, but it
+ * prevents accidentally mixing degree-values with radian-values at compile time.
+ *
+ * Use this when you already have a value in radians (e.g., from `Math.atan2`, `Math.PI`,
+ * or your own radian-based computations) and want to pass it to APIs that require `Radians`.
+ *
+ * @param x - Angle value already expressed in **radians**.
+ * @returns The same numeric value, branded as {@link Radians}.
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * const theta = rad(Math.PI / 3);
+ * // theta has type Radians
+ * ```
+ */
+export declare const rad: (x: number) => Radians;
+//# sourceMappingURL=radians.d.ts.map

package/dist/categories/helpers/radians.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"radians.d.ts","sourceRoot":"","sources":["../../../src/categories/helpers/radians.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,MAAM,KAAgC,OAAO,CAAC;AAEzE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,GAAG,GAAI,GAAG,MAAM,KAAG,OAAuB,CAAC"}

package/dist/categories/helpers/radians.js

@@ -0,0 +1,40 @@
+/**
+ * Convert **degrees → radians**.
+ *
+ * Uses the standard relation:
+ * $$
+ * \pi\ \text{rad} = 180^\circ
+ * $$
+ *
+ * @param deg - Angle in **degrees**.
+ * @returns Angle in **radians** (branded as {@link Radians}).
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * const halfTurn = toRad(180); // π (Radians)
+ * const rightAngle = toRad(90); // π/2 (Radians)
+ * ```
+ */
+export const toRad = (deg) => ((deg * Math.PI) / 180);
+/**
+ * Brand a numeric value as {@link Radians}.
+ *
+ * This is a **type-level** helper only: it does not change the runtime value, but it
+ * prevents accidentally mixing degree-values with radian-values at compile time.
+ *
+ * Use this when you already have a value in radians (e.g., from `Math.atan2`, `Math.PI`,
+ * or your own radian-based computations) and want to pass it to APIs that require `Radians`.
+ *
+ * @param x - Angle value already expressed in **radians**.
+ * @returns The same numeric value, branded as {@link Radians}.
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * const theta = rad(Math.PI / 3);
+ * // theta has type Radians
+ * ```
+ */
+export const rad = (x) => x;
+//# sourceMappingURL=radians.js.map

package/dist/categories/helpers/radians.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"radians.js","sourceRoot":"","sources":["../../../src/categories/helpers/radians.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,GAAW,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,GAAG,CAAY,CAAC;AAEzE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,CAAS,EAAW,EAAE,CAAC,CAAY,CAAC"}

package/dist/categories/helpers/rot-1.d.ts

@@ -0,0 +1,38 @@
+import { Matrix3x3Type, Radians } from '@interstellar-tools/types';
+/**
+ * Construct a **right-handed rotation matrix about the x-axis** (often written **R₁**).
+ *
+ * This returns the 3×3 direction cosine matrix (DCM) for an active rotation by angle `theta`
+ * around the **+X** axis, using the common aerospace convention:
+ *
+ * $$
+ * \mathbf{R}_1(\theta)=
+ * \begin{bmatrix}
+ * 1 & 0 & 0 \\
+ * 0 & \cos\theta & -\sin\theta \\
+ * 0 & \sin\theta & \cos\theta
+ * \end{bmatrix}
+ * $$
+ *
+ * ::: info Notes:
+ *
+ * - `theta` is in **radians**.
+ * - Matrix layout is **row-major**: `M[row][col]`.
+ * - Useful for composing 3-1-3 / 3-2-1 sequences (e.g., IAU body orientation) and for
+ *   general 3D frame transforms in mapping pipelines.
+ *
+ * :::
+ *
+ * @param theta - Rotation angle ($ \theta $) in **radians** (finite).
+ * @returns 3×3 rotation matrix ($ \mathbf{R}_1(\theta) $) (row-major).
+ * @throws {TypeError} If `theta` is not a finite number.
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * // Rotate a vector about +X by 90°:
+ * const R = rot1(Math.PI / 2);
+ * ```
+ */
+export declare const rot1: (theta: Radians) => Matrix3x3Type;
+//# sourceMappingURL=rot-1.d.ts.map

package/dist/categories/helpers/rot-1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rot-1.d.ts","sourceRoot":"","sources":["../../../src/categories/helpers/rot-1.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,IAAI,GAAI,OAAO,OAAO,KAAG,aAYrC,CAAC"}

package/dist/categories/helpers/rot-1.js

@@ -0,0 +1,47 @@
+/**
+ * Construct a **right-handed rotation matrix about the x-axis** (often written **R₁**).
+ *
+ * This returns the 3×3 direction cosine matrix (DCM) for an active rotation by angle `theta`
+ * around the **+X** axis, using the common aerospace convention:
+ *
+ * $$
+ * \mathbf{R}_1(\theta)=
+ * \begin{bmatrix}
+ * 1 & 0 & 0 \\
+ * 0 & \cos\theta & -\sin\theta \\
+ * 0 & \sin\theta & \cos\theta
+ * \end{bmatrix}
+ * $$
+ *
+ * ::: info Notes:
+ *
+ * - `theta` is in **radians**.
+ * - Matrix layout is **row-major**: `M[row][col]`.
+ * - Useful for composing 3-1-3 / 3-2-1 sequences (e.g., IAU body orientation) and for
+ *   general 3D frame transforms in mapping pipelines.
+ *
+ * :::
+ *
+ * @param theta - Rotation angle ($ \theta $) in **radians** (finite).
+ * @returns 3×3 rotation matrix ($ \mathbf{R}_1(\theta) $) (row-major).
+ * @throws {TypeError} If `theta` is not a finite number.
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * // Rotate a vector about +X by 90°:
+ * const R = rot1(Math.PI / 2);
+ * ```
+ */
+export const rot1 = (theta) => {
+    if (!Number.isFinite(theta))
+        throw new TypeError(`theta must be finite. Received: ${theta}`);
+    const c = Math.cos(theta);
+    const s = Math.sin(theta);
+    return [
+        [1, 0, 0],
+        [0, c, -s],
+        [0, s, c]
+    ];
+};
+//# sourceMappingURL=rot-1.js.map

package/dist/categories/helpers/rot-1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rot-1.js","sourceRoot":"","sources":["../../../src/categories/helpers/rot-1.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,KAAc,EAAiB,EAAE;IACpD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QACzB,MAAM,IAAI,SAAS,CAAC,mCAAmC,KAAK,EAAE,CAAC,CAAC;IAElE,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAE1B,OAAO;QACL,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACT,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACV,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;KACD,CAAC;AACb,CAAC,CAAC"}

package/dist/categories/helpers/rot-3.d.ts

@@ -0,0 +1,38 @@
+import { Matrix3x3Type, Radians } from '@interstellar-tools/types';
+/**
+ * Construct a **right-handed rotation matrix about the z-axis** (often written **R₃**).
+ *
+ * This returns the 3×3 direction cosine matrix (DCM) for an active rotation by angle `theta`
+ * around the **+Z** axis:
+ *
+ * $$
+ * \mathbf{R}_3(\theta)=
+ * \begin{bmatrix}
+ * \cos\theta & -\sin\theta & 0 \\
+ * \sin\theta & \cos\theta  & 0 \\
+ * 0          & 0           & 1
+ * \end{bmatrix}
+ * $$
+ *
+ * ::: info Notes:
+ *
+ * - `theta` is in **radians**.
+ * - Matrix layout is **row-major**: `M[row][col]`.
+ * - Common in 3-1-3 / 3-2-1 rotation sequences (e.g., IAU pole + prime meridian rotations)
+ *   and general 3D coordinate transforms.
+ *
+ * :::
+ *
+ * @param theta - Rotation angle ($ \theta $) in **radians** (finite).
+ * @returns 3×3 rotation matrix ($ \mathbf{R}_3(\theta) $) (row-major).
+ * @throws {TypeError} If `theta` is not a finite number.
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * // Rotate about +Z by 90°:
+ * const R = rot3(Math.PI / 2);
+ * ```
+ */
+export declare const rot3: (theta: Radians) => Matrix3x3Type;
+//# sourceMappingURL=rot-3.d.ts.map

package/dist/categories/helpers/rot-3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rot-3.d.ts","sourceRoot":"","sources":["../../../src/categories/helpers/rot-3.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,IAAI,GAAI,OAAO,OAAO,KAAG,aAYrC,CAAC"}

package/dist/categories/helpers/rot-3.js

@@ -0,0 +1,47 @@
+/**
+ * Construct a **right-handed rotation matrix about the z-axis** (often written **R₃**).
+ *
+ * This returns the 3×3 direction cosine matrix (DCM) for an active rotation by angle `theta`
+ * around the **+Z** axis:
+ *
+ * $$
+ * \mathbf{R}_3(\theta)=
+ * \begin{bmatrix}
+ * \cos\theta & -\sin\theta & 0 \\
+ * \sin\theta & \cos\theta  & 0 \\
+ * 0          & 0           & 1
+ * \end{bmatrix}
+ * $$
+ *
+ * ::: info Notes:
+ *
+ * - `theta` is in **radians**.
+ * - Matrix layout is **row-major**: `M[row][col]`.
+ * - Common in 3-1-3 / 3-2-1 rotation sequences (e.g., IAU pole + prime meridian rotations)
+ *   and general 3D coordinate transforms.
+ *
+ * :::
+ *
+ * @param theta - Rotation angle ($ \theta $) in **radians** (finite).
+ * @returns 3×3 rotation matrix ($ \mathbf{R}_3(\theta) $) (row-major).
+ * @throws {TypeError} If `theta` is not a finite number.
+ * @group Helpers
+ *
+ * @example
+ * ```ts
+ * // Rotate about +Z by 90°:
+ * const R = rot3(Math.PI / 2);
+ * ```
+ */
+export const rot3 = (theta) => {
+    if (!Number.isFinite(theta))
+        throw new TypeError(`theta must be finite. Received: ${theta}`);
+    const c = Math.cos(theta);
+    const s = Math.sin(theta);
+    return [
+        [c, -s, 0],
+        [s, c, 0],
+        [0, 0, 1]
+    ];
+};
+//# sourceMappingURL=rot-3.js.map

package/dist/categories/helpers/rot-3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rot-3.js","sourceRoot":"","sources":["../../../src/categories/helpers/rot-3.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,KAAc,EAAiB,EAAE;IACpD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QACzB,MAAM,IAAI,SAAS,CAAC,mCAAmC,KAAK,EAAE,CAAC,CAAC;IAElE,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAE1B,OAAO;QACL,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QACV,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACT,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;KACD,CAAC;AACb,CAAC,CAAC"}