ootk 4.0.9 → 5.1.0

package/src/observation/RAE.ts

@@ -0,0 +1,261 @@
+/**
+ * @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/>.
+ */
+
+/* eslint-disable no-undefined */
+import { ITRF } from '../coordinate/ITRF.js';
+import { J2000 } from '../coordinate/J2000.js';
+import { AngularDistanceMethod } from '../enums/AngularDistanceMethod.js';
+import { Degrees, Kilometers, KilometersPerSecond, Radians } from '../main.js';
+import { Vector3D } from '../operations/Vector3D.js';
+import { EpochUTC } from '../time/EpochUTC.js';
+import { DEG2RAD, halfPi, RAD2DEG, TAU } from '../utils/constants.js';
+import { angularDistance } from '../utils/functions.js';
+
+// / Range, azimuth, and elevation.
+export class RAE {
+  constructor(
+    public epoch: EpochUTC,
+    public rng: Kilometers,
+    public azRad: Radians,
+    public elRad: Radians,
+    /** The range rate of the satellite relative to the observer in kilometers per second. */
+    public rngRate?: number,
+    /** The azimuth rate of the satellite relative to the observer in radians per second. */
+    public azRateRad?: number,
+    /** The elevation rate of the satellite relative to the observer in radians per second. */
+    public elRateRad?: number,
+  ) {
+    // Do nothing
+  }
+
+  // / Create a new [Razel] object, using degrees for the angular values.
+  static fromDegrees(
+    epoch: EpochUTC,
+    range: Kilometers,
+    azimuth: Degrees,
+    elevation: Degrees,
+    rangeRate?: number,
+    azimuthRate?: number,
+    elevationRate?: number,
+  ): RAE {
+    const azimuthRateRad = azimuthRate ? azimuthRate * DEG2RAD : undefined;
+    const elevationRateRad = elevationRate ? elevationRate * DEG2RAD : undefined;
+
+    return new RAE(
+      epoch,
+      range,
+      (azimuth * DEG2RAD) as Radians,
+      (elevation * DEG2RAD) as Radians,
+      rangeRate,
+      azimuthRateRad,
+      elevationRateRad,
+    );
+  }
+
+  /**
+   * Create a [Razel] object from an inertial [state] and [site] vector.
+   * @param state The inertial [state] vector.
+   * @param site The observer [site] vector.
+   * @returns A new [Razel] object.
+   */
+  static fromStateVector(state: J2000, site: J2000): RAE {
+    const stateEcef = state.toITRF();
+    const siteEcef = site.toITRF();
+    const po2 = halfPi;
+    const r = stateEcef.position.subtract(siteEcef.position);
+    const rDot = stateEcef.velocity;
+    const geo = siteEcef.toGeodetic();
+    const p = r.rotZ(geo.lon).rotY((po2 - geo.lat) as Radians);
+    const pDot = rDot.rotZ(geo.lon).rotY((po2 - geo.lat) as Radians);
+    const pS = p.x;
+    const pE = p.y;
+    const pZ = p.z;
+    const pSDot = pDot.x;
+    const pEDot = pDot.y;
+    const pZDot = pDot.z;
+    const pMag = p.magnitude();
+    const pSEMag = Math.sqrt(pS * pS + pE * pE);
+    const elevation = Math.asin(pZ / pMag);
+    let azimuth;
+
+    if (elevation !== po2) {
+      azimuth = Math.atan2(-pE, pS) + Math.PI;
+    } else {
+      azimuth = Math.atan2(-pEDot, pSDot) + Math.PI;
+    }
+    const rangeRate = p.dot(pDot) / pMag;
+    const azimuthRate = (pSDot * pE - pEDot * pS) / (pS * pS + pE * pE);
+    const elevationRate = (pZDot - rangeRate * Math.sin(elevation)) / pSEMag;
+
+    return new RAE(
+      state.epoch,
+      pMag,
+      (azimuth % TAU) as Radians,
+      elevation as Radians,
+      rangeRate,
+      azimuthRate,
+      elevationRate,
+    );
+  }
+
+  /**
+   * Gets the azimuth in degrees.
+   * @returns The azimuth in degrees.
+   */
+  get az(): Degrees {
+    return this.azRad * RAD2DEG as Degrees;
+  }
+
+  /**
+   * Gets the elevation angle in degrees.
+   * @returns The elevation angle in degrees.
+   */
+  get el(): Degrees {
+    return this.elRad * RAD2DEG as Degrees;
+  }
+
+  /**
+   * Gets the azimuth rate in degrees per second.
+   * @returns The azimuth rate in degrees per second, or undefined if it is not available.
+   */
+  get azRate(): number | undefined {
+    return this.azRateRad ? this.azRateRad * RAD2DEG : undefined;
+  }
+
+  /**
+   * Gets the elevation rate in degrees per second.
+   * @returns The elevation rate in degrees per second, or undefined if the elevation rate is not set.
+   */
+  get elRate(): number | undefined {
+    return this.elRateRad ? this.elRateRad * RAD2DEG : undefined;
+  }
+
+  toString(): string {
+    return [
+      '[RazEl]',
+      `  Epoch:     ${this.epoch}`,
+      `  Azimuth:   ${this.az.toFixed(4)}°`,
+      `  Elevation: ${this.el.toFixed(4)}°`,
+      `  Range:     ${this.rng.toFixed(3)} km`,
+    ].join('\n');
+  }
+
+  /**
+   * Return the position relative to the observer [site].
+   *
+   * An optional azimuth [az] _(rad)_ and elevation [el] _(rad)_ value can be
+   * passed to override the values contained in this observation.
+   * @param site The observer [site].
+   * @param azRad Azimuth _(rad)_.
+   * @param elRad Elevation _(rad)_.
+   * @returns A [Vector3D] object.
+   */
+  position(site: J2000, azRad?: Radians, elRad?: Radians): Vector3D<Kilometers> {
+    const ecef = site.toITRF();
+    const geo = ecef.toGeodetic();
+    const po2 = halfPi;
+    const newAz = azRad ?? this.azRad;
+    const newEl = elRad ?? this.elRad;
+    const sAz = Math.sin(newAz);
+    const cAz = Math.cos(newAz);
+    const sEl = Math.sin(newEl);
+    const cEl = Math.cos(newEl);
+    const pSez = new Vector3D<Kilometers>(
+      (-this.rng * cEl * cAz) as Kilometers,
+      (this.rng * cEl * sAz) as Kilometers,
+      (this.rng * sEl) as Kilometers,
+    );
+    const rEcef = pSez
+      .rotY(-(po2 - geo.lat) as Radians)
+      .rotZ(-geo.lon as Radians)
+      .add(ecef.position);
+
+    return new ITRF(this.epoch, rEcef, Vector3D.origin as Vector3D<KilometersPerSecond>).toJ2000().position;
+  }
+
+  /**
+   * Convert this observation into a [J2000] state vector.
+   *
+   * This will throw an error if the [rangeRate], [elevationRate], or
+   * [azimuthRate] are not defined.
+   * @param site The observer [site].
+   * @returns A [J2000] state vector.
+   */
+  toStateVector(site: J2000): J2000 {
+    // If the rates are not defined then assume stationary
+    this.rngRate ??= 0;
+    this.elRateRad ??= 0;
+    this.azRateRad ??= 0;
+
+    const ecef = site.toITRF();
+    const geo = ecef.toGeodetic();
+    const po2 = halfPi;
+    const sAz = Math.sin(this.azRad);
+    const cAz = Math.cos(this.azRad);
+    const sEl = Math.sin(this.elRad);
+    const cEl = Math.cos(this.elRad);
+    const pSez = new Vector3D<Kilometers>(
+      (-this.rng * cEl * cAz) as Kilometers,
+      (this.rng * cEl * sAz) as Kilometers,
+      (this.rng * sEl) as Kilometers,
+    );
+    const pDotSez = new Vector3D<Kilometers>(
+      (-this.rngRate * cEl * cAz +
+        this.rng * sEl * cAz * this.elRateRad +
+        this.rng * cEl * sAz * this.azRateRad) as Kilometers,
+      (this.rngRate * cEl * sAz -
+        this.rng * sEl * sAz * this.elRateRad +
+        this.rng * cEl * cAz * this.azRateRad) as Kilometers,
+      (this.rngRate * sEl + this.rng * cEl * this.elRateRad) as Kilometers,
+    );
+    const pEcef = pSez.rotY(-(po2 - geo.lat) as Radians).rotZ(-geo.lon as Radians);
+    const pDotEcef = pDotSez
+      .rotY(-(po2 - geo.lat) as Radians)
+      .rotZ(-geo.lon as Radians) as unknown as Vector3D<KilometersPerSecond>;
+    const rEcef = pEcef.add(ecef.position);
+
+    return new ITRF(this.epoch, rEcef, pDotEcef).toJ2000();
+  }
+
+  /**
+   * Calculate the angular distance _(rad)_ between this and another [Razel]
+   * object.
+   * @param razel The other [Razel] object.
+   * @param method The angular distance method to use.
+   * @returns The angular distance _(rad)_.
+   */
+  angle(razel: RAE, method: AngularDistanceMethod = AngularDistanceMethod.Cosine): number {
+    return angularDistance(this.azRad, this.elRad, razel.azRad, razel.elRad, method);
+  }
+
+  /**
+   * Calculate the angular distance _(°)_ between this and another [Razel]
+   * object.
+   * @param razel The other [Razel] object.
+   * @param method The angular distance method to use.
+   * @returns The angular distance _(°)_.
+   */
+  angleDegrees(razel: RAE, method: AngularDistanceMethod = AngularDistanceMethod.Cosine): number {
+    return this.angle(razel, method) * RAD2DEG;
+  }
+}

package/src/observation/RadecGeocentric.ts

@@ -0,0 +1,206 @@
+/**
+ * @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 { Degrees, DegreesPerSecond, Kilometers, KilometersPerSecond, Radians, RadiansPerSecond } from '../main.js';
+import { J2000 } from '../coordinate/J2000.js';
+import { AngularDistanceMethod } from '../enums/AngularDistanceMethod.js';
+import { Vector3D } from '../operations/Vector3D.js';
+import { EpochUTC } from '../time/EpochUTC.js';
+import { DEG2RAD, RAD2DEG, TAU } from '../utils/constants.js';
+import { angularDistance } from '../utils/functions.js';
+import { radecToPosition, radecToVelocity } from './ObservationUtils.js';
+
+/**
+ * Represents a geocentric right ascension and declination observation.
+ *
+ * In geocentric coordinates, observations are considered from the Earth's center. This approach simplifies calculations
+ * for distant celestial objects, as it assumes a uniform observation point that ignores the observer's specific
+ * location on Earth.
+ */
+export class RadecGeocentric {
+  constructor(
+    public epoch: EpochUTC,
+    public rightAscension: Radians,
+    public declination: Radians,
+    public range?: Kilometers,
+    public rightAscensionRate?: RadiansPerSecond | null,
+    public declinationRate?: RadiansPerSecond | null,
+    public rangeRate?: KilometersPerSecond | null,
+  ) {
+    // Nothing to do here.
+  }
+
+  /**
+   * Creates a RadecGeocentric object from the given parameters in degrees.
+   * @param epoch - The epoch in UTC.
+   * @param rightAscensionDegrees - The right ascension in degrees.
+   * @param declinationDegrees - The declination in degrees.
+   * @param range - The range in kilometers (optional).
+   * @param rightAscensionRateDegrees - The right ascension rate in degrees per second (optional).
+   * @param declinationRateDegrees - The declination rate in degrees per second (optional).
+   * @param rangeRate - The range rate in kilometers per second (optional).
+   * @returns A new RadecGeocentric object.
+   */
+  static fromDegrees(
+    epoch: EpochUTC,
+    rightAscensionDegrees: Degrees,
+    declinationDegrees: Degrees,
+    range?: Kilometers,
+    rightAscensionRateDegrees?: Degrees,
+    declinationRateDegrees?: Degrees,
+    rangeRate?: KilometersPerSecond,
+  ): RadecGeocentric {
+    const rightAscensionRate = rightAscensionRateDegrees
+      ? rightAscensionRateDegrees * DEG2RAD as RadiansPerSecond
+      : null;
+    const declinationRate = declinationRateDegrees ? declinationRateDegrees * DEG2RAD as RadiansPerSecond : null;
+
+    return new RadecGeocentric(
+      epoch,
+      rightAscensionDegrees * DEG2RAD as Radians,
+      declinationDegrees * DEG2RAD as Radians,
+      range,
+      rightAscensionRate,
+      declinationRate,
+      rangeRate,
+    );
+  }
+
+  /**
+   * Creates a RadecGeocentric object from a state vector in J2000 coordinates.
+   * @param state - The J2000 state vector.
+   * @returns A new RadecGeocentric object.
+   */
+  static fromStateVector(state: J2000): RadecGeocentric {
+    const rI = state.position.x;
+    const rJ = state.position.y;
+    const rK = state.position.z;
+    const vI = state.velocity.x;
+    const vJ = state.velocity.y;
+    const vK = state.velocity.z;
+    const rMag = state.position.magnitude();
+    const declination = Math.asin(rK / rMag);
+    const rIJMag = Math.sqrt(rI * rI + rJ * rJ);
+    let rightAscension;
+
+    if (rIJMag !== 0) {
+      rightAscension = Math.atan2(rJ, rI);
+    } else {
+      rightAscension = Math.atan2(vJ, vI);
+    }
+    const rangeRate = state.position.dot(state.velocity) / rMag as KilometersPerSecond;
+    const rightAscensionRate = (vI * rJ - vJ * rI) / (-(rJ * rJ) - rI * rI);
+    const declinationRate = (vK - rangeRate * (rK / rMag)) / rIJMag;
+
+    return new RadecGeocentric(
+      state.epoch,
+      rightAscension % TAU as Radians,
+      declination as Radians,
+      rMag,
+      rightAscensionRate as RadiansPerSecond,
+      declinationRate as RadiansPerSecond,
+      rangeRate,
+    );
+  }
+
+  /**
+   * Gets the right ascension in degrees.
+   * @returns The right ascension in degrees.
+   */
+  get rightAscensionDegrees(): Degrees {
+    return this.rightAscension * RAD2DEG as Degrees;
+  }
+
+  /**
+   * Gets the declination in degrees.
+   * @returns The declination in degrees.
+   */
+  get declinationDegrees(): Degrees {
+    return this.declination * RAD2DEG as Degrees;
+  }
+
+  /**
+   * Gets the right ascension rate in degrees per second.
+   * @returns The right ascension rate in degrees per second, or null if it is not available.
+   */
+  get rightAscensionRateDegrees(): DegreesPerSecond | null {
+    return this.rightAscensionRate ? this.rightAscensionRate * RAD2DEG as DegreesPerSecond : null;
+  }
+
+  /**
+   * Gets the rate of change of declination in degrees per second.
+   * @returns The rate of change of declination in degrees per second, or null if not available.
+   */
+  get declinationRateDegrees(): DegreesPerSecond | null {
+    return this.declinationRate ? this.declinationRate * RAD2DEG as DegreesPerSecond : null;
+  }
+
+  /**
+   * Calculates the position vector in geocentric coordinates.
+   * @param range - The range in kilometers (optional). If not provided, it uses the default range or 1.0 kilometer.
+   * @returns The position vector in geocentric coordinates.
+   */
+  position(range?: Kilometers): Vector3D<Kilometers> {
+    const r = range ?? this.range ?? 1.0 as Kilometers;
+
+    return radecToPosition(this.rightAscension, this.declination, r);
+  }
+
+  /**
+   * Calculates the velocity vector of the celestial object.
+   * @param range - The range of the celestial object in kilometers. If not provided, it uses the stored range value.
+   * @param rangeRate - The range rate of the celestial object in kilometers per second.
+   * If not provided, it uses the stored range rate value.
+   * @returns The velocity vector of the celestial object in kilometers per second.
+   * @throws Error if the right ascension rate or declination rate is missing.
+   */
+  velocity(range?: Kilometers, rangeRate?: KilometersPerSecond): Vector3D<KilometersPerSecond> {
+    if (!this.rightAscensionRate || !this.declinationRate) {
+      throw new Error('Velocity unsolvable, missing ra/dec rates.');
+    }
+    const r = range ?? this.range ?? 1.0 as Kilometers;
+    const rd = rangeRate ?? this.rangeRate ?? 0.0 as KilometersPerSecond;
+
+    return radecToVelocity(this.rightAscension, this.declination, r, this.rightAscensionRate, this.declinationRate, rd);
+  }
+
+  /**
+   * Calculates the angular distance between two celestial coordinates (RA and Dec).
+   * @param radec - The celestial coordinates to compare with.
+   * @param method - The method to use for calculating the angular distance. Default is `AngularDistanceMethod.Cosine`.
+   * @returns The angular distance between the two celestial coordinates in radians.
+   */
+  angle(radec: RadecGeocentric, method: AngularDistanceMethod = AngularDistanceMethod.Cosine): Radians {
+    return angularDistance(this.rightAscension, this.declination, radec.rightAscension, radec.declination, method);
+  }
+
+  /**
+   * Calculates the angle in degrees between two RadecGeocentric objects.
+   * @param radec - The RadecGeocentric object to calculate the angle with.
+   * @param method - The method to use for calculating the angular distance. Default is AngularDistanceMethod.Cosine.
+   * @returns The angle in degrees.
+   */
+  angleDegrees(radec: RadecGeocentric, method: AngularDistanceMethod = AngularDistanceMethod.Cosine): Degrees {
+    return this.angle(radec, method) * RAD2DEG as Degrees;
+  }
+}