ootk 4.0.9 → 5.0.0

package/src/body/Celestial.ts

@@ -0,0 +1,134 @@
+/**
+ * @author Theodore Kruczek.
+ * @license MIT
+ * @copyright (c) 2022-2025 Theodore Kruczek Permission is
+ * hereby granted, free of charge, to any person obtaining a copy of this
+ * software and associated documentation files (the "Software"), to deal in the
+ * Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do
+ * so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { AzEl, Degrees, Kilometers, RAD2DEG, RaDec, Radians, Sun } from '../main.js';
+
+/**
+ * Celestial is a static class that provides methods for calculating the position of celestial objects such as the Sun,
+ * Moon, and planets in the sky.
+ */
+export class Celestial {
+  private constructor() {
+    // disable constructor
+  }
+
+  /**
+   * Calculates the azimuth and elevation of a celestial object at a given date, latitude,
+   * longitude, right ascension, and declination.
+   * @param date - The date for which to calculate the azimuth and elevation.
+   * @param lat - The latitude of the observer.
+   * @param lon - The longitude of the observer.
+   * @param ra - The right ascension of the celestial object.
+   * @param dec - The declination of the celestial object.
+   * @returns An object containing the azimuth and elevation in degrees.
+   */
+  static azEl(date: Date, lat: Degrees, lon: Degrees, ra: Radians, dec: Radians): AzEl<Degrees> {
+    const c: RaDec = {
+      ra,
+      dec,
+      dist: 0 as Kilometers,
+    };
+    const azEl = Sun.azEl(date, lat, lon, c);
+
+    const el = <Radians>(azEl.el + Celestial.atmosphericRefraction(azEl.el)); // elevation correction for refraction
+
+    return {
+      az: (azEl.az * RAD2DEG) as Degrees,
+      el: (el * RAD2DEG) as Degrees,
+    };
+  }
+
+  /**
+   * Atmospheric refraction in astronomy, refers to the bending of light as it passes through the Earth's
+   * atmosphere. This effect is most noticeable for celestial objects like stars and planets when they are
+   * close to the horizon. Here's a breakdown of how it works:
+   *
+   * Actual Position: Due to this bending of light, the apparent position of a celestial object is slightly
+   * different from its true position in the sky. When a star or planet is near the horizon, the effect is more
+   * pronounced because the light path passes through more of the Earth's atmosphere, which increases the amount of
+   * bending.
+   *
+   * A familiar example of atmospheric refraction is observed during sunrise and sunset. The Sun appears to
+   * be above the horizon when it is actually just below it. This is because the light from the Sun is bent
+   * upwards as it passes through the atmosphere.
+   * @param h - elevation
+   * @returns refraction
+   */
+  static atmosphericRefraction(h: Radians): Radians {
+    if (h < 0) {
+      h = <Radians>0;
+    }
+
+    return <Radians>(0.0002967 / Math.tan(h + 0.00312536 / (h + 0.08901179)));
+  }
+
+  /**
+   * Calculate the declination. Similar to latitude on Earth, declination is another celestial coordinate.
+   * It measures how far north or south an object is from the celestial equator
+   * @param l - ecliptic longitude
+   * @param b - ecliptic latitude
+   * @returns declination
+   */
+  static declination(l: number, b: number): Radians {
+    return <Radians>Math.asin(Math.sin(b) * Math.cos(Sun.e) + Math.cos(b) * Math.sin(Sun.e) * Math.sin(l));
+  }
+
+  /**
+   * Calculate the right ascension. This is a celestial coordinate used to determine the position of objects
+   * in the sky. It's analogous to longitude on Earth. Right Ascension indicates how far east an object is
+   * from the vernal equinox along the celestial equator.
+   * @param l - ecliptic longitude
+   * @param b - ecliptic latitude
+   * @returns right ascension
+   */
+  static rightAscension(l: number, b: number): Radians {
+    return <Radians>Math.atan2(Math.sin(l) * Math.cos(Sun.e) - Math.tan(b) * Math.sin(Sun.e), Math.cos(l));
+  }
+
+  /**
+   * Calculate the elevation. Elevation, or altitude, is the angle between an object in the sky and the
+   * observer's local horizon. It's commonly expressed in degrees, where 0 degrees is right at the horizon
+   * and 90 degrees is directly overhead (the zenith), but we are using radians to support trigonometric
+   * functions like Math.sin() and Math.cos().
+   * @param H - siderealTime
+   * @param phi - latitude
+   * @param dec - The declination of the sun
+   * @returns elevation
+   */
+  static elevation(H: number, phi: Radians, dec: Radians): Radians {
+    return <Radians>Math.asin(Math.sin(phi) * Math.sin(dec) + Math.cos(phi) * Math.cos(dec) * Math.cos(H));
+  }
+
+  /**
+   * Calculate the azimuth. This is a compass direction measurement. Azimuth measures the angle along
+   * the horizon from a specific reference direction (usually true north) to the point where a vertical
+   * line from the object intersects the horizon.
+   * @param H - siderealTime
+   * @param phi - latitude
+   * @param dec - The declination of the sun
+   * @returns azimuth in rad
+   */
+  static azimuth(H: number, phi: Radians, dec: Radians): Radians {
+    return <Radians>(Math.PI + Math.atan2(Math.sin(H), Math.cos(H) * Math.sin(phi) - Math.tan(dec) * Math.cos(phi)));
+  }
+}

package/src/body/Earth.ts

@@ -0,0 +1,260 @@
+/**
+ * @author Theodore Kruczek.
+ * @license MIT
+ * @copyright (c) 2022-2025 Theodore Kruczek Permission is
+ * hereby granted, free of charge, to any person obtaining a copy of this
+ * software and associated documentation files (the "Software"), to deal in the
+ * Software without restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do
+ * so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import {
+  angularDiameter,
+  AngularDiameterMethod,
+  asec2rad,
+  DataHandler,
+  DEG2RAD,
+  earthGravityParam,
+  EpochUTC,
+  evalPoly,
+  Kilometers,
+  RAD2DEG,
+  Radians,
+  RadiansPerSecond,
+  secondsPerDay,
+  secondsPerSiderealDay,
+  TAU,
+  ttasec2rad,
+  Vector3D,
+} from '../main.js';
+import { NutationAngles } from './NutationAngles.js';
+import { PrecessionAngles } from './PrecessionAngles.js';
+
+// / Earth metrics and operations.
+export class Earth {
+  private constructor() {
+    // disable constructor
+  }
+
+  // / Earth gravitational parameter _(km²/s³)_.
+  static readonly mu: number = earthGravityParam;
+
+  // / Earth equatorial radius.
+  static readonly radiusEquator = 6378.1363 as Kilometers;
+
+  // / Earth coefficient of flattening _(unitless)_.
+  static readonly flattening: number = 1.0 / 298.257223563;
+
+  // / Earth polar radius.
+  static readonly radiusPolar = (Earth.radiusEquator * (1.0 - Earth.flattening)) as Kilometers;
+
+  // / Earth mean radius.
+  static readonly radiusMean = ((2.0 * Earth.radiusEquator + Earth.radiusPolar) / 3.0) as Kilometers;
+
+  // / Earth eccentricity squared _(unitless)_.
+  static readonly eccentricitySquared: number = Earth.flattening * (2.0 - Earth.flattening);
+
+  // / Earth J2 effect coefficient _(unitless)_.
+  static readonly j2: number = 1.08262668355315e-3;
+
+  // / Earth J3 effect coefficient _(unitless)_.
+  static readonly j3: number = -2.53265648533224e-6;
+
+  // / Earth J4 effect coefficient _(unitless)_.
+  static readonly j4: number = -1.619621591367e-6;
+
+  // / Earth J5 effect coefficient _(unitless)_.
+  static readonly j5: number = -2.27296082868698e-7;
+
+  // / Earth J6 effect coefficient _(unitless)_.
+  static readonly j6: number = 5.40681239107085e-7;
+
+  // / Earth rotation vector _(rad/s)_.
+  static readonly rotation = new Vector3D<RadiansPerSecond>(
+    0 as RadiansPerSecond,
+    0 as RadiansPerSecond,
+    7.292115146706979e-5 as RadiansPerSecond,
+  );
+
+  // / Calculate mean motion _(rad/s)_ from a given [semimajorAxis] _(km)_.
+  static smaToMeanMotion(semimajorAxis: Kilometers): RadiansPerSecond {
+    return Math.sqrt(Earth.mu / (semimajorAxis * semimajorAxis * semimajorAxis)) as RadiansPerSecond;
+  }
+
+  /**
+   * Converts revolutions per day to semi-major axis.
+   * @param rpd - The number of revolutions per day.
+   * @returns The semi-major axis value.
+   */
+  static revsPerDayToSma(rpd: number): number {
+    return Earth.mu ** (1 / 3) / ((TAU * rpd) / secondsPerDay) ** (2 / 3);
+  }
+
+  // / Calculate Earth [PrecessionAngles] at a given UTC [epoch].
+  static precession(epoch: EpochUTC): PrecessionAngles {
+    const t = epoch.toTT().toJulianCenturies();
+    const zeta = evalPoly(t, Earth.zetaPoly_);
+    const theta = evalPoly(t, Earth.thetaPoly_);
+    const zed = evalPoly(t, Earth.zedPoly_);
+
+    return { zeta: zeta as Radians, theta: theta as Radians, zed: zed as Radians };
+  }
+
+  // / Calculate Earth [NutationAngles] for a given UTC [epoch].
+  static nutation(epoch: EpochUTC): NutationAngles {
+    const t = epoch.toTT().toJulianCenturies();
+    const moonAnom = evalPoly(t, Earth.moonAnomPoly_);
+    const sunAnom = evalPoly(t, Earth.sunAnomPoly_);
+    const moonLat = evalPoly(t, Earth.moonLatPoly_);
+    const sunElong = evalPoly(t, Earth.sunElongPoly_);
+    const moonRaan = evalPoly(t, Earth.moonRaanPoly_);
+    let deltaPsi = 0.0;
+    let deltaEpsilon = 0.0;
+    const dh = DataHandler.getInstance();
+
+    for (let i = 0; i < 4; i++) {
+      const [a1, a2, a3, a4, a5, ai, bi, ci, di] = dh.getIau1980Coeffs(i);
+      const arg = a1 * moonAnom + a2 * sunAnom + a3 * moonLat + a4 * sunElong + a5 * moonRaan;
+      const sinC = ai + bi * t;
+      const cosC = ci + di * t;
+
+      deltaPsi += sinC * Math.sin(arg);
+      deltaEpsilon += cosC * Math.cos(arg);
+    }
+    deltaPsi *= ttasec2rad;
+    deltaEpsilon *= ttasec2rad;
+    const meanEpsilon = evalPoly(t, Earth.meanEpsilonPoly_);
+    const epsilon = meanEpsilon + deltaEpsilon;
+    const eqEq =
+      deltaPsi * Math.cos(meanEpsilon) +
+      0.00264 * asec2rad * Math.sin(moonRaan) +
+      0.000063 * asec2rad * Math.sin(2.0 * moonRaan);
+    const gast = epoch.gmstAngle() + eqEq;
+
+    return {
+      dPsi: deltaPsi as Radians,
+      dEps: deltaEpsilon as Radians,
+      mEps: meanEpsilon as Radians,
+      eps: epsilon as Radians,
+      eqEq: eqEq as Radians,
+      gast: gast as Radians,
+    };
+  }
+
+  // / Convert a [semimajorAxis] _(km)_ to an eastward drift rate _(rad/day)_.
+  static smaToDrift(semimajorAxis: number): number {
+    const t = (TAU * Math.sqrt(semimajorAxis ** 3 / Earth.mu)) / secondsPerSiderealDay;
+
+    return (1.0 - t) * TAU;
+  }
+
+  // / Convert a [semimajorAxis] _(km)_ to an eastward drift rate _(°/day)_.
+  static smaToDriftDegrees(semimajorAxis: number): number {
+    return Earth.smaToDrift(semimajorAxis) * RAD2DEG;
+  }
+
+  // / Convert an eastward [driftRate] _(rad/day)_ to a semimajor-axis _(km)_.
+  static driftToSemimajorAxis(driftRate: number): number {
+    const t = (-driftRate / TAU + 1) * secondsPerSiderealDay;
+
+    return ((Earth.mu * t * t) / (4 * Math.PI * Math.PI)) ** (1 / 3);
+  }
+
+  // / Convert an eastward [driftRate] _(°/day)_ to a semimajor-axis _(km)_.
+  static driftDegreesToSma(driftRate: number): number {
+    return Earth.driftToSemimajorAxis(DEG2RAD * driftRate);
+  }
+
+  /**
+   * Calculates the diameter of the Earth based on the satellite position.
+   * @param satPos The position of the satellite.
+   * @returns The diameter of the Earth.
+   */
+  static diameter(satPos: Vector3D): number {
+    return angularDiameter(Earth.radiusEquator * 2, satPos.magnitude(), AngularDiameterMethod.Sphere);
+  }
+
+  // / Earth precession `zeta` polynomial coefficients.
+  private static readonly zetaPoly_: Float64Array = Float64Array.from([
+    0.017998 * asec2rad,
+    0.30188 * asec2rad,
+    2306.2181 * asec2rad,
+    0.0,
+  ]);
+
+  // / Earth precession `theta` polynomial coefficients.
+  private static readonly thetaPoly_: Float64Array = Float64Array.from([
+    -0.041833 * asec2rad,
+    -0.42665 * asec2rad,
+    2004.3109 * asec2rad,
+    0.0,
+  ]);
+
+  // / Earth precession `zed` polynomial coefficients.
+  private static readonly zedPoly_: Float64Array = Float64Array.from([
+    0.018203 * asec2rad,
+    1.09468 * asec2rad,
+    2306.2181 * asec2rad,
+    0,
+  ]);
+
+  private static readonly moonAnomPoly_: Float64Array = Float64Array.from([
+    1.4343e-5 * DEG2RAD,
+    0.0088553 * DEG2RAD,
+    (1325.0 * 360.0 + 198.8675605) * DEG2RAD,
+    134.96340251 * DEG2RAD,
+  ]);
+
+  // / Earth nutation Sun anomaly polynomial coefficients.
+  private static readonly sunAnomPoly_: Float64Array = Float64Array.from([
+    3.8e-8 * DEG2RAD,
+    -0.0001537 * DEG2RAD,
+    (99.0 * 360.0 + 359.0502911) * DEG2RAD,
+    357.52910918 * DEG2RAD,
+  ]);
+
+  // / Earth nutation Moon latitude polynomial coefficients.
+  private static readonly moonLatPoly_: Float64Array = Float64Array.from([
+    -2.88e-7 * DEG2RAD,
+    -0.003542 * DEG2RAD,
+    (1342.0 * 360.0 + 82.0174577) * DEG2RAD,
+    93.27209062 * DEG2RAD,
+  ]);
+
+  // / Earth nutation Sun elongation polynomial coefficients.
+  private static readonly sunElongPoly_: Float64Array = Float64Array.from([
+    1.831e-6 * DEG2RAD,
+    -0.0017696 * DEG2RAD,
+    (1236.0 * 360.0 + 307.1114469) * DEG2RAD,
+    297.85019547 * DEG2RAD,
+  ]);
+
+  // / Earth nutation Moon right-ascension polynomial coefficients.
+  private static readonly moonRaanPoly_: Float64Array = Float64Array.from([
+    2.139e-6 * DEG2RAD,
+    0.0020756 * DEG2RAD,
+    -(5.0 * 360.0 + 134.1361851) * DEG2RAD,
+    125.04455501 * DEG2RAD,
+  ]);
+
+  // / Earth nutation mean epsilon polynomial coefficients.
+  private static readonly meanEpsilonPoly_: Float64Array = Float64Array.from([
+    0.001813 * asec2rad,
+    -0.00059 * asec2rad,
+    -46.815 * asec2rad,
+    84381.448 * asec2rad,
+  ]);
+}