test: ✅ add tests for geodetic class

src/coordinate/Geodetic.ts

@@ -1,74 +1,173 @@
 import { Earth } from '../body/Earth';
-import { AngularDistanceMethod } from '../main';
+import { AngularDistanceMethod, Degrees, GroundObject, Kilometers, Radians } from '../main';
 import { Vector3D } from '../operations/Vector3D';
 import { EpochUTC } from '../time/EpochUTC';
 import { DEG2RAD, RAD2DEG } from '../utils/constants';
 import { angularDistance } from '../utils/functions';
 import { ITRF } from './ITRF';
 
-// / Geodetic coordinates.
+/**
+ * This Geodetic class represents a geodetic coordinate in three-dimensional
+ * space, consisting of latitude, longitude, and altitude. It provides various
+ * methods to perform calculations and operations related to geodetic
+ * coordinates.
+ *
+ * This is a class for geodetic coordinates. This is related to the GroundObject
+ * class, which is used to represent an object on the surface of the Earth.
+ */
 export class Geodetic {
-  latitude: number;
-  longitude: number;
-  altitude: number;
-
-  constructor(latitude: number, longitude: number, altitude: number) {
-    this.latitude = latitude;
-    this.longitude = longitude;
-    this.altitude = altitude;
+  lat: Radians;
+  lon: Radians;
+  alt: Kilometers;
+
+  constructor(latitude: Radians, longitude: Radians, altitude: Kilometers) {
+    if (Math.abs(latitude) > Math.PI / 2) {
+      // eslint-disable-next-line no-console
+      console.warn(longitude * RAD2DEG);
+      throw new RangeError('Latitude must be between -90° and 90° in Radians.');
+    }
+
+    if (Math.abs(longitude) > Math.PI) {
+      // eslint-disable-next-line no-console
+      console.warn(longitude * RAD2DEG);
+      throw new RangeError('Longitude must be between -180° and 180° in Radians.');
+    }
+
+    if (altitude < -Earth.radiusMean) {
+      throw new RangeError('Altitude cannot be less than -6378.137 km.');
+    }
+
+    this.lat = latitude;
+    this.lon = longitude;
+    this.alt = altitude;
   }
 
-  static fromDegrees(latDeg: number, lonDeg: number, alt: number): Geodetic {
-    return new Geodetic(latDeg * DEG2RAD, lonDeg * DEG2RAD, alt);
+  /**
+   * Creates a Geodetic object from latitude, longitude, and altitude values in
+   * degrees.
+   * @param latitude The latitude value in degrees.
+   *
+   * @param longitude The longitude value in degrees.
+   *
+   * @param altitude The altitude value in kilometers.
+   *
+   * @returns A Geodetic object representing the specified latitude, longitude,
+   * and altitude.
+   */
+  static fromDegrees(latitude: Degrees, longitude: Degrees, altitude: Kilometers): Geodetic {
+    return new Geodetic((latitude * DEG2RAD) as Radians, (longitude * DEG2RAD) as Radians, altitude);
   }
 
+  /**
+   * Returns a string representation of the Geodetic object.
+   *
+   * @returns A string containing the latitude, longitude, and altitude of the
+   * Geodetic object.
+   */
   toString(): string {
     return [
       'Geodetic',
-      `  Latitude:  ${this.latitudeDegrees.toFixed(4)}°`,
-      `  Longitude: ${this.longitudeDegrees.toFixed(4)}°`,
-      `  Altitude:  ${this.altitude.toFixed(3)} km`,
+      `  Latitude:  ${this.latDeg.toFixed(4)}°`,
+      `  Longitude: ${this.lonDeg.toFixed(4)}°`,
+      `  Altitude:  ${this.alt.toFixed(3)} km`,
     ].join('\n');
   }
 
-  get latitudeDegrees(): number {
-    return this.latitude * RAD2DEG;
+  /**
+   * Gets the latitude in degrees.
+   * @returns The latitude in degrees.
+   */
+  get latDeg(): number {
+    return this.lat * RAD2DEG;
+  }
+
+  /**
+   * Gets the longitude in degrees.
+   * @returns The longitude in degrees.
+   */
+  get lonDeg(): number {
+    return this.lon * RAD2DEG;
   }
 
-  get longitudeDegrees(): number {
-    return this.longitude * RAD2DEG;
+  /**
+   * Converts the geodetic coordinates to a ground position.
+   * @returns The ground position object.
+   */
+  toGroundObject(): GroundObject {
+    return new GroundObject({
+      lat: this.latDeg as Degrees,
+      lon: this.lonDeg as Degrees,
+      alt: this.alt,
+    });
   }
 
+  /**
+   * Converts the geodetic coordinates to the International Terrestrial
+   * Reference Frame (ITRF) coordinates.
+   * @param epoch The epoch in UTC. @returns The ITRF coordinates.
+   */
   toITRF(epoch: EpochUTC): ITRF {
-    const sLat = Math.sin(this.latitude);
-    const cLat = Math.cos(this.latitude);
+    const sLat = Math.sin(this.lat);
+    const cLat = Math.cos(this.lat);
     const nVal = Earth.radiusEquator / Math.sqrt(1 - Earth.eccentricitySquared * sLat * sLat);
     const r = new Vector3D(
-      (nVal + this.altitude) * cLat * Math.cos(this.longitude),
-      (nVal + this.altitude) * cLat * Math.sin(this.longitude),
-      (nVal * (1 - Earth.eccentricitySquared) + this.altitude) * sLat,
+      (nVal + this.alt) * cLat * Math.cos(this.lon),
+      (nVal + this.alt) * cLat * Math.sin(this.lon),
+      (nVal * (1 - Earth.eccentricitySquared) + this.alt) * sLat,
     );
 
     return new ITRF(epoch, r, Vector3D.origin);
   }
 
-  angle(g: Geodetic, method: AngularDistanceMethod = AngularDistanceMethod.Haversine): number {
-    return angularDistance(this.longitude, this.latitude, g.longitude, g.latitude, method);
+  /**
+   * Calculates the angle between two geodetic coordinates.
+   * @param g The geodetic coordinate to calculate the angle to. @param method
+   * The method to use for calculating the angular distance (optional, default
+   * is Haversine). @returns The angle between the two geodetic coordinates in
+   * radians.
+   */
+  angle(g: Geodetic, method: AngularDistanceMethod = AngularDistanceMethod.Haversine): Radians {
+    return angularDistance(this.lon, this.lat, g.lon, g.lat, method) as Radians;
   }
 
-  angleDegrees(g: Geodetic, method: AngularDistanceMethod = AngularDistanceMethod.Haversine): number {
-    return this.angle(g, method) * RAD2DEG;
+  /**
+   * Calculates the angle in degrees between two Geodetic coordinates.
+   * @param g The Geodetic coordinate to calculate the angle with. @param method
+   * The method to use for calculating the angular distance (optional, default
+   * is Haversine). @returns The angle in degrees.
+   */
+  angleDeg(g: Geodetic, method: AngularDistanceMethod = AngularDistanceMethod.Haversine): Degrees {
+    return (this.angle(g, method) * RAD2DEG) as Degrees;
   }
 
-  distance(g: Geodetic, method: AngularDistanceMethod = AngularDistanceMethod.Haversine): number {
-    return this.angle(g, method) * Earth.radiusMean;
+  /**
+   * Calculates the distance between two geodetic coordinates.
+   * @param g The geodetic coordinates to calculate the distance to. @param
+   * method The method to use for calculating the angular distance. Default is
+   * Haversine. @returns The distance between the two geodetic coordinates in
+   * kilometers.
+   */
+  distance(g: Geodetic, method: AngularDistanceMethod = AngularDistanceMethod.Haversine): Kilometers {
+    return (this.angle(g, method) * Earth.radiusMean) as Kilometers;
   }
 
-  fieldOfView(): number {
-    return Math.acos(Earth.radiusMean / (Earth.radiusMean + this.altitude));
+  /**
+   * Calculates the field of view based on the altitude of the Geodetic object.
+   * @returns The field of view in radians.
+   */
+  fieldOfView(): Radians {
+    return Math.acos(Earth.radiusMean / (Earth.radiusMean + this.alt)) as Radians;
   }
 
-  sight(g: Geodetic, method: AngularDistanceMethod = AngularDistanceMethod.Haversine): boolean {
+  /**
+   * Determines if the current geodetic coordinate can see another geodetic
+   * coordinate.
+   * @param g The geodetic coordinate to check for visibility. @param method The
+   * method to use for calculating the angular distance (optional, default is
+   * Haversine). @returns A boolean indicating if the current coordinate can see
+   * the other coordinate.
+   */
+  isInView(g: Geodetic, method: AngularDistanceMethod = AngularDistanceMethod.Haversine): boolean {
     const fov = Math.max(this.fieldOfView(), g.fieldOfView());
 
     return this.angle(g, method) <= fov;

src/coordinate/ITRF.ts

@@ -1,4 +1,5 @@
 /* eslint-disable class-methods-use-this */
+import { Kilometers, Radians } from 'src/main';
 import { Earth } from '../body/Earth';
 import { Geodetic } from './Geodetic';
 import { J2000 } from './J2000';
@@ -7,20 +8,19 @@ import { StateVector } from './StateVector';
 /**
  * The International Terrestrial Reference Frame (ITRF) is a geocentric
  * reference frame for the Earth. It is the successor to the International
- * Terrestrial Reference System (ITRS). The ITRF definition is maintained by
- * the International Earth Rotation and Reference Systems Service (IERS).
- * Several versions of ITRF exist, each with a different epoch, to address the
- * issue of crustal motion. The latest version is ITRF2014, based on data
- * collected from 1980 to 2014.
+ * Terrestrial Reference System (ITRS). The ITRF definition is maintained by the
+ * International Earth Rotation and Reference Systems Service (IERS). Several
+ * versions of ITRF exist, each with a different epoch, to address the issue of
+ * crustal motion. The latest version is ITRF2014, based on data collected from
+ * 1980 to 2014.
  * @see https://en.wikipedia.org/wiki/International_Terrestrial_Reference_Frame
  *
  * This is a geocentric coordinate system, also referenced as ECEF (Earth
- * Centered Earth Fixed). It is a Cartesian coordinate system with the origin
- * at the center of the Earth. The x-axis intersects the sphere of the Earth
- * at 0° latitude (the equator) and 0° longitude (the Prime Meridian). The
- * z-axis goes through the North Pole. The y-axis goes through 90° East
- * longitude.
- * @see https://en.wikipedia.org/wiki/Earth-centered,_Earth-fixed_coordinate_system
+ * Centered Earth Fixed). It is a Cartesian coordinate system with the origin at
+ * the center of the Earth. The x-axis intersects the sphere of the Earth at 0°
+ * latitude (the equator) and 0° longitude (the Prime Meridian). The z-axis goes
+ * through the North Pole. The y-axis goes through 90° East longitude. @see
+ * https://en.wikipedia.org/wiki/Earth-centered,_Earth-fixed_coordinate_system
  */
 export class ITRF extends StateVector {
   get name(): string {
@@ -92,7 +92,7 @@ export class ITRF extends StateVector {
     }
     const alt = r / Math.cos(lat) - sma * c;
 
-    return new Geodetic(lat, lon, alt);
+    return new Geodetic(lat as Radians, lon as Radians, alt as Kilometers);
   }
 
   /**

src/objects/GroundObject.ts

@@ -0,0 +1,141 @@
+import {
+  GroundPositionParams,
+  Degrees,
+  EcfVec3,
+  EciVec3,
+  Kilometers,
+  LlaVec3,
+  Radians,
+  RaeVec3,
+  calcGmst,
+  lla2eci,
+  llaRad2ecf,
+  DEG2RAD,
+  Geodetic,
+} from '../main';
+
+import { BaseObject } from './BaseObject';
+import { Satellite } from './Satellite';
+
+export class GroundObject extends BaseObject {
+  name = 'Unknown Ground Position';
+  lat: Degrees;
+  lon: Degrees;
+  alt: Kilometers;
+
+  constructor(info: GroundPositionParams) {
+    super(info);
+
+    this.validateInputData_(info);
+    this.lat = info.lat;
+    this.lon = info.lon;
+    this.alt = info.alt;
+  }
+
+  /**
+   * Calculates the relative azimuth, elevation, and range between this
+   * GroundObject and a Satellite.
+   * @param satellite The Satellite object. @param date The date for which to
+   * calculate the RAE values. Defaults to the current date. @returns The
+   * relative azimuth, elevation, and range values in kilometers and degrees.
+   */
+  rae(satellite: Satellite, date: Date = new Date()): RaeVec3<Kilometers, Degrees> {
+    return satellite.rae(this, date);
+  }
+
+  /**
+   * Calculates ECF position at a given time.
+   *
+   * @optimized version of this.toGeodetic().toITRF().position;
+   */
+  ecf(): EcfVec3<Kilometers> {
+    return llaRad2ecf(this.toGeodetic());
+  }
+
+  /**
+   * Calculates the Earth-Centered Inertial (ECI) position vector of the ground
+   * object at a given date.
+   *
+   * @optimzed version of this.toGeodetic().toITRF().toJ2000().position;
+   *
+   * @param date The date for which to calculate the ECI position vector.
+   * Defaults to the current date.
+   *
+   * @returns The ECI position vector of the ground object.
+   */
+  eci(date: Date = new Date()): EciVec3<Kilometers> {
+    const { gmst } = calcGmst(date);
+
+    return lla2eci(this.toGeodetic(), gmst);
+  }
+
+  /**
+   * Converts the latitude, longitude, and altitude of the GroundObject to
+   * radians and kilometers.
+   *
+   * @optimized version of this.toGeodetic() without class instantiation for
+   * better performance and serialization.
+   *
+   * @returns An object containing the latitude, longitude, and altitude in
+   * radians and kilometers.
+   */
+  llaRad(): LlaVec3<Radians, Kilometers> {
+    return {
+      lat: (this.lat * DEG2RAD) as Radians,
+      lon: (this.lon * DEG2RAD) as Radians,
+      alt: this.alt,
+    };
+  }
+
+  /**
+   * Creates a GroundObject object from a Geodetic position.
+   *
+   * @param geodetic The geodetic coordinates.
+   * @returns A new GroundObject object.
+   */
+  static fromGeodetic(geodetic: Geodetic): GroundObject {
+    return new GroundObject({
+      lat: geodetic.latDeg as Degrees,
+      lon: geodetic.lonDeg as Degrees,
+      alt: geodetic.alt,
+    });
+  }
+
+  /**
+   * Converts the ground position to geodetic coordinates.
+   * @returns The geodetic coordinates.
+   */
+  toGeodetic(): Geodetic {
+    return Geodetic.fromDegrees(this.lat, this.lon, this.alt);
+  }
+
+  /**
+   * Validates the input data for the GroundObject.
+   * @param info - The GroundPositionParams object containing the latitude,
+   * longitude, and altitude. @returns void
+   */
+  private validateInputData_(info: GroundPositionParams) {
+    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');
+  }
+
+  /**
+   * Validates a parameter value against a minimum and maximum value.
+   * @template T - The type of the parameter value. @param value - The parameter
+   * value to validate. @param minValue - The minimum allowed value. If not
+   * provided, no minimum value check will be performed. @param maxValue - The
+   * maximum allowed value. If not provided, no maximum value check will be
+   * performed. @param errorMessage - The error message to throw if the value is
+   * outside the allowed range. @throws {Error} - Throws an error with the
+   * specified error message if the value is outside the allowed range.
+   */
+  private validateParameter_<T>(value: T, minValue: T, maxValue: T, errorMessage: string): void {
+    if (minValue && value < minValue) {
+      throw new Error(errorMessage);
+    }
+    if (maxValue && value > maxValue) {
+      throw new Error(errorMessage);
+    }
+  }
+}