ootk 4.0.9 → 5.1.0

package/src/types/types.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,8 +15,727 @@
  * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
  */
 
-import { Kilometers, Milliseconds, SatelliteParams, SensorParams, Vec3 } from 'ootk-core';
-import { CommLink } from '../main.js';
+import { Vector3D, PassType, Satellite, CommLink, SatelliteParams, SensorParams } from '../main.js';
+import { Sgp4ErrorCode } from '../sgp4/sgp4-error.js';
+
+/**
+ * Represents a distinct type.
+ *
+ * This type is used to create new types based on existing ones, but with a
+ * unique identifier. This can be useful for creating types that are
+ * semantically different but structurally the same.
+ * @template T The base type from which the distinct type is created.
+ * @template DistinctName A unique identifier for the distinct type.
+ * __TYPE__ A property that holds the unique identifier for the
+ * distinct type.
+ */
+type Distinct<T, DistinctName> = T & { __TYPE__: DistinctName };
+
+// Possible usages
+
+/**
+ * Represents a quantity of days.
+ */
+export type Days = Distinct<number, 'Days'>;
+
+/**
+ * Represents a quantity of hours.
+ *
+ * This type is based on the number type, but is distinct and cannot be used
+ * interchangeably with other number-based types.
+ */
+export type Hours = Distinct<number, 'Hours'>;
+
+/**
+ * Represents a quantity of minutes.
+ */
+export type Minutes = Distinct<number, 'Minutes'>;
+
+/**
+ * Represents a quantity of seconds.
+ */
+export type Seconds = Distinct<number, 'Seconds'>;
+
+/**
+ * Represents a quantity of milliseconds.
+ */
+export type Milliseconds = Distinct<number, 'Milliseconds'>;
+
+/**
+ * Represents a quantity of degrees.
+ */
+export type Degrees = Distinct<number, 'Degrees'>;
+
+/**
+ * Represents a quantity of radians.
+ */
+export type Radians = Distinct<number, 'Radians'>;
+
+/**
+ * Represents a quantity of kilometers.
+ */
+export type Kilometers = Distinct<number, 'Kilometers'>;
+
+/**
+ * Represents a quantity of meters.
+ */
+export type Meters = Distinct<number, 'Meters'>;
+
+/**
+ * Represents the type for seconds per meter per second.
+ */
+export type SecondsPerMeterPerSecond = Distinct<number, 'SecondsPerMeterPerSecond'>;
+
+/**
+ * Represents a value in kilometers per second.
+ */
+export type KilometersPerSecond = Distinct<number, 'KilometersPerSecond'>;
+
+/**
+ * Represents a value in Radians per second.
+ */
+export type RadiansPerSecond = Distinct<number, 'RadiansPerSecond'>;
+
+/**
+ * Represents a value in degrees per second.
+ */
+export type DegreesPerSecond = Distinct<number, 'DegreesPerSecond'>;
+
+/**
+ * Represents a value in meters per second.
+ */
+export type MetersPerSecond = Distinct<number, 'MetersPerSecond'>;
+
+/**
+ * Represents a three-dimensional vector.
+ *
+ * This type is used to represent a point in space in terms of x, y, and z
+ * coordinates. It is a generic type that allows for flexibility in the units of
+ * measure used for each dimension. The default unit of measure is Kilometers.
+ * @template Units The unit of measure used for the dimensions. This is
+ * typically a type representing a distance, such as kilometers or meters. The
+ * default is Kilometers.
+ * x The x dimension of the vector, representing the distance from the
+ * origin to the point in the x direction.
+ * y The y dimension of the vector, representing the distance from the
+ * origin to the point in the y direction. @property z The z dimension of the
+ * vector, representing the distance from the origin to the point in the z
+ * direction.
+ */
+export type Vec3<Units = Kilometers> = {
+  x: Units;
+  y: Units;
+  z: Units;
+};
+
+/**
+ * Represents a three-dimensional vector in Earth-Centered Inertial (ECI)
+ * coordinates.
+ *
+ * This type is used to represent a point in space in terms of x, y, and z
+ * coordinates. It is a generic type that allows for flexibility in the units of
+ * measure used for each dimension. The default unit of measure is Kilometers.
+ * x The x dimension of the vector, representing the distance from the
+ * origin to the point in the x direction.
+ * y The y dimension of the vector, representing the distance from the
+ * origin to the point in the y direction. @property z The z dimension of the
+ * vector, representing the distance from the origin to the point in the z
+ * direction.
+ */
+export type EciVec3<Units = Kilometers> = Vec3<Units>;
+
+/**
+ * Represents a three-dimensional vector in Earth-Centered Fixed (ECF)
+ * coordinates.
+ *
+ * NOTE: ECF (Earth-Centered Fixed) and ECEF (Earth-Centered, Earth-Fixed) are
+ * essentially the same thing. Both refer to a coordinate system that is fixed
+ * with respect to the Earth, meaning that the coordinates of a point in this
+ * system do not change even as the Earth rotates.
+ *
+ * The difference between the two is that ECF is a Cartesian coordinate system,
+ * while ECEF is a spherical coordinate system. The ECF system is used in this
+ * library because it is easier to work with in the context of the SGP4
+ * algorithm.
+ *
+ * This type is used to represent a point in space in terms of x, y, and z
+ * coordinates. It is a generic type that allows for flexibility in the units of
+ * measure used for each dimension. The default unit of measure is Kilometers.
+ * x The x dimension of the vector, representing the distance from the
+ * origin to the point in the x direction.
+ * y The y dimension of the vector, representing the distance from the
+ * origin to the point in the y direction. @property z The z dimension of the
+ * vector, representing the distance from the origin to the point in the z
+ * direction.
+ */
+export type EcfVec3<Units = Kilometers> = Vec3<Units>;
+
+/**
+ * Represents a three-dimensional vector in Earth-Centered Earth-Fixed (ECEF)
+ * coordinates.
+ */
+export type EcefVec3<Units = Kilometers> = EcfVec3<Units>;
+
+/**
+ * Represents a three-dimensional vector in East, North, Up (ENU) coordinates.
+ *
+ * East–west tangent to parallels, North–south tangent to meridians, and Up–down
+ * in the direction normal to the oblate spheroid used as Earth's ellipsoid,
+ * which does not generally pass through the center of Earth.
+ *
+ * In many targeting and tracking applications the local East, North, Up (ENU)
+ * Cartesian coordinate system is far more intuitive and practical than ECEF or
+ * Geodetic coordinates. The local ENU coordinates are formed from a plane
+ * tangent to the Earth's surface fixed to a specific location and hence it is
+ * sometimes known as a "Local Tangent" or "local geodetic" plane. By convention
+ * the east axis is labeled x, the north y, and the up z.
+ * @see https://en.wikipedia.org/wiki/Local_tangent_plane_coordinates
+ * @template Units The unit of measure used for the dimensions. This is
+ * typically a type representing a distance, such as kilometers or meters. The
+ * default is Kilometers.
+ * e The east dimension of the vector, representing the distance from
+ * the origin to the point in the east direction.
+ * n The north dimension of the vector, representing the distance from
+ * the origin to the point in the north direction. @property u The up dimension
+ * of the vector, representing the distance from the origin to the point in the
+ * upward direction.
+ */
+export type EnuVec3<Units = Kilometers> = Vec3<Units>;
+
+/**
+ * Represents a three-dimensional vector in geographical coordinates.
+ *
+ * This type is used to represent a point in space in terms of latitude,
+ * longitude, and altitude. It is a generic type that allows for flexibility in
+ * the units of measure used for each dimension.
+ * @template A The unit of measure used for the latitude and longitude
+ * dimensions. This is typically a type representing an angle, such as degrees
+ * or radians. The default is Radians.
+ * @template D The unit of measure used for the altitude dimension. This is
+ * typically a type representing a distance, such as kilometers or meters. The
+ * default is Kilometers.
+ */
+export type LlaVec3<A = Degrees, D = Kilometers> = {
+  lat: A;
+  lon: A;
+  alt: D;
+};
+
+/**
+ * Represents a three-dimensional vector in Range, Azimuth, and Elevation (RAE)
+ * coordinates.
+ *
+ * This type is used to represent a point in space in terms of range, azimuth,
+ * and elevation. It is a generic type that allows for flexibility in the units
+ * of measure used for each dimension.
+ * @template DistanceUnit The unit of measure used for the altitude dimension.
+ * This is typically a type representing a distance, such as kilometers or
+ * meters. The default is Kilometers.
+ * @template AngleUnit The unit of measure used for the latitude and longitude
+ * dimensions. This is typically a type representing an angle, such as degrees
+ * or radians. The default is Radians.
+ * rng The range dimension of the vector, representing the distance
+ * from the origin to the point.
+ * az The azimuth dimension of the vector, representing the angle in
+ * the horizontal plane from a reference direction. @property el The elevation
+ * dimension of the vector, representing the angle from the horizontal plane to
+ * the point.
+ */
+export type RaeVec3<DistanceUnit = Kilometers, AngleUnit = Degrees> = {
+  rng: DistanceUnit;
+  az: AngleUnit;
+  el: AngleUnit;
+};
+
+/**
+ * Represents a three-dimensional vector in South, East, and Zenith (SEZ)
+ * coordinates.
+ *
+ * This type is used to represent a point in space in terms of south, east, and
+ * zenith. It is a generic type that allows for flexibility in the units of
+ * measure used for each dimension.
+ * s The south dimension of the vector
+ * e The east dimension of the vector @property z The zenith dimension
+ * of the vector
+ */
+export type SezVec3<D = Kilometers> = {
+  s: D;
+  e: D;
+  z: D;
+};
+
+/**
+ * SatelliteRecord contains all of the orbital parameters necessary for running SGP4. It is generated by Sgp4.
+ */
+export interface SatelliteRecord {
+  Om: number;
+  PInco: number;
+  a: number;
+  alta: number;
+  altp: number;
+  am: number;
+  argpdot: number;
+  argpo: number;
+  atime: number;
+  aycof: number;
+  bstar: number;
+  cc1: number;
+  cc4: number;
+  cc5: number;
+  con41: number;
+  d2: number;
+  d2201: number;
+  d2211: number;
+  d3: number;
+  d3210: number;
+  d3222: number;
+  d4: number;
+  d4410: number;
+  d4422: number;
+  d5220: number;
+  d5232: number;
+  d5421: number;
+  d5433: number;
+  dedt: number;
+  del1: number;
+  del2: number;
+  del3: number;
+  delmo: number;
+  didt: number;
+  dmdt: number;
+  dnodt: number;
+  domdt: number;
+  e3: number;
+  ecco: number;
+  ee2: number;
+  em: number;
+  epochdays: number;
+  epochyr: number;
+  error: Sgp4ErrorCode;
+  eta: number;
+  gsto: number;
+  im: number;
+  inclo: number;
+  init: boolean;
+  irez: number;
+  /** is imprecise flag */
+  isimp: boolean;
+  j2: number;
+  j3: number;
+  j3oj2: number;
+  j4: number;
+  jdsatepoch: number;
+  mdot: number;
+  method: string;
+  mm: number;
+  mo: number;
+  mus: number;
+  nddot: number;
+  ndot: number;
+  nm: number;
+  no: number;
+  nodecf: number;
+  nodedot: number;
+  nodeo: number;
+  om: number;
+  omgcof: number;
+  operationmode: string;
+  peo: number;
+  pgho: number;
+  pho: number;
+  plo: number;
+  radiusearthkm: number;
+  satnum: string;
+  se2: number;
+  se3: number;
+  sgh2: number;
+  sgh3: number;
+  sgh4: number;
+  sh2: number;
+  sh3: number;
+  si2: number;
+  si3: number;
+  sinmao: number;
+  sl2: number;
+  sl3: number;
+  sl4: number;
+  t: number;
+  t2cof: number;
+  t3cof: number;
+  t4cof: number;
+  t5cof: number;
+  tumin: number;
+  vkmpersec: number;
+  x1mth2: number;
+  x7thm1: number;
+  xfact: number;
+  xgh2: number;
+  xgh3: number;
+  xgh4: number;
+  xh2: number;
+  xh3: number;
+  xi2: number;
+  xi3: number;
+  xke: number;
+  xl2: number;
+  xl3: number;
+  xl4: number;
+  xlamo: number;
+  xlcof: number;
+  xli: number;
+  xmcof: number;
+  xni: number;
+  zmol: number;
+  zmos: number;
+}
+
+/**
+ * The StateVector is a type that represents the output from the Sgp4.propagate
+ * function. It consists of two main properties: position and velocity, each of
+ * which is a three-dimensional vector.
+ *
+ * The position and velocity vectors are represented as objects with x, y, and z
+ * properties, each of which is a number. Alternatively, they can be a boolean
+ * value.
+ *
+ * This type is primarily used in the context of satellite tracking and
+ * prediction, where it is crucial to know both the current position and
+ * velocity of a satellite.
+ */
+export type StateVectorSgp4 = {
+  position:
+  | {
+    x: Kilometers;
+    y: Kilometers;
+    z: Kilometers;
+  }
+  | false;
+  velocity:
+  | {
+    x: KilometersPerSecond;
+    y: KilometersPerSecond;
+    z: KilometersPerSecond;
+  }
+  | false;
+};
+
+export type PosVel<T = Kilometers, T2 = KilometersPerSecond> = {
+  position: Vec3<T>;
+  velocity: Vec3<T2>;
+};
+
+/**
+ * A type that represents a three-dimensional vector in a flat array format.
+ * This type is used in vector mathematics and physics calculations.
+ *
+ * It is an array of three numbers, where each number represents a coordinate in
+ * 3D space:
+ * - The first number represents the x-coordinate.
+ * - The second number represents the y-coordinate.
+ * - The third number represents the z-coordinate.
+ *
+ * This format is particularly useful in scenarios where you need to perform
+ * operations on vectors, such as addition, subtraction, scalar multiplication,
+ * dot product, and cross product.
+ */
+export type Vec3Flat<T = number> = [T, T, T];
+
+/**
+ * A type that represents a two-line element set (TLE). A TLE is a data format
+ * used to convey sets of orbital elements that describe the orbits of
+ * Earth-orbiting objects. It consists of two lines of text, each of which is 69
+ * characters long.
+ * @see https://en.wikipedia.org/wiki/Two-line_element_set
+ */
+export type TleLine1 = Distinct<string, 'TLE Line 1'>;
+
+/**
+ * A type that represents a two-line element set (TLE). A TLE is a data format
+ * used to convey sets of orbital elements that describe the orbits of
+ * Earth-orbiting objects. It consists of two lines of text, each of which is 69
+ * characters long.
+ * @see https://en.wikipedia.org/wiki/Two-line_element_set
+ */
+export type TleLine2 = Distinct<string, 'TLE Line 2'>;
+
+/**
+ * The Line1Data type represents the first line of a two-line element set (TLE).
+ * A TLE is a data format used to convey sets of orbital elements that describe
+ * the orbits of Earth-orbiting objects.
+ *
+ * The properties of this type include:
+ * - lineNumber1: The line number of the TLE (should be 1 for this line).
+ * - satNum: The satellite number.
+ * - satNumRaw: The raw string representation of the satellite number.
+ * - classification: The classification of the satellite (e.g., "U" for
+ * unclassified).
+ * - intlDes: The international designator for the satellite.
+ * - intlDesYear: The year of the international designator.
+ * - intlDesLaunchNum: The launch number of the international designator.
+ * - intlDesLaunchPiece: The piece of the launch of the international
+ * designator.
+ * - epochYear: The last two digits of the year of the epoch.
+ * - epochYearFull: The full four-digit year of the epoch.
+ * - epochDay: The day of the year of the epoch.
+ * - meanMoDev1: The first derivative of the Mean Motion.
+ * - meanMoDev2: The second derivative of the Mean Motion.
+ * - bstar: The BSTAR drag term.
+ * - ephemerisType: The type of ephemeris used.
+ * - elsetNum: The element set number.
+ * - checksum1: The checksum of the first line of the TLE.
+ * @see https://en.wikipedia.org/wiki/Two-line_element_set
+ */
+export type Line1Data = {
+  lineNumber1: number;
+  satNum: number;
+  satNumRaw: string;
+  classification: string;
+  intlDes: string;
+  intlDesYear: number;
+  intlDesLaunchNum: number;
+  intlDesLaunchPiece: string;
+  epochYear: number;
+  epochYearFull: number;
+  epochDay: number;
+  meanMoDev1: number;
+  meanMoDev2: number;
+  bstar: number;
+  ephemerisType: number;
+  elsetNum: number;
+  checksum1: number;
+};
+
+/**
+ * The Line2Data type represents the second line of a two-line element set
+ * (TLE). A TLE is a data format used to convey sets of orbital elements that
+ * describe the orbits of Earth-orbiting objects.
+ *
+ * The properties of this type include:
+ * - lineNumber2: The line number of the TLE (should be 2 for this line).
+ * - satNum: The satellite number.
+ * - satNumRaw: The raw string representation of the satellite number.
+ * - inclination: The inclination of the satellite's orbit.
+ * - rightAscension: The Right Ascension of the Ascending Node.
+ * - eccentricity: The eccentricity of the satellite's orbit.
+ * - argOfPerigee: The argument of perigee.
+ * - meanAnomaly: The mean anomaly of the satellite.
+ * - meanMotion: The mean motion of the satellite.
+ * - revNum: The revolution number at epoch.
+ * - checksum2: The checksum of the second line of the TLE.
+ * - period: The period of the satellite's orbit, derived from the mean motion.
+ * @see https://en.wikipedia.org/wiki/Two-line_element_set
+ */
+export type Line2Data = {
+  lineNumber2: number;
+  satNum: number;
+  satNumRaw: string;
+  inclination: Degrees;
+  rightAscension: Degrees;
+  eccentricity: number;
+  argOfPerigee: Degrees;
+  meanAnomaly: Degrees;
+  meanMotion: number;
+  revNum: number;
+  checksum2: number;
+  period: Minutes;
+};
+
+/**
+ * Enum representing different types of objects.
+ */
+export enum SpaceObjectType {
+  UNKNOWN = 0,
+  PAYLOAD = 1,
+  ROCKET_BODY = 2,
+  DEBRIS = 3,
+  SPECIAL = 4,
+  BALLISTIC_MISSILE = 8,
+  STAR = 9,
+  INTERGOVERNMENTAL_ORGANIZATION = 10,
+  SUBORBITAL_PAYLOAD_OPERATOR = 11,
+  PAYLOAD_OWNER = 12,
+  METEOROLOGICAL_ROCKET_LAUNCH_AGENCY_OR_MANUFACTURER = 13,
+  PAYLOAD_MANUFACTURER = 14,
+  LAUNCH_AGENCY = 15,
+  LAUNCH_SITE = 16,
+  LAUNCH_POSITION = 17,
+  LAUNCH_FACILITY = 18,
+  CONTROL_FACILITY = 19,
+  GROUND_SENSOR_STATION = 20,
+  OPTICAL = 21,
+  MECHANICAL = 22,
+  PHASED_ARRAY_RADAR = 23,
+  OBSERVER = 24,
+  BISTATIC_RADIO_TELESCOPE = 25,
+  COUNTRY = 26,
+  LAUNCH_VEHICLE_MANUFACTURER = 27,
+  ENGINE_MANUFACTURER = 28,
+  NOTIONAL = 29,
+  FRAGMENT = 30,
+  SHORT_TERM_FENCE = 31,
+  MAX_SPACE_OBJECT_TYPE = 32,
+}
+
+/**
+ * Represents the Greenwich Mean Sidereal Time (GMST).
+ *
+ * GMST is a time system that is a measure of the angle, on the celestial
+ * equator, from the Greenwich meridian to the meridian that passes through the
+ * vernal equinox.
+ */
+export type GreenwichMeanSiderealTime = Distinct<number, 'Greenwich Mean Sidereal Time'>;
+
+/**
+ * Represents the azimuth and elevation of an object in the sky. Azimuth and
+ * elevation are the two coordinates that define the position of a celestial
+ * body (sun, moon, planet, star, etc.) in the sky as observed from a specific
+ * location on the Earth's surface.
+ * @template Units The units in which the azimuth and elevation are expressed.
+ * By default, this is radians.
+ * az The azimuth of the object. This is the angle between the
+ * observer's north vector and the perpendicular projection of the object onto
+ * the observer's local horizon.
+ * el The elevation of the object. This is the angle between the
+ * object and the observer's local horizon.
+ */
+export type AzEl<Units = Radians> = {
+  az: Units;
+  el: Units;
+};
+
+/**
+ * Represents the coordinates of a celestial object in Right Ascension (RA) and
+ * Declination (Dec).
+ */
+export type RaDec = {
+  dec: Radians;
+  ra: Radians;
+  dist: Kilometers;
+};
+
+/**
+ * Represents the solar noon and nadir times.
+ * solarNoon The time at which the sun is at its highest point in the
+ * sky (directly above the observer's head). This is the midpoint of the day.
+ * nadir The time at which the sun is at its lowest point, directly
+ * below the observer. This is the midpoint of the night.
+ */
+export type SunTime = {
+  solarNoon: Date;
+  nadir: Date;
+  goldenHourDuskStart: Date;
+  goldenHourDawnEnd: Date;
+  sunsetStart: Date;
+  sunriseEnd: Date;
+  sunsetEnd: Date;
+  sunriseStart: Date;
+  goldenHourDuskEnd: Date;
+  goldenHourDawnStart: Date;
+  blueHourDuskStart: Date;
+  blueHourDawnEnd: Date;
+  civilDusk: Date;
+  civilDawn: Date;
+  blueHourDuskEnd: Date;
+  blueHourDawnStart: Date;
+  nauticalDusk: Date;
+  nauticalDawn: Date;
+  amateurDusk: Date;
+  amateurDawn: Date;
+  astronomicalDusk: Date;
+  astronomicalDawn: Date;
+};
+
+export type LaunchDetails = {
+  launchDate?: string;
+  launchMass?: string;
+  launchSite?: string;
+  launchVehicle?: string;
+  launchPad?: string;
+};
+
+export type SpaceCraftDetails = {
+  lifetime?: string | number;
+  maneuver?: string;
+  manufacturer?: string;
+  motor?: string;
+  power?: string;
+  payload?: string;
+  purpose?: string;
+  shape?: string;
+  span?: string;
+  bus?: string;
+  configuration?: string;
+  equipment?: string;
+  dryMass?: string;
+};
+
+export type OperationsDetails = {
+  user?: string;
+  mission?: string;
+  owner?: string;
+  country?: string;
+};
+
+export type Lookangle = {
+  type: PassType;
+  time: Date;
+  az: Degrees;
+  el: Degrees;
+  rng: Kilometers;
+  maxElPass?: Degrees;
+};
+/**
+ * Two-line element set data for a satellite.
+ */
+export type TleData = {
+  satNum: number;
+  intlDes: string;
+  epochYear: number;
+  epochDay: number;
+  meanMoDev1: number;
+  meanMoDev2: number;
+  bstar: number;
+  inclination: Degrees;
+  rightAscension: Degrees;
+  eccentricity: number;
+  argOfPerigee: Degrees;
+  meanAnomaly: Degrees;
+  meanMotion: number;
+  period: Minutes;
+};
+/**
+ * Represents a set of data containing both Line 1 and Line 2 TLE information.
+ */
+export type TleDataFull = Line1Data & Line2Data;
+export type StringifiedNumber = `${number}.${number}`;
+
+/**
+ * Represents a set of data containing both Line 1 and Line 2 TLE information.
+ *
+ * TODO: TleParams types should be more consistent.
+ */
+export type TleParams = {
+  sat?: Satellite;
+  inc: string | number;
+  meanmo: string | number;
+  rasc: string | number;
+  argPe: string | number;
+  meana: string | number;
+  ecen: string;
+  epochyr: string;
+  epochday: string;
+  /** COSPAR International Designator */
+  intl: string;
+  /** alpha 5 satellite number */
+  scc: string;
+};
+// / Position and velocity [Vector3D] container.
+
+export type PositionVelocity = {
+  position: Vector3D<Kilometers>;
+  velocity: Vector3D<KilometersPerSecond>;
+};
+
 
 export enum ZoomValue {
   LEO = 0.45,