ootk 3.0.0 → 4.0.0-1

package/src/interpolator/LagrangeInterpolator.ts

@@ -0,0 +1,192 @@
+/**
+ * @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, EpochWindow, J2000, Kilometers, KilometersPerSecond, Seconds, Vector3D } from 'ootk-core';
+import { StateInterpolator } from './StateInterpolator';
+
+export class LagrangeInterpolator extends StateInterpolator {
+  private t_: Float64Array;
+  private x_: Float64Array;
+  private y_: Float64Array;
+  private z_: Float64Array;
+  private order: number;
+
+  constructor(t: Float64Array, x: Float64Array, y: Float64Array, z: Float64Array, order = 10) {
+    super();
+    this.t_ = t;
+    this.x_ = x;
+    this.y_ = y;
+    this.z_ = z;
+    this.order = order;
+  }
+
+  /**
+   * Creates a LagrangeInterpolator from an array of J2000 ephemeris data.
+   * @param ephemeris - The array of J2000 ephemeris data.
+   * @param order - The order of the LagrangeInterpolator. Default is 10.
+   * @returns A new LagrangeInterpolator instance.
+   */
+  static fromEphemeris(ephemeris: J2000[], order = 10): LagrangeInterpolator {
+    const k = ephemeris.length;
+    const t = new Float64Array(k);
+    const x = new Float64Array(k);
+    const y = new Float64Array(k);
+    const z = new Float64Array(k);
+
+    for (let i = 0; i < k; i++) {
+      const state = ephemeris[i];
+
+      t[i] = state.epoch.posix;
+      x[i] = state.position.x;
+      y[i] = state.position.y;
+      z[i] = state.position.z;
+    }
+
+    return new LagrangeInterpolator(t, x, y, z, order);
+  }
+
+  get sizeBytes(): number {
+    return (64 * 4 * this.t_.length) / 8;
+  }
+
+  interpolate(epoch: EpochUTC): J2000 | null {
+    if (!this.inWindow(epoch)) {
+      return null;
+    }
+    const posix = epoch.posix;
+    const subDex = this.slice_(posix);
+    const start = subDex.left;
+    const stop = subDex.right;
+    const ts = this.t_.subarray(start, stop);
+    const xs = this.x_.subarray(start, stop);
+    const ys = this.y_.subarray(start, stop);
+    const zs = this.z_.subarray(start, stop);
+    const position = new Vector3D(
+      LagrangeInterpolator.position_(ts, xs, posix) as Kilometers,
+      LagrangeInterpolator.position_(ts, ys, posix) as Kilometers,
+      LagrangeInterpolator.position_(ts, zs, posix) as Kilometers,
+    );
+    const velocity = new Vector3D(
+      LagrangeInterpolator.velocity_(ts, xs, posix) as KilometersPerSecond,
+      LagrangeInterpolator.velocity_(ts, ys, posix) as KilometersPerSecond,
+      LagrangeInterpolator.velocity_(ts, zs, posix) as KilometersPerSecond,
+    );
+
+    return new J2000(epoch, position, velocity);
+  }
+
+  private static position_(xs: Float64Array, ys: Float64Array, x: number): number {
+    const k = xs.length - 1;
+    let result = 0.0;
+
+    for (let j = 0; j < k; j++) {
+      let product = ys[j];
+
+      for (let m = 0; m < k; m++) {
+        if (j === m) {
+          continue;
+        }
+        product *= (x - xs[m]) / (xs[j] - xs[m]);
+      }
+      result += product;
+    }
+
+    return result;
+  }
+
+  private static velocity_(xs: Float64Array, ys: Float64Array, x: number): number {
+    const k = xs.length;
+    let result = 0.0;
+
+    for (let j = 0; j < k; j++) {
+      let total = 0.0;
+
+      for (let i = 0; i < k; i++) {
+        if (i === j) {
+          continue;
+        }
+        let product = 1 / (xs[j] - xs[i]);
+
+        for (let m = 0; m < k; m++) {
+          if (m === i || m === j) {
+            continue;
+          }
+          product *= (x - xs[m]) / (xs[j] - xs[m]);
+        }
+        total += product;
+      }
+      result += ys[j] * total;
+    }
+
+    return result;
+  }
+
+  private static _getClosest(target: number, t1: number, d1: number, t2: number, d2: number): number {
+    return target - t1 >= t2 - target ? d2 : d1;
+  }
+
+  private slice_(posix: number): { left: number; right: number } {
+    const n = this.t_.length;
+
+    if (posix <= this.t_[0]) {
+      return { left: 0, right: this.order };
+    }
+    if (posix >= this.t_[n - 1]) {
+      return { left: n - this.order, right: n };
+    }
+
+    let i = 0;
+    let j = this.t_.length;
+    let mid = 0;
+
+    while (i < j) {
+      mid = (i + j) >> 1;
+      if (this.t_[mid] === posix) {
+        break;
+      }
+      if (posix < this.t_[mid]) {
+        if (mid > 0 && posix > this.t_[mid - 1]) {
+          mid = LagrangeInterpolator._getClosest(posix, this.t_[mid - 1], mid - 1, this.t_[mid], mid);
+          break;
+        }
+        j = mid;
+      } else {
+        if (mid < this.t_.length - 1 && posix < this.t_[mid + 1]) {
+          mid = LagrangeInterpolator._getClosest(posix, this.t_[mid], mid, this.t_[mid + 1], mid + 1);
+          break;
+        }
+        i = mid + 1;
+      }
+    }
+    const offset = Math.floor(this.order / 2);
+    const left = mid - offset;
+    const right = mid + offset - (this.order % 2 === 1 ? 1 : 0);
+
+    if (left < 0) {
+      return { left: 0, right: this.order };
+    }
+    if (right > n) {
+      return { left: n - this.order, right: n };
+    }
+
+    return { left, right };
+  }
+
+  window(): EpochWindow {
+    return new EpochWindow(new EpochUTC(this.t_[0] as Seconds), new EpochUTC(this.t_[this.t_.length - 1] as Seconds));
+  }
+}

package/src/interpolator/StateInterpolator.ts

@@ -0,0 +1,39 @@
+/**
+ * @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, J2000 } from 'ootk-core';
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/* eslint-disable class-methods-use-this */
+
+import { Interpolator } from './Interpolator';
+
+// / Base class for state vector interpolators.
+export abstract class StateInterpolator extends Interpolator {
+  /**
+   * Interpolates the state at the given epoch.
+   * @param epoch The epoch in UTC format.
+   * @throws If the interpolator has not been initialized.
+   */
+  interpolate(epoch: EpochUTC): J2000 | null {
+    throw new Error('Not implemented.');
+  }
+
+  // / Return the size _(bytes)_ of this interpolator's cached data.
+  get sizeBytes(): number {
+    throw new Error('Not implemented.');
+  }
+}

package/src/interpolator/VerletBlendInterpolator.ts

@@ -0,0 +1,146 @@
+/**
+ * @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 {
+  copySign,
+  Earth,
+  EpochUTC,
+  EpochWindow,
+  J2000,
+  Kilometers,
+  KilometersPerSecond,
+  Seconds,
+  Vector3D,
+} from 'ootk-core';
+import { CubicSplineInterpolator } from './CubicSplineInterpolator';
+import { LagrangeInterpolator } from './LagrangeInterpolator';
+import { StateInterpolator } from './StateInterpolator';
+
+/**
+ * Two-body Velocity Verlet Blend interpolator.
+ *
+ * The [VerletBlendInterpolator] retains the original ephemerides, so the
+ * original _"truth"_ states can be retrieved if needed without imparting any
+ * additional error, so this can be used to build other interpolator types.
+ * The implementation is simple and very tolerant when working with sparse
+ * ephemerides.
+ */
+export class VerletBlendInterpolator extends StateInterpolator {
+  constructor(public ephemeris: J2000[]) {
+    super();
+  }
+
+  get sizeBytes(): number {
+    return (64 * 7 * this.ephemeris.length) / 8;
+  }
+
+  window(): EpochWindow {
+    return new EpochWindow(this.ephemeris[0].epoch, this.ephemeris[this.ephemeris.length - 1].epoch);
+  }
+
+  private static getClosest_(target: number, s1: J2000, s2: J2000): J2000 {
+    return target - s1.epoch.posix >= s2.epoch.posix - target ? s2 : s1;
+  }
+
+  private matchState_(epoch: EpochUTC): J2000 {
+    const target = epoch.posix;
+
+    if (target <= this.ephemeris[0].epoch.posix) {
+      return this.ephemeris[0];
+    }
+    if (target >= this.ephemeris[this.ephemeris.length - 1].epoch.posix) {
+      return this.ephemeris[this.ephemeris.length - 1];
+    }
+
+    let i = 0;
+    let j = this.ephemeris.length;
+    let mid = 0;
+
+    while (i < j) {
+      mid = (i + j) >> 1;
+      if (this.ephemeris[mid].epoch.posix === target) {
+        return this.ephemeris[mid];
+      }
+      if (target < this.ephemeris[mid].epoch.posix) {
+        if (mid > 0 && target > this.ephemeris[mid - 1].epoch.posix) {
+          return VerletBlendInterpolator.getClosest_(target, this.ephemeris[mid - 1], this.ephemeris[mid]);
+        }
+        j = mid;
+      } else {
+        if (mid < this.ephemeris.length - 1 && target < this.ephemeris[mid + 1].epoch.posix) {
+          return VerletBlendInterpolator.getClosest_(target, this.ephemeris[mid], this.ephemeris[mid + 1]);
+        }
+        i = mid + 1;
+      }
+    }
+
+    return this.ephemeris[mid];
+  }
+
+  private static _gravity(position: Vector3D): Vector3D {
+    const r = position.magnitude();
+
+    return position.scale(-Earth.mu / (r * r * r));
+  }
+
+  private static integrate_(state: J2000, step: Seconds): J2000 {
+    const x0 = state.position;
+    const a0 = VerletBlendInterpolator._gravity(x0) as Vector3D<KilometersPerSecond>;
+    const v0 = state.velocity;
+    const x1 = x0
+      .add(v0.scale(step) as unknown as Vector3D<Kilometers>)
+      .add(a0.scale(0.5 * step * step) as unknown as Vector3D<Kilometers>);
+    const a1 = VerletBlendInterpolator._gravity(x1) as Vector3D<KilometersPerSecond>;
+    const v1 = v0
+      .add(a0.add(a1).scale(0.5 * step) as Vector3D<KilometersPerSecond>);
+
+    return new J2000(state.epoch.roll(step), x1, v1);
+  }
+
+  interpolate(epoch: EpochUTC): J2000 | null {
+    if (!this.inWindow(epoch)) {
+      return null;
+    }
+    let state = this.matchState_(epoch);
+
+    while (state.epoch.posix !== epoch.posix) {
+      const delta = epoch.posix - state.epoch.posix;
+      const stepMag = Math.min(5.0, Math.abs(delta));
+      const stepSize = copySign(stepMag, delta) as Seconds;
+
+      state = VerletBlendInterpolator.integrate_(state, stepSize);
+    }
+
+    return state;
+  }
+
+  getCachedState(epoch: EpochUTC): J2000 | null {
+    if (!this.inWindow(epoch)) {
+      return null;
+    }
+
+    return this.matchState_(epoch);
+  }
+
+  toCubicSpline(): CubicSplineInterpolator {
+    return CubicSplineInterpolator.fromEphemeris(this.ephemeris);
+  }
+
+  toLagrange(order = 10): LagrangeInterpolator {
+    return LagrangeInterpolator.fromEphemeris(this.ephemeris, order);
+  }
+}

package/src/main.ts

@@ -0,0 +1,32 @@
+/**
+ * @author @thkruz Theodore Kruczek
+ * @description Orbital Object ToolKit (ootk) is a collection of tools for working
+ * with satellites and other orbital objects.
+ * @license AGPL-3.0-or-later
+ * @copyright (c) 2020-2024 Theodore Kruczek
+ *
+ * Many of the classes are based off of the work of @david-rc-dayton and his
+ * Pious Squid library (https://github.com/david-rc-dayton/pious_squid).
+ *
+ * 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/>.
+ */
+
+export * from 'ootk-core';
+export * from './coordinate';
+export * from './objects';
+export * from './operations';
+export * from './transforms';
+export * from './interfaces';
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+export * from './types/types';
+export * from './utils';

package/src/maneuver/TwoBurnOrbitTransfer.ts

@@ -0,0 +1,79 @@
+/**
+ * @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 { Earth, EpochUTC, MetersPerSecond, Seconds, SecondsPerMeterPerSecond } from 'ootk-core';
+import { Thrust } from '../force/Thrust';
+
+// / Container for a two-burn orbit transfer.
+export class TwoBurnOrbitTransfer {
+  // / Create a new [TwoBurnOrbitTransfer] object.
+  constructor(
+    public vInit: number,
+    public vFinal: number,
+    public vTransA: number,
+    public vTransB: number,
+    public tTrans: Seconds,
+  ) {
+    // Nothing to do here.
+  }
+
+  /**
+   * Calculates the parameters for a Hohmann transfer orbit between two circular orbits.
+   * @param rInit The initial radius of the orbit. (km)
+   * @param rFinal The final radius of the orbit. (km)
+   * @returns An instance of TwoBurnOrbitTransfer containing the calculated parameters.
+   */
+  static hohmannTransfer(rInit: number, rFinal: number): TwoBurnOrbitTransfer {
+    const vInit = Math.sqrt(Earth.mu / rInit);
+    const vFinal = Math.sqrt(Earth.mu / rFinal);
+    const vTransA = vInit * (Math.sqrt((2.0 * rFinal) / (rInit + rFinal)) - 1.0);
+    const vTransB = vFinal * (1.0 - Math.sqrt((2 * rInit) / (rInit + rFinal)));
+    const tTrans = Math.PI * Math.sqrt((rInit + rFinal) ** 3 / (8.0 * Earth.mu)) as Seconds;
+
+    return new TwoBurnOrbitTransfer(vInit, vFinal, vTransA, vTransB, tTrans);
+  }
+
+  // / Return the total delta-velocity magnitude for both maneuvers _(km/s)_.
+  get deltaV(): number {
+    return Math.abs(this.vTransA) + Math.abs(this.vTransB);
+  }
+
+  /**
+   * Calculates the two maneuver thrusts required for a two-burn orbit transfer.
+   * @param epoch The epoch of the maneuver.
+   * @param durationRate The duration rate of the maneuver (s/m/s).
+   * @returns An array containing the two thrust objects representing the maneuvers.
+   */
+  toManeuvers(epoch: EpochUTC, durationRate = 0.0 as SecondsPerMeterPerSecond): [Thrust, Thrust] {
+    const mA = new Thrust(
+      epoch,
+      0.0 as MetersPerSecond,
+      this.vTransA * 1000.0 as MetersPerSecond,
+      0.0 as MetersPerSecond,
+      durationRate,
+    );
+    const mB = new Thrust(
+      epoch.roll(this.tTrans),
+      0.0 as MetersPerSecond,
+      this.vTransB * 1000.0 as MetersPerSecond,
+      0.0 as MetersPerSecond,
+      durationRate,
+    );
+
+    return [mA, mB];
+  }
+}