ootk 3.0.0 → 4.0.0-1

package/src/operations/EulerAngles.ts

@@ -0,0 +1,183 @@
+/**
+ * @author @thkruz Theodore Kruczek
+ * @license AGPL-3.0-or-later
+ * @copyright (c) 2020-2024 Theodore Kruczek
+ *
+ * Orbital Object ToolKit is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Affero General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * Orbital Object ToolKit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License along with
+ * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+import { DEG2RAD, Degrees, Matrix, RAD2DEG, Radians, Vector3D } from 'ootk-core';
+
+// / Class containing Euler angles.
+export class EulerAngles {
+  // / Roll component _(rad)_.
+  roll: number;
+
+  // / Pitch component _(rad)_.
+  pitch: number;
+
+  // / Yaw component _(rad)_.
+  yaw: number;
+
+  /**
+   * Create a new EulerAngles object from roll, pitch, and yaw angles in radians.
+   * @param roll Roll angle in radians.
+   * @param pitch Pitch angle in radians.
+   * @param yaw Yaw angle in radians.
+   */
+  constructor(roll: Radians, pitch: Radians, yaw: Radians) {
+    this.roll = roll;
+    this.pitch = pitch;
+    this.yaw = yaw;
+  }
+
+  /**
+   * Create a new EulerAngles object from roll, pitch, and yaw angles.
+   * @param rollDeg Roll angle in degrees.
+   * @param pitchDeg Pitch angle in degrees.
+   * @param yawDeg Yaw angle in degrees.
+   * @returns EulerAngles object.
+   */
+  static fromDegrees(rollDeg: Degrees, pitchDeg: Degrees, yawDeg: Degrees): EulerAngles {
+    const roll = rollDeg * DEG2RAD as Radians;
+    const pitch = pitchDeg * DEG2RAD as Radians;
+    const yaw = yawDeg * DEG2RAD as Radians;
+
+    return new EulerAngles(roll, pitch, yaw);
+  }
+
+  /**
+   * Create a new EulerAngles object from 3-2-1 ordered direction cosine matrix c.
+   * @param c 3-2-1 ordered direction cosine matrix.
+   * @returns EulerAngles object.
+   */
+  static fromDcm321(c: Matrix): EulerAngles {
+    const roll = Math.atan(c.elements[1][2] / c.elements[2][2]) as Radians;
+    const pitch = -Math.asin(c.elements[0][2]) as Radians;
+    const yaw = Math.atan(c.elements[0][1] / c.elements[0][0]) as Radians;
+
+    return new EulerAngles(roll, pitch, yaw);
+  }
+
+  /**
+   * Gets the roll angle in degrees.
+   * @returns The roll angle in degrees.
+   */
+  get rollDegrees(): Degrees {
+    return this.roll * RAD2DEG as Degrees;
+  }
+
+  /**
+   * Gets the pitch angle in degrees.
+   * @returns The pitch angle in degrees.
+   */
+  get pitchDegrees(): Degrees {
+    return this.pitch * RAD2DEG as Degrees;
+  }
+
+  /**
+   * Gets the yaw angle in degrees.
+   * @returns The yaw angle in degrees.
+   */
+  get yawDegrees(): Degrees {
+    return this.yaw * RAD2DEG as Degrees;
+  }
+
+  /**
+   * Gets the roll angle in radians.
+   * @returns The roll angle in radians.
+   */
+  get phi(): Radians {
+    return this.roll as Radians;
+  }
+
+  /**
+   * Gets the pitch angle in radians.
+   * @returns The pitch angle in radians.
+   */
+  get theta(): Radians {
+    return this.pitch as Radians;
+  }
+
+  /**
+   * Gets the yaw angle in radians.
+   * @returns The yaw angle in radians.
+   */
+  get psi(): Radians {
+    return this.yaw as Radians;
+  }
+
+  /**
+   * Gets the roll component in degrees.
+   * @returns The roll component in degrees.
+   */
+  get phiDegrees(): Degrees {
+    return this.phi * RAD2DEG as Degrees;
+  }
+
+  /**
+   * Gets the pitch component in degrees.
+   * @returns The pitch component in degrees.
+   */
+  get thetaDegrees(): Degrees {
+    return this.theta * RAD2DEG as Degrees;
+  }
+
+  /**
+   * Gets the yaw component in degrees.
+   * @returns The yaw component in degrees.
+   */
+  get psiDegrees(): Degrees {
+    return this.psi * RAD2DEG as Degrees;
+  }
+
+  /**
+   * Returns a string representation of the Euler angles.
+   * @param precision The number of decimal places to include in the string representation. Default is 6.
+   * @returns A string representation of the Euler angles.
+   */
+  toString(precision = 6): string {
+    const rollStr = this.rollDegrees.toFixed(precision);
+    const pitchStr = this.pitchDegrees.toFixed(precision);
+    const yawStr = this.yawDegrees.toFixed(precision);
+
+    return `Euler(roll: ${rollStr}°, pitch: ${pitchStr}°, yaw: ${yawStr}°)`;
+  }
+
+  /**
+   * Calculates the Direction Cosine Matrix (DCM) using the 3-2-1 Euler angles convention.
+   * @returns The calculated DCM as a Matrix object.
+   */
+  dcm321(): Matrix {
+    const sPhi = Math.sin(this.phi);
+    const cPhi = Math.cos(this.phi);
+    const sTheta = Math.sin(this.theta);
+    const cTheta = Math.cos(this.theta);
+    const sPsi = Math.sin(this.psi);
+    const cPsi = Math.cos(this.psi);
+
+    return new Matrix([
+      [cTheta * cPsi, cTheta * sPsi, -sTheta],
+      [sPhi * sTheta * cPsi - cPhi * sPsi, sPhi * sTheta * sPsi + cPhi * cPsi, sPhi * cTheta],
+      [cPhi * sTheta * cPsi + sPhi * sPsi, cPhi * sTheta * sPsi - sPhi * cPsi, cPhi * cTheta],
+    ]);
+  }
+
+  /**
+   * Rotates a 3D vector using a 3-2-1 Euler angle sequence.
+   * @param v The vector to rotate.
+   * @returns The rotated vector.
+   */
+  rotateVector321(v: Vector3D): Vector3D {
+    return this.dcm321().multiplyVector3D(v);
+  }
+}

package/src/operations/Quaternion.ts

@@ -0,0 +1,222 @@
+/**
+ * @author @thkruz Theodore Kruczek
+ * @license AGPL-3.0-or-later
+ * @copyright (c) 2020-2024 Theodore Kruczek
+ *
+ * Orbital Object ToolKit is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Affero General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * Orbital Object ToolKit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License along with
+ * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+import { Matrix, Radians, RadiansPerSecond, Vector, Vector3D, wrapAngle } from 'ootk-core';
+
+export class Quaternion {
+  x: number;
+  y: number;
+  z: number;
+  w: number;
+
+  constructor(x: number, y: number, z: number, w: number) {
+    this.x = x;
+    this.y = y;
+    this.z = z;
+    this.w = w;
+  }
+
+  static zero = new Quaternion(0, 0, 0, 0);
+  static one = new Quaternion(0, 0, 0, 1);
+  static xAxis = new Quaternion(1, 0, 0, 0);
+  static yAxis = new Quaternion(0, 1, 0, 0);
+  static zAxis = new Quaternion(0, 0, 1, 0);
+
+  toString(precision = 8): string {
+    const xStr = this.x.toFixed(precision);
+    const yStr = this.y.toFixed(precision);
+    const zStr = this.z.toFixed(precision);
+    const wStr = this.w.toFixed(precision);
+
+    return `Q(x: ${xStr}, y: ${yStr}, z: ${zStr}, w: ${wStr})`;
+  }
+
+  positivePolar(): Quaternion {
+    return this.w >= 0 ? this.normalize() : this.negate().normalize();
+  }
+
+  magnitudeSquared(): number {
+    return this.w * this.w + this.x * this.x + this.y * this.y + this.z * this.z;
+  }
+
+  magnitude(): number {
+    return Math.sqrt(this.magnitudeSquared());
+  }
+
+  scale(n: number): Quaternion {
+    return new Quaternion(n * this.x, n * this.y, n * this.z, n * this.w);
+  }
+
+  negate(): Quaternion {
+    return this.scale(-1);
+  }
+
+  normalize(): Quaternion {
+    const m = this.magnitude();
+
+    if (m === 0) {
+      return Quaternion.zero;
+    }
+
+    return this.scale(1 / m);
+  }
+
+  conjugate(): Quaternion {
+    return new Quaternion(-this.x, -this.y, -this.z, this.w);
+  }
+
+  inverse(): Quaternion {
+    return this.conjugate().scale(1 / this.magnitudeSquared());
+  }
+
+  add(q: Quaternion): Quaternion {
+    return new Quaternion(this.x + q.x, this.y + q.y, this.z + q.z, this.w + q.w);
+  }
+
+  subtract(q: Quaternion): Quaternion {
+    return new Quaternion(this.x - q.x, this.y - q.y, this.z - q.z, this.w - q.w);
+  }
+
+  addReal(n: number): Quaternion {
+    return new Quaternion(this.x, this.y, this.z, this.w + n);
+  }
+
+  multiply(q: Quaternion): Quaternion {
+    const mx = this.w * q.x + this.x * q.w + this.y * q.z - this.z * q.y;
+    const my = this.w * q.y - this.x * q.z + this.y * q.w + this.z * q.x;
+    const mz = this.w * q.z + this.x * q.y - this.y * q.x + this.z * q.w;
+    const mw = this.w * q.w - this.x * q.x - this.y * q.y - this.z * q.z;
+
+    return new Quaternion(mx, my, mz, mw);
+  }
+
+  dot(q: Quaternion): number {
+    return this.x * q.x + this.y * q.y + this.z * q.z + this.w * q.w;
+  }
+
+  rotateVector(v: Vector): Vector {
+    const q = this.multiply(new Quaternion(v.x, v.y, v.z, 0)).multiply(this.conjugate());
+
+    return new Vector([q.x, q.y, q.z]);
+  }
+
+  rotateVector3D(v: Vector3D): Vector3D {
+    const q = this.multiply(new Quaternion(v.x, v.y, v.z, 0)).multiply(this.conjugate());
+
+    return new Vector3D(q.x, q.y, q.z);
+  }
+
+  lerp(q: Quaternion, t: number): Quaternion {
+    const f = 1.0 - t;
+
+    return new Quaternion(
+      f * this.x + t * q.x,
+      f * this.y + t * q.y,
+      f * this.z + t * q.z,
+      f * this.w + t * q.w,
+    ).positivePolar();
+  }
+
+  slerp(q: Quaternion, t: number): Quaternion {
+    let qp = q;
+    let dotP = this.dot(qp);
+
+    if (dotP < 0) {
+      dotP = -dotP;
+      qp = qp.negate();
+    }
+    if (dotP > 0.9995) {
+      return this.lerp(qp, t);
+    }
+    const theta = Math.acos(dotP);
+    const sinTheta = Math.sin(theta);
+    const f1 = Math.sin((1.0 - t) * theta) / sinTheta;
+    const f2 = Math.sin(t * theta) / sinTheta;
+
+    return new Quaternion(
+      f1 * this.x + f2 * qp.x,
+      f1 * this.y + f2 * qp.y,
+      f1 * this.z + f2 * qp.z,
+      f1 * this.w + f2 * qp.w,
+    ).positivePolar();
+  }
+
+  toVector3D(): Vector3D {
+    return new Vector3D(this.x, this.y, this.z);
+  }
+
+  angle(q: Quaternion): Radians {
+    const c = this.multiply(q.conjugate()).normalize();
+
+    return 2 * Math.atan2(c.toVector3D().magnitude(), c.w) as Radians;
+  }
+
+  geodesicAngle(q: Quaternion): Radians {
+    const p = this.dot(q);
+
+    return wrapAngle(Math.acos(2 * p * p - 1.0) as Radians);
+  }
+
+  distance(q: Quaternion): number {
+    const m01 = this.subtract(q).magnitude();
+    const p01 = this.add(q).magnitude();
+
+    return m01 < p01 ? m01 : p01;
+  }
+
+  delta(qTo: Quaternion): Quaternion {
+    return this.inverse().multiply(qTo);
+  }
+
+  toDirectionCosineMatrix(): Matrix {
+    const w2 = this.w * this.w;
+    const x2 = this.x * this.x;
+    const y2 = this.y * this.y;
+    const z2 = this.z * this.z;
+    const m = [
+      [w2 + x2 - y2 - z2, 2.0 * (this.x * this.y + this.z * this.w), 2.0 * (this.x * this.z - this.y * this.w)],
+      [2.0 * (this.x * this.y - this.z * this.w), w2 - x2 + y2 - z2, 2.0 * (this.y * this.z + this.x * this.w)],
+      [2.0 * (this.x * this.z + this.y * this.w), 2.0 * (this.y * this.z - this.x * this.w), w2 - x2 - y2 + z2],
+    ];
+
+    return new Matrix(m);
+  }
+
+  toRotationMatrix(): Matrix {
+    return this.toDirectionCosineMatrix().transpose();
+  }
+
+  vectorAngle(observer: Vector3D, target: Vector3D, forward: Vector3D): number {
+    const delta = target.subtract(observer);
+    const transform = this.toDirectionCosineMatrix().multiplyVector3D(delta);
+
+    return forward.angle(transform);
+  }
+
+  kinematics(angularVelocity: Vector3D<RadiansPerSecond>): Quaternion {
+    const wPrime = new Vector([0, angularVelocity.x, angularVelocity.y, angularVelocity.z]);
+    const qMat = new Matrix([
+      [this.x, this.w, -this.z, this.y],
+      [this.y, this.z, this.w, -this.x],
+      [this.z, -this.y, this.x, this.w],
+      [this.w, -this.x, -this.y, -this.z],
+    ]);
+    const result = qMat.multiplyVector(wPrime).scale(0.5).elements;
+
+    return new Quaternion(result[0], result[1], result[2], result[3]);
+  }
+}

package/src/operations/RandomGaussianSource.ts

@@ -0,0 +1,51 @@
+/**
+ * @author @thkruz Theodore Kruczek
+ * @license AGPL-3.0-or-later
+ * @copyright (c) 2020-2024 Theodore Kruczek
+ *
+ * Orbital Object ToolKit is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Affero General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * Orbital Object ToolKit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License along with
+ * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+import { Vector, Vector3D } from 'ootk-core';
+import { BoxMuller } from './BoxMuller';
+
+export class RandomGaussianSource {
+  private _boxMuller: BoxMuller;
+
+  constructor(seed = 0) {
+    this._boxMuller = new BoxMuller(0, 1, seed);
+  }
+
+  nextGauss(): number {
+    return this._boxMuller.nextGauss();
+  }
+
+  gaussVector(n: number): Vector {
+    if (n < 1) {
+      throw new Error('n must be greater than 0');
+    }
+
+    const result = new Vector([this.nextGauss()]);
+
+    for (let i = 0; i < n; i++) {
+      if (i > 0) {
+        result.add(new Vector([this.nextGauss()]));
+      }
+    }
+
+    return result;
+  }
+
+  gaussSphere(radius = 1.0): Vector3D {
+    return this.gaussVector(3).toVector3D(0).normalize().scale(radius);
+  }
+}

package/src/operations/index.ts

@@ -0,0 +1,4 @@
+export { BoxMuller } from './BoxMuller';
+export { EulerAngles } from './EulerAngles';
+export { Quaternion } from './Quaternion';
+export { RandomGaussianSource } from './RandomGaussianSource';

package/src/optimize/ChebyshevCompressor.ts

@@ -0,0 +1,96 @@
+/**
+ * @author @thkruz Theodore Kruczek
+ * @license AGPL-3.0-or-later
+ * @copyright (c) 2020-2024 Theodore Kruczek
+ *
+ * Orbital Object ToolKit is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Affero General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * Orbital Object ToolKit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License along with
+ * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+import { EpochUTC, Seconds, Vector3D } from 'ootk-core';
+import { StateInterpolator } from '../interpolator/StateInterpolator';
+import { ChebyshevCoefficients } from './../interpolator/ChebyshevCoefficients';
+import { ChebyshevInterpolator } from './../interpolator/ChebyshevInterpolator';
+
+// / Ephemeris compressor.
+export class ChebyshevCompressor {
+  // / Create a new [ChebyshevCompressor] object from an [Interpolator].
+  constructor(private _interpolator: StateInterpolator) {
+    // Do nothing.
+  }
+
+  // / Return the cosine of π times [x].
+  private static _cosPi(x: number): number {
+    return Math.cos(Math.PI * x);
+  }
+
+  private _fitCoefficient(j: number, n: number, a: number, b: number): Vector3D {
+    let sumX = 0.0;
+    let sumY = 0.0;
+    let sumZ = 0.0;
+    const h = 0.5;
+
+    for (let i = 0; i < n; i++) {
+      const x = ChebyshevCompressor._cosPi((i + h) / n);
+      const seconds = x * (h * (b - a)) + h * (b + a) as Seconds;
+      const state = this._interpolator.interpolate(new EpochUTC(seconds))!;
+      const fx = state.position.x;
+      const fy = state.position.y;
+      const fz = state.position.z;
+      const nFac = ChebyshevCompressor._cosPi((j * (i + h)) / n);
+
+      sumX += fx * nFac;
+      sumY += fy * nFac;
+      sumZ += fz * nFac;
+    }
+
+    return new Vector3D(sumX * (2 / n), sumY * (2 / n), sumZ * (2 / n));
+  }
+
+  private _fitWindow(coeffs: number, a: Seconds, b: Seconds): ChebyshevCoefficients {
+    const cx = new Float64Array();
+    const cy = new Float64Array();
+    const cz = new Float64Array();
+
+    for (let j = 0; j < coeffs; j++) {
+      const result = this._fitCoefficient(j, coeffs, a, b);
+
+      cx[j] = result.x;
+      cy[j] = result.y;
+      cz[j] = result.z;
+    }
+
+    return new ChebyshevCoefficients(a, b, cx, cy, cz);
+  }
+
+  /**
+   * Compress this object's interpolater, using the provided coefficients
+   * per revolution [cpr].
+   * @param cpr Coefficients per revolution.
+   * @returns A new [ChebyshevInterpolator] object.
+   */
+  compress(cpr = 21): ChebyshevInterpolator {
+    const { start, end } = this._interpolator.window();
+    const period = this._interpolator.interpolate(start)!.period;
+    const coefficients: ChebyshevCoefficients[] = [];
+    let current = start;
+
+    while (current < end) {
+      const step = Math.min(period, end.posix - current.posix) as Seconds;
+      const segment = current.roll(step);
+
+      coefficients.push(this._fitWindow(cpr, current.posix, segment.posix));
+      current = segment;
+    }
+
+    return new ChebyshevInterpolator(coefficients);
+  }
+}