ootk 4.0.8 → 5.0.0

package/dist/coordinate/Tle.d.ts

@@ -0,0 +1,430 @@
+/**
+ * @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 { ClassicalElements, TEME } from './index.js';
+import { Sgp4OpsMode } from '../enums/Sgp4OpsMode.js';
+import { Satellite } from '../main.js';
+import { Sgp4GravConstants } from '../sgp4/sgp4.js';
+import { EpochUTC } from '../time/EpochUTC.js';
+import { Degrees, Line1Data, Line2Data, Minutes, TleData, TleDataFull, TleLine1, TleLine2 } from '../types/types.js';
+/**
+ * Tle is a static class with a collection of methods for working with TLEs.
+ */
+export declare class Tle {
+    line1: string;
+    line2: string;
+    epoch: EpochUTC;
+    satnum: number;
+    private readonly satrec_;
+    /**
+     * Mapping of alphabets to their corresponding numeric values.
+     */
+    private static readonly alpha5_;
+    /** The argument of perigee field. */
+    private static readonly argPerigee_;
+    /** The BSTAR drag term field. */
+    private static readonly bstar_;
+    /** The checksum field. */
+    private static readonly checksum_;
+    /** The classification field. */
+    private static readonly classification_;
+    /** The eccentricity field. */
+    private static readonly eccentricity_;
+    /** The element set number field. */
+    private static readonly elsetNum_;
+    /** The ephemeris type field. */
+    private static readonly ephemerisType_;
+    /** The epoch day field. */
+    private static readonly epochDay_;
+    /** The epoch year field. */
+    private static readonly epochYear_;
+    /** The inclination field. */
+    private static readonly inclination_;
+    /** The international designator launch number field. */
+    private static readonly intlDesLaunchNum_;
+    /** The international designator launch piece field. */
+    private static readonly intlDesLaunchPiece_;
+    /** The international designator year field. */
+    private static readonly intlDesYear_;
+    /** The line number field. */
+    private static readonly lineNumber_;
+    /** The mean anomaly field. */
+    private static readonly meanAnom_;
+    /** The first derivative of the mean motion field. */
+    private static readonly meanMoDev1_;
+    /** The second derivative of the mean motion field. */
+    private static readonly meanMoDev2_;
+    /** The mean motion field. */
+    private static readonly meanMo_;
+    /** The right ascension of the ascending node field. */
+    private static readonly rightAscension_;
+    /** The revolution number field. */
+    private static readonly revNum_;
+    /** The satellite number field. */
+    private static readonly satNum_;
+    constructor(line1: string, line2: string, opsMode?: Sgp4OpsMode, gravConst?: Sgp4GravConstants);
+    toString(): string;
+    /**
+     * Gets the semimajor axis of the TLE.
+     * @returns The semimajor axis value.
+     */
+    get semimajorAxis(): number;
+    /**
+     * Gets the eccentricity of the TLE.
+     * @returns The eccentricity value.
+     */
+    get eccentricity(): number;
+    /**
+     * Gets the inclination of the TLE.
+     * @returns The inclination in degrees.
+     */
+    get inclination(): number;
+    /**
+     * Gets the inclination in degrees.
+     * @returns The inclination in degrees.
+     */
+    get inclinationDegrees(): number;
+    /**
+     * Gets the apogee of the TLE (Two-Line Elements) object.
+     * Apogee is the point in an orbit that is farthest from the Earth.
+     * It is calculated as the product of the semimajor axis and (1 + eccentricity).
+     * @returns The apogee value.
+     */
+    get apogee(): number;
+    /**
+     * Gets the perigee of the TLE (Two-Line Element Set).
+     * The perigee is the point in the orbit of a satellite or other celestial body where it is closest to the Earth.
+     * It is calculated as the product of the semimajor axis and the difference between 1 and the eccentricity.
+     * @returns The perigee value.
+     */
+    get perigee(): number;
+    /**
+     * Gets the period of the TLE in minutes.
+     * @returns The period of the TLE in minutes.
+     */
+    get period(): Minutes;
+    /**
+     * Parses the epoch string and returns the corresponding EpochUTC object.
+     * @param epochStr - The epoch string to parse.
+     * @returns The parsed EpochUTC object.
+     */
+    private static parseEpoch_;
+    static calcElsetAge(sat: Satellite, nowInput?: Date, outputUnits?: 'days' | 'hours' | 'minutes' | 'seconds'): number;
+    /**
+     * Propagates the TLE (Two-Line Element Set) to a specific epoch and returns the TEME (True Equator Mean Equinox)
+     * coordinates.
+     * @param epoch The epoch to propagate the TLE to.
+     * @returns The TEME coordinates at the specified epoch.
+     * @throws Error if propagation fails.
+     */
+    propagate(epoch: EpochUTC): TEME;
+    /**
+     * Converts the state vector to position and velocity arrays.
+     * @param stateVector - The state vector containing position and velocity information.
+     * @param r - The array to store the position values.
+     * @param v - The array to store the velocity values.
+     */
+    private static sv2rv_;
+    /**
+     * Returns the current state of the satellite in the TEME coordinate system.
+     * @returns The current state of the satellite.
+     */
+    private currentState_;
+    /**
+     * Gets the state of the TLE in the TEME coordinate system.
+     * @returns The state of the TLE in the TEME coordinate system.
+     */
+    get state(): TEME;
+    /**
+     * Calculates the Semi-Major Axis (SMA) from the second line of a TLE.
+     * @param line2 The second line of the TLE.
+     * @returns The Semi-Major Axis (SMA) in kilometers.
+     */
+    private static tleSma_;
+    /**
+     * Parses the eccentricity value from the second line of a TLE.
+     * @param line2 The second line of the TLE.
+     * @returns The eccentricity value.
+     */
+    private static tleEcc_;
+    /**
+     * Calculates the inclination angle from the second line of a TLE.
+     * @param line2 The second line of the TLE.
+     * @returns The inclination angle in radians.
+     */
+    private static tleInc_;
+    /**
+     * Creates a TLE (Two-Line Element) object from classical orbital elements.
+     * @param elements - The classical orbital elements.
+     * @returns A TLE object.
+     */
+    static fromClassicalElements(elements: ClassicalElements): Tle;
+    /**
+     * Argument of perigee.
+     * @see https://en.wikipedia.org/wiki/Argument_of_perigee
+     * @example 69.9862
+     * @param tleLine2 The second line of the Tle to parse.
+     * @returns The argument of perigee in degrees (0 to 360).
+     */
+    static argOfPerigee(tleLine2: TleLine2): Degrees;
+    /**
+     * BSTAR drag term (decimal point assumed).  Estimates the effects of atmospheric drag on the satellite's motion.
+     * @see https://en.wikipedia.org/wiki/BSTAR
+     * @example 0.000036771
+     * @description ('36771-4' in the original Tle or 0.36771 * 10 ^ -4)
+     * @param tleLine1 The first line of the Tle to parse.
+     * @returns The drag coefficient.
+     */
+    static bstar(tleLine1: TleLine1): number;
+    /**
+     * Tle line 1 checksum (modulo 10), for verifying the integrity of this line of the Tle.
+     * @example 3
+     * @param tleLine The first line of the Tle to parse.
+     * @returns The checksum value (0 to 9)
+     */
+    static checksum(tleLine: TleLine1 | TleLine2): number;
+    /**
+     * Returns the satellite classification.
+     * Some websites like https://KeepTrack.space and Celestrak.org will embed
+     * information in this field about the source of the Tle.
+     * @example 'U'
+     * unclassified
+     * @example 'C'
+     * confidential
+     * @example 'S'
+     * secret
+     * @param tleLine1 The first line of the Tle to parse.
+     * @returns The satellite classification.
+     */
+    static classification(tleLine1: TleLine1): string;
+    /**
+     * Orbital eccentricity, decimal point assumed. All artificial Earth satellites have an eccentricity between 0
+     * (perfect circle) and 1 (parabolic orbit).
+     * @example 0.0006317
+     * (`0006317` in the original Tle)
+     * @param tleLine2 The second line of the Tle to parse.
+     * @returns The eccentricity of the satellite (0 to 1)
+     */
+    static eccentricity(tleLine2: TleLine2): number;
+    /**
+     * Tle element set number, incremented for each new Tle generated.
+     * @see https://en.wikipedia.org/wiki/Two-line_element_set
+     * @example 999
+     * @param tleLine1 The first line of the Tle to parse.
+     * @returns The element number (1 to 999)
+     */
+    static elsetNum(tleLine1: TleLine1): number;
+    /**
+     * Private value - used by United States Space Force to reference the orbit model used to generate the Tle. Will
+     * always be seen as zero externally (e.g. by "us", unless you are "them" - in which case, hello!).
+     *
+     * Starting in 2024, this may contain a 4 if the Tle was generated using the new SGP4-XP model. Until the source code
+     * is released, there is no way to support that format in JavaScript or TypeScript.
+     * @example 0
+     * @param tleLine1 The first line of the Tle to parse.
+     * @returns The ephemeris type.
+     */
+    static ephemerisType(tleLine1: TleLine1): 0;
+    /**
+     * Fractional day of the year when the Tle was generated (Tle epoch).
+     * @example 206.18396726
+     * @param tleLine1 The first line of the Tle to parse.
+     * @returns The day of the year the Tle was generated. (1 to 365.99999999)
+     */
+    static epochDay(tleLine1: string): number;
+    /**
+     * Year when the Tle was generated (Tle epoch), last two digits.
+     * @example 17
+     * @param tleLine1 The first line of the Tle to parse.
+     * @returns The year the Tle was generated. (0 to 99)
+     */
+    static epochYear(tleLine1: TleLine1): number;
+    /**
+     * Year when the Tle was generated (Tle epoch), four digits.
+     * @example 2008
+     * @param tleLine1 The first line of the Tle to parse.
+     * @returns The year the Tle was generated. (1957 to 2056)
+     */
+    static epochYearFull(tleLine1: TleLine1): number;
+    /**
+     * Inclination relative to the Earth's equatorial plane in degrees. 0 to 90 degrees is a prograde orbit and 90 to 180
+     * degrees is a retrograde orbit.
+     * @example 51.6400
+     * @param tleLine2 The second line of the Tle to parse.
+     * @returns The inclination of the satellite. (0 to 180)
+     */
+    static inclination(tleLine2: TleLine2): Degrees;
+    /**
+     * International Designator (COSPAR ID)
+     * @see https://en.wikipedia.org/wiki/International_Designator
+     * @param tleLine1 The first line of the Tle to parse.
+     * @returns The International Designator.
+     */
+    static intlDes(tleLine1: TleLine1): string;
+    /**
+     * International Designator (COSPAR ID): Launch number of the year.
+     * @example 67
+     * @param tleLine1 The first line of the Tle to parse.
+     * @returns The launch number of the International Designator. (1 to 999)
+     */
+    static intlDesLaunchNum(tleLine1: string): number;
+    /**
+     * International Designator  (COSPAR ID): Piece of the launch.
+     * @example 'A'
+     * @param tleLine1 The first line of the Tle to parse.
+     * @returns The launch piece of the International Designator. (A to ZZZ)
+     */
+    static intlDesLaunchPiece(tleLine1: TleLine1): string;
+    /**
+     * International Designator (COSPAR ID): Last 2 digits of launch year.
+     * @example 98
+     * @param tleLine1 The first line of the Tle to parse.
+     * @returns The year of the International Designator. (0 to 99)
+     */
+    static intlDesYear(tleLine1: TleLine1): number;
+    /**
+     * This should always return a 1 or a 2.
+     * @example 1
+     * @param tleLine The first line of the Tle to parse.
+     * @returns The line number of the Tle. (1 or 2)
+     */
+    static lineNumber(tleLine: TleLine1 | TleLine2): 1 | 2;
+    /**
+     * Mean anomaly. Indicates where the satellite was located within its orbit at the time of the Tle epoch.
+     * @see https://en.wikipedia.org/wiki/Mean_Anomaly
+     * @example 25.2906
+     * @param tleLine2 The second line of the Tle to parse.
+     * @returns The mean anomaly of the satellite. (0 to 360)
+     */
+    static meanAnomaly(tleLine2: TleLine2): Degrees;
+    /**
+     * First Time Derivative of the Mean Motion divided by two.  Defines how mean motion changes over time, so Tle
+     * propagators can still be used to make reasonable guesses when times are distant from the original Tle epoch. This
+     * is recorded in units of orbits per day per day.
+     * @example 0.00001961
+     * @param tleLine1 The first line of the Tle to parse.
+     * @returns The first derivative of the mean motion.
+     */
+    static meanMoDev1(tleLine1: TleLine1): number;
+    /**
+     * Second Time Derivative of Mean Motion divided by six (decimal point assumed). Measures rate of change in the Mean
+     * Motion Dot so software can make reasonable guesses when times are distant from the original Tle epoch. Usually
+     * zero, unless the satellite is manuevering or in a decaying orbit. This is recorded in units of orbits per day per
+     * day per day.
+     * @example 0
+     * '00000-0' in the original Tle or 0.00000 * 10 ^ 0
+     * @param tleLine1 The first line of the Tle to parse.
+     * @returns The second derivative of the mean motion.
+     */
+    static meanMoDev2(tleLine1: string): number;
+    /**
+     * Revolutions around the Earth per day (mean motion).
+     * @see https://en.wikipedia.org/wiki/Mean_Motion
+     * @example 15.54225995
+     * @param tleLine2 The second line of the Tle to parse.
+     * @returns The mean motion of the satellite. (0 to 18)
+     */
+    static meanMotion(tleLine2: TleLine2): number;
+    /**
+     * Calculates the period of a satellite orbit based on the given Tle line 2.
+     * @example 92.53035747
+     * @param tleLine2 The Tle line 2.
+     * @returns The period of the satellite orbit in minutes.
+     */
+    static period(tleLine2: TleLine2): Minutes;
+    /**
+     * Right ascension of the ascending node in degrees. Essentially, this is the angle of the satellite as it crosses
+     * northward (ascending) across the Earth's equator (equatorial plane).
+     * @example 208.9163
+     * @param tleLine2 The second line of the Tle to parse.
+     * @returns The right ascension of the satellite. (0 to 360)
+     */
+    static rightAscension(tleLine2: TleLine2): Degrees;
+    /**
+     * NORAD catalog number. To support Alpha-5, the first digit can be a letter. This will NOT be converted to a number.
+     * Use satNum() for that.
+     * @see https://en.wikipedia.org/wiki/Satellite_Catalog_Number
+     * @example 25544
+     * @example B1234
+     * @param tleLine The first line of the Tle to parse.
+     * @returns NORAD catalog number.
+     */
+    static rawSatNum(tleLine: TleLine1 | TleLine2): string;
+    /**
+     * Total satellite revolutions when this Tle was generated. This number rolls over (e.g. 99999 -> 0).
+     * @example 6766
+     * @param tleLine2 The second line of the Tle to parse.
+     * @returns The revolutions around the Earth per day (mean motion). (0 to 99999)
+     */
+    static revNum(tleLine2: TleLine2): number;
+    /**
+     * NORAD catalog number converted to a number.
+     * @see https://en.wikipedia.org/wiki/Satellite_Catalog_Number
+     * @example 25544
+     * @example 111234
+     * @param tleLine The first line of the Tle to parse.
+     * @returns NORAD catalog number. (0 to 339999)
+     */
+    static satNum(tleLine: TleLine1 | TleLine2): number;
+    /**
+     * Parse the first line of the Tle.
+     * @param tleLine1 The first line of the Tle to parse.
+     * @returns Returns the data from the first line of the Tle.
+     */
+    static parseLine1(tleLine1: TleLine1): Line1Data;
+    /**
+     * Parse the second line of the Tle.
+     * @param tleLine2 The second line of the Tle to parse.
+     * @returns Returns the data from the second line of the Tle.
+     */
+    static parseLine2(tleLine2: TleLine2): Line2Data;
+    /**
+     * Parses the Tle into orbital data.
+     *
+     * If you want all of the data then use parseTleFull instead.
+     * @param tleLine1 Tle line 1
+     * @param tleLine2 Tle line 2
+     * @returns Returns most commonly used orbital data from Tle
+     */
+    static parse(tleLine1: TleLine1, tleLine2: TleLine2): TleData;
+    /**
+     * Parses all of the data contained in the Tle.
+     *
+     * If you only want the most commonly used data then use parseTle instead.
+     * @param tleLine1 The first line of the Tle to parse.
+     * @param tleLine2 The second line of the Tle to parse.
+     * @returns Returns all of the data from the Tle.
+     */
+    static parseAll(tleLine1: TleLine1, tleLine2: TleLine2): TleDataFull;
+    /**
+     * Converts a 6 digit SCC number to a 5 digit SCC alpha 5 number
+     * @param sccNum The 6 digit SCC number
+     * @returns The 5 digit SCC alpha 5 number
+     */
+    static convert6DigitToA5(sccNum: string): string;
+    /**
+     * Converts a 5-digit SCC number to a 6-digit SCC number.
+     * @param sccNum - The 5-digit SCC number to convert.
+     * @returns The converted 6-digit SCC number.
+     */
+    static convertA5to6Digit(sccNum: string): string;
+}