ootk 4.0.9 → 5.1.0

package/src/coordinate/RIC.ts

@@ -0,0 +1,87 @@
+/**
+ * @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) 2025 Kruczek Labs LLC
+ *
+ * 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) which
+ * is licensed under the MIT license.
+ *
+ * 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 } from '../operations/Matrix.js';
+import { J2000 } from './J2000.js';
+import { RelativeState } from './RelativeState.js';
+
+/**
+ * Represents a Radial-Intrack-Crosstrack (RIC) coordinates.
+ */
+export class RIC extends RelativeState {
+  /**
+   * Gets the name of the RIC coordinate system.
+   * @returns The name of the RIC coordinate system.
+   */
+  get name(): string {
+    return 'RIC';
+  }
+
+  /**
+   * Creates a new RIC (Radial-Intrack-Crosstrack) coordinate from the J2000 state vectors.
+   * @param state - The J2000 state vector.
+   * @param origin - The J2000 state vector of the origin.
+   * @param transform - The transformation matrix.
+   * @returns The RIC coordinate.
+   */
+  static fromJ2000Matrix(state: J2000, origin: J2000, transform: Matrix): RIC {
+    const dr = state.position.subtract(origin.position);
+    const dv = state.velocity.subtract(origin.velocity);
+
+    return new RIC(transform.multiplyVector3D(dr), transform.multiplyVector3D(dv));
+  }
+
+  /**
+   * Creates a RIC (Radial-Intrack-Crosstrack) coordinate system from a J2000 state and origin.
+   * @param state The J2000 state.
+   * @param origin The J2000 origin.
+   * @returns The RIC coordinate system.
+   */
+  static fromJ2000(state: J2000, origin: J2000): RIC {
+    return RIC.fromJ2000Matrix(state, origin, RelativeState.createMatrix(origin.position, origin.velocity));
+  }
+
+  /**
+   * Transforms the current RIC coordinate to the J2000 coordinate system using the provided origin and transform
+   * matrix.
+   * @param origin The origin J2000 coordinate.
+   * @param transform The transformation matrix.
+   * @returns The transformed J2000 coordinate.
+   */
+  toJ2000Matrix(origin: J2000, transform: Matrix): J2000 {
+    const tt = transform.transpose();
+    const tr = tt.multiplyVector3D(this.position);
+    const tv = tt.multiplyVector3D(this.velocity);
+
+    return new J2000(origin.epoch, origin.position.add(tr), origin.velocity.add(tv));
+  }
+
+  /**
+   * Transforms the current RIC coordinate to the J2000 coordinate system using the provided origin.
+   * @param origin The origin J2000 coordinate.
+   * @returns The transformed J2000 coordinate.
+   */
+  toJ2000(origin: J2000): J2000 {
+    return this.toJ2000Matrix(origin, RelativeState.createMatrix(origin.position, origin.velocity));
+  }
+}

package/src/coordinate/RelativeState.ts

@@ -0,0 +1,101 @@
+/**
+ * @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) 2025 Kruczek Labs LLC
+ *
+ * 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) which
+ * is licensed under the MIT license.
+ *
+ * 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 { Kilometers, KilometersPerSecond } from '../main.js';
+import { Matrix } from '../operations/Matrix.js';
+import { Vector3D } from '../operations/Vector3D.js';
+import { J2000 } from './J2000.js';
+
+/**
+ * Represents the relative state of an object in 3D space.
+ */
+export abstract class RelativeState {
+  position: Vector3D<Kilometers>;
+  velocity: Vector3D<KilometersPerSecond>;
+  constructor(position: Vector3D<Kilometers>, velocity: Vector3D<KilometersPerSecond>) {
+    this.position = position;
+    this.velocity = velocity;
+  }
+
+  /**
+   * Gets the name of the coordinate system.
+   * @returns The name of the coordinate system.
+   */
+  abstract get name(): string;
+
+  /**
+   * Returns a string representation of the RelativeState object. The string includes the name, position, and velocity
+   * of the object.
+   * @returns A string representation of the RelativeState object.
+   */
+  toString(): string {
+    return [
+      `[${this.name}]`,
+      `  Position: ${this.position.toString(6)} km`,
+      `  Velocity: ${this.velocity.toString(9)} km/s`,
+    ].join('\n');
+  }
+
+  /**
+   * Transforms the current RelativeState coordinate to the J2000 coordinate
+   * @param origin The origin J2000 coordinate.
+   * @returns The transformed J2000 coordinate.
+   */
+  abstract toJ2000(origin: J2000): J2000;
+
+  /**
+   * Creates a matrix based on the given position and velocity vectors. The matrix represents the relative state of an
+   * object in 3D space.
+   * @param position - The position vector.
+   * @param velocity - The velocity vector.
+   * @returns The matrix representing the relative state.
+   */
+  static createMatrix(position: Vector3D, velocity: Vector3D): Matrix {
+    const ru = position.normalize();
+    const cu = position.cross(velocity).normalize();
+    const iu = cu.cross(ru).normalize();
+
+    return new Matrix([
+      [ru.x, ru.y, ru.z],
+      [iu.x, iu.y, iu.z],
+      [cu.x, cu.y, cu.z],
+    ]);
+  }
+
+  /**
+   * Calculates the range of the relative state.
+   * @returns The range in kilometers.
+   */
+  get range(): Kilometers {
+    return this.position.magnitude();
+  }
+
+  /**
+   * Calculates the range rate of the relative state. Range rate is the dot product of the position and velocity divided
+   * by the range.
+   * @returns The range rate in Kilometers per second.
+   */
+  get rangeRate(): number {
+    return this.position.dot(this.velocity) / this.range;
+  }
+}

package/src/coordinate/StateVector.ts

@@ -0,0 +1,123 @@
+/**
+ * @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) 2025 Kruczek Labs LLC
+ *
+ * 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) which
+ * is licensed under the MIT license.
+ *
+ * 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 {
+  ClassicalElements, TAU, Earth, Kilometers, KilometersPerSecond, Minutes, EpochUTC, Vector3D,
+} from '../main.js';
+
+/**
+ * A state vector is a set of coordinates used to specify the position and
+ * velocity of an object in a particular reference frame.
+ */
+export abstract class StateVector {
+  epoch: EpochUTC;
+  position: Vector3D<Kilometers>;
+  velocity: Vector3D<KilometersPerSecond>;
+  constructor(epoch: EpochUTC, position: Vector3D<Kilometers>, velocity: Vector3D<KilometersPerSecond>) {
+    this.epoch = epoch;
+    this.position = position;
+    this.velocity = velocity;
+  }
+
+  /**
+   * The name of the reference frame in which the state vector is defined.
+   * @returns The name of the reference frame.
+   */
+  abstract get name(): string;
+
+  /**
+   * Whether the state vector is defined in an inertial reference frame.
+   * @returns True if the state vector is defined in an inertial reference
+   */
+  abstract get inertial(): boolean;
+
+  /**
+   * Returns a string representation of the StateVector object. The string includes the name, epoch, position, and
+   * velocity.
+   * @returns A string representation of the StateVector object.
+   */
+  toString(): string {
+    return [
+      `[${this.name}]`,
+      `  Epoch: ${this.epoch}`,
+      `  Position: ${this.position.toString(6)} km`,
+      `  Velocity: ${this.velocity.toString(9)} km/s`,
+    ].join('\n');
+  }
+
+  /**
+   * Calculates the mechanical energy of the state vector.
+   * @returns The mechanical energy value.
+   */
+  get mechanicalEnergy(): number {
+    const r = this.position.magnitude();
+    const v = this.velocity.magnitude();
+
+    return v * v * 0.5 - Earth.mu / r;
+  }
+
+  /**
+   * Calculates the semimajor axis of the state vector.
+   * @returns The semimajor axis in kilometers.
+   */
+  get semimajorAxis(): Kilometers {
+    const energy = this.mechanicalEnergy;
+
+    return (-Earth.mu / (2.0 * energy)) as Kilometers;
+  }
+
+  /**
+   * Gets the period of the state vector in minutes.
+   * @returns The period in minutes.
+   */
+  get period(): Minutes {
+    const a = this.semimajorAxis;
+    const periodSeconds = TAU * Math.sqrt((a * a * a) / Earth.mu);
+
+    return (periodSeconds / 60.0) as Minutes;
+  }
+
+  /**
+   * Gets the angular rate of the state vector.
+   * @returns The angular rate.
+   */
+  get angularRate(): number {
+    const a = this.semimajorAxis;
+
+    return Math.sqrt(Earth.mu / (a * a * a));
+  }
+
+  /**
+   * Converts the state vector to classical elements.
+   * @param mu The gravitational parameter of the celestial body. Defaults to Earth's gravitational parameter.
+   * @returns The classical elements corresponding to the state vector.
+   * @throws Error if classical elements are undefined for fixed frames.
+   */
+  toClassicalElements(mu = Earth.mu): ClassicalElements {
+    if (!this.inertial) {
+      throw new Error('Classical elements are undefined for fixed frames.');
+    }
+
+    return ClassicalElements.fromStateVector(this, mu);
+  }
+}

package/src/coordinate/TEME.ts

@@ -0,0 +1,97 @@
+/**
+ * @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) 2025 Kruczek Labs LLC
+ *
+ * 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) which
+ * is licensed under the MIT license.
+ *
+ * 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 { Kilometers, KilometersPerSecond, Radians, Vector3D } from '../main.js';
+import { Earth } from '../body/Earth.js';
+import type { ClassicalElements } from './ClassicalElements.js';
+import { J2000 } from './J2000.js';
+import { StateVector } from './StateVector.js';
+
+/**
+ * True Equator Mean Equinox (TEME) is a coordinate system commonly used in satellite tracking and orbit prediction. It
+ * is a reference frame that defines the position and orientation of an object relative to the Earth's equator and
+ * equinox.
+ *
+ * By using the True Equator Mean Equinox (TEME) coordinate system, we can accurately describe the position and motion
+ * of satellites relative to the Earth's equator and equinox. This is particularly useful for tracking and predicting
+ * satellite orbits in various applications, such as satellite communication, navigation, and remote sensing.
+ */
+export class TEME extends StateVector {
+  /**
+   * Gets the name of the coordinate system.
+   * @returns The name of the coordinate system.
+   */
+  get name(): string {
+    return 'TEME';
+  }
+
+  /**
+   * Gets a value indicating whether the coordinate is inertial.
+   * @returns A boolean value indicating whether the coordinate is inertial.
+   */
+  get inertial(): boolean {
+    return true;
+  }
+
+  /**
+   * Creates a TEME (True Equator Mean Equinox) object from classical orbital elements.
+   * @param elements - The classical orbital elements.
+   * @returns A new TEME object.
+   */
+  static fromClassicalElements(elements: ClassicalElements): TEME {
+    const rv = elements.toPositionVelocity();
+
+    return new TEME(elements.epoch, rv.position, rv.velocity);
+  }
+
+  /**
+   * Converts the TEME (True Equator Mean Equinox) coordinates to J2000 coordinates.
+   * @returns The J2000 coordinates.
+   */
+  toJ2000(): J2000 {
+    const p = Earth.precession(this.epoch);
+    const n = Earth.nutation(this.epoch);
+    const eps = n.mEps + n.dEps;
+    const dPsiCosEps = n.dPsi * Math.cos(eps);
+    const rMOD = this.position
+      .rotZ(-dPsiCosEps as Radians)
+      .rotX(eps)
+      .rotZ(n.dPsi)
+      .rotX(-n.mEps);
+    const vMOD = this.velocity
+      .rotZ(-dPsiCosEps as Radians)
+      .rotX(eps)
+      .rotZ(n.dPsi)
+      .rotX(-n.mEps);
+    const rJ2K = rMOD
+      .rotZ(p.zed)
+      .rotY(-p.theta as Radians)
+      .rotZ(p.zeta) as Vector3D<Kilometers>;
+    const vJ2K = vMOD
+      .rotZ(p.zed)
+      .rotY(-p.theta as Radians)
+      .rotZ(p.zeta) as Vector3D<KilometersPerSecond>;
+
+    return new J2000(this.epoch, rJ2K, vJ2K);
+  }
+}