ootk 4.0.9 → 5.1.0

package/src/objects/Satellite.ts

@@ -0,0 +1,552 @@
+/**
+ * @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 type { ClassicalElements } from '../coordinate/index.js';
+import { Geodetic } from '../coordinate/Geodetic.js';
+import { ITRF } from '../coordinate/ITRF.js';
+import { J2000 } from '../coordinate/J2000.js';
+import { RIC } from '../coordinate/RIC.js';
+import { Tle } from '../coordinate/Tle.js';
+import { OptionsParams } from '../interfaces/OptionsParams.js';
+import { SatelliteParams } from '../interfaces/SatelliteParams.js';
+import { RAE } from '../observation/RAE.js';
+import { Vector3D } from '../operations/Vector3D.js';
+import { EpochUTC } from '../time/EpochUTC.js';
+import { ecf2rae, eci2ecf, eci2lla, jday } from '../transforms/index.js';
+import {
+  Degrees,
+  EcfVec3,
+  EciVec3,
+  GreenwichMeanSiderealTime,
+  Kilometers,
+  KilometersPerSecond,
+  LlaVec3,
+  Minutes,
+  PosVel,
+  Radians,
+  RaeVec3,
+  SatelliteRecord,
+  Seconds,
+  TleLine1,
+  TleLine2,
+} from '../types/types.js';
+import { DEG2RAD, MILLISECONDS_TO_DAYS, MINUTES_PER_DAY, RAD2DEG } from '../utils/constants.js';
+import { dopplerFactor } from './../utils/functions.js';
+import { BaseObject } from './BaseObject.js';
+import { GroundObject } from './GroundObject.js';
+import { OmmDataFormat, OmmParsedDataFormat } from '../interfaces/OmmFormat.js';
+import { Sgp4 } from '../main.js';
+
+/**
+ * Represents a satellite object with orbital information and methods for
+ * calculating its position and other properties.
+ */
+export class Satellite extends BaseObject {
+  apogee!: Kilometers;
+  argOfPerigee!: Degrees;
+  bstar!: number;
+  eccentricity!: number;
+  epochDay!: number;
+  epochYear!: number;
+  inclination!: Degrees;
+  intlDes!: string;
+  meanAnomaly!: Degrees;
+  meanMoDev1!: number;
+  meanMoDev2!: number;
+  meanMotion!: number;
+  options: OptionsParams;
+  perigee!: Kilometers;
+  period!: Minutes;
+  rightAscension!: Degrees;
+  satrec!: SatelliteRecord;
+  /** The satellite catalog number as listed in the TLE. */
+  sccNum!: string;
+  /** The 5 digit alpha-numeric satellite catalog number. */
+  sccNum5!: string;
+  /** The 6 digit numeric satellite catalog number. */
+  sccNum6!: string;
+  tle1!: TleLine1;
+  tle2!: TleLine2;
+  /** The semi-major axis of the satellite's orbit. */
+  semiMajorAxis!: Kilometers;
+  /** The semi-minor axis of the satellite's orbit. */
+  semiMinorAxis!: Kilometers;
+
+  constructor(info: SatelliteParams, options?: OptionsParams) {
+    super(info);
+
+    if (info.tle1 && info.tle2) {
+      this.parseTleAndUpdateOrbit_(info.tle1, info.tle2, info.sccNum);
+    } else if (info.omm) {
+      this.parseOmmAndUpdateOrbit_(info.omm);
+    } else {
+      throw new Error('tle1 and tle2 or omm must be provided to create a Satellite object.');
+    }
+
+    this.options = options ?? {
+      notes: '',
+    };
+  }
+
+  private parseTleAndUpdateOrbit_(tle1: TleLine1, tle2: TleLine2, sccNum?: string) {
+    const tleData = Tle.parse(tle1, tle2);
+
+    this.tle1 = tle1;
+    this.tle2 = tle2;
+
+    this.sccNum = sccNum ?? tleData.satNum.toString();
+    this.sccNum5 = Tle.convert6DigitToA5(this.sccNum);
+    this.sccNum6 = Tle.convertA5to6Digit(this.sccNum5);
+    this.intlDes = tleData.intlDes;
+    this.epochYear = tleData.epochYear;
+    this.epochDay = tleData.epochDay;
+    this.meanMoDev1 = tleData.meanMoDev1;
+    this.meanMoDev2 = tleData.meanMoDev2;
+    this.bstar = tleData.bstar;
+    this.inclination = tleData.inclination;
+    this.rightAscension = tleData.rightAscension;
+    this.eccentricity = tleData.eccentricity;
+    this.argOfPerigee = tleData.argOfPerigee;
+    this.meanAnomaly = tleData.meanAnomaly;
+    this.meanMotion = tleData.meanMotion;
+    this.period = tleData.period;
+    this.semiMajorAxis = ((8681663.653 / this.meanMotion) ** (2 / 3)) as Kilometers;
+    this.semiMinorAxis = (this.semiMajorAxis * Math.sqrt(1 - this.eccentricity ** 2)) as Kilometers;
+    this.apogee = (this.semiMajorAxis * (1 + this.eccentricity) - 6371) as Kilometers;
+    this.perigee = (this.semiMajorAxis * (1 - this.eccentricity) - 6371) as Kilometers;
+    this.satrec = Sgp4.createSatrec(tle1, tle2);
+  }
+
+  private parseOmmAndUpdateOrbit_(omm: OmmDataFormat) {
+    this.sccNum = omm.NORAD_CAT_ID.padStart(5, '0');
+    this.sccNum5 = Tle.convert6DigitToA5(omm.NORAD_CAT_ID);
+    this.sccNum6 = Tle.convertA5to6Digit(this.sccNum5);
+    this.intlDes = omm.OBJECT_ID;
+    const YYYY = omm.EPOCH.slice(0, 4);
+    const MM = omm.EPOCH.slice(5, 7);
+    const DD = omm.EPOCH.slice(8, 10);
+    const hh = omm.EPOCH.slice(11, 13);
+    const mm = omm.EPOCH.slice(14, 16);
+    const ss = omm.EPOCH.slice(17, 23);
+    const epochDateObj = Date.UTC(Number(YYYY), Number(MM) - 1, Number(DD), Number(hh), Number(mm), Number(ss));
+    const dayOfYear = (epochDateObj - Date.UTC(Number(YYYY), 0, 0)) / 86400000;
+
+    const ommParsed: OmmParsedDataFormat = {
+      ...omm,
+      epoch: {
+        year: Number(YYYY),
+        month: Number(MM),
+        day: Number(DD),
+        hour: Number(hh),
+        minute: Number(mm),
+        second: Number(ss),
+        doy: dayOfYear,
+      },
+    };
+
+    this.epochYear = parseInt(YYYY.slice(2, 4));
+    this.epochDay = dayOfYear;
+    this.meanMoDev1 = parseFloat(omm.MEAN_MOTION_DOT);
+    this.meanMoDev2 = parseFloat(omm.MEAN_MOTION_DDOT);
+    this.bstar = parseFloat(omm.BSTAR);
+    this.inclination = parseFloat(omm.INCLINATION) as Degrees;
+    this.rightAscension = parseFloat(omm.RA_OF_ASC_NODE) as Degrees;
+    this.eccentricity = parseFloat(omm.ECCENTRICITY);
+    this.argOfPerigee = parseFloat(omm.ARG_OF_PERICENTER) as Degrees;
+    this.meanAnomaly = parseFloat(omm.MEAN_ANOMALY) as Degrees;
+    this.meanMotion = parseFloat(omm.MEAN_MOTION);
+    this.period = 1440 / this.meanMotion as Minutes;
+    this.semiMajorAxis = ((8681663.653 / this.meanMotion) ** (2 / 3)) as Kilometers;
+    this.semiMinorAxis = (this.semiMajorAxis * Math.sqrt(1 - this.eccentricity ** 2)) as Kilometers;
+    this.apogee = (this.semiMajorAxis * (1 + this.eccentricity) - 6371) as Kilometers;
+    this.perigee = (this.semiMajorAxis * (1 - this.eccentricity) - 6371) as Kilometers;
+    this.satrec = Sgp4.createSatrecFromOmm(ommParsed);
+  }
+
+  /**
+   * Checks if the object is a satellite.
+   * @returns True if the object is a satellite, false otherwise.
+   */
+  override isSatellite(): boolean {
+    return true;
+  }
+
+  /**
+   * Returns whether the satellite is static or not.
+   * @returns True if the satellite is static, false otherwise.
+   */
+  override isStatic(): boolean {
+    return false;
+  }
+
+  /**
+   * Checks if the given SatelliteRecord object is valid by checking if its properties are all numbers.
+   * @param satrec - The SatelliteRecord object to check.
+   * @returns True if the SatelliteRecord object is valid, false otherwise.
+   */
+  static isValidSatrec(satrec: SatelliteRecord): boolean {
+    if (
+      isNaN(satrec.a) ||
+      isNaN(satrec.am) ||
+      isNaN(satrec.alta) ||
+      isNaN(satrec.em) ||
+      isNaN(satrec.mo) ||
+      isNaN(satrec.ecco) ||
+      isNaN(satrec.no)
+    ) {
+      return false;
+    }
+
+    return true;
+  }
+
+  ageOfElset(nowInput?: Date, outputUnits: 'days' | 'hours' | 'minutes' | 'seconds' = 'days'): number {
+    return Tle.calcElsetAge(this.tle1, nowInput, outputUnits);
+  }
+
+  editTle(tle1: TleLine1, tle2: TleLine2, sccNum?: string): void {
+    this.parseTleAndUpdateOrbit_(tle1, tle2, sccNum);
+  }
+
+  /**
+   * Calculates the azimuth angle of the satellite relative to the given sensor at the specified date. If no date is
+   * provided, the current time of the satellite is used.
+   * @variation optimized
+   * @param observer - The observer's position on the ground.
+   * @param date - The date at which to calculate the azimuth angle. Optional, defaults to the current date.
+   * @returns The azimuth angle of the satellite relative to the given sensor at the specified date.
+   */
+  az(observer: GroundObject, date: Date = new Date()): Degrees | null {
+    const rae = this.rae(observer, date);
+
+    if (!rae) {
+      return null;
+    }
+
+    return (rae.az * RAD2DEG) as Degrees;
+  }
+
+  /**
+   * Calculates the RAE (Range, Azimuth, Elevation) values for a given sensor and date. If no date is provided, the
+   * current time is used.
+   * @variation expanded
+   * @param observer - The observer's position on the ground.
+   * @param date - The date at which to calculate the RAE values. Optional, defaults to the current date.
+   * @returns The RAE values for the given sensor and date.
+   */
+  toRae(observer: GroundObject, date: Date = new Date()): RAE | null {
+    const rae = this.rae(observer, date);
+
+    if (!rae) {
+      return null;
+    }
+
+    const rae2 = this.rae(observer, new Date(date.getTime() + 1000));
+
+    if (!rae2) {
+      return null;
+    }
+
+    const epoch = new EpochUTC(date.getTime() / 1000 as Seconds);
+    const rangeRate = rae2.rng - rae.rng;
+    const azimuthRate = rae2.az - rae.az;
+    const elevationRate = rae2.el - rae.el;
+
+    return new RAE(
+      epoch,
+      rae.rng,
+      (rae.az * DEG2RAD) as Radians,
+      (rae.el * DEG2RAD) as Radians,
+      rangeRate,
+      azimuthRate,
+      elevationRate,
+    );
+  }
+
+  /**
+   * Calculates ECF position at a given time.
+   * @variation optimized
+   * @param date - The date at which to calculate the ECF position. Optional, defaults to the current date.
+   * @returns The ECF position at the specified date.
+   */
+  ecf(date: Date = new Date()): EcfVec3<Kilometers> | null {
+    const { gmst } = Satellite.calculateTimeVariables(date);
+    const eci = this.eci(date);
+
+    if (!eci) {
+      return null;
+    }
+
+    return eci2ecf(eci.position, gmst);
+  }
+
+  /**
+   * Calculates ECI position at a given time.
+   * @variation optimized
+   * @param date - The date at which to calculate the ECI position. Optional, defaults to the current date.
+   * @param j - Julian date. Optional, defaults to null.
+   * @param gmst - Greenwich Mean Sidereal Time. Optional, defaults to null.
+   * @returns The ECI position at the specified date.
+   */
+  eci(date?: Date, j?: number, gmst?: GreenwichMeanSiderealTime): PosVel | null {
+    date ??= new Date();
+    const { m } = Satellite.calculateTimeVariables(date, this.satrec, j, gmst);
+
+    if (!m) {
+      return null;
+    }
+    const pv = Sgp4.propagate(this.satrec, m);
+
+    if (!pv.position || !pv.velocity) {
+      return null;
+    }
+
+    return pv as PosVel;
+  }
+
+  /**
+   * Calculates the J2000 coordinates for a given date. If no date is provided, the current time is used.
+   * @variation expanded
+   * @param date - The date for which to calculate the J2000 coordinates, defaults to the current date.
+   * @returns The J2000 coordinates for the specified date.
+   * @throws Error if propagation fails.
+   */
+  toJ2000(date: Date = new Date()): J2000 {
+    const { m } = Satellite.calculateTimeVariables(date, this.satrec);
+
+    if (!m) {
+      throw new Error('Propagation failed!');
+    }
+    const pv = Sgp4.propagate(this.satrec, m);
+
+    if (!pv.position) {
+      throw new Error('Propagation failed!');
+    } else {
+      const p = pv.position as EciVec3;
+      const v = pv.velocity as EciVec3<KilometersPerSecond>;
+
+      const epoch = new EpochUTC(date.getTime() / 1000 as Seconds);
+      const pos = new Vector3D(p.x, p.y, p.z);
+      const vel = new Vector3D(v.x, v.y, v.z);
+
+      return new J2000(epoch, pos, vel);
+    }
+  }
+
+  /**
+   * Returns the elevation angle of the satellite as seen by the given sensor at the specified time.
+   * @variation optimized
+   * @param observer - The observer's position on the ground.
+   * @param date - The date at which to calculate the elevation angle. Optional, defaults to the current date.
+   * @returns The elevation angle of the satellite as seen by the given sensor at the specified time.
+   */
+  el(observer: GroundObject, date: Date = new Date()): Degrees | null {
+    const rae = this.rae(observer, date);
+
+    if (!rae) {
+      return null;
+    }
+
+    return (rae.el * RAD2DEG) as Degrees;
+  }
+
+  /**
+   * Calculates LLA position at a given time.
+   * @variation optimized
+   * @param date - The date at which to calculate the LLA position. Optional, defaults to the current date.
+   * @param j - Julian date. Optional, defaults to null.
+   * @param gmst - Greenwich Mean Sidereal Time. Optional, defaults to null.
+   * @returns The LLA position at the specified date.
+   */
+  lla(date?: Date, j?: number, gmst?: GreenwichMeanSiderealTime):
+    LlaVec3<Degrees, Kilometers> | null {
+    date ??= new Date();
+    if (!j || !gmst) {
+      const timeVar = Satellite.calculateTimeVariables(date, this.satrec);
+
+      j = timeVar.j;
+      gmst = timeVar.gmst;
+    }
+
+    const eci = this.eci(date, j, gmst);
+
+    if (!eci) {
+      return null;
+    }
+
+    const pos = eci.position;
+    const lla = eci2lla(pos, gmst);
+
+    return lla;
+  }
+
+  /**
+   * Converts the satellite's position to geodetic coordinates.
+   * @variation expanded
+   * @param date The date for which to calculate the geodetic coordinates. Defaults to the current date.
+   * @returns The geodetic coordinates of the satellite.
+   */
+  toGeodetic(date: Date = new Date()): Geodetic {
+    return this.toJ2000(date).toITRF().toGeodetic();
+  }
+
+  /**
+   * Converts the satellite's position to the International Terrestrial Reference Frame (ITRF) at the specified date.
+   * If no date is provided, the current date is used.
+   * @variation expanded
+   * @param date The date for which to convert the position. Defaults to the current date.
+   * @returns The satellite's position in the ITRF at the specified date.
+   */
+  toITRF(date: Date = new Date()): ITRF {
+    return this.toJ2000(date).toITRF();
+  }
+
+  /**
+   * Converts the current satellite's position to the Reference-Inertial-Celestial (RIC) frame
+   * relative to the specified reference satellite at the given date.
+   * @variation expanded
+   * @param reference The reference satellite.
+   * @param date The date for which to calculate the RIC frame. Defaults to the current date.
+   * @returns The RIC frame representing the current satellite's position relative to the reference satellite.
+   */
+  toRIC(reference: Satellite, date: Date = new Date()): RIC {
+    return RIC.fromJ2000(this.toJ2000(date), reference.toJ2000(date));
+  }
+
+  /**
+   * Converts the satellite object to a TLE (Two-Line Element) object.
+   * @returns The TLE object representing the satellite.
+   */
+  toTle(): Tle {
+    return new Tle(this.tle1, this.tle2);
+  }
+
+  /**
+   * Converts the satellite's position to classical orbital elements.
+   * @param date The date for which to calculate the classical elements. Defaults to the current date.
+   * @returns The classical orbital elements of the satellite.
+   */
+  toClassicalElements(date: Date = new Date()): ClassicalElements {
+    return this.toJ2000(date).toClassicalElements();
+  }
+
+  /**
+   * Calculates the RAE (Range, Azimuth, Elevation) vector for a given sensor and time.
+   * @variation optimized
+   * @param observer - The observer's position on the ground.
+   * @param date - The date at which to calculate the RAE vector. Optional, defaults to the current date.
+   * @param j - Julian date. Optional, defaults to null.
+   * @param gmst - Greenwich Mean Sidereal Time. Optional, defaults to null.
+   * @returns The RAE vector for the given sensor and time.
+   */
+  rae(observer: GroundObject, date?: Date, j?: number, gmst?: GreenwichMeanSiderealTime):
+    RaeVec3<Kilometers, Degrees> | null {
+    date ??= new Date();
+    gmst ??= Satellite.calculateTimeVariables(date, this.satrec).gmst;
+    const eci = this.eci(date, j, gmst);
+
+    if (!eci) {
+      return null;
+    }
+
+    const ecf = eci2ecf(eci.position, gmst);
+
+    return ecf2rae(observer, ecf);
+  }
+
+  /**
+   * Returns the range of the satellite from the given sensor at the specified time.
+   * @variation optimized
+   * @param observer - The observer's position on the ground.
+   * @param date - The date at which to calculate the range. Optional, defaults to the current date.
+   * @returns The range of the satellite from the given sensor at the specified time.
+   */
+  rng(observer: GroundObject, date: Date = new Date()): Kilometers | null {
+    const rae = this.rae(observer, date);
+
+    if (!rae) {
+      return null;
+    }
+
+    return rae.rng;
+  }
+
+  /**
+   * Applies the Doppler effect to the given frequency based on the observer's position and the date.
+   * @param freq - The frequency to apply the Doppler effect to.
+   * @param observer - The observer's position on the ground.
+   * @param date - The date at which to calculate the Doppler effect. Optional, defaults to the current date.
+   * @returns The frequency after applying the Doppler effect.
+   */
+  applyDoppler(freq: number, observer: GroundObject, date?: Date): number | null {
+    const doppler = this.dopplerFactor(observer, date);
+
+    if (!doppler) {
+      return null;
+    }
+
+    return freq * doppler;
+  }
+
+  /**
+   * Calculates the Doppler factor for the satellite.
+   * @param observer The observer's ground position.
+   * @param date The optional date for which to calculate the Doppler factor. If not provided, the current date is used.
+   * @returns The calculated Doppler factor.
+   */
+  dopplerFactor(observer: GroundObject, date?: Date): number | null {
+    const position = this.eci(date);
+
+    if (!position) {
+      return null;
+    }
+
+    return dopplerFactor(observer.eci(date), position.position, position.velocity);
+  }
+
+  /**
+   * Calculates the time variables for a given date relative to the TLE epoch.
+   * @param date Date to calculate
+   * @param satrec Satellite orbital information
+   * @param j Julian date
+   * @param gmst Greenwich Mean Sidereal Time
+   * @returns Time variables
+   */
+  private static calculateTimeVariables(
+    date: Date, satrec?: SatelliteRecord, j?: number, gmst?: GreenwichMeanSiderealTime,
+  ) {
+    j ??= jday(
+      date.getUTCFullYear(),
+      date.getUTCMonth() + 1,
+      date.getUTCDate(),
+      date.getUTCHours(),
+      date.getUTCMinutes(),
+      date.getUTCSeconds(),
+    ) + date.getUTCMilliseconds() * MILLISECONDS_TO_DAYS;
+    gmst ??= Sgp4.gstime(j);
+
+    const m = satrec ? (j - satrec.jdsatepoch) * MINUTES_PER_DAY : null;
+
+    return { gmst, m, j };
+  }
+}