ootk 4.0.9 → 5.1.0

package/src/objects/Sensor.ts

@@ -0,0 +1,279 @@
+/**
+ * @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 { PassType } from '../enums/PassType.js';
+import { SensorParams } from '../interfaces/SensorParams.js';
+import { Degrees, Kilometers, KilometersPerSecond, Lookangle, RaeVec3, SpaceObjectType } from '../types/types.js';
+import { GroundObject } from './GroundObject.js';
+import { Satellite } from './Satellite.js';
+import { calcGmst, lla2eci, J2000, Vector3D, EpochUTC } from '../main.js';
+
+export class Sensor extends GroundObject {
+  minRng: Kilometers;
+  minAz: Degrees;
+  minEl: Degrees;
+  maxRng: Kilometers;
+  maxAz: Degrees;
+  maxEl: Degrees;
+  minRng2?: Kilometers;
+  minAz2?: Degrees;
+  minEl2?: Degrees;
+  maxRng2?: Kilometers;
+  maxAz2?: Degrees;
+  maxEl2?: Degrees;
+
+  constructor(info: SensorParams) {
+    // If there is a sensor type verify it is valid
+    if (info.type) {
+      switch (info.type) {
+        case SpaceObjectType.OPTICAL:
+        case SpaceObjectType.MECHANICAL:
+        case SpaceObjectType.PHASED_ARRAY_RADAR:
+        case SpaceObjectType.OBSERVER:
+        case SpaceObjectType.BISTATIC_RADIO_TELESCOPE:
+        case SpaceObjectType.SHORT_TERM_FENCE:
+          break;
+        default:
+          throw new Error('Invalid sensor type');
+      }
+    }
+
+    super(info);
+
+    this.validateSensorInputData_(info);
+
+    this.minRng = info.minRng;
+    this.minAz = info.minAz;
+    this.minEl = info.minEl;
+    this.maxRng = info.maxRng;
+    this.maxAz = info.maxAz;
+    this.maxEl = info.maxEl;
+    this.minRng2 = info.minRng2;
+    this.minAz2 = info.minAz2;
+    this.minEl2 = info.minEl2;
+    this.maxRng2 = info.maxRng2;
+    this.maxAz2 = info.maxAz2;
+    this.maxEl2 = info.maxEl2;
+  }
+
+  /**
+   * Checks if the object is a sensor.
+   * @returns True if the object is a sensor, false otherwise.
+   */
+  override isSensor(): boolean {
+    return true;
+  }
+
+  calculatePasses(planningInterval: number, sat: Satellite, date: Date = new Date()) {
+    let isInViewLast = false;
+    let maxElThisPass = <Degrees>0;
+    const msnPlanPasses: Lookangle[] = [];
+    const startTime = date.getTime();
+
+    for (let timeOffset = 0; timeOffset < planningInterval; timeOffset++) {
+      const curTime = new Date(startTime + timeOffset * 1000);
+      const rae = this.rae(sat, curTime);
+
+      if (!rae) {
+        continue;
+      }
+
+      const isInView = this.isRaeInFov(rae);
+
+      if (timeOffset === 0) {
+        // Propagate Backwards to get the previous pass
+        const oldRae = this.rae(sat, new Date(date.getTime() - 1 * 1000));
+
+        if (!oldRae) {
+          continue;
+        }
+
+        isInViewLast = this.isRaeInFov(oldRae);
+      }
+
+      const type = Sensor.getPassType_(isInView, isInViewLast);
+
+      maxElThisPass = <Degrees>Math.max(maxElThisPass, rae.el);
+
+      if (type === PassType.ENTER || type === PassType.EXIT) {
+        const pass = <Lookangle>{
+          type,
+          time: curTime,
+          az: rae.az,
+          el: rae.el,
+          rng: rae.rng,
+        };
+
+        // Only set maxEl for EXIT passes
+        if (type === PassType.EXIT) {
+          pass.maxElPass = maxElThisPass;
+        }
+
+        msnPlanPasses.push(pass);
+        maxElThisPass = <Degrees>0;
+      }
+
+      isInViewLast = isInView;
+    }
+
+    return msnPlanPasses;
+  }
+
+  /**
+   * Checks if the given RAE vector is within the field of view of the sensor.
+   * @param rae - The RAE vector to check.
+   * @returns True if the RAE vector is within the field of view, false otherwise.
+   */
+  isRaeInFov(rae: RaeVec3<Kilometers, Degrees>): boolean {
+    if (rae.el < this.minEl || rae.el > this.maxEl) {
+      return false;
+    }
+
+    if (rae.rng < this.minRng || rae.rng > this.maxRng) {
+      return false;
+    }
+
+    if (this.minAz > this.maxAz) {
+      // North Facing Sensors
+      if (rae.az < this.minAz && rae.az > this.maxAz) {
+        return false;
+      }
+      // Normal Facing Sensors
+    } else if (rae.az < this.minAz || rae.az > this.maxAz) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Checks if a satellite is in the field of view (FOV) of the sensor.
+   * @param sat - The satellite to check.
+   * @param date - The date to use for the calculation. Defaults to the current date.
+   * @returns A boolean indicating whether the satellite is in the FOV.
+   */
+  isSatInFov(sat: Satellite, date: Date = new Date()): boolean {
+    const rae = this.rae(sat, date);
+
+    if (!rae) {
+      return false;
+    }
+
+    return this.isRaeInFov(rae);
+  }
+
+  /**
+   * Checks if the sensor is in deep space.
+   * @returns True if the sensor is in deep space, false otherwise.
+   */
+  isDeepSpace(): boolean {
+    return this.maxRng > 6000;
+  }
+
+  /**
+   * Checks if the sensor is near Earth.
+   * @returns True if the sensor is near Earth, false otherwise.
+   */
+  isNearEarth(): boolean {
+    return this.maxRng <= 6000;
+  }
+
+  toJ2000(date: Date = new Date()): J2000 {
+    const gmst = calcGmst(date).gmst;
+    const position = lla2eci(this.llaRad(), gmst);
+
+    return new J2000(
+      EpochUTC.fromDateTime(date),
+      new Vector3D(position.x, position.y, position.z),
+      new Vector3D(0 as KilometersPerSecond, 0 as KilometersPerSecond, 0 as KilometersPerSecond),
+    );
+  }
+
+  /**
+   * Returns the pass type based on the current and previous visibility states.
+   * @param isInView - Indicates if the object is currently in view.
+   * @param isInViewLast - Indicates if the object was in view in the previous state.
+   * @returns The pass type.
+   */
+  private static getPassType_(isInView: boolean, isInViewLast: boolean) {
+    let type = PassType.OUT_OF_VIEW;
+
+    if (isInView && !isInViewLast) {
+      type = PassType.ENTER;
+    } else if (!isInView && isInViewLast) {
+      type = PassType.EXIT;
+    } else if (isInView && isInViewLast) {
+      type = PassType.IN_VIEW;
+    }
+
+    return type;
+  }
+
+  /**
+   * Validates the field of view (FOV) parameters of the sensor.
+   * @param info - The sensor parameters.
+   */
+  private validateFov_(info: SensorParams) {
+    this.validateParameter(info.maxAz, 0, 360, 'Invalid maximum azimuth - must be between 0 and 360');
+    this.validateParameter(info.minAz, 0, 360, 'Invalid maximum azimuth - must be between 0 and 360');
+    this.validateParameter(info.maxEl, -15, 180, 'Invalid maximum elevation - must be between 0 and 180');
+    this.validateParameter(info.minEl, -15, 90, 'Invalid minimum elevation - must be between 0 and 90');
+    this.validateParameter(info.maxRng, 0, null, 'Invalid maximum range - must be greater than 0');
+    this.validateParameter(info.minRng, 0, null, 'Invalid minimum range - must be greater than 0');
+  }
+
+  /**
+   * Validates the field of view parameters for the sensor.
+   * @param info - The sensor parameters.
+   */
+  private validateFov2_(info: SensorParams) {
+    this.validateParameter(info.maxAz2, 0, 360, 'Invalid maximum azimuth2 - must be between 0 and 360');
+    this.validateParameter(info.minAz2, 0, 360, 'Invalid maximum azimuth2 - must be between 0 and 360');
+    this.validateParameter(info.maxEl2, -15, 180, 'Invalid maximum elevation2 - must be between 0 and 180');
+    this.validateParameter(info.minEl2, -15, 90, 'Invalid minimum elevation2 - must be between 0 and 90');
+    this.validateParameter(info.maxRng2, 0, null, 'Invalid maximum range2 - must be greater than 0');
+    this.validateParameter(info.minRng2, 0, null, 'Invalid minimum range2 - must be greater than 0');
+  }
+
+  /**
+   * Validates the input data for the sensor.
+   * @param info - The sensor parameters.
+   */
+  private validateSensorInputData_(info: SensorParams) {
+    this.validateLla_(info);
+    this.validateFov_(info);
+    if (info.minAz2 || info.maxAz2 || info.minEl2 || info.maxEl2 || info.minRng2 || info.maxRng2) {
+      this.validateFov2_(info);
+    }
+  }
+
+  /**
+   * Validates the latitude, longitude, and altitude of a sensor.
+   * @param info - The sensor parameters containing the latitude, longitude, and altitude.
+   */
+  private validateLla_(info: SensorParams) {
+    this.validateParameter(info.lat, -90, 90, 'Invalid latitude - must be between -90 and 90');
+    this.validateParameter(info.lon, -180, 180, 'Invalid longitude - must be between -180 and 180');
+    this.validateParameter(info.alt, 0, null, 'Invalid altitude - must be greater than 0');
+  }
+}

package/src/objects/Star.ts

@@ -0,0 +1,96 @@
+/**
+ * @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 {
+  Celestial,
+  Degrees,
+  ecf2eci,
+  EciVec3,
+  GreenwichMeanSiderealTime,
+  jday,
+  Kilometers,
+  LlaVec3,
+  MILLISECONDS_TO_DAYS,
+  Radians,
+  rae2ecf,
+  RaeVec3,
+  Sgp4,
+  SpaceObjectType,
+  StarObjectParams,
+} from '../main.js';
+import { BaseObject } from './BaseObject.js';
+
+export class Star extends BaseObject {
+  ra: Radians;
+  dec: Radians;
+  bf: string;
+  h: string;
+  pname: string;
+  vmag?: number;
+
+  constructor(info: StarObjectParams) {
+    super(info);
+    this.type = SpaceObjectType.STAR;
+
+    this.ra = info.ra;
+    this.dec = info.dec;
+
+    this.pname = info.pname ?? '';
+    this.bf = info.bf ?? '';
+    this.h = info.h ?? '';
+    this.vmag = info.vmag;
+  }
+
+  eci(lla: LlaVec3 = { lat: <Degrees>180, lon: <Degrees>0, alt: <Kilometers>0 }, date: Date = new Date()): EciVec3 {
+    const rae = this.rae(lla, date);
+    const { gmst } = Star.calculateTimeVariables_(date);
+
+    // Arbitrary distance to enable using ECI coordinates
+    return ecf2eci(rae2ecf(rae, { lat: <Degrees>0, lon: <Degrees>0, alt: <Kilometers>0 }), gmst);
+  }
+
+  rae(
+    lla: LlaVec3<Degrees, Kilometers> = { lat: <Degrees>180, lon: <Degrees>0, alt: <Kilometers>0 },
+    date: Date = new Date(),
+  ): RaeVec3 {
+    const starPos = Celestial.azEl(date, lla.lat, lla.lon, this.ra, this.dec);
+
+    return { az: starPos.az, el: starPos.el, rng: <Kilometers>250000 };
+  }
+
+  private static calculateTimeVariables_(date: Date): { gmst: GreenwichMeanSiderealTime; j: number } {
+    const j =
+      jday(
+        date.getUTCFullYear(),
+        date.getUTCMonth() + 1,
+        date.getUTCDate(),
+        date.getUTCHours(),
+        date.getUTCMinutes(),
+        date.getUTCSeconds(),
+      ) +
+      date.getUTCMilliseconds() * MILLISECONDS_TO_DAYS;
+    const gmst = Sgp4.gstime(j);
+
+    return { gmst, j };
+  }
+}

package/src/objects/index.ts

@@ -1,3 +1,8 @@
+export { BaseObject } from './BaseObject.js';
+export { GroundObject } from './GroundObject.js';
+export { Satellite } from './Satellite.js';
+export { Sensor } from './Sensor.js';
+export { Star } from './Star.js';
 export { DetailedSatellite } from './DetailedSatellite.js';
 export { DetailedSensor } from './DetailedSensor.js';
 export { LandObject } from './LandObject.js';

package/src/observation/Observation.ts

@@ -1,7 +1,7 @@
 /**
  * @author @thkruz Theodore Kruczek
  * @license AGPL-3.0-or-later
- * @copyright (c) 2020-2024 Theodore Kruczek
+ * @copyright (c) 2025 Kruczek Labs LLC
  *
  * 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
@@ -15,7 +15,7 @@
  * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
  */
 
-import { EpochUTC, J2000, Matrix, Vector, Vector3D } from 'ootk-core';
+import { EpochUTC, J2000, Matrix, Vector, Vector3D } from '../main.js';
 import { Propagator } from '../propagator/Propagator.js';
 import { RandomGaussianSource } from './../operations/RandomGaussianSource.js';
 import { PropagatorPairs } from './PropagatorPairs.js';

package/src/observation/ObservationOptical.ts

@@ -1,7 +1,7 @@
 /**
  * @author @thkruz Theodore Kruczek
  * @license AGPL-3.0-or-later
- * @copyright (c) 2020-2024 Theodore Kruczek
+ * @copyright (c) 2025 Kruczek Labs LLC
  *
  * 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
@@ -27,7 +27,7 @@ import {
   RIC,
   Vector,
   Vector3D,
-} from 'ootk-core';
+} from '../main.js';
 import { RandomGaussianSource } from '../operations/RandomGaussianSource.js';
 import { Propagator } from '../propagator/Propagator.js';
 import { Observation } from './Observation.js';
@@ -38,28 +38,28 @@ import { PropagatorPairs } from './PropagatorPairs.js';
 export class ObservationOptical extends Observation {
   // / Create a new [ObservationOptical] object.
   constructor(
-    private _site: J2000,
+    private readonly site_: J2000,
     public observation: RadecTopocentric,
-    private _noise: Matrix = ObservationOptical.defaultNoise,
+    private readonly noise_: Matrix = ObservationOptical.defaultNoise,
   ) {
     super();
   }
 
   // / Inertial site location.
   get site(): J2000 {
-    return this._site;
+    return this.site_;
   }
 
   // / Noise matrix.
   get noise(): Matrix {
-    return this._noise;
+    return this.noise_;
   }
 
   /**
    * Default noise matrix _(right-ascension, declination)_.
    * Based on the Maui Optical Site noise model.
    */
-  static defaultNoise: Matrix = ObservationOptical.noiseFromSigmas(
+  static readonly defaultNoise: Matrix = ObservationOptical.noiseFromSigmas(
     0.0037 * DEG2RAD as Radians,
     0.003 * DEG2RAD as Radians,
   );

package/src/observation/ObservationRadar.ts

@@ -1,7 +1,7 @@
 /**
  * @author @thkruz Theodore Kruczek
  * @license AGPL-3.0-or-later
- * @copyright (c) 2020-2024 Theodore Kruczek
+ * @copyright (c) 2025 Kruczek Labs LLC
  *
  * 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
@@ -28,7 +28,7 @@ import {
   RIC,
   Vector,
   Vector3D,
-} from 'ootk-core';
+} from '../main.js';
 import { RandomGaussianSource } from '../operations/RandomGaussianSource.js';
 import { Propagator } from '../propagator/Propagator.js';
 import { Observation } from './Observation.js';
@@ -38,12 +38,16 @@ import { PropagatorPairs } from './PropagatorPairs.js';
 // / Radar observation data.
 export class ObservationRadar extends Observation {
   // / Create a new [ObservationRadar] object.
-  constructor(private _site: J2000, public observation: RAE, private _noise: Matrix = ObservationRadar.defaultNoise) {
+  constructor(
+    private readonly site_: J2000,
+    public observation: RAE,
+    private readonly noise_: Matrix = ObservationRadar.defaultNoise,
+  ) {
     super();
   }
 
   // / Default noise matrix.
-  private static defaultNoise: Matrix =
+  private static readonly defaultNoise: Matrix =
     ObservationRadar.noiseFromSigmas(0.32 as Kilometers, 0.015 * DEG2RAD as Radians, 0.015 * DEG2RAD as Radians);
 
   get epoch(): EpochUTC {
@@ -51,11 +55,11 @@ export class ObservationRadar extends Observation {
   }
 
   get site(): J2000 {
-    return this._site;
+    return this.site_;
   }
 
   get noise(): Matrix {
-    return this._noise;
+    return this.noise_;
   }
 
   toVector(): Vector {

package/src/observation/ObservationUtils.ts

@@ -1,7 +1,7 @@
 /**
  * @author @thkruz Theodore Kruczek
  * @license AGPL-3.0-or-later
- * @copyright (c) 2020-2024 Theodore Kruczek
+ * @copyright (c) 2025 Kruczek Labs LLC
  *
  * 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
@@ -15,7 +15,36 @@
  * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
  */
 
-import { Matrix } from 'ootk-core';
+import { Radians, Kilometers, Vector3D, RadiansPerSecond, KilometersPerSecond, Matrix } from '../main.js';
+
+export const radecToPosition = (ra: Radians, dec: Radians, r: Kilometers): Vector3D<Kilometers> => {
+  const ca = Math.cos(ra);
+  const sa = Math.sin(ra);
+  const cd = Math.cos(dec);
+  const sd = Math.sin(dec);
+
+  return new Vector3D(r * cd * ca as Kilometers, r * cd * sa as Kilometers, r * sd as Kilometers);
+};
+
+export const radecToVelocity = (
+  ra: Radians,
+  dec: Radians,
+  r: Kilometers,
+  raDot: RadiansPerSecond,
+  decDot: RadiansPerSecond,
+  rDot: KilometersPerSecond,
+): Vector3D<KilometersPerSecond> => {
+  const ca = Math.cos(ra);
+  const sa = Math.sin(ra);
+  const cd = Math.cos(dec);
+  const sd = Math.sin(dec);
+
+  return new Vector3D(
+    rDot * cd * ca - r * sd * ca * decDot - r * cd * sa * raDot as KilometersPerSecond,
+    rDot * cd * sa - r * sd * sa * decDot + r * cd * ca * raDot as KilometersPerSecond,
+    rDot * sd + r * cd * decDot as KilometersPerSecond,
+  );
+};
 
 export const normalizeAngle = (a: number, b: number): number => {
   const x = a - b;

package/src/observation/PropagatorPairs.ts

@@ -1,7 +1,7 @@
 /**
  * @author @thkruz Theodore Kruczek
  * @license AGPL-3.0-or-later
- * @copyright (c) 2020-2024 Theodore Kruczek
+ * @copyright (c) 2025 Kruczek Labs LLC
  *
  * 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
@@ -18,7 +18,7 @@
 import { Propagator } from '../propagator/Propagator.js';
 
 export class PropagatorPairs {
-  constructor(private _posStep: number, private _velStep: number) {
+  constructor(private readonly posStep_: number, private readonly velStep_: number) {
     // Do nothing.
   }
 
@@ -40,6 +40,6 @@ export class PropagatorPairs {
    * @returns The step size.
    */
   step(index: number): number {
-    return index < 3 ? this._posStep : this._velStep;
+    return index < 3 ? this.posStep_ : this.velStep_;
   }
 }