/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 Kruczek Labs LLC
*
* Custom error classes for ootk.
*
* Error Handling Convention:
* - ValidationError: Invalid constructor arguments, out-of-range values
* - ParseError: Malformed external data formats (TLE, OEM, Horizons)
* - PropagationError: Unrecoverable propagation failures (use null for expected failures)
* - OrbitDeterminationError: IOD algorithm convergence failures
*
* Methods that may fail for expected reasons (e.g., satellite decay, time outside
* ephemeris window) should return null rather than throwing.
*/
/**
* Base class for all ootk errors.
*
* All custom error classes in ootk extend this base class, allowing
* callers to catch all ootk-specific errors with a single catch block.
*
* @example
* ```typescript
* try {
* const sat = new Satellite({ tle1, tle2 });
* } catch (e) {
* if (e instanceof OotkError) {
* console.log('ootk error:', e.message);
* }
* }
* ```
*/
declare class OotkError extends Error {
constructor(message: string);
}
/**
* Thrown when input validation fails (invalid ranges, types, formats).
*
* Use this error for:
* - Constructor parameter validation
* - Method argument validation
* - Out-of-range numeric values
* - Invalid enum values
*
* @example
* ```typescript
* if (latitude < -90 || latitude > 90) {
* throw new ValidationError(
* 'Latitude must be between -90 and 90 degrees',
* 'latitude',
* latitude,
* );
* }
* ```
*/
declare class ValidationError extends OotkError {
readonly field?: string | undefined;
readonly value?: unknown | undefined;
/**
* Creates a new ValidationError.
* @param message - Human-readable error message
* @param field - Optional name of the field that failed validation
* @param value - Optional value that failed validation
*/
constructor(message: string, field?: string | undefined, value?: unknown | undefined);
}
/**
* Thrown when parsing external data formats fails.
*
* Use this error for:
* - TLE parsing failures
* - OEM file parsing failures
* - Horizons data parsing failures
* - Any external data format that cannot be parsed
*
* @example
* ```typescript
* if (line1.length !== 69) {
* throw new ParseError(
* 'TLE line 1 must be exactly 69 characters',
* 'TLE',
* 1,
* );
* }
* ```
*/
declare class ParseError extends OotkError {
readonly format?: string | undefined;
readonly line?: number | undefined;
/**
* Creates a new ParseError.
* @param message - Human-readable error message
* @param format - Optional format identifier (e.g., 'TLE', 'OEM', 'HORIZONS')
* @param line - Optional line number where the error occurred
*/
constructor(message: string, format?: string | undefined, line?: number | undefined);
}
/**
* Thrown when orbital propagation encounters an unrecoverable error.
*
* Note: Expected failures (e.g., satellite decay, epoch before TLE epoch)
* should return null rather than throwing this error. Use PropagationError
* only for truly unexpected, unrecoverable failures.
*
* @example
* ```typescript
* if (!isFinite(position.x)) {
* throw new PropagationError(
* 'Propagation produced non-finite position',
* epoch,
* );
* }
* ```
*/
declare class PropagationError extends OotkError {
readonly epoch?: Date | undefined;
/**
* Creates a new PropagationError.
* @param message - Human-readable error message
* @param epoch - Optional epoch at which the propagation failed
*/
constructor(message: string, epoch?: Date | undefined);
}
/**
* Thrown when orbit determination algorithms fail to converge.
*
* Use this error for:
* - Gauss IOD failures
* - Gooding IOD failures
* - Gibbs IOD failures
* - Lambert solver failures
* - Any iterative algorithm that fails to converge
*
* @example
* ```typescript
* if (iterations > maxIterations) {
* throw new OrbitDeterminationError(
* 'Algorithm failed to converge after maximum iterations',
* 'Gooding',
* );
* }
* ```
*/
declare class OrbitDeterminationError extends OotkError {
readonly algorithm?: string | undefined;
/**
* Creates a new OrbitDeterminationError.
* @param message - Human-readable error message
* @param algorithm - Optional algorithm name (e.g., 'Gauss', 'Gooding', 'Lambert')
*/
constructor(message: string, algorithm?: string | undefined);
}
/**
* @author 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-2026 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 .
*/
/** Enumeration representing different methods for calculating angular diameter. */
declare enum AngularDiameterMethod {
Circle = 0,
Sphere = 1
}
/**
* @author 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-2026 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 .
*/
/** Enumeration representing different methods for calculating angular distance. */
declare enum AngularDistanceMethod {
Cosine = 0,
Haversine = 1
}
declare enum CatalogSource {
UNKNOWN = "unknown",
USSF = "spacetrack",
CELESTRAK = "celestrak",
CELESTRAK_SUP = "celestrak-sup",
UNIV_OF_MICH = "univ-of-mich",
CALPOLY = "calpoly",
NUSPACE = "nuspace",
VIMPEL = "vimpel",
SATNOGS = "satnogs",
TLE_TXT = "TLE.txt",
EXTRA_JSON = "extra.json"
}
declare enum CommLink {
AEHF = "AEHF",
GALILEO = "Galileo",
IRIDIUM = "Iridium",
STARLINK = "Starlink",
WGS = "WGS"
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Enum representing the reference frame for field of view boresight specification.
*/
declare enum FovFrame {
/** Topocentric: azimuth/elevation from local horizon (default for ground sensors) */
TOPOCENTRIC = "TOPOCENTRIC",
/** Body-fixed: relative to platform body axes (for space-based sensors) */
BODY = "BODY"
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Enum representing different field of view geometric shapes.
*/
declare enum FovShape {
/** Elliptical cone around boresight (default) */
ELLIPTICAL_CONE = "ELLIPTICAL_CONE",
/** Circular cone around boresight (symmetric case) */
CIRCULAR_CONE = "CIRCULAR_CONE"
}
/**
* @author 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-2026 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 .
*/
/** Orbit regime classifications. */
declare enum OrbitRegime {
LEO = "Low Earth Orbit",
MEO = "Medium Earth Orbit",
HEO = "Highly Eccentric Orbit",
GEO = "Geosynchronous Orbit",
OTHER = "Uncategorized Orbit"
}
/**
* @author 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-2026 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 .
*/
declare enum PassType {
OUT_OF_VIEW = -1,
ENTER = 0,
IN_VIEW = 1,
EXIT = 2
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Enum representing available propagator implementations.
*/
declare enum PropagatorType {
/** SGP4/SDP4 analytical propagator (TLE-based). */
SGP4 = "SGP4",
/** Kepler analytical two-body propagator. */
KEPLER = "KEPLER",
/** Runge-Kutta 4th order fixed-step numerical propagator. */
RK4 = "RK4",
/** Dormand-Prince 5(4) adaptive numerical propagator. */
DP54 = "DP54",
/** @deprecated Use DP54 instead. */
DORMAND_PRINCE = "DP54",
/** Runge-Kutta 8(9) adaptive numerical propagator. */
RK89 = "RK89"
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Enum representing different types of sensors.
*/
declare enum SensorType {
/** Optical/visual sensor (telescope, camera) */
OPTICAL = "OPTICAL",
/** Mechanical tracking radar (dish-based) */
MECHANICAL_RADAR = "MECHANICAL_RADAR",
/** Phased array radar (electronic beam steering) */
PHASED_ARRAY_RADAR = "PHASED_ARRAY_RADAR",
/** Laser ranging sensor (SLR - Satellite Laser Ranging) */
LASER_RANGING = "LASER_RANGING",
/** Passive RF sensor (SIGINT, no transmission) */
PASSIVE_RF = "PASSIVE_RF",
/** Bistatic radio telescope */
BISTATIC_RADIO_TELESCOPE = "BISTATIC_RADIO_TELESCOPE"
}
/**
* @author 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-2026 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 .
*/
declare enum Sgp4OpsMode {
AFSPC = "a",
IMPROVED = "i"
}
/**
* @author @thkruz Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Represents the illumination status of a satellite relative to the Sun.
*
* This enum is used to indicate whether a satellite is in sunlight, in Earth's
* shadow (eclipse), or in an unknown state.
*/
declare enum SunStatus {
/** Unknown illumination state - typically when position data is unavailable */
UNKNOWN = -1,
/** Satellite is in Earth's umbral shadow (full eclipse - no direct sunlight) */
UMBRAL = 0,
/** Satellite is in Earth's penumbral shadow (partial eclipse - partial sunlight) */
PENUMBRAL = 1,
/** Satellite is fully illuminated by the Sun */
SUN = 2
}
declare enum PayloadStatus {
OPERATIONAL = "+",
NONOPERATIONAL = "-",
PARTIALLY_OPERATIONAL = "P",
BACKUP_STANDBY = "B",
SPARE = "S",
EXTENDED_MISSION = "X",
DECAYED = "D",
UNKNOWN = "?"
}
/**
* @author 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-2026 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 .
*/
/**
* Base class for all Epoch time representations.
*
* The Epoch class hierarchy provides precise time handling for orbital mechanics
* calculations. Different astronomical time scales are required for different
* applications:
*
* ## Class Hierarchy
* ```
* Epoch (base class)
* ├── EpochUTC - Coordinated Universal Time (primary user-facing class)
* ├── EpochTAI - International Atomic Time
* ├── EpochTT - Terrestrial Time
* └── EpochTDB - Barycentric Dynamical Time
*
* EpochGPS - GPS Time (standalone, week/seconds format)
* ```
*
* ## Time Scale Conversion Chain
* ```
* UTC ──(+leap seconds)──► TAI ──(+32.184s)──► TT ──(+relativistic)──► TDB
* │
* └──(week/seconds since 1980-01-06)──► GPS
* ```
*
* ## Internal Representation
* All Epoch subclasses store time as POSIX seconds (seconds since
* 1970-01-01T00:00:00.000 in their respective time scale). This provides
* a consistent internal representation while allowing conversions between
* time scales.
*
* @see EpochUTC - The primary entry point for time operations
* @see EpochTAI - For continuous atomic timekeeping
* @see EpochTT - For Earth-based astronomical observations
* @see EpochTDB - For planetary ephemerides and solar system calculations
* @see EpochGPS - For GPS/GNSS applications
*/
declare class Epoch {
posix: Seconds;
constructor(posix?: Seconds);
toString(): string;
toExcelString(): string;
difference(epoch: Epoch): Seconds;
equals(epoch: Epoch): boolean;
toDateTime(): Date;
toEpochYearAndDay(): {
epochYr: string;
epochDay: string;
};
private getDayOfYear_;
private isLeapYear_;
toJulianDate(): number;
toJulianCenturies(): number;
operatorGreaterThan(other: Epoch): boolean;
operatorGreaterThanOrEqual(other: Epoch): boolean;
operatorLessThan(other: Epoch): boolean;
operatorLessThanOrEqual(other: Epoch): boolean;
}
/**
* @author 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-2026 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 .
*/
/**
* Represents an epoch in GPS Time format.
*
* GPS Time uses a week number and seconds-into-week format, referenced to
* the GPS epoch of January 6, 1980, 00:00:00 UTC. Unlike UTC, GPS Time does
* **not** include leap seconds, so it runs ahead of UTC by the accumulated
* leap seconds since 1980 minus 19 seconds.
*
* ## GPS Time Structure
* GPS time is expressed as two components:
* - **Week number**: Weeks since January 6, 1980
* - **Seconds of week**: Seconds elapsed in the current week (0 to 604799)
*
* ## Relationship to Other Time Scales
* ```
* GPS = UTC + leap_seconds - 19
* GPS = TAI - 19
* ```
*
* The 19-second offset exists because GPS Time was synchronized with UTC
* when there were 19 leap seconds, and GPS Time has not added leap seconds
* since then.
*
* ## Week Number Rollover
* GPS receivers transmit week numbers with limited bits, causing rollover:
* - **10-bit rollover**: Every 1024 weeks (~19.7 years)
* - **13-bit rollover**: Every 8192 weeks (~157 years)
*
* Use `week10Bit` or `week13Bit` getters when interfacing with receivers
* that use these formats.
*
* ## When to Use EpochGPS
* - **GPS receiver data**: Parsing timestamps from GPS/GNSS receivers
* - **Navigation messages**: Working with GPS broadcast ephemerides
* - **GNSS applications**: Any Global Navigation Satellite System work
* - **Precise timing**: GPS provides nanosecond-level timing
*
* ## When NOT to Use EpochGPS
* - For general satellite tracking (use EpochUTC)
* - For astronomical calculations (use EpochTT or EpochTDB)
* - For user-facing timestamps (use EpochUTC)
*
* ## Creating and Converting Instances
* ```typescript
* // Convert from UTC to GPS
* const utc = EpochUTC.now();
* const gps = utc.toGPS();
*
* console.log(gps.week); // Full week number
* console.log(gps.seconds); // Seconds into week
* console.log(gps.week10Bit); // 10-bit week (for legacy receivers)
*
* // Convert back to UTC
* const utcAgain = gps.toUTC();
* ```
*
* @see EpochUTC - Primary time class, use toGPS() to convert
*/
declare class EpochGPS {
week: number;
seconds: number;
/**
* Create a new GPS epoch given the [week] since reference epoch, and number
* of [seconds] into the [week].
* @param week Number of weeks since the GPS reference epoch.
* @param seconds Number of seconds into the week.
*/
constructor(week: number, seconds: number);
/** Cached GPS reference epoch (1980-01-06T00:00:00.000Z) */
private static reference_;
/**
* Gets the GPS reference epoch (1980-01-06T00:00:00.000Z).
* Uses lazy initialization to avoid circular dependency issues.
*/
static getReference(): EpochUTC;
static readonly offset: Seconds;
get week10Bit(): number;
get week13Bit(): number;
toString(): string;
/** Convert this to a UTC epoch. */
toUTC(): EpochUTC;
}
/**
* @author 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-2026 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 .
*/
/**
* Represents an epoch in International Atomic Time (TAI).
*
* TAI is a continuous time scale maintained by atomic clocks worldwide. Unlike
* UTC, TAI does **not** include leap seconds, making it ideal for applications
* requiring uniform time intervals.
*
* ## Relationship to Other Time Scales
* ```
* TAI = UTC + leap_seconds
* TT = TAI + 32.184 seconds
* ```
*
* As of 2024, TAI is ahead of UTC by 37 seconds. This offset increases
* whenever a leap second is added to UTC (typically every few years).
*
* ## When to Use EpochTAI
* - When you need continuous timekeeping without leap second discontinuities
* - As an intermediate step when converting between UTC and TT/TDB
* - For precise timing applications where uniform seconds are required
* - When interfacing with systems that use atomic time
*
* ## When NOT to Use EpochTAI
* - For user-facing timestamps (use EpochUTC instead)
* - For TLE epoch parsing (TLEs use UTC)
* - When civil time is expected
*
* ## Creating Instances
* EpochTAI is typically created by converting from EpochUTC:
* ```typescript
* const utc = EpochUTC.now();
* const tai = utc.toTAI();
* ```
*
* @see EpochUTC - Primary time class, use toTAI() to convert
* @see EpochTT - Terrestrial Time, derived from TAI + 32.184s
*/
declare class EpochTAI extends Epoch {
}
/**
* @author 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-2026 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 .
*/
/**
* Represents an epoch in Barycentric Dynamical Time (TDB).
*
* TDB is the time scale used for solar system barycentric calculations. It
* accounts for relativistic time dilation effects due to Earth's motion
* around the Sun and its position in the solar system's gravitational field.
*
* ## Relationship to Other Time Scales
* ```
* TDB ≈ TT + 0.001658·sin(M) + 0.000014·sin(2M)
* ```
* Where M is the mean anomaly of Earth's orbit. The difference between TDB
* and TT is periodic with amplitude of approximately ±1.6 milliseconds.
*
* ## When to Use EpochTDB
* - **JPL planetary ephemerides**: DE430, DE440, etc. use TDB as their
* time argument
* - **Solar system body positions**: Calculating positions of planets,
* moons, and asteroids
* - **Interplanetary mission planning**: Trajectories involving multiple
* solar system bodies
* - **Barycentric coordinate systems**: ICRF/BCRS calculations
*
* ## When NOT to Use EpochTDB
* - For Earth-centered calculations (use EpochTT)
* - For user-facing timestamps (use EpochUTC)
* - For satellite orbit propagation around Earth (use EpochTT or EpochUTC)
*
* ## Creating Instances
* EpochTDB is typically created by converting from EpochUTC:
* ```typescript
* const utc = EpochUTC.now();
* const tdb = utc.toTDB();
*
* // Use TDB for querying planetary ephemerides
* const sunPosition = solarSystem.getSunPosition(tdb);
* const moonPosition = solarSystem.getMoonPosition(tdb);
* ```
*
* ## Technical Note
* The conversion from TT to TDB uses a simplified formula based on Earth's
* mean anomaly. For sub-microsecond precision, more complex models from
* IERS conventions may be required.
*
* @see EpochUTC - Primary time class, use toTDB() to convert
* @see EpochTT - Geocentric time scale, TDB differs by ~1.6ms periodic
*/
declare class EpochTDB extends Epoch {
}
/**
* @author 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-2026 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 .
*/
/**
* Represents an epoch in Terrestrial Time (TT).
*
* Terrestrial Time is the modern successor to Ephemeris Time (ET) and is the
* primary time scale used for geocentric (Earth-centered) astronomical
* calculations. It provides a uniform time scale tied to the Earth's geoid.
*
* ## Relationship to Other Time Scales
* ```
* TT = TAI + 32.184 seconds
* TT = UTC + leap_seconds + 32.184 seconds
* ```
*
* The 32.184 second offset is a fixed constant that was chosen to maintain
* continuity with Ephemeris Time when TT was introduced in 1991.
*
* ## When to Use EpochTT
* - **Earth-centered force models**: Precession, nutation, and polar motion
* calculations typically require TT
* - **Astronomical almanacs**: Most published ephemerides for Earth-based
* observations use TT
* - **High-precision Earth orientation**: IERS Earth Orientation Parameters
* are referenced to TT
* - **Satellite orbit propagation**: When using force models that reference
* Earth's orientation
*
* ## When NOT to Use EpochTT
* - For user-facing timestamps (use EpochUTC)
* - For solar system barycentric calculations (use EpochTDB)
* - For GPS applications (use EpochGPS)
*
* ## Creating Instances
* EpochTT is typically created by converting from EpochUTC:
* ```typescript
* const utc = EpochUTC.now();
* const tt = utc.toTT();
*
* // TT is used internally for Julian centuries calculations
* const julianCenturies = tt.toJulianCenturies();
* ```
*
* ## J2000.0 Epoch
* The standard astronomical epoch J2000.0 (January 1, 2000, 12:00:00 TT) is
* defined in Terrestrial Time. This is the reference point for many
* astronomical coordinate systems and ephemerides.
*
* @see EpochUTC - Primary time class, use toTT() to convert
* @see EpochTAI - TAI + 32.184s = TT
* @see EpochTDB - For solar system barycentric calculations
*/
declare class EpochTT extends Epoch {
}
/**
* @author 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-2026 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 .
*/
/** Parameters for creating an EpochUTC from date components. */
type FromDateParams = {
year: number;
month: number;
day: number;
hour?: number;
minute?: number;
second?: number;
};
/**
* Represents an epoch in Coordinated Universal Time (UTC).
*
* EpochUTC is the **primary time class** for ootk and should be used as the
* default choice for most operations. It represents civil time with leap
* second corrections and serves as the entry point for conversions to other
* astronomical time scales.
*
* ## When to Use EpochUTC
* - Parsing and working with TLE (Two-Line Element) epochs
* - User-facing timestamps and I/O operations
* - General satellite tracking and pass predictions
* - Any operation where civil time is the natural choice
*
* ## Creating Instances
* ```typescript
* // Current time
* const now = EpochUTC.now();
*
* // From date components
* const epoch = EpochUTC.fromDate({ year: 2024, month: 6, day: 15, hour: 12 });
*
* // From JavaScript Date
* const epoch = EpochUTC.fromDateTime(new Date());
*
* // From ISO 8601 string
* const epoch = EpochUTC.fromDateTimeString('2024-06-15T12:00:00Z');
*
* // From definitive orbit format ("DDD/YYYY HH:MM:SS.sss")
* const epoch = EpochUTC.fromDefinitiveString('166/2024 12:00:00.000');
* ```
*
* ## Converting to Other Time Scales
* ```typescript
* const utc = EpochUTC.now();
*
* const tai = utc.toTAI(); // International Atomic Time
* const tt = utc.toTT(); // Terrestrial Time
* const tdb = utc.toTDB(); // Barycentric Dynamical Time
* const gps = utc.toGPS(); // GPS Time (week/seconds)
* ```
*
* ## Time Arithmetic
* ```typescript
* const epoch = EpochUTC.now();
* const oneHourLater = epoch.roll(3600 as Seconds);
* const difference = oneHourLater.difference(epoch); // 3600 seconds
* ```
*
* ## Sidereal Time
* EpochUTC provides Greenwich Mean Sidereal Time (GMST) calculations,
* essential for converting between Earth-fixed and inertial reference frames:
* ```typescript
* const gmstRadians = epoch.gmstAngle();
* const gmstDegrees = epoch.gmstAngleDegrees();
* ```
*
* @see Epoch - Base class with common functionality
* @see EpochTAI - For continuous timekeeping without leap seconds
* @see EpochTT - For Earth-based astronomical observations
* @see EpochTDB - For planetary ephemerides
* @see EpochGPS - For GPS/GNSS applications
*/
declare class EpochUTC extends Epoch {
static now(): EpochUTC;
static fromDate({ year, month, day, hour, minute, second }: FromDateParams): EpochUTC;
static fromDateTime(dt: Date): EpochUTC;
static fromDateTimeString(dateTimeString: string): EpochUTC;
static fromJ2000TTSeconds(seconds: Seconds): EpochUTC;
static fromDefinitiveString(definitiveString: string): EpochUTC;
roll(seconds: Seconds): EpochUTC;
toMjd(): number;
toMjdGsfc(): number;
toTAI(): EpochTAI;
toTT(): EpochTT;
toTDB(): EpochTDB;
toGPS(): EpochGPS;
gmstAngle(): number;
gmstAngleDegrees(): number;
private static readonly gmstPoly_;
private static readonly dayOfYearLookup_;
private static isLeapYear_;
private static dayOfYear_;
private static dateToPosix_;
}
/**
* @author 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-2026 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 .
*/
interface ClassicalElementsParams {
epoch: EpochUTC;
semimajorAxis: Kilometers;
eccentricity: number;
inclination: Radians;
rightAscension: Radians;
argPerigee: Radians;
trueAnomaly: Radians;
mu?: number;
}
/**
* @author 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-2026 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 .
*/
interface EquinoctialElementsParams {
epoch: EpochUTC;
h: number;
k: number;
lambda: Radians;
a: Kilometers;
p: number;
q: number;
mu?: number;
/** Retrograde factor. 1 for prograde orbits, -1 for retrograde orbits. */
I?: 1 | -1;
}
/**
* @author 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-2026 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 .
*/
/**
* Equinoctial elements are a set of orbital elements used to describe the
* orbits of celestial bodies, such as satellites around a planet. They provide
* an alternative to the traditional Keplerian elements and are especially
* useful for avoiding singularities and numerical issues in certain types of
* orbits.
*
* Unlike Keplerian elements, equinoctial elements don't suffer from
* singularities at zero eccentricity (circular orbits) or zero inclination
* (equatorial orbits). This makes them more reliable for numerical simulations
* and analytical studies, especially in these edge cases.
* @see https://faculty.nps.edu/dad/orbital/th0.pdf
*/
declare class EquinoctialElements {
epoch: EpochUTC;
/** The semi-major axis of the orbit in kilometers. */
a: Kilometers;
/** The h component of the eccentricity vector. */
h: number;
/** The k component of the eccentricity vector. */
k: number;
/** The p component of the ascending node vector. */
p: number;
/** The q component of the ascending node vector. */
q: number;
/** The mean longitude of the orbit in radians. */
lambda: Radians;
/** The gravitational parameter of the central body in km³/s². */
mu: number;
/** The retrograde factor. 1 for prograde orbits, -1 for retrograde orbits. */
I: 1 | -1;
constructor({ epoch, h, k, lambda, a, p, q, mu, I }: EquinoctialElementsParams);
/**
* Returns a string representation of the EquinoctialElements object.
* @returns A string representation of the EquinoctialElements object.
*/
toString(): string;
/**
* Gets the semimajor axis.
* @returns The semimajor axis in kilometers.
*/
get semimajorAxis(): Kilometers;
/**
* Gets the mean longitude.
* @returns The mean longitude in radians.
*/
get meanLongitude(): Radians;
/**
* Calculates the mean motion of the celestial object.
* @returns The mean motion in units of radians per second.
*/
get meanMotion(): number;
/**
* Gets the retrograde factor.
* @returns The retrograde factor.
*/
get retrogradeFactor(): number;
/**
* Checks if the orbit is prograde.
* @returns True if the orbit is prograde, false otherwise.
*/
isPrograde(): boolean;
/**
* Checks if the orbit is retrograde.
* @returns True if the orbit is retrograde, false otherwise.
*/
isRetrograde(): boolean;
/**
* Gets the period of the orbit.
* @returns The period in minutes.
*/
get period(): Minutes;
/**
* Gets the number of revolutions per day.
* @returns The number of revolutions per day.
*/
get revsPerDay(): number;
/**
* Converts the equinoctial elements to classical elements.
* @returns The classical elements.
*/
toClassicalElements(): ClassicalElements;
/**
* Converts the equinoctial elements to position and velocity.
* @returns The position and velocity in classical elements.
*/
toPositionVelocity(): PositionVelocity;
}
/**
* @author 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-2026 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 .
*/
/**
* The ClassicalElements class represents the classical orbital elements of an object.
* @example
* ```ts
* const epoch = EpochUTC.fromDateTime(new Date('2024-01-14T14:39:39.914Z'));
* const elements = new ClassicalElements({
* epoch,
* semimajorAxis: 6943.547853722985 as Kilometers,
* eccentricity: 0.0011235968124658146,
* inclination: 0.7509087232045765 as Radians,
* rightAscension: 0.028239555738616327 as Radians,
* argPerigee: 2.5386411901807353 as Radians,
* trueAnomaly: 0.5931399364974058 as Radians,
* });
* ```
*/
declare class ClassicalElements {
epoch: EpochUTC;
semimajorAxis: Kilometers;
eccentricity: number;
inclination: Radians;
rightAscension: Radians;
argPerigee: Radians;
trueAnomaly: Radians;
/** Gravitational parameter in km³/s². */
mu: number;
constructor({ epoch, semimajorAxis, eccentricity, inclination, rightAscension, argPerigee, trueAnomaly, mu, }: ClassicalElementsParams);
/**
* Creates a new instance of ClassicalElements from a StateVector.
* @param state The StateVector to convert.
* @param mu The gravitational parameter of the central body. Default value is Earth's gravitational parameter.
* @returns A new instance of ClassicalElements.
* @throws Error if the StateVector is not in an inertial frame.
*/
static fromStateVector(state: StateVector, mu?: number): ClassicalElements;
/**
* Gets the inclination in degrees.
* @returns The inclination in degrees.
*/
get inclinationDegrees(): Degrees;
/**
* Gets the right ascension in degrees.
* @returns The right ascension in degrees.
*/
get rightAscensionDegrees(): Degrees;
/**
* Gets the argument of perigee in degrees.
* @returns The argument of perigee in degrees.
*/
get argPerigeeDegrees(): Degrees;
/**
* Gets the true anomaly in degrees.
* @returns The true anomaly in degrees.
*/
get trueAnomalyDegrees(): Degrees;
/**
* Gets the apogee of the classical elements. It is measured from the surface of the earth.
* @returns The apogee in kilometers.
*/
get apogee(): Kilometers;
/**
* Gets the perigee of the classical elements. The perigee is the point in an
* orbit that is closest to the surface of the earth.
* @returns The perigee distance in kilometers.
*/
get perigee(): number;
toString(): string;
/**
* Calculates the mean motion of the celestial object.
* @returns The mean motion in radians.
*/
get meanMotion(): Radians;
/**
* Calculates the period of the orbit.
* @returns The period in seconds.
*/
get period(): Minutes;
/**
* Compute the number of revolutions completed per day for this orbit.
* @returns The number of revolutions per day.
*/
get revsPerDay(): number;
/**
* Returns the orbit regime based on the classical elements.
* @returns The orbit regime.
*/
getOrbitRegime(): OrbitRegime;
/**
* Converts the classical orbital elements to position and velocity vectors.
* @returns An object containing the position and velocity vectors.
*/
toPositionVelocity(): PositionVelocity;
/**
* Converts the classical elements to J2000 state vector.
* @return The J2000 state vector.
*/
toJ2000(): J2000;
/**
* Converts the classical elements to equinoctial elements.
* @returns The equinoctial elements.
*/
toEquinoctialElements(): EquinoctialElements;
/**
* Propagates the classical elements to a given epoch.
* @param propEpoch - The epoch to propagate the classical elements to.
* @returns The classical elements at the propagated epoch.
*/
propagate(propEpoch: EpochUTC): ClassicalElements;
/**
* Calculates the J2 nodal precession rate (RAAN drift rate).
*
* The nodal precession is caused by Earth's oblateness (J2 perturbation) and
* causes the right ascension of the ascending node to drift over time.
*
* @returns Precession rate in radians per second.
*
* @example
* ```ts
* const elements = ClassicalElements.fromStateVector(state);
* const raanDriftPerDay = elements.nodalPrecessionRate * 86400; // rad/day
* const raanDriftDegreesPerDay = raanDriftPerDay * RAD2DEG; // deg/day
* ```
*/
get nodalPrecessionRate(): number;
/**
* Returns the RAAN normalized for J2 precession since the epoch.
*
* This accounts for the secular drift of the right ascension due to
* Earth's oblateness, allowing comparison of RAAN values across different epochs.
*
* @param targetEpoch - The epoch to normalize the RAAN to.
* @returns The normalized RAAN in radians, wrapped to [0, 2π).
*
* @example
* ```ts
* const elements = ClassicalElements.fromStateVector(state);
* const futureEpoch = elements.epoch.roll(86400); // 1 day later
* const normalizedRaan = elements.normalizedRaan(futureEpoch);
* ```
*/
normalizedRaan(targetEpoch: EpochUTC): Radians;
}
/**
* @author 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-2026 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 .
*/
/**
* A Vector is a mathematical object that has both magnitude and direction.
*/
declare class Vector {
elements: T[] | Float64Array;
/**
* The length of the vector.
*/
readonly length: number;
/**
* Represents a 3-dimensional vector.
*/
static readonly origin3: Vector<0>;
/**
* Represents a vector with all elements set to zero.
*/
static readonly origin6: Vector<0>;
/**
* Represents the x-axis vector.
*/
static readonly xAxis: Vector<0 | 1>;
/**
* Represents the y-axis vector.
*/
static readonly yAxis: Vector<0 | 1>;
/**
* Represents the z-axis vector.
*/
static readonly zAxis: Vector<0 | 1>;
/**
* Represents a vector pointing along the negative x-axis.
*/
static readonly xAxisNeg: Vector<0 | -1>;
/**
* Represents a vector pointing along the negative y-axis.
*/
static readonly yAxisNeg: Vector<0 | -1>;
/**
* Represents a vector pointing along the negative z-axis.
*/
static readonly zAxisNeg: Vector<0 | -1>;
constructor(elements: T[] | Float64Array);
/**
* Creates a zero vector of the specified length.
* @param length The length of the vector.
* @returns A new Vector object representing the zero vector.
*/
static zero(length: number): Vector;
/**
* Creates a new Vector with the specified length, filled with the specified
* value.
* @param length The length of the new Vector.
* @param value The value to fill the Vector with.
* @returns A new Vector filled with the specified value.
*/
static filled(length: number, value: number): Vector;
/**
* Creates a new Vector instance from an array of elements.
* @param elements - The array of elements to create the Vector from.
* @returns A new Vector instance.
*/
static fromList(elements: number[]): Vector;
/**
* Returns a string representation of the vector.
* @param fixed - The number of digits to appear after the decimal point.
* Defaults to -1.
* @returns A string representation of the vector.
*/
toString(fixed?: number): string;
/**
* Returns a string representation of the x value of the vector.
* @returns A string representation of the x value of the vector.
*/
get x(): number;
/**
* Returns a string representation of the y value of the vector.
* @returns A string representation of the y value of the vector.
*/
get y(): number;
/**
* Returns a string representation of the z value of the vector.
* @returns A string representation of the z value of the vector.
*/
get z(): number;
/**
* Converts the vector elements to an array.
* @returns An array containing the vector elements.
*/
toList(): number[];
/**
* Converts the vector to a Float64Array.
* @returns The vector as a Float64Array.
*/
toArray(): Float64Array;
/**
* Calculates the magnitude of the vector.
* @returns The magnitude of the vector.
*/
magnitude(): number;
/**
* Adds the elements of another vector to this vector and returns a new
* vector.
* @param v - The vector to add.
* @returns A new vector containing the sum of the elements.
*/
add(v: Vector): Vector;
/**
* Subtracts a vector from the current vector.
* @param v The vector to subtract.
* @returns A new vector representing the result of the subtraction.
*/
subtract(v: Vector): Vector;
/**
* Scales the vector by a given factor.
* @param n The scaling factor.
* @returns A new Vector object representing the scaled vector.
*/
scale(n: number): Vector;
/**
* Negates the vector by scaling it by -1.
* @returns A new Vector object representing the negated vector.
*/
negate(): Vector;
/**
* Return the Euclidean distance between this and another Vector.
* @param v The vector to calculate the distance to.
* @returns The distance between the two vectors.
*/
distance(v: Vector): number;
/**
* Normalizes the vector, making it a unit vector with the same direction but
* a magnitude of 1. If the vector has a magnitude of 0, it returns a zero
* vector of the same length.
* @returns The normalized vector.
*/
normalize(): Vector;
/**
* Calculates the dot product of this vector and another vector.
* @param v - The vector to calculate the dot product with.
* @returns The dot product of the two vectors.
*/
dot(v: Vector): number;
/**
* Calculates the outer product of this vector with another vector.
* @param v The vector to calculate the outer product with.
* @returns A matrix representing the outer product of the two vectors.
*/
outer(v: Vector): Matrix;
/**
* Calculates the cross product of this vector and the given vector.
* @param v - The vector to calculate the cross product with.
* @returns The resulting vector.
*/
cross(v: Vector): Vector;
/**
* Calculate the skew-symmetric matrix for this [Vector].
* @returns The skew-symmetric matrix.
* @throws [Error] if the vector is not of length 3.
*/
skewSymmetric(): Matrix;
/**
* Rotates the vector around the X-axis by the specified angle.
* @param theta The angle in radians.
* @returns The rotated vector.
*/
rotX(theta: Radians): Vector;
/**
* Rotates the vector around the Y-axis by the specified angle.
* @param theta The angle of rotation in radians.
* @returns A new Vector representing the rotated vector.
*/
rotY(theta: Radians): Vector;
/**
* Rotates the vector around the Z-axis by the specified angle.
* @param theta The angle of rotation in radians.
* @returns A new Vector representing the rotated vector.
*/
rotZ(theta: Radians): Vector;
/**
* Calculates the angle between this vector and another vector.
* @param v The other vector.
* @returns The angle between the two vectors in radians.
*/
angle(v: Vector): Radians;
/**
* Calculates the angle between this vector and another vector in degrees.
* @param v The other vector.
* @returns The angle between the two vectors in degrees.
*/
angleDegrees(v: Vector): Degrees;
/**
* Determines if there is line of sight between this vector and another vector
* within a given radius.
* @param v - The vector to check line of sight with.
* @param radius - The radius within which line of sight is considered.
* @returns True if there is line of sight, false otherwise.
*/
sight(v: Vector, radius: number): boolean;
/**
* Returns the bisect vector between this vector and the given vector. The
* bisect vector is calculated by scaling this vector's magnitude by the
* magnitude of the given vector, adding the result to the product of scaling
* the given vector's magnitude by this vector's magnitude, and then
* normalizing the resulting vector.
* @param v - The vector to calculate the bisect with.
* @returns The bisect vector.
*/
bisect(v: Vector): Vector;
/**
* Joins the current vector with another vector.
* @param v The vector to join with.
* @returns A new vector that contains the elements of both vectors.
*/
join(v: Vector): Vector;
/**
* Returns a new Vector containing a portion of the elements from the
* specified start index to the specified end index
* @param start The start index of the slice (inclusive).
* @param end The end index of the slice (exclusive).
* @returns A new Vector containing the sliced elements.
*/
slice(start: number, end: number): Vector;
/**
* Returns a new Matrix object representing the row vector.
* @returns The row vector as a Matrix object.
*/
row(): Matrix;
/**
* Returns a new Matrix object representing the column vector of this Vector.
* @returns The column vector as a Matrix object.
*/
column(): Matrix;
/**
* Converts the elements at the specified index to a Vector3D object.
* @param index - The index of the elements to convert.
* @returns A new Vector3D object containing the converted elements.
*/
toVector3D(index: number): Vector3D;
}
/**
* @author 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-2026 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 .
*/
/**
* A matrix is a rectangular array of numbers or other mathematical objects for
* which operations such as addition and multiplication are defined.
*/
declare class Matrix {
elements: number[][];
readonly rows: number;
readonly columns: number;
constructor(elements: number[][]);
/**
* Creates a matrix with all elements set to zero.
* @param rows - The number of rows in the matrix.
* @param columns - The number of columns in the matrix.
* @returns A matrix with all elements set to zero.
*/
static allZeros(rows: number, columns: number): Matrix;
/**
* Creates a new Matrix with the specified number of rows and columns, filled
* with the specified value.
* @param rows The number of rows in the matrix.
* @param columns The number of columns in the matrix.
* @param value The value to fill the matrix with. Default is 0.0.
* @returns A new Matrix filled with the specified value.
*/
static fill(rows: number, columns: number, value?: number): Matrix;
/**
* Creates a rotation matrix around the X-axis.
* @param theta - The angle of rotation in radians.
* @returns The rotation matrix.
*/
static rotX(theta: Radians): Matrix;
/**
* Creates a rotation matrix around the y-axis.
* @param theta - The angle of rotation in radians.
* @returns The rotation matrix.
*/
static rotY(theta: Radians): Matrix;
/**
* Creates a rotation matrix around the Z-axis.
* @param theta The angle of rotation in radians.
* @returns The rotation matrix.
*/
static rotZ(theta: Radians): Matrix;
/**
* Creates a zero matrix with the specified number of rows and columns.
* @param rows The number of rows in the matrix.
* @param columns The number of columns in the matrix.
* @returns A new Matrix object representing the zero matrix.
*/
static zero(rows: number, columns: number): Matrix;
/**
* Creates an identity matrix of the specified dimension.
* @param dimension The dimension of the identity matrix.
* @returns The identity matrix.
*/
static identity(dimension: number): Matrix;
/**
* Creates a diagonal matrix with the given diagonal elements.
* @param d - An array of diagonal elements.
* @returns A new Matrix object representing the diagonal matrix.
*/
static diagonal(d: number[]): Matrix;
/**
* Adds the elements of another matrix to this matrix and returns the result.
* @param m - The matrix to be added.
* @returns The resulting matrix after addition.
*/
add(m: Matrix): Matrix;
/**
* Subtracts the elements of another matrix from this matrix.
* @param m - The matrix to subtract.
* @returns A new matrix containing the result of the subtraction.
*/
subtract(m: Matrix): Matrix;
/**
* Scales the matrix by multiplying each element by a scalar value.
* @param n - The scalar value to multiply each element by.
* @returns A new Matrix object representing the scaled matrix.
*/
scale(n: number): Matrix;
/**
* Negates the matrix by scaling it by -1.
* @returns The negated matrix.
*/
negate(): Matrix;
/**
* Multiplies this matrix with another matrix.
* @param m The matrix to multiply with.
* @returns The resulting matrix.
*/
multiply(m: Matrix): Matrix;
/**
* Computes the outer product of this matrix with another matrix.
* @param m - The matrix to compute the outer product with.
* @returns The resulting matrix.
*/
outerProduct(m: Matrix): Matrix;
/**
* Multiplies the matrix by a vector.
* @param v The vector to multiply by.
* @returns A new vector representing the result of the multiplication.
*/
multiplyVector(v: Vector): Vector;
/**
* Multiplies a 3D vector by the matrix.
* @template T - The type of the vector elements.
* @param v - The 3D vector to multiply.
* @returns The resulting 3D vector after multiplication.
*/
multiplyVector3D(v: Vector3D): Vector3D;
/**
* Returns a new Matrix object where each element is the reciprocal of the
* corresponding element in the current matrix. If an element in the current
* matrix is zero, the corresponding element in the output matrix will also be
* zero.
* @returns A new Matrix object representing the reciprocal of the current
* matrix.
*/
reciprocal(): Matrix;
/**
* Transposes the matrix by swapping rows with columns.
* @returns A new Matrix object representing the transposed matrix.
*/
transpose(): Matrix;
/**
* Performs the Cholesky decomposition on the matrix.
* @returns A new Matrix object representing the Cholesky decomposition of the
* original matrix.
*/
cholesky(): Matrix;
/**
* Swaps two rows in the matrix.
* @param i - The index of the first row.
* @param j - The index of the second row.
*/
private _swapRows;
/**
* Converts the matrix to reduced row echelon form using the Gaussian
* elimination method. This method modifies the matrix in-place.
*/
private toReducedRowEchelonForm_;
/**
* Calculates the inverse of the matrix.
* @returns The inverse of the matrix.
*/
inverse(): Matrix;
}
/**
* @author 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-2026 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 .
*/
declare class Vector3D {
x: T;
y: T;
z: T;
constructor(x: T, y: T, z: T);
/**
* Create a new Vector3D object from the first three elements of a Vector
* object.
* @param v The Vector object to convert.
* @returns A new Vector3D object.
*/
static fromVector(v: Vector): Vector3D;
static readonly origin: Vector3D;
static readonly xAxis: Vector3D;
static readonly yAxis: Vector3D;
static readonly zAxis: Vector3D;
static readonly xAxisNeg: Vector3D;
static readonly yAxisNeg: Vector3D;
static readonly zAxisNeg: Vector3D;
toList(): T[];
toArray(): Float64Array;
toVector(): Vector;
toString(fixed?: number): string;
magnitude(): T;
add(v: Vector3D): Vector3D;
subtract(v: Vector3D): Vector3D;
scale(n: U): Vector3D;
negate(): Vector3D;
/**
* Return the Euclidean distance between this and another Vector3D.
* @param v The other Vector3D.
* @returns The distance between this and the other Vector3D.
*/
distance(v: Vector3D): T;
/**
* Convert this to a unit Vector3D.
* @returns A unit Vector3D.
*/
normalize(): Vector3D;
dot(v: Vector3D): T;
outer(v: Vector3D): Matrix;
cross(v: Vector3D): Vector3D;
skewSymmetric(): Matrix;
rotX(theta: number): Vector3D;
rotY(theta: Radians): Vector3D;
rotZ(theta: Radians): Vector3D;
angle(v: Vector3D): Radians;
angleDegrees(v: Vector3D): number;
sight(v: Vector3D, radius: Kilometers): boolean;
bisect(v: Vector3D): Vector3D;
row(): Matrix;
column(): Matrix;
join(v: Vector3D): Vector;
static readonly zero: Vector3D;
}
/**
* @author 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-2026 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 .
*/
/**
* A state vector is a set of coordinates used to specify the position and
* velocity of an object in a particular reference frame.
*/
declare abstract class StateVector {
epoch: EpochUTC;
position: Vector3D;
velocity: Vector3D;
constructor(epoch: EpochUTC, position: Vector3D, velocity: Vector3D);
/**
* The name of the reference frame in which the state vector is defined.
* @returns The name of the reference frame.
*/
abstract get name(): string;
/**
* Whether the state vector is defined in an inertial reference frame.
* @returns True if the state vector is defined in an inertial reference
*/
abstract get inertial(): boolean;
/**
* Returns a string representation of the StateVector object. The string includes the name, epoch, position, and
* velocity.
* @returns A string representation of the StateVector object.
*/
toString(): string;
/**
* Calculates the mechanical energy of the state vector.
* @returns The mechanical energy value.
*/
get mechanicalEnergy(): number;
/**
* Calculates the semimajor axis of the state vector.
* @returns The semimajor axis in kilometers.
*/
get semimajorAxis(): Kilometers;
/**
* Gets the period of the state vector in minutes.
* @returns The period in minutes.
*/
get period(): Minutes;
/**
* Gets the angular rate of the state vector.
* @returns The angular rate.
*/
get angularRate(): number;
/**
* Converts the state vector to classical elements.
* @param mu The gravitational parameter of the celestial body. Defaults to Earth's gravitational parameter.
* @returns The classical elements corresponding to the state vector.
* @throws Error if classical elements are undefined for fixed frames.
*/
toClassicalElements(mu?: number): ClassicalElements;
}
/**
* Represents a position and velocity in the J2000 coordinate system. This is an Earth-centered inertial (ECI)
* coordinate system.
*
* Commonly used ECI frame is defined with the Earth's Mean Equator and Mean Equinox (MEME) at 12:00 Terrestrial Time on
* 1 January 2000. It can be referred to as J2K, J2000 or EME2000. The x-axis is aligned with the mean vernal equinox.
* The z-axis is aligned with the Earth's rotation axis (or equivalently, the celestial North Pole) as it was at that
* time. The y-axis is rotated by 90° East about the celestial equator.
* @see https://en.wikipedia.org/wiki/Earth-centered_inertial
*/
declare class J2000 extends StateVector {
/**
* Creates a J2000 coordinate from classical elements.
* @param elements The classical elements.
* @returns The J2000 coordinate.
*/
static fromClassicalElements(elements: ClassicalElements): J2000;
/**
* Gets the name of the coordinate system.
* @returns The name of the coordinate system.
*/
get name(): string;
/**
* Gets a value indicating whether the coordinate system is inertial.
* @returns A boolean value indicating whether the coordinate system is inertial.
*/
get inertial(): boolean;
/**
* Converts the coordinates from J2000 to the International Terrestrial Reference Frame (ITRF).
* This is an ECI to ECEF transformation.
* @returns The ITRF coordinates.
*/
toITRF(): ITRF;
/**
* Converts the J2000 coordinate to the TEME coordinate.
* @returns The TEME coordinate.
*/
toTEME(): TEME;
}
/**
* 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.
* @see https://en.wikipedia.org/wiki/International_Terrestrial_Reference_Frame
*
* This is a geocentric coordinate system, also referenced as ECF/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
*/
declare class ITRF extends StateVector {
/**
* Gets the name of the ITRF coordinate system.
* @returns The name of the coordinate system.
*/
get name(): string;
/**
* Gets a value indicating whether the coordinate system is inertial.
* @returns A boolean value indicating whether the coordinate system is inertial.
*/
get inertial(): boolean;
/**
* Gets the height of the ITRF coordinate above the surface of the Earth in kilometers.
* @returns The height in kilometers.
*/
get height(): Kilometers;
/**
* Gets the altitude in kilometers.
* @returns The altitude in kilometers.
*/
get alt(): Kilometers;
/**
* Converts the current coordinate to the J2000 coordinate system. This is an Earth-Centered Inertial (ECI) coordinate
* system with the origin at the center of the Earth.
* @see https://en.wikipedia.org/wiki/Epoch_(astronomy)#Julian_years_and_J2000
* @returns The coordinate in the J2000 coordinate system.
*/
toJ2000(): J2000;
/**
* Converts the current ITRF coordinate to Geodetic coordinate. This is a coordinate system for latitude, longitude,
* and altitude.
* @returns The converted Geodetic coordinate.
*/
toGeodetic(): Geodetic;
}
/**
* True Equator Mean Equinox (TEME) is a coordinate system commonly used in satellite tracking and orbit prediction. It
* is a reference frame that defines the position and orientation of an object relative to the Earth's equator and
* equinox.
*
* By using the True Equator Mean Equinox (TEME) coordinate system, we can accurately describe the position and motion
* of satellites relative to the Earth's equator and equinox. This is particularly useful for tracking and predicting
* satellite orbits in various applications, such as satellite communication, navigation, and remote sensing.
*/
declare class TEME extends StateVector {
/**
* Gets the name of the coordinate system.
* @returns The name of the coordinate system.
*/
get name(): string;
/**
* Gets a value indicating whether the coordinate is inertial.
* @returns A boolean value indicating whether the coordinate is inertial.
*/
get inertial(): boolean;
/**
* Creates a TEME (True Equator Mean Equinox) object from classical orbital elements.
* @param elements - The classical orbital elements.
* @returns A new TEME object.
*/
static fromClassicalElements(elements: ClassicalElements): TEME;
/**
* Converts the TEME (True Equator Mean Equinox) coordinates to J2000 coordinates.
* @returns The J2000 coordinates.
*/
toJ2000(): J2000;
}
/**
* @author 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-2026 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 .
*/
interface BaseObjectParams {
id?: number;
name?: string;
type?: SpaceObjectType;
active?: boolean;
metadata?: Record;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Configuration options for history tracking.
*/
interface HistoryConfig {
/** Maximum number of entries to store. Undefined means unlimited. */
maxLength?: number;
/** Minimum time between samples in milliseconds. */
samplingInterval?: number;
/** If true, automatically removes oldest entries when maxLength is reached. */
autoClean?: boolean;
}
/**
* A single entry in the history.
*/
interface HistoryEntry {
time: Date;
data: T;
}
/**
* Generic history tracking class for storing time-stamped data.
* Used to track object state over time for visualization and analysis.
*/
declare class History {
private entries_;
private config_;
private lastSampleTime_;
constructor(config?: HistoryConfig);
/**
* Adds a new entry to the history.
* Respects sampling interval and max length constraints.
* @param time - The timestamp for this entry
* @param data - The data to store
*/
add(time: Date, data: T): void;
/**
* Returns all history entries.
*/
getAll(): HistoryEntry[];
/**
* Returns entries within a time range (inclusive).
* @param start - Start of the time range
* @param end - End of the time range
*/
getRange(start: Date, end: Date): HistoryEntry[];
/**
* Returns the last n entries.
* @param n - Number of entries to return
*/
getLast(n: number): HistoryEntry[];
/**
* Returns the first entry, or undefined if empty.
*/
getFirst(): HistoryEntry | undefined;
/**
* Returns the most recent entry, or undefined if empty.
*/
getLatest(): HistoryEntry | undefined;
/**
* Clears all history entries.
*/
clear(): void;
/**
* Creates a deep copy of this history.
* @returns A new History instance with cloned entries
*/
clone(): History;
/**
* Returns the number of entries in the history.
*/
get length(): number;
/**
* Returns the current configuration.
*/
get config(): HistoryConfig;
/**
* Returns true if the history is empty.
*/
get isEmpty(): boolean;
/**
* Returns the time span covered by the history in milliseconds.
* Returns 0 if there are fewer than 2 entries.
*/
get timeSpan(): number;
toString(): string;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* State data that can be recorded in history.
*/
interface HistoricalState {
position: TemeVec3;
velocity: TemeVec3;
}
/**
* Serialized representation of a BaseObject.
* Used for persistence and data transfer.
*/
interface SerializedObject {
/** The class name of the object */
type: string;
/** Unique identifier */
id: number;
/** Human-readable name */
name: string;
/** Additional type-specific data */
[key: string]: unknown;
}
/**
* Placeholder interface for sensors (will be defined in Phase 2).
* This allows SpaceObject and GroundObject to reference sensors
* without creating circular dependencies.
*/
interface SensorInterface {
id: number;
name: string;
}
/**
* Placeholder interface for communication devices (will be defined in Phase 3).
* This allows SpaceObject and GroundObject to reference comm devices
* without creating circular dependencies.
*/
interface CommunicationDeviceInterface {
id: number;
name: string;
}
/**
* @author 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-2026 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 .
*/
/**
* Abstract base class for all objects in the ootk system.
* Provides common functionality for identification, type checking,
* history tracking, and serialization.
*/
declare abstract class BaseObject {
/** Unique identifier for the object */
id: number;
/** Human-readable name */
name: string;
/** Type classification of the object */
type: SpaceObjectType;
/** Whether the object is currently active */
active: boolean;
/** Additional metadata for the object */
metadata?: Record;
/** History tracking (null until enabled) */
private history_;
constructor(info: BaseObjectParams);
/**
* Enables history tracking for this object.
* @param config - Optional configuration for history behavior
*/
enableHistory(config?: HistoryConfig): void;
/**
* Disables history tracking and clears existing history.
*/
disableHistory(): void;
/**
* Returns the history object if enabled, null otherwise.
*/
get history(): History | null;
/**
* Returns true if history tracking is enabled.
*/
get isHistoryEnabled(): boolean;
/**
* Records a state to history if history tracking is enabled.
* @param time - The timestamp for this state
* @param state - The state to record
*/
protected recordToHistory(time: Date, state: HistoricalState): void;
/**
* Serializes the object to a plain object for persistence.
*/
serialize(): SerializedObject;
/**
* Returns type-specific serialization data.
* Subclasses must implement this to add their specific properties.
*/
protected abstract serializeSpecific(): Record;
/**
* Checks if the object is a satellite.
* @returns True if the object is a satellite, false otherwise.
*/
isSatellite(): boolean;
/**
* Checks if the object is a ground object.
* @returns True if the object is a ground object, false otherwise.
*/
isGroundObject(): boolean;
/**
* Returns whether the object is a sensor.
* @returns True if the object is a sensor, false otherwise.
*/
isSensor(): boolean;
/**
* Checks if the object is a marker.
* @returns True if the object is a marker, false otherwise.
*/
isMarker(): boolean;
/**
* Returns whether the object's position is static.
* @returns True if the object is static, false otherwise.
*/
isStatic(): boolean;
isPayload(): boolean;
isRocketBody(): boolean;
isDebris(): boolean;
isStar(): boolean;
isMissile(): boolean;
isNotional(): boolean;
getTypeString(): string;
/**
* Validates a parameter value against a minimum and maximum value.
* @param value - The value to be validated.
* @param minValue - The minimum allowed value.
* @param maxValue - The maximum allowed value.
* @param errorMessage - The error message to be thrown if the value is invalid.
*/
validateParameter(value: T, minValue: T | null, maxValue: T | null, errorMessage: string): void;
}
/**
* @author 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-2026 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 .
*/
/**
* Parameters for constructing a GroundObject.
*/
interface GroundObjectParams extends BaseObjectParams {
lat: Degrees;
lon: Degrees;
alt: Kilometers;
}
/**
* Abstract base class for all objects on Earth's surface.
* Provides coordinate conversion methods and component attachment capabilities.
*/
declare abstract class GroundObject extends BaseObject {
name: string;
readonly lat: Degrees;
readonly lon: Degrees;
readonly alt: Kilometers;
/** Sensors attached to this ground object */
sensors: SensorInterface[];
/** Communication devices attached to this ground object */
commDevices: CommunicationDeviceInterface[];
constructor(info: GroundObjectParams);
/**
* 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): RaeVec3 | null;
/**
* Calculates ECEF position at a given time.
* @variation optimized version of this.toGeodetic().toITRF().position;
* @returns The ECEF position vector of the ground object.
*/
ecef(): EcefVec3;
/**
* Calculates the Earth-Centered Inertial (ECI) position vector of the ground object at a given date.
* @variation optimized 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): TemeVec3;
/**
* Returns the latitude, longitude, and altitude of the GroundObject.
* @returns The latitude, longitude, and altitude as an LlaVec3 object.
*/
lla(): LlaVec3;
/**
* Converts the latitude, longitude, and altitude of the GroundObject to radians and kilometers.
* @variation 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;
get latRad(): Radians;
get lonRad(): Radians;
/**
* Converts the ground position to geodetic coordinates.
* @returns The geodetic coordinates.
*/
toGeodetic(): Geodetic;
/**
* Converts the ground position to J2000 inertial coordinates.
* Ground objects have zero velocity in the inertial frame (ignoring Earth rotation).
* @param date - The date for the conversion (defaults to now)
* @returns J2000 state vector
*/
toJ2000(date?: Date): J2000;
/**
* Adds a sensor to this ground object.
* @param sensor - The sensor to add
*/
addSensor(sensor: SensorInterface): void;
/**
* Removes a sensor from this ground object.
* @param sensorId - The ID of the sensor to remove
*/
removeSensor(sensorId: number): void;
/**
* Adds a communication device to this ground object.
* @param device - The device to add
*/
addCommDevice(device: CommunicationDeviceInterface): void;
/**
* Removes a communication device from this ground object.
* @param deviceId - The ID of the device to remove
*/
removeCommDevice(deviceId: number): void;
isGroundObject(): boolean;
/**
* Validates the input data for the GroundObject.
* @param info - The GroundPositionParams object containing the latitude,
* longitude, and altitude.
*/
private validateGroundObjectInputData_;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Parameters for constructing a GroundStation.
*/
interface GroundStationParams extends GroundObjectParams {
}
/**
* A concrete ground station that can host sensors and communication devices.
* Use this class for fixed ground locations like tracking stations, observatories, etc.
*/
declare class GroundStation extends GroundObject {
constructor(info: GroundStationParams);
/**
* Creates a GroundStation from a Geodetic position.
* @param geodetic - The geodetic coordinates
* @param name - Optional name for the station
* @param id - Optional unique identifier
*/
static fromGeodetic(geodetic: Geodetic, name?: string, id?: number): GroundStation;
/**
* Creates a deep copy of this ground station.
*/
clone(): GroundStation;
/**
* Creates a new GroundStation at a different position.
* The original instance remains unchanged.
* @param lat - New latitude in degrees
* @param lon - New longitude in degrees
* @param alt - Optional new altitude in kilometers (defaults to current altitude)
* @returns A new GroundStation at the specified position
*/
moveTo(lat: Degrees, lon: Degrees, alt?: Kilometers): GroundStation;
/**
* Returns true since GroundStation is always a ground object.
*/
isGroundObject(): boolean;
/**
* Returns type-specific serialization data.
*/
protected serializeSpecific(): Record;
toString(): string;
}
/**
* @author 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-2026 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 .
*/
/**
* 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.
*/
declare class Geodetic {
readonly lat: Radians;
readonly lon: Radians;
readonly alt: Kilometers;
constructor(latitude: Radians, longitude: Radians, altitude: Kilometers);
/**
* 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;
/**
* Returns a string representation of the Geodetic object.
* @returns A string containing the latitude, longitude, and altitude of the Geodetic object.
*/
toString(): string;
/**
* Gets the latitude in degrees.
* @returns The latitude in degrees.
*/
get latDeg(): number;
/**
* Gets the longitude in degrees.
* @returns The longitude in degrees.
*/
get lonDeg(): number;
/**
* Converts the geodetic coordinates to a ground station.
* @returns The ground station object.
*/
toGroundStation(): GroundStation;
/**
* 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;
/**
* 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): Radians;
/**
* 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): Degrees;
/**
* 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): Kilometers;
/**
* Calculates the field of view based on the altitude of the Geodetic object.
* @returns The field of view in radians.
*/
fieldOfView(): Radians;
/**
* 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): boolean;
}
/**
* @author 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-2026 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 .
*/
/**
* A class containing static methods for formatting TLEs (Two-Line Elements).
*/
declare abstract class FormatTle {
private constructor();
/**
* Creates a TLE (Two-Line Element) string based on the provided TleParams.
* @param tleParams - The parameters used to generate the TLE.
* @returns An object containing the TLE strings tle1 and tle2.
*/
static createTle(tleParams: TleParams): {
tle1: TleLine1;
tle2: TleLine2;
};
/**
* Converts the argument of perigee to a stringified number.
* @param argPe - The argument of perigee to be converted. Can be either a number or a string.
* @returns The argument of perigee as a stringified number.
* @throws Error if the length of the argument of perigee is not 8.
*/
static argumentOfPerigee(argPe: number | string): StringifiedNumber;
/**
* Returns the eccentricity value formatted for TLE.
* @param ecen - The eccentricity value (string or number).
* @returns The eccentricity value formatted as 7 digits without leading "0.".
* @throws Error if the length of the eccentricity string is not 7.
*/
static eccentricity(ecen: string | number): string;
/**
* Converts the inclination value to a string representation.
* @param inc - The inclination value to be converted.
* @returns The string representation of the inclination value.
* @throws Error if the length of the converted value is not 8.
*/
static inclination(inc: number | string): StringifiedNumber;
/**
* Converts the mean anomaly to a string representation with 8 digits, padded with leading zeros.
* @param meana - The mean anomaly to be converted. Can be either a number or a string.
* @returns The mean anomaly as a string with 8 digits, padded with leading zeros.
* @throws Error if the length of the mean anomaly is not 8.
*/
static meanAnomaly(meana: number | string): StringifiedNumber;
/**
* Converts the mean motion value to a string representation with 8 decimal
* places. If the input is a number, it is converted to a string. If the input
* is already a string, it is parsed as a float and then converted to a string
* with 8 decimal places. The resulting string is padded with leading zeros to
* ensure a length of 11 characters. Throws an error if the resulting string
* does not have a length of 11 characters.
* @param meanmo - The mean motion value to be converted.
* @returns The string representation of the mean motion value with 8 decimal
* places and padded with leading zeros.
* @throws Error if the resulting string does not have a length of 11
* characters.
*/
static meanMotion(meanmo: number | string): StringifiedNumber;
/**
* Converts the right ascension value to a stringified number.
* @param rasc - The right ascension value to convert.
* @returns The stringified number representation of the right ascension.
* @throws Error if the length of the converted right ascension is not 8.
*/
static rightAscension(rasc: number | string): StringifiedNumber;
/**
* Sets a character at a specific index in a string. If the index is out of range, the original string is returned.
* @param str - The input string.
* @param index - The index at which to set the character.
* @param chr - The character to set at the specified index.
* @returns The modified string with the character set at the specified index.
*/
static setCharAt(str: string, index: number, chr: string): string;
/**
* Format mean motion dot (first derivative / 2) for TLE line 1.
* Format: sign + ".NNNNNNNN" = 10 chars total.
* @param value - Mean motion dot value (rev/day^2)
* @returns Formatted 10-character string
*/
static formatMeanMotionDot(value: number): string;
/**
* Format a value in TLE exponential notation for BSTAR or mean motion ddot.
* Format: "sNNNNN±N" (8 chars) where mantissa has implied leading decimal point.
* Example: 0.00017507 → " 17507-3" (i.e., .17507 × 10^-3)
* @param value - The value to format
* @returns Formatted 8-character string
*/
static formatTleExponential(value: number): string;
/**
* Compute TLE line checksum (modulo 10 sum of digits, '-' counts as 1).
* @param line - TLE line (first 68 characters are summed)
* @returns Checksum digit (0-9)
*/
static tleChecksum(line: string): number;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
declare abstract class Force {
/**
* Calculate the acceleration due to the perturbing force on a given
* state vector.
* @param state The state vector.
* @throws If the force cannot be calculated.
*/
abstract acceleration(state: J2000): Vector3D;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
declare class Thrust implements Force {
center: EpochUTC;
radial: MetersPerSecond;
intrack: MetersPerSecond;
crosstrack: MetersPerSecond;
durationRate: SecondsPerMeterPerSecond;
constructor(center: EpochUTC, radial: MetersPerSecond, intrack: MetersPerSecond, crosstrack: MetersPerSecond, durationRate?: SecondsPerMeterPerSecond);
deltaV: Vector3D;
get magnitude(): MetersPerSecond;
get duration(): Seconds;
get start(): EpochUTC;
get stop(): EpochUTC;
acceleration(state: J2000): Vector3D;
apply(state: J2000): J2000;
get isImpulsive(): boolean;
}
/**
* @author 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-2026 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 .
*/
declare class EpochWindow {
start: EpochUTC;
end: EpochUTC;
constructor(start: EpochUTC, end: EpochUTC);
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
declare abstract class Interpolator {
abstract window(): EpochWindow;
inWindow(epoch: EpochUTC): boolean;
overlap(interpolator: Interpolator): EpochWindow | null;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
declare abstract class StateInterpolator extends Interpolator {
/**
* Interpolates the state at the given epoch.
* @param epoch The epoch in UTC format.
* @throws If the interpolator has not been initialized.
*/
abstract interpolate(epoch: EpochUTC): J2000 | null;
get sizeBytes(): number;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
declare class ForceModel {
private centralGravity_?;
private thirdBodyGravity_?;
private solarRadiationPressure_?;
private atmosphericDrag_?;
private maneuverThrust_;
setGravity(mu?: number): this;
setEarthGravity(degree: number, order: number): void;
setThirdBodyGravity({ moon, sun }: {
moon?: boolean | undefined;
sun?: boolean | undefined;
}): void;
setSolarRadiationPressure(mass: number, area: number, coeff?: number): void;
/**
* Sets the atmospheric drag for the force model.
* @deprecated This is still a work in progress!
* @param mass - The mass of the object.
* @param area - The cross-sectional area of the object.
* @param coeff - The drag coefficient. Default value is 2.2.
* @param cosine - The cosine of the angle between the object's velocity vector and the drag force vector.
*/
setAtmosphericDrag(mass: number, area: number, coeff?: number, cosine?: number): void;
loadManeuver(maneuver: Thrust): void;
clearManeuver(): void;
acceleration(state: J2000): Vector3D;
derivative(state: J2000): Vector;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
declare class Waypoint {
epoch: EpochUTC;
relativePosition: Vector3D;
constructor(epoch: EpochUTC, relativePosition: Vector3D);
/**
* Return the perturbed error in a [maneuver] when compared against the
* target [waypoint] given an initial [state], [forceModel],
* [target] interpolator, and speculative relative maneuver
* [components] _(m/s)_.
* @param waypoint The waypoint to target.
* @param maneuver The maneuver to perturb.
* @param state The initial state of the interceptor.
* @param forceModel The force model to use for propagation.
* @param target The target interpolator.
* @param components The speculative maneuver components.
* @returns The perturbed error in the maneuver.
*/
static _error(waypoint: Waypoint, maneuver: Thrust, state: J2000, forceModel: ForceModel, target: StateInterpolator, components: Float64Array): number;
/**
* Generate a score function for refining perturbed [waypoint] maneuvers.
*
* The score function takes an array of speculative radial, intrack, and
* crosstrack components _(m/s)_ and returns the propagated error from the
* desired waypoint target.
* @param waypoint The waypoint to target.
* @param maneuver The maneuver to perturb.
* @param state The initial state of the interceptor.
* @param forceModel The force model to use for propagation.
* @param target The target interpolator.
* @returns A score function for refining maneuvers.
*/
static _refineManeuverScore(waypoint: Waypoint, maneuver: Thrust, state: J2000, forceModel: ForceModel, target: StateInterpolator): (components: Float64Array) => number;
/**
* Convert an array of [waypoints] into a maneuver sequence given an
* [interceptor] state, [pivot] epoch for the first burn to arrive at the
* first waypoint, and [target] ephemeris interpolator.
*
* Optional arguments are as follows:
* - `preManeuvers`: maneuvers to execute before the pivot burn
* - `postManeuvers`: maneuvers to execute after the last pivot burn
* - `durationRate`: thruster duration rate _(s/m/s)_
* - `forceModel`: interceptor force model, defaults to two-body
* - `refine`: refine maneuvers to account for perturbations if `true`
* - `maxIter`: maximum refinement iterations per maneuver
* - `printIter`: print debug information on each refinement iteration
* @param interceptor The interceptor state.
* @param pivot The epoch of the first burn.
* @param waypoints The waypoints to target.
* @param target The target interpolator.
* @param preManeuvers The maneuvers to execute before the pivot burn.
* @param postManeuvers The maneuvers to execute after the last pivot burn.
* @param root0 The optional arguments.
* @param root0.durationRate The thruster duration rate.
* @param root0.forceModel The interceptor force model.
* @param root0.refine Whether to refine maneuvers to account for perturbations.
* @param root0.maxIter The maximum refinement iterations per maneuver.
* @param root0.printIter Whether to print debug information on each refinement iteration.
* @returns An array of maneuvers.
*/
static toManeuvers(interceptor: J2000, pivot: EpochUTC, waypoints: Waypoint[], target: StateInterpolator, preManeuvers: Thrust[] | null, postManeuvers: Thrust[] | null, { durationRate, forceModel, refine, maxIter, printIter, }?: {
durationRate?: number;
forceModel?: ForceModel;
refine?: boolean;
maxIter?: number;
printIter?: boolean;
}): Thrust[];
static _refineManeuvers(waypoints: Waypoint[], maneuvers: Thrust[], interceptor: J2000, forceModel: ForceModel, target: StateInterpolator, { maxIter, printIter, }?: {
maxIter?: number;
printIter?: boolean;
}): Thrust[];
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
declare class Hill {
epoch: EpochUTC;
position: Vector3D;
velocity: Vector3D;
private semimajorAxis_;
private meanMotion_;
constructor(epoch: EpochUTC, position: Vector3D, velocity: Vector3D, semimajorAxis: Kilometers);
static fromState(origin: J2000, radialPosition: Kilometers, intrackPosition: Kilometers, nodeVelocity: KilometersPerSecond, nodeOffsetTime: Seconds): Hill;
static fromNmc(origin: J2000, majorAxisRange: Kilometers, nodeVelocity: KilometersPerSecond, nodeOffsetTime: Seconds, translation?: number): Hill;
static fromPerch(origin: J2000, perchRange: Kilometers, nodeVelocity: KilometersPerSecond, nodeOffsetTime: Seconds): Hill;
get semimajorAxis(): Kilometers;
set semimajorAxis(sma: Kilometers);
get meanMotion(): RadiansPerSecond;
toJ2000Matrix(origin: J2000, transform: Matrix): J2000;
toJ2000(origin: J2000): J2000;
static transitionMatrix(t: number, meanMotion: number): Matrix;
transition(t: Seconds): Hill;
transitionWithMatrix(stm: Matrix, t: Seconds): Hill;
propagate(newEpoch: EpochUTC): Hill;
propagateWithMatrix(stm: Matrix, newEpoch: EpochUTC): Hill;
maneuver(maneuver: Thrust): Hill;
ephemeris(start: EpochUTC, stop: EpochUTC, step?: Seconds): Hill[];
get period(): Seconds;
nextRadialTangent(): Hill;
solveManeuver(waypoint: Waypoint, ignoreCrosstrack?: boolean): Thrust;
maneuverSequence(pivot: EpochUTC, waypoints: Waypoint[], preManeuvers?: Thrust[], postManeuvers?: Thrust[]): Thrust[];
maneuverOrigin(maneuver: Thrust): Hill;
get name(): string;
toString(): string;
}
/**
* @author 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-2026 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 .
*/
/**
* Represents the relative state of an object in 3D space.
*/
declare abstract class RelativeState {
position: Vector3D;
velocity: Vector3D;
constructor(position: Vector3D, velocity: Vector3D);
/**
* Gets the name of the coordinate system.
* @returns The name of the coordinate system.
*/
abstract get name(): string;
/**
* Returns a string representation of the RelativeState object. The string includes the name, position, and velocity
* of the object.
* @returns A string representation of the RelativeState object.
*/
toString(): string;
/**
* Transforms the current RelativeState coordinate to the J2000 coordinate
* @param origin The origin J2000 coordinate.
* @returns The transformed J2000 coordinate.
*/
abstract toJ2000(origin: J2000): J2000;
/**
* Creates a matrix based on the given position and velocity vectors. The matrix represents the relative state of an
* object in 3D space.
* @param position - The position vector.
* @param velocity - The velocity vector.
* @returns The matrix representing the relative state.
*/
static createMatrix(position: Vector3D, velocity: Vector3D): Matrix;
/**
* Calculates the range of the relative state.
* @returns The range in kilometers.
*/
get range(): Kilometers;
/**
* Calculates the range rate of the relative state. Range rate is the dot product of the position and velocity divided
* by the range.
* @returns The range rate in Kilometers per second.
*/
get rangeRate(): number;
}
/**
* @author 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-2026 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 .
*/
/**
* Represents a position and velocity with x, y, z components.
*/
interface PosVelLike {
position: {
x: number;
y: number;
z: number;
};
velocity: {
x: number;
y: number;
z: number;
};
}
/**
* Represents a Radial-Intrack-Crosstrack (RIC) coordinates.
*/
declare class RIC extends RelativeState {
/**
* Gets the name of the RIC coordinate system.
* @returns The name of the RIC coordinate system.
*/
get name(): string;
/**
* Creates a new RIC (Radial-Intrack-Crosstrack) coordinate from the J2000 state vectors.
* @param state - The J2000 state vector.
* @param origin - The J2000 state vector of the origin.
* @param transform - The transformation matrix.
* @returns The RIC coordinate.
*/
static fromJ2000Matrix(state: J2000, origin: J2000, transform: Matrix): RIC;
/**
* Creates a RIC (Radial-Intrack-Crosstrack) coordinate system from a J2000 state and origin.
* @param state The J2000 state.
* @param origin The J2000 origin.
* @returns The RIC coordinate system.
*/
static fromJ2000(state: J2000, origin: J2000): RIC;
/**
* Creates a RIC coordinate from raw position/velocity objects.
* This is a convenience method that wraps fromJ2000 for simpler usage.
* @param state The state with position and velocity vectors.
* @param origin The origin (reference) with position and velocity vectors.
* @param epoch Optional epoch for the state vectors. Defaults to current time.
* @returns The RIC coordinate.
*/
static fromPosVel(state: PosVelLike, origin: PosVelLike, epoch?: Date): RIC;
/**
* Transforms the current RIC coordinate to the J2000 coordinate system using the provided origin and transform
* matrix.
* @param origin The origin J2000 coordinate.
* @param transform The transformation matrix.
* @returns The transformed J2000 coordinate.
*/
toJ2000Matrix(origin: J2000, transform: Matrix): J2000;
/**
* Transforms the current RIC coordinate to the J2000 coordinate system using the provided origin.
* @param origin The origin J2000 coordinate.
* @returns The transformed J2000 coordinate.
*/
toJ2000(origin: J2000): J2000;
}
/**
* Represents the data format for orbital elements as provided by the OMM system.
* Numeric fields accept both string and number to support CelesTrak's JSON format
* (which sends numbers as numbers) and other sources that send them as strings.
*/
interface OmmDataFormat {
OBJECT_NAME: string;
OBJECT_ID: string;
/** Date in YYYY-MM-DDTHH:MM:SS.SSSSSS UTC format */
EPOCH: string;
MEAN_MOTION: string | number;
ECCENTRICITY: string | number;
INCLINATION: string | number;
RA_OF_ASC_NODE: string | number;
ARG_OF_PERICENTER: string | number;
MEAN_ANOMALY: string | number;
EPHEMERIS_TYPE: string | number;
CLASSIFICATION_TYPE: string;
NORAD_CAT_ID: string | number;
ELEMENT_SET_NO: string | number;
REV_AT_EPOCH: string | number;
BSTAR: string | number;
MEAN_MOTION_DOT: string | number;
MEAN_MOTION_DDOT: string | number;
}
/**
* Represents the parsed data format for orbital elements as provided by the OMM system.
* String fields are preserved from the original data; the `epoch` property contains
* the parsed date/time values used for SGP4 initialization.
*/
interface OmmParsedDataFormat {
OBJECT_NAME: string;
OBJECT_ID: string;
/** Date in YYYY-MM-DDTHH:MM:SS.SSSSSS UTC format */
EPOCH: string;
MEAN_MOTION: string;
ECCENTRICITY: string;
INCLINATION: string;
RA_OF_ASC_NODE: string;
ARG_OF_PERICENTER: string;
MEAN_ANOMALY: string;
EPHEMERIS_TYPE: string;
CLASSIFICATION_TYPE: string;
NORAD_CAT_ID: string;
ELEMENT_SET_NO: string;
REV_AT_EPOCH: string;
BSTAR: string;
MEAN_MOTION_DOT: string;
MEAN_MOTION_DDOT: string;
epoch: {
year: number;
month: number;
day: number;
hour: number;
minute: number;
second: number;
doy: number;
};
}
/**
* @author 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-2026 Kruczek Labs LLC
*
* This class was ported from the python-sgp4 library by Brandon Rhodes. That library
* is licensed under the MIT license and he maintains the copyright for that work.
*
* 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 .
*/
declare enum Sgp4GravConstants {
wgs72old = "wgs72old",
wgs72 = "wgs72",
wgs84 = "wgs84"
}
declare class Sgp4 {
private static angle_;
private static asinh_;
static createSatrec(tleLine1: string, tleLine2: string, whichconst?: Sgp4GravConstants, opsmode?: Sgp4OpsMode): SatelliteRecord;
static createSatrecFromOmm(omm: OmmParsedDataFormat, whichconst?: Sgp4GravConstants, opsmode?: Sgp4OpsMode): SatelliteRecord;
private static cross_;
static days2mdhms(year: number, days: number): {
mon: number;
day: number;
hr: number;
min: number;
sec: number;
};
private static dot_;
static gstime(jdut1: number): GreenwichMeanSiderealTime;
static invjday(jd: number, jdfrac: number): {
year: number;
mon: number;
day: number;
hr: number;
min: number;
sec: number;
};
static jday(year: number | Date, mon?: number, day?: number, hr?: number, min?: number, sec?: number, ms?: number): {
jd: number;
jdFrac: number;
};
private static mag_;
private static newtonnu_;
static propagate(satrec: SatelliteRecord, tsince: number): StateVectorSgp4;
static rv2coe(r: Vec3Flat, v: Vec3Flat, mus: number): {
p: number;
a: number;
ecc: number;
incl: number;
omega: number;
argp: number;
nu: number;
m: number;
arglat: number;
truelon: number;
lonper: number;
};
/**
* Determines the sign of a given number.
* @param x - The input number to evaluate.
* @returns `-1.0` if the input number is less than `0.0`, otherwise `1.0`.
*/
private static sgn_;
/**
* Computes the hyperbolic sine of a given number.
*
* The hyperbolic sine is calculated using the formula:
* sinh(x) = (e^x - e^(-x)) / 2
* @param x - The input number for which to calculate the hyperbolic sine.
* @returns The hyperbolic sine of the input number.
*/
private static sinh_;
private static dpper_;
private static dscom_;
private static dsinit_;
private static dspace_;
private static getgravconst_;
private static initl_;
private static sgp4init_;
}
/**
* @author 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-2026 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 .
*/
/**
* Classification of a satellite catalog number by its representation.
*
* - `numeric5` — 1-5 numeric digits, value 0-99 999.
* - `alpha5` — 5 chars, leading letter (A-Z, excl. I/O), value 100 000-339 999.
* - `numeric6` — 6 numeric digits, value 100 000-339 999.
* - `extended` — 7+ numeric digits (e.g. CelesTrak supplemental 9-digit IDs).
* Cannot be encoded in TLE cols 3-7 without truncation; canonical ID lives
* on `Satellite.sccNum`.
* - `invalid` — empty, malformed, or otherwise unclassifiable.
*/
type SatNumKind = 'numeric5' | 'alpha5' | 'numeric6' | 'extended' | 'invalid';
/**
* Tle is a static class with a collection of methods for working with TLEs.
*/
declare class Tle {
line1: TleLine1;
line2: TleLine2;
epoch: EpochUTC;
satnum: number;
private readonly satrec_;
/**
* Mapping of alpha-5 leading letters to their numeric values. Sourced from the
* leaf `alpha5` module so TLE format helpers can share it without importing Tle.
*/
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(tle1: TleLine1, 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
* almost always be seen as zero externally (e.g. by "us", unless you are "them" - in which case, hello!).
*
* A value of 1 is tolerated in addition to 0: the field is informational and does not change how SGP4/SDP4
* propagate the element set, and a handful of archival TLEs carry a 1 (originally an SGP marker).
*
* A value of 4 indicates the SGP4-XP model. Until that source code is released there is no way to support that
* format in JavaScript or TypeScript, so it is rejected explicitly. Any other value is treated as malformed.
* @example 0
* @param tleLine1 The first line of the Tle to parse.
* @returns The ephemeris type (0 or 1).
*/
static ephemerisType(tleLine1: TleLine1): 0 | 1;
/**
* 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;
/**
* Classifies a satellite catalog number by representation. See {@link SatNumKind}.
* Pure function; no side effects.
* @param sccNum The catalog number string.
* @returns The {@link SatNumKind} describing the input.
*/
static classifySatNum(sccNum: string): SatNumKind;
/**
* Converts a 6-digit numeric SCC number to its 5-character alpha-5 form.
*
* Inputs shorter than 6 chars or already in alpha-5 form pass through unchanged.
*
* @param sccNum The SCC number to convert.
* @returns The 5-character alpha-5 representation.
* @throws {ValidationError} If `sccNum` exceeds the alpha-5 range (numeric value > 339 999,
* or length > 6). For such IDs the canonical value should be kept on
* `Satellite.sccNum` and the TLE column populated with the last 5 digits.
*/
static convert6DigitToA5(sccNum: string): string;
/**
* Converts a 5-character alpha-5 SCC number to its 6-digit numeric form.
*
* Inputs shorter than 5 chars pass through unchanged. Numeric inputs without
* an alpha-5 leading letter pass through unchanged (5-digit numeric, in-range
* 6-digit numeric, and extended 7+ digit numeric IDs are all identity).
*
* @param sccNum The SCC number to convert.
* @returns The 6-digit numeric representation, or the input itself if it
* is already a numeric form.
* @throws {ValidationError} If `sccNum` is malformed: 6-digit numeric whose
* value exceeds 339 999, or contains stray letters in a non-leading position.
*/
static convertA5to6Digit(sccNum: string): string;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Options for creating a propagator from a Satellite via `createPropagator()`.
*/
interface NumericalPropagatorOptions {
/**
* The propagator type to create. Defaults to PropagatorType.RK89.
*/
type?: PropagatorType;
/**
* The force model for numerical propagators (RK4, DP54, RK89).
* If not provided, defaults to point-mass gravity.
* Ignored for SGP4 and KEPLER types.
*/
forceModel?: ForceModel;
/**
* Tolerance for adaptive propagators (DP54, RK89).
* Smaller values = more accurate but slower.
* Defaults to 1e-9.
* Ignored for SGP4, KEPLER, and RK4.
*/
tolerance?: number;
/**
* Fixed step size in seconds for RK4 propagator.
* Defaults to 15.0 seconds.
* Ignored for other propagator types.
*/
stepSize?: number;
}
interface OptionsParams {
notes: string;
}
/**
* Information about a space object.
*/
interface SatelliteParams extends LaunchDetails, SpaceCraftDetails, OperationsDetails {
name?: string;
rcs?: number | null;
omm?: OmmDataFormat;
tle1?: TleLine1;
tle2?: TleLine2;
type?: SpaceObjectType;
vmag?: number | null;
sccNum?: string;
intlDes?: string;
position?: TemeVec3;
time?: Date;
/** Unique identifier */
id?: number;
/** Whether the satellite is active */
active?: boolean;
/** Length in meters */
length?: string;
/** Diameter in meters */
diameter?: string;
/** Catalog source (e.g., VIMPEL) */
source?: CatalogSource | string;
/** Alternate catalog ID */
altId?: string;
/** Alternate name */
altName?: string;
/** Operational status */
status?: PayloadStatus;
/** Configuration for tracking position/velocity history during propagation */
historyConfig?: HistoryConfig;
}
/**
* @author 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-2026 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 .
*/
declare class RAE {
epoch: EpochUTC;
rng: Kilometers;
azRad: Radians;
elRad: Radians;
/** The range rate of the satellite relative to the observer in kilometers per second. */
rngRate?: number | undefined;
/** The azimuth rate of the satellite relative to the observer in radians per second. */
azRateRad?: number | undefined;
/** The elevation rate of the satellite relative to the observer in radians per second. */
elRateRad?: number | undefined;
constructor(epoch: EpochUTC, rng: Kilometers, azRad: Radians, elRad: Radians,
/** The range rate of the satellite relative to the observer in kilometers per second. */
rngRate?: number | undefined,
/** The azimuth rate of the satellite relative to the observer in radians per second. */
azRateRad?: number | undefined,
/** The elevation rate of the satellite relative to the observer in radians per second. */
elRateRad?: number | undefined);
static fromDegrees(epoch: EpochUTC, range: Kilometers, azimuth: Degrees, elevation: Degrees, rangeRate?: number, azimuthRate?: number, elevationRate?: number): RAE;
/**
* Create a [Razel] object from an inertial [state] and [site] vector.
* @param state The inertial [state] vector.
* @param site The observer [site] vector.
* @returns A new [Razel] object.
*/
static fromStateVector(state: J2000, site: J2000): RAE;
/**
* Gets the azimuth in degrees.
* @returns The azimuth in degrees.
*/
get az(): Degrees;
/**
* Gets the elevation angle in degrees.
* @returns The elevation angle in degrees.
*/
get el(): Degrees;
/**
* Gets the azimuth rate in degrees per second.
* @returns The azimuth rate in degrees per second, or undefined if it is not available.
*/
get azRate(): number | undefined;
/**
* Gets the elevation rate in degrees per second.
* @returns The elevation rate in degrees per second, or undefined if the elevation rate is not set.
*/
get elRate(): number | undefined;
toString(): string;
/**
* Return the position relative to the observer [site].
*
* An optional azimuth [az] _(rad)_ and elevation [el] _(rad)_ value can be
* passed to override the values contained in this observation.
* @param site The observer [site].
* @param azRad Azimuth _(rad)_.
* @param elRad Elevation _(rad)_.
* @returns A [Vector3D] object.
*/
position(site: J2000, azRad?: Radians, elRad?: Radians): Vector3D;
/**
* Convert this observation into a [J2000] state vector.
*
* This will throw an error if the [rangeRate], [elevationRate], or
* [azimuthRate] are not defined.
* @param site The observer [site].
* @returns A [J2000] state vector.
*/
toStateVector(site: J2000): J2000;
/**
* Calculate the angular distance _(rad)_ between this and another [Razel]
* object.
* @param razel The other [Razel] object.
* @param method The angular distance method to use.
* @returns The angular distance _(rad)_.
*/
angle(razel: RAE, method?: AngularDistanceMethod): number;
/**
* Calculate the angular distance _(°)_ between this and another [Razel]
* object.
* @param razel The other [Razel] object.
* @param method The angular distance method to use.
* @returns The angular distance _(°)_.
*/
angleDegrees(razel: RAE, method?: AngularDistanceMethod): number;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
declare class CubicSpline {
t0: Seconds;
p0: Vector3D;
m0: Vector3D;
t1: Seconds;
p1: Vector3D;
m1: Vector3D;
constructor(t0: Seconds, p0: Vector3D, m0: Vector3D, t1: Seconds, p1: Vector3D, m1: Vector3D);
private position_;
private velocity_;
/**
* Interpolates the position and velocity at a given time.
* (km) and velocity (km/s) vectors at the provided time.
* @param t The time value to interpolate at _(POSIX seconds)_.
* @returns An array containing the interpolated position and velocity as Vector3D objects.
*/
interpolate(t: Seconds): Vector3D[];
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Cubic spline ephemeris interpolator.
*
* The [CubicSplineInterpolator] is a very fast and accurate interpolator
* at the expense of memory due to the cached spline pairs used in the
* interpolation operation. Accuracy is significantly impacted when using
* sparse ephemerides.
*/
declare class CubicSplineInterpolator extends StateInterpolator {
private readonly splines_;
constructor(splines_: CubicSpline[]);
static fromEphemeris(ephemeris: J2000[]): CubicSplineInterpolator;
get sizeBytes(): number;
private matchSpline_;
interpolate(epoch: EpochUTC): J2000 | null;
window(): EpochWindow;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
declare class LagrangeInterpolator extends StateInterpolator {
private readonly t_;
private readonly x_;
private readonly y_;
private readonly z_;
private readonly order;
constructor(t: Float64Array, x: Float64Array, y: Float64Array, z: Float64Array, order?: number);
/**
* Creates a LagrangeInterpolator from an array of J2000 ephemeris data.
* @param ephemeris - The array of J2000 ephemeris data.
* @param order - The order of the LagrangeInterpolator. Default is 10.
* @returns A new LagrangeInterpolator instance.
*/
static fromEphemeris(ephemeris: J2000[], order?: number): LagrangeInterpolator;
get sizeBytes(): number;
interpolate(epoch: EpochUTC): J2000 | null;
private static position_;
private static velocity_;
private static _getClosest;
private slice_;
window(): EpochWindow;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Two-body Velocity Verlet Blend interpolator.
*
* The [VerletBlendInterpolator] retains the original ephemerides, so the
* original _"truth"_ states can be retrieved if needed without imparting any
* additional error, so this can be used to build other interpolator types.
* The implementation is simple and very tolerant when working with sparse
* ephemerides.
*/
declare class VerletBlendInterpolator extends StateInterpolator {
ephemeris: J2000[];
constructor(ephemeris: J2000[]);
get sizeBytes(): number;
window(): EpochWindow;
private static getClosest_;
private matchState_;
private static _gravity;
private static integrate_;
interpolate(epoch: EpochUTC): J2000 | null;
getCachedState(epoch: EpochUTC): J2000 | null;
toCubicSpline(): CubicSplineInterpolator;
toLagrange(order?: number): LagrangeInterpolator;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
declare abstract class Propagator {
abstract propagate(epoch: EpochUTC): J2000;
ephemeris(start: EpochUTC, stop: EpochUTC, interval?: Seconds): VerletBlendInterpolator;
abstract reset(): void;
abstract checkpoint(): number;
abstract restore(index: number): void;
abstract clearCheckpoints(): void;
abstract get state(): J2000;
maneuver(maneuver: Thrust, interval?: Seconds): J2000[];
ephemerisManeuver(start: EpochUTC, finish: EpochUTC, _maneuvers: Thrust[], interval?: Seconds): VerletBlendInterpolator;
ascendingNodeEpoch(start: EpochUTC): EpochUTC;
descendingNodeEpoch(start: EpochUTC): EpochUTC;
apogeeEpoch(start: EpochUTC): EpochUTC;
perigeeEpoch(start: EpochUTC): EpochUTC;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
declare abstract class RungeKuttaAdaptive extends Propagator {
private readonly initState_;
private forceModel_;
private readonly tolerance_;
/**
* Create a new [RungeKuttaAdaptive] object from an initial state vector
* along with an optional [ForceModel] and [tolerance].
* @param initState_ Initial state vector.
* @param forceModel_ Numerical integration force model.
* @param tolerance_ Minimum allowable local error tolerance.
*/
constructor(initState_: J2000, forceModel_?: ForceModel, tolerance_?: number);
private _cacheState;
private readonly _checkpoints;
private _stepSize;
private static readonly _minTolerance;
protected abstract get a(): Float64Array;
protected abstract get b(): Float64Array[];
protected abstract get ch(): Float64Array;
protected abstract get c(): Float64Array;
protected abstract get order(): number;
get state(): J2000;
reset(): void;
setForceModel(forceModel: ForceModel): void;
private kfn_;
private integrate_;
propagate(epoch: EpochUTC): J2000;
maneuver(maneuver: Thrust, interval?: Seconds): J2000[];
ephemerisManeuver(start: EpochUTC, finish: EpochUTC, maneuvers: Thrust[], interval?: Seconds): VerletBlendInterpolator;
checkpoint(): number;
clearCheckpoints(): void;
restore(index: number): void;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
declare class RungeKutta89Propagator extends RungeKuttaAdaptive {
private readonly a_;
private readonly b_;
private readonly ch_;
private readonly c_;
get a(): Float64Array;
get b(): Float64Array[];
get ch(): Float64Array;
get c(): Float64Array;
get order(): number;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Sgp4Propagator is a propagator that uses the SGP4 model to propagate the state of an object.
* This class is useful for propagating multiple states with the same TLE, since it caches the
* state of the TLE at different epochs.
*/
declare class Sgp4Propagator extends Propagator {
private readonly tle_;
constructor(tle_: Tle);
private cacheState_;
private checkpoints_;
/**
* Gets the state of the propagator in the J2000 coordinate system.
* @returns The J2000 state of the propagator.
*/
get state(): J2000;
/**
* Calculates the ephemeris maneuver using the SGP4 propagator.
* @param start The start epoch in UTC.
* @param finish The finish epoch in UTC.
* @param maneuvers The array of thrust maneuvers.
* @param interval The time interval in seconds.
*/
ephemerisManeuver(_start: EpochUTC, _finish: EpochUTC, _maneuvers: Thrust[], _interval?: number): VerletBlendInterpolator;
/**
* Performs a maneuver with the given thrust.
* @param maneuver - The thrust maneuver to perform.
* @param interval - The time interval for the maneuver (default: 60.0 seconds).
* @throws Error if maneuvers cannot be modeled with SGP4.
*/
maneuver(_maneuver: Thrust, _interval?: number): J2000[];
/**
* Propagates the state of the Sgp4Propagator to a specified epoch in J2000 coordinates.
* @param epoch - The epoch in UTC format.
* @returns The propagated state in J2000 coordinates.
*/
propagate(epoch: EpochUTC): J2000;
/**
* Resets the state of the Sgp4Propagator by updating the cache state
* to the current J2000 state of the TLE.
*/
reset(): void;
/**
* Saves the current state of the propagator and returns the index of the checkpoint.
* @returns The index of the checkpoint.
*/
checkpoint(): number;
/**
* Clears all the checkpoints in the propagator.
*/
clearCheckpoints(): void;
/**
* Restores the state of the propagator to a previously saved checkpoint.
* @param index - The index of the checkpoint to restore.
*/
restore(index: number): void;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Parameters for constructing a SpaceObject.
*/
interface SpaceObjectParams extends BaseObjectParams {
/** Initial position in TEME frame */
position?: TemeVec3;
/** Initial velocity in TEME frame */
velocity?: TemeVec3;
}
/**
* Abstract base class for all objects in space (satellites, debris, etc.).
* Provides position/velocity state, coordinate conversion methods,
* and component attachment capabilities.
*/
declare abstract class SpaceObject extends BaseObject {
/**
* Current position in TEME (True Equator Mean Equinox) frame.
* This is a cache of the last computed state.
*/
position: TemeVec3;
/**
* Current velocity in TEME (True Equator Mean Equinox) frame.
* This is a cache of the last computed state.
*/
velocity: TemeVec3;
/** Sensors attached to this space object */
sensors: SensorInterface[];
/** Communication devices attached to this space object */
commDevices: CommunicationDeviceInterface[];
constructor(info: SpaceObjectParams);
/**
* Returns the total velocity magnitude in km/s.
*/
get totalVelocity(): number;
/**
* Returns the position and velocity in the TEME (True Equator Mean Equinox) frame at the given time.
*
* **Coordinate Frame: TEME (Earth-Centered Inertial)**
*
* TEME is the native output frame of SGP4/SDP4 propagation. It is an inertial frame
* that uses the true equator of date and a simplified mean equinox. For standard J2000
* ECI coordinates, use {@link toJ2000} instead.
*
* **Frame comparison:**
* | Method | Frame | Inertial | Precision | Use Case |
* |--------|-------|----------|-----------|----------|
* | `eci()` | TEME | Yes | Lower | SGP4-native, visualization |
* | `toJ2000()` | J2000 | Yes | Higher | Force models, interop |
* | `ecef()` | ECEF | No | Lower | Quick Earth-fixed |
* | `toITRF()` | ITRF | No | Higher | Precise Earth-fixed |
*
* @param date - The time to calculate position for (defaults to now)
* @returns Position and velocity in TEME frame, or null if propagation fails
*/
abstract eci(date?: Date): PosVel | null;
/**
* Returns the position in ECEF (Earth-Centered Earth-Fixed) coordinates at the given time.
*
* **Coordinate Frame: ECEF (Earth-Fixed)**
*
* ECEF coordinates rotate with the Earth. This uses a simplified transformation from TEME
* based on GMST rotation. For higher precision Earth-fixed coordinates, use {@link toITRF}.
*
* @param date - The time to calculate position for (defaults to now)
* @returns ECEF position, or null if propagation fails
*/
abstract ecef(date?: Date): EcefVec3 | null;
/**
* Returns the geodetic position (latitude, longitude, altitude) at the given time.
*
* **Coordinate System: Geodetic (WGS84)**
*
* Returns geographic coordinates on the WGS84 ellipsoid. Derived from ECEF coordinates.
*
* @param date - The time to calculate position for (defaults to now)
* @returns Geodetic coordinates (lat/lon in degrees, alt in km), or null if propagation fails
*/
abstract lla(date?: Date): LlaVec3 | null;
/**
* Returns the Range, Azimuth, and Elevation from a ground observer.
* @param observer - The ground observer's position
* @param date - The time to calculate for (defaults to now)
* @returns RAE coordinates (range in km, az/el in degrees), or null if position cannot be calculated
*/
rae(observer: GroundObject, date?: Date): RaeVec3 | null;
/**
* Returns the azimuth angle from a ground observer.
* @param observer - The ground observer's position
* @param date - The time to calculate for (defaults to now)
* @returns Azimuth in degrees (0-360), or null if position cannot be calculated
*/
az(observer: GroundObject, date?: Date): Degrees | null;
/**
* Returns the elevation angle from a ground observer.
* @param observer - The ground observer's position
* @param date - The time to calculate for (defaults to now)
* @returns Elevation in degrees (-90 to 90), or null if position cannot be calculated
*/
el(observer: GroundObject, date?: Date): Degrees | null;
/**
* Returns the range (distance) from a ground observer.
* @param observer - The ground observer's position
* @param date - The time to calculate for (defaults to now)
* @returns Range in kilometers, or null if position cannot be calculated
*/
rng(observer: GroundObject, date?: Date): Kilometers | null;
/**
* Returns the state vector in J2000 (EME2000) frame at the given time.
*
* **Coordinate Frame: J2000 (Earth-Centered Inertial)**
*
* J2000 is the standard Earth-Centered Inertial frame defined at the J2000.0 epoch
* (January 1, 2000, 12:00 TT). Use this frame for:
* - Force modeling and numerical propagation
* - Interoperability with external systems
* - Precise astrodynamics calculations
*
* @param date - The time to calculate for (defaults to now)
* @returns J2000 state vector with position and velocity
*/
abstract toJ2000(date?: Date): J2000;
/**
* Returns the state vector in ITRF (International Terrestrial Reference Frame) at the given time.
*
* **Coordinate Frame: ITRF (Earth-Fixed)**
*
* ITRF is the standard Earth-fixed frame maintained by IERS. Unlike the simplified ECEF
* from `ecef()`, ITRF includes full precession/nutation modeling. Use this frame for:
* - Precise Earth-fixed coordinates
* - GPS/GNSS interoperability
* - Ground track calculations requiring high accuracy
*
* @param date - The time to calculate for (defaults to now)
* @returns ITRF state vector with position and velocity
*/
abstract toITRF(date?: Date): ITRF;
/**
* Returns classical orbital elements at the given time.
*
* Classical (Keplerian) elements define the orbit shape and orientation:
* - Semi-major axis (a), Eccentricity (e), Inclination (i)
* - Right Ascension of Ascending Node (Ω), Argument of Perigee (ω)
* - True/Mean Anomaly (ν/M)
*
* @param date - The time to calculate for (defaults to now)
* @returns Classical orbital elements
*/
abstract toClassicalElements(date?: Date): ClassicalElements;
/**
* Creates a deep copy of this object.
* @param options - Optional clone options (implementation-specific)
*/
abstract clone(options?: Record): SpaceObject;
/**
* Adds a sensor to this space object.
* @param sensor - The sensor to add
*/
addSensor(sensor: SensorInterface): void;
/**
* Removes a sensor from this space object.
* @param sensorId - The ID of the sensor to remove
*/
removeSensor(sensorId: number): void;
/**
* Adds a communication device to this space object.
* @param device - The device to add
*/
addCommDevice(device: CommunicationDeviceInterface): void;
/**
* Removes a communication device from this space object.
* @param deviceId - The ID of the device to remove
*/
removeCommDevice(deviceId: number): void;
/**
* Space objects are satellites by default.
*/
isSatellite(): boolean;
/**
* Space objects are never static.
*/
isStatic(): boolean;
}
/**
* @author 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-2026 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 .
*/
/**
* Options for the Satellite.clone() method.
*/
interface SatelliteCloneOptions {
/** If true, clone history entries. If false (default), start with empty history but same config. */
cloneHistory?: boolean;
}
/**
* Represents a satellite object with orbital information and methods for
* calculating its position and other properties.
*/
declare class Satellite extends SpaceObject {
apogee: Kilometers;
argOfPerigee: Degrees;
bstar: number;
eccentricity: number;
epochDay: number;
epochYear: number;
inclination: Degrees;
intlDes: string;
meanAnomaly: Degrees;
meanMoDev1: number;
meanMoDev2: number;
meanMotion: number;
options: OptionsParams;
perigee: Kilometers;
period: Minutes;
rightAscension: Degrees;
satrec: SatelliteRecord;
/** The canonical satellite catalog number. May be a 5-digit numeric, alpha-5,
* 6-digit numeric, or an extended (7+ digit) ID such as CelesTrak supplemental
* 9-digit IDs. */
sccNum: string;
/** The 5-character alpha-5 representation, or `null` when {@link sccNum} is
* an extended ID that exceeds the alpha-5 capacity (max numeric value 339 999). */
sccNum5: string | null;
/** The 6-digit numeric representation, or `null` when {@link sccNum} is
* an extended ID that exceeds the alpha-5 capacity (max numeric value 339 999). */
sccNum6: string | null;
tle1: TleLine1;
tle2: TleLine2;
/** The semi-major axis of the satellite's orbit. */
semiMajorAxis: Kilometers;
/** The semi-minor axis of the satellite's orbit. */
semiMinorAxis: Kilometers;
/** Launch date (ISO string or human-readable) */
launchDate: string;
/** Launch mass in kg */
launchMass: string;
/** Launch site name/code */
launchSite: string;
/** Launch pad identifier */
launchPad: string;
/** Launch vehicle name */
launchVehicle: string;
/** Satellite bus/platform */
bus: string;
/** Satellite configuration */
configuration: string;
/** Dry mass in kg */
dryMass: string;
/** Equipment list */
equipment: string;
/** Expected lifetime */
lifetime: string | number;
/** Maneuver capability */
maneuver: string;
/** Manufacturer name */
manufacturer: string;
/** Propulsion motor */
motor: string;
/** Payload description */
payload: string;
/** Power system description */
power: string;
/** Primary purpose/mission type */
purpose: string;
/** Physical shape */
shape: string;
/** Solar panel span */
span: string;
/** Length in meters */
length: string;
/** Diameter in meters */
diameter: string;
/** Mission name */
mission: string;
/** Operating user/agency */
user: string;
/** Owner organization */
owner: string;
/** Country of origin/registration */
country: string;
/** Catalog source (e.g., VIMPEL) */
source: string;
/** Alternate catalog ID */
altId: string;
/** Alternate name */
altName: string;
/** Visual magnitude */
vmag: number | null;
/** Radar cross-section */
rcs: number | null;
/** Operational status */
status: PayloadStatus;
constructor(info: SatelliteParams, options?: OptionsParams);
/**
* Initializes detailed properties from params.
*/
private initDetailedProperties_;
/**
* Zeroes out the SCC number in TLE for VIMPEL sources.
*/
private static setSccNumTo0_;
/**
* Creates a Satellite from TLE lines.
* @param tle1 - First line of TLE
* @param tle2 - Second line of TLE
* @param name - Optional satellite name
*/
static fromTLE(tle1: TleLine1, tle2: TleLine2, name?: string): Satellite;
/**
* Creates a Satellite from a Tle object.
* @param tle - The Tle object
* @param name - Optional satellite name (overrides TLE name)
*/
static fromTle(tle: Tle, name?: string): Satellite;
/**
* Creates a Satellite from an OMM (Orbit Mean-elements Message) data object.
* @param omm - The OMM data in flat format
* @param name - Optional satellite name (overrides OMM OBJECT_NAME)
*/
static fromOmm(omm: OmmDataFormat, name?: string): Satellite;
/**
* Converts an OMM international designator (e.g. `"2026-114A"`) to the
* TLE intl-des column format (cols 10-17, e.g. `"26114A"`). Inputs that
* don't match the OMM `YYYY-NNNL...` pattern pass through unchanged.
*/
private static ommObjectIdToTleIntlDes_;
/**
* Normalizes {@link sccNum} to the display-canonical numeric form and derives
* {@link sccNum5} and {@link sccNum6}. The class invariant is that
* `Satellite.sccNum` is always numeric — never an alpha-5 string. Alpha-5
* inputs ("T0001") are converted to their 6-digit numeric equivalent
* ("270001"); the alpha-5 form is preserved on {@link sccNum5}.
*
* Extended (7+ digit) IDs that exceed the alpha-5 capacity (max 339 999)
* leave sccNum5/sccNum6 set to `null`.
*
* Invalid input (empty string, malformed token) is passed through unchanged
* so callers can store placeholder sccNums on notional / debris stubs.
*/
private assignAlpha5Forms_;
private parseTleAndUpdateOrbit_;
private parseOmmAndUpdateOrbit_;
/**
* Checks if the object is a satellite.
* @returns True if the object is a satellite, false otherwise.
*/
isSatellite(): boolean;
/**
* Returns whether the satellite is static or not.
* @returns True if the satellite is static, false otherwise.
*/
isStatic(): boolean;
/**
* Checks if the given SatelliteRecord object is valid by checking if its properties are all numbers.
* @param satrec - The SatelliteRecord object to check.
* @returns True if the SatelliteRecord object is valid, false otherwise.
*/
static isValidSatrec(satrec: SatelliteRecord): boolean;
ageOfElset(nowInput?: Date, outputUnits?: 'days' | 'hours' | 'minutes' | 'seconds'): number;
editTle(tle1: TleLine1, tle2: TleLine2, sccNum?: string): void;
/**
* Converts the satellite object to a TLE (Two-Line Element) object.
* @returns The TLE object representing the satellite.
*/
toTle(): Tle;
/**
* Calculates the azimuth angle of the satellite relative to the given sensor at the specified date. If no date is
* provided, the current time of the satellite is used.
* @variation optimized
* @param observer - The observer's position on the ground.
* @param date - The date at which to calculate the azimuth angle. Optional, defaults to the current date.
* @returns The azimuth angle of the satellite relative to the given sensor at the specified date.
*/
az(observer: GroundObject, date?: Date): Degrees | null;
/**
* Calculates the RAE (Range, Azimuth, Elevation) values for a given sensor and date. If no date is provided, the
* current time is used.
* @variation expanded
* @param observer - The observer's position on the ground.
* @param date - The date at which to calculate the RAE values. Optional, defaults to the current date.
* @returns The RAE values for the given sensor and date.
*/
toRae(observer: GroundObject, date?: Date): RAE | null;
/**
* Calculates position in the ECEF (Earth-Centered Earth-Fixed) frame at a given time.
*
* **Coordinate Frame: ECEF (pseudo-ITRF)**
*
* Returns Earth-fixed coordinates that rotate with the Earth. The transformation
* from TEME to ECEF uses a simplified rotation based on GMST (Greenwich Mean Sidereal Time).
*
* For higher precision Earth-fixed coordinates that account for precession, nutation,
* and polar motion, use `toITRF()` instead.
*
* @variation optimized
* @param date - The date at which to calculate the ECEF position. Optional, defaults to the current date.
* @returns The ECEF position at the specified date, or null if propagation fails.
*/
ecef(date?: Date): EcefVec3 | null;
/**
* Calculates position and velocity in the TEME (True Equator Mean Equinox) frame at a given time.
*
* **Coordinate Frame: TEME**
*
* TEME is the native output frame of SGP4/SDP4 propagation. It uses the true equator of date
* and a mean equinox that accounts for precession but uses a simplified nutation model.
*
* **When to use TEME vs J2000:**
* - Use TEME (`eci()`) for quick calculations, visualization, and when frame accuracy isn't critical
* - Use J2000 (`toJ2000()`) for precise calculations, force modeling, and interoperability with
* other systems that expect J2000 coordinates
*
* To convert to other frames:
* - J2000: Use `toJ2000()` method
* - ITRF/ECEF: Use `toITRF()` or `ecef()` methods
* - Geodetic: Use `lla()` or `toGeodetic()` methods
*
* @variation optimized
* @param date - The date at which to calculate the position. Optional, defaults to the current date.
* @param j - Julian date. Optional, defaults to null.
* @param gmst - Greenwich Mean Sidereal Time. Optional, defaults to null.
* @example
* ```typescript
* import { Satellite, Tle } from 'ootk';
*
* const tle = new Tle(
* '1 25544U 98067A 24001.50000000 .00016717 00000-0 10270-3 0 9002',
* '2 25544 51.6400 208.9163 0006730 358.5720 122.3372 15.50104550 10001'
* );
* const satellite = new Satellite({ tle });
*
* // Get current position in TEME frame
* const pv = satellite.eci();
* if (pv) {
* console.log(`Position: ${pv.position.x.toFixed(2)}, ${pv.position.y.toFixed(2)}, ${pv.position.z.toFixed(2)} km`);
* console.log(`Velocity: ${pv.velocity.x.toFixed(4)} km/s`);
* }
*
* // For J2000 frame, use toJ2000() instead
* const j2000 = satellite.toJ2000();
* ```
* @returns Position and velocity in TEME frame, or null if propagation fails.
*/
eci(date?: Date, j?: number, gmst?: GreenwichMeanSiderealTime): PosVel | null;
/**
* Calculates the position and velocity in the J2000 (EME2000) frame at a given time.
*
* **Coordinate Frame: J2000**
*
* J2000 (also called EME2000) is an Earth-Centered Inertial (ECI) frame defined by:
* - Origin: Earth's center of mass
* - X-axis: Mean vernal equinox at J2000.0 epoch (Jan 1, 2000 12:00 TT)
* - Z-axis: Earth's mean rotation axis at J2000.0
* - Y-axis: Completes right-handed system
*
* This is the standard ECI frame for precise calculations and interoperability.
*
* **Internally:** SGP4 outputs TEME, which is then converted to J2000 via precession
* and nutation transformations.
*
* @variation expanded
* @param date - The date for which to calculate the J2000 coordinates, defaults to the current date.
* @returns The J2000 state vector (position and velocity).
* @throws Error if propagation fails.
*/
toJ2000(date?: Date): J2000;
/**
* Returns the elevation angle of the satellite as seen by the given sensor at the specified time.
* @variation optimized
* @param observer - The observer's position on the ground.
* @param date - The date at which to calculate the elevation angle. Optional, defaults to the current date.
* @returns The elevation angle of the satellite as seen by the given sensor at the specified time.
*/
el(observer: GroundObject, date?: Date): Degrees | null;
/**
* Calculates LLA position at a given time.
* @variation optimized
* @param date - The date at which to calculate the LLA position. Optional, defaults to the current date.
* @param j - Julian date. Optional, defaults to null.
* @param gmst - Greenwich Mean Sidereal Time. Optional, defaults to null.
* @returns The LLA position at the specified date.
*/
lla(date?: Date, j?: number, gmst?: GreenwichMeanSiderealTime): LlaVec3 | null;
/**
* Converts the satellite's position to geodetic coordinates.
* @variation expanded
* @param date The date for which to calculate the geodetic coordinates. Defaults to the current date.
* @returns The geodetic coordinates of the satellite.
*/
toGeodetic(date?: Date): Geodetic;
/**
* Converts the satellite's position to the ITRF (International Terrestrial Reference Frame) at the specified date.
*
* **Coordinate Frame: ITRF (Earth-Fixed)**
*
* ITRF is the standard Earth-fixed geocentric reference frame. Unlike the simplified ECEF
* transformation in `ecef()`, this method performs the full transformation chain:
* TEME → J2000 → ITRF, accounting for precession, nutation, and Earth rotation.
*
* Use ITRF when you need:
* - Precise Earth-fixed coordinates
* - Interoperability with GPS/GNSS systems
* - Accurate ground track calculations
*
* @variation expanded
* @param date The date for which to convert the position. Defaults to the current date.
* @returns The satellite's position in the ITRF at the specified date.
*/
toITRF(date?: Date): ITRF;
/**
* Converts the current satellite's position to the Reference-Inertial-Celestial (RIC) frame
* relative to the specified reference satellite at the given date.
* @variation expanded
* @param reference The reference satellite.
* @param date The date for which to calculate the RIC frame. Defaults to the current date.
* @returns The RIC frame representing the current satellite's position relative to the reference satellite.
*/
toRIC(reference: Satellite, date?: Date): RIC;
/**
* Converts the satellite's position to classical orbital elements.
* @param date The date for which to calculate the classical elements. Defaults to the current date.
* @returns The classical orbital elements of the satellite.
*/
toClassicalElements(date?: Date): ClassicalElements;
/**
* Calculates the RAE (Range, Azimuth, Elevation) vector for a given sensor and time.
* @variation optimized
* @param observer - The observer's position on the ground.
* @param date - The date at which to calculate the RAE vector. Optional, defaults to the current date.
* @param j - Julian date. Optional, defaults to null.
* @param gmst - Greenwich Mean Sidereal Time. Optional, defaults to null.
* @example
* ```typescript
* import { Satellite, GroundObject, Tle, Degrees, Kilometers } from 'ootk';
*
* const tle = new Tle(line1, line2);
* const satellite = new Satellite({ tle });
*
* // Define ground observer
* const observer = new GroundObject({
* lat: 40.0 as Degrees,
* lon: -75.0 as Degrees,
* alt: 0.1 as Kilometers,
* });
*
* // Get look angles
* const rae = satellite.rae(observer);
* if (rae) {
* console.log(`Range: ${rae.rng.toFixed(1)} km`);
* console.log(`Azimuth: ${rae.az.toFixed(2)}°`);
* console.log(`Elevation: ${rae.el.toFixed(2)}°`);
*
* // Check if above horizon
* if (rae.el > 0) {
* console.log('Satellite is visible!');
* }
* }
* ```
* @returns The RAE vector for the given sensor and time.
*/
rae(observer: GroundObject, date?: Date, j?: number, gmst?: GreenwichMeanSiderealTime): RaeVec3 | null;
/**
* Returns the range of the satellite from the given sensor at the specified time.
* @variation optimized
* @param observer - The observer's position on the ground.
* @param date - The date at which to calculate the range. Optional, defaults to the current date.
* @returns The range of the satellite from the given sensor at the specified time.
*/
rng(observer: GroundObject, date?: Date): Kilometers | null;
/**
* Applies the Doppler effect to the given frequency based on the observer's position and the date.
* @param freq - The frequency to apply the Doppler effect to.
* @param observer - The observer's position on the ground.
* @param date - The date at which to calculate the Doppler effect. Optional, defaults to the current date.
* @returns The frequency after applying the Doppler effect.
*/
applyDoppler(freq: number, observer: GroundObject, date?: Date): number | null;
/**
* Calculates the Doppler factor for the satellite.
* @param observer The observer's ground position.
* @param date The optional date for which to calculate the Doppler factor. If not provided, the current date is used.
* @returns The calculated Doppler factor.
*/
dopplerFactor(observer: GroundObject, date?: Date): number | null;
/**
* Returns the launch details of the satellite.
* @returns An object containing the launch date, launch mass, launch site, launch pad, and launch vehicle.
*/
getLaunchDetails(): LaunchDetails;
/**
* Returns the operations details of the satellite.
* @returns An object containing the user, mission, owner, and country details.
*/
getOperationsDetails(): OperationsDetails;
/**
* Returns the spacecraft details.
* @returns An object containing spacecraft configuration and physical details.
*/
getSpaceCraftDetails(): SpaceCraftDetails;
/**
* Creates a deep copy of this satellite.
*
* By default, history configuration is preserved but starts empty.
* Pass `{ cloneHistory: true }` to also clone the history entries.
*
* Sensors and communication devices are deep cloned with their
* parent references updated to point to the cloned satellite.
*
* @param options - Clone options
* @returns A new Satellite instance
*/
clone(options?: SatelliteCloneOptions): Satellite;
/**
* Returns type-specific serialization data.
*/
protected serializeSpecific(): Record;
/**
* Calculates ECI positions along the satellite's current orbit.
*
* @param startDate - The start date for the orbit calculation.
* @param points - Number of points to calculate (default: 180).
* @param orbits - Number of orbits to calculate (default: 1).
* @returns Array of ECI position vectors.
* @example
* ```typescript
* const orbitPoints = satellite.getOrbitPointsEci(new Date(), 360);
* orbitPoints.forEach(pt => console.log(`${pt.x}, ${pt.y}, ${pt.z}`));
* ```
*/
getOrbitPointsEci(startDate?: Date, points?: number, orbits?: number): Vector3D[];
/**
* Calculates ECEF positions along the satellite's current orbit.
*
* @param startDate - The start date for the orbit calculation.
* @param points - Number of points to calculate (default: 180).
* @param orbits - Number of orbits to calculate (default: 1).
* @returns Array of ECEF position vectors.
*/
getOrbitPointsEcef(startDate?: Date, points?: number, orbits?: number): Vector3D[];
/**
* Calculates LLA positions along the satellite's current orbit.
*
* @param startDate - The start date for the orbit calculation.
* @param points - Number of points to calculate (default: 180).
* @param orbits - Number of orbits to calculate (default: 1).
* @returns Array of LLA positions with timestamps.
* @example
* ```typescript
* const groundTrack = satellite.getOrbitPointsLla(new Date(), 360);
* groundTrack.forEach(pt => console.log(`${pt.lat}°, ${pt.lon}° at ${pt.time}`));
* ```
*/
getOrbitPointsLla(startDate?: Date, points?: number, orbits?: number): {
lat: Degrees;
lon: Degrees;
alt: Kilometers;
time: Date;
}[];
/**
* Calculates RIC (Radial, In-track, Cross-track) positions relative to another satellite along the orbit.
*
* @param reference - The reference satellite for RIC calculations.
* @param startDate - The start date for the orbit calculation.
* @param points - Number of points to calculate (default: 180).
* @param orbits - Number of orbits to calculate (default: 1).
* @returns Array of RIC state vectors.
* @example
* ```typescript
* const relativeOrbit = sat1.getOrbitPointsRic(sat2, new Date(), 360);
* relativeOrbit.forEach(ric => console.log(`R: ${ric.position.x}, I: ${ric.position.y}, C: ${ric.position.z}`));
* ```
*/
getOrbitPointsRic(reference: Satellite, startDate?: Date, points?: number, orbits?: number): RIC[];
/**
* Determines if the satellite is moving northward or southward.
* @param date - The date at which to calculate the direction.
* @returns 'N' for northward, 'S' for southward.
* @throws Error if direction cannot be determined.
* @example
* ```typescript
* const direction = satellite.getDirection(new Date());
* console.log(`Satellite is moving ${direction === 'N' ? 'North' : 'South'}`);
* ```
*/
getDirection(date?: Date): 'N' | 'S';
/**
* Calculates the nodal precession rate of the satellite's orbit.
*
* The nodal precession is caused by Earth's oblateness (J2 effect) and causes
* the orbital plane to rotate around Earth's axis over time.
*
* @returns The nodal precession rate in degrees per day.
* @example
* ```typescript
* const rate = satellite.getNodalPrecessionRate();
* console.log(`RAAN precesses at ${rate.toFixed(4)} deg/day`);
* ```
*/
getNodalPrecessionRate(): DegreesPerDay;
/**
* Calculates the normalized RAAN (Right Ascension of Ascending Node) accounting for nodal precession.
*
* This adjusts the RAAN from the TLE epoch to the specified date by applying
* the precession rate over the elapsed time.
*
* @param date - The date for which to calculate the normalized RAAN.
* @returns The normalized RAAN in degrees (0-360 range).
* @example
* ```typescript
* const raan = satellite.normalizeRaan(new Date());
* console.log(`Current RAAN: ${raan.toFixed(2)}°`);
* ```
*/
normalizeRaan(date?: Date): Degrees;
/**
* Calculates the angular separation between this satellite and another.
*
* Returns the azimuth and elevation angles of the relative position vector
* in the orbital plane reference frame.
*
* @param other - The other satellite.
* @param date - The date for the calculation.
* @returns Object containing azimuth and elevation angles in degrees.
* @throws Error if positions are undefined.
* @example
* ```typescript
* const angle = sat1.angleTo(sat2, new Date());
* console.log(`Az: ${angle.az.toFixed(2)}°, El: ${angle.el.toFixed(2)}°`);
* ```
*/
angleTo(other: Satellite, date?: Date): {
az: Degrees;
el: Degrees;
};
/**
* Calculates the angle between this satellite, another satellite, and the Sun.
*
* Returns the angle at this satellite between the vector to the other satellite
* and the vector to the Sun.
*
* @param other - The other satellite.
* @param sunPosition - The Sun's ECI position vector.
* @param date - The date for the calculation.
* @returns The angle in radians.
* @throws Error if positions are undefined.
*/
sunAngleTo(other: Satellite, sunPosition: Vector3D, date?: Date): Radians;
/**
* Determines the illumination status of the satellite (sunlit, penumbra, or umbra).
*
* Uses the Sun's lighting ratio to determine if the satellite is in Earth's shadow.
*
* @param date - The date for the calculation.
* @returns The sun status (UMBRAL, PENUMBRAL, SUN, or UNKNOWN).
* @example
* ```typescript
* const status = satellite.getSunStatus(new Date());
* if (status === SunStatus.SUN) {
* console.log('Satellite is sunlit');
* } else if (status === SunStatus.UMBRAL) {
* console.log('Satellite is in full eclipse');
* }
* ```
*/
getSunStatus(date?: Date): SunStatus;
/**
* Result of closest approach calculation.
*/
/**
* Finds the closest approach between this satellite and another within a search window.
*
* Searches through the specified duration to find the minimum distance between
* the two satellites using RIC (Radial, In-track, Cross-track) coordinates.
*
* @param other - The other satellite.
* @param startDate - The start date for the search.
* @param duration - Search duration in seconds (default: 86400 = 1 day).
* @param stepSize - Time step in seconds (default: 1).
* @returns Object containing offset, distance, RIC state, and date of closest approach.
* @throws Error if no valid approach found.
* @example
* ```typescript
* const result = sat1.findClosestApproach(sat2, new Date(), 86400);
* console.log(`Closest: ${result.distance.toFixed(2)} km at ${result.date}`);
* console.log(`RIC: R=${result.ric.position.x}, I=${result.ric.position.y}, C=${result.ric.position.z}`);
* ```
*/
findClosestApproach(other: Satellite, startDate?: Date, duration?: number, stepSize?: number): {
offset: number;
distance: Kilometers;
ric: RIC;
date: Date;
};
/**
* Creates a Propagator instance initialized from this satellite's state at the given date.
*
* Returns a fully-featured Propagator with the complete API including propagate(),
* ephemeris(), maneuver(), checkpoint/restore, and orbital event finding.
*
* @param date - The date to initialize the propagator state. Defaults to current date.
* @param options - Propagator configuration options.
* @returns A Propagator instance.
* @example
* ```typescript
* // Quick default (RK89 with point-mass gravity)
* const prop = satellite.createPropagator();
* const futureState = prop.propagate(futureEpoch);
*
* // Full customization
* const forceModel = new ForceModel()
* .setGravity()
* .setThirdBodyGravity({ moon: true, sun: true });
*
* const prop = satellite.createPropagator(new Date(), {
* type: PropagatorType.DP54,
* forceModel,
* tolerance: 1e-12,
* });
*
* const ephemeris = prop.ephemeris(start, stop, 60 as Seconds);
* ```
*/
createPropagator(date?: Date, options?: NumericalPropagatorOptions): Propagator;
/**
* Creates an Sgp4Propagator from this satellite's TLE.
*
* @returns An Sgp4Propagator instance.
* @example
* ```typescript
* const prop = satellite.createSgp4Propagator();
* const state = prop.propagate(futureEpoch);
* ```
*/
createSgp4Propagator(): Sgp4Propagator;
/**
* Creates a high-accuracy numerical propagator (RK89) from this satellite's state.
*
* For other propagator types or RK4, use `createPropagator()` with options.
*
* @param date - The date to initialize the propagator state. Defaults to current date.
* @param forceModel - The force model. Defaults to point-mass gravity.
* @param tolerance - Adaptive step tolerance. Defaults to 1e-9.
* @returns A RungeKutta89Propagator instance.
* @example
* ```typescript
* const fm = new ForceModel()
* .setGravity()
* .setThirdBodyGravity({ moon: true, sun: true })
* .setSolarRadiationPressure(500, 10, 1.2);
*
* const prop = satellite.createNumericalPropagator(new Date(), fm);
* const state = prop.propagate(futureEpoch);
* ```
*/
createNumericalPropagator(date?: Date, forceModel?: ForceModel, tolerance?: number): RungeKutta89Propagator;
/**
* Calculates the time variables for a given date relative to the TLE epoch.
* @param date Date to calculate
* @param satrec Satellite orbital information
* @param j Julian date
* @param gmst Greenwich Mean Sidereal Time
* @returns Time variables
*/
private static calculateTimeVariables_;
/** Single-entry memo for calculateTimeVariables_, keyed on Date.getTime() */
private static timeVariablesCacheMs_;
private static timeVariablesCacheJ_;
private static timeVariablesCacheGmst_;
}
/**
* Improved error handling for SGP4
*/
declare enum Sgp4ErrorCode {
NO_ERROR = 0,
MEAN_ELEMENTS_INVALID = 1,// ecc >= 1.0 or ecc < -0.001 or a < 0.95 er
MEAN_MOTION_NEGATIVE = 2,// mean motion less than 0.0
PERT_ELEMENTS_INVALID = 3,// pert elements, ecc < 0.0 or ecc > 1.0
SEMI_LATUS_RECTUM_NEGATIVE = 4,// semi-latus rectum < 0.0
EPOCH_ELEMENTS_SUBORBITAL = 5,// epoch elements are sub-orbital
SATELLITE_DECAYED = 6
}
declare class Sgp4Error extends Error {
code: Sgp4ErrorCode;
constructor(code: Sgp4ErrorCode, message?: string);
static getDefaultMessage(code: Sgp4ErrorCode): string;
}
interface Sgp4Result {
success: boolean;
value?: T;
error?: Sgp4Error;
}
/**
* @author @thkruz Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* 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 & {
__TYPE__: DistinctName;
};
/**
* Represents a quantity of days.
*/
type Days = Distinct;
/**
* 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.
*/
type Hours = Distinct;
/**
* Represents a quantity of minutes.
*/
type Minutes = Distinct;
/**
* Represents a quantity of seconds.
*/
type Seconds = Distinct;
/**
* Represents a quantity of milliseconds.
*/
type Milliseconds = Distinct;
/**
* Represents a quantity of degrees.
*/
type Degrees = Distinct;
/**
* Represents a quantity of radians.
*/
type Radians = Distinct;
/**
* Represents a quantity of kilometers.
*/
type Kilometers = Distinct;
/**
* Represents a quantity of meters.
*/
type Meters = Distinct;
/**
* Represents the type for seconds per meter per second.
*/
type SecondsPerMeterPerSecond = Distinct;
/**
* Represents a value in kilometers per second.
*/
type KilometersPerSecond = Distinct;
/**
* Represents a value in Radians per second.
*/
type RadiansPerSecond = Distinct;
/**
* Represents a value in degrees per second.
*/
type DegreesPerSecond = Distinct;
/**
* Represents a value in degrees per day.
*/
type DegreesPerDay = Distinct;
/**
* Represents a value in meters per second.
*/
type MetersPerSecond = Distinct;
/**
* Reference frame type for coordinate systems.
* This is a phantom type - it exists only at compile time for type safety.
*
* - TEME: True Equator Mean Equinox (SGP4 output frame)
* - J2000: J2000 Earth-Centered Inertial (mean equator and equinox of J2000.0)
* - GCRF: Geocentric Celestial Reference Frame (ICRF aligned)
* - ITRF: International Terrestrial Reference Frame (Earth-fixed)
*/
type ReferenceFrame = 'TEME' | 'J2000' | 'GCRF' | 'ITRF';
/**
* 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.
* @template Frame The reference frame for the coordinates. This is a phantom type
* that exists only at compile time for type safety. Defaults to 'TEME' since
* SGP4 outputs TEME coordinates.
* 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.
*/
type Vec3 = {
x: Units;
y: Units;
z: Units;
/** Phantom type for reference frame - not present at runtime */
readonly __frame?: Frame;
};
/**
* TEME (True Equator Mean Equinox) frame vector.
* This is the native output frame of SGP4/SDP4 propagation.
*/
type TemeVec3 = Vec3;
/**
* J2000 frame vector (Mean equator and equinox of J2000.0).
*/
type J2000Vec3 = Vec3;
/**
* GCRF (Geocentric Celestial Reference Frame) vector.
* This is aligned with the ICRF (International Celestial Reference Frame).
*/
type GcrfVec3 = Vec3;
/**
* ITRF (International Terrestrial Reference Frame) vector.
* This is an Earth-fixed frame that rotates with the Earth.
*/
type ItrfVec3 = Vec3;
/**
* Represents a three-dimensional vector in Earth-Centered Earth Fixed (ECEF)
* 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.
*
* 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.
*/
type EcefVec3 = Vec3;
/**
* 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.
*/
type EnuVec3 = Vec3;
/**
* 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.
*/
type LlaVec3 = {
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.
*/
type RaeVec3 = {
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
*/
type SezVec3 = {
s: D;
e: D;
z: D;
};
/**
* SatelliteRecord contains all of the orbital parameters necessary for running SGP4. It is generated by Sgp4.
*/
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.
*
* **IMPORTANT: Both position and velocity are in the TEME (True Equator Mean Equinox)
* reference frame.** TEME is the native output frame of the SGP4/SDP4 propagator.
*
* 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 false if
* propagation fails.
*
* 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.
*/
type StateVectorSgp4 = {
/** Position in TEME (True Equator Mean Equinox) frame in kilometers */
position: TemeVec3 | false;
/** Velocity in TEME (True Equator Mean Equinox) frame in km/s */
velocity: TemeVec3 | false;
};
/**
* Position and velocity state vector.
* @template PosUnits Unit of measure for position (default: Kilometers)
* @template VelUnits Unit of measure for velocity (default: KilometersPerSecond)
* @template Frame Reference frame for the coordinates (default: 'TEME')
*/
type PosVel = {
position: Vec3;
velocity: Vec3;
};
/**
* 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.
*/
type Vec3Flat = [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
*/
type TleLine1 = Distinct;
/**
* 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
*/
type TleLine2 = Distinct;
/**
* 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
*/
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
*/
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.
*/
declare 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,
EPHEMERIS_SATELLITE = 32,
TERRESTRIAL_PLANET = 33,
GAS_GIANT = 34,
ICE_GIANT = 35,
DWARF_PLANET = 36,
MOON = 37,
DYNAMIC_GROUND_OBJECT = 38,
MAX_SPACE_OBJECT_TYPE = 40
}
/**
* 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.
*/
type GreenwichMeanSiderealTime = Distinct;
/**
* 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.
*/
type AzEl = {
az: Units;
el: Units;
};
/**
* Represents the coordinates of a celestial object in Right Ascension (RA) and
* Declination (Dec).
*/
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.
*/
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;
};
type LaunchDetails = {
launchDate?: string;
launchMass?: string;
launchSite?: string;
launchVehicle?: string;
launchPad?: string;
};
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;
};
type OperationsDetails = {
user?: string;
mission?: string;
owner?: string;
country?: string;
};
type Lookangle = {
type: PassType;
time: Date;
az: Degrees;
el: Degrees;
rng: Kilometers;
maxElPass?: Degrees;
};
/**
* Two-line element set data for a satellite.
*/
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.
*/
type TleDataFull = Line1Data & Line2Data;
type StringifiedNumber = `${number}.${number}`;
/**
* Represents a set of data containing both Line 1 and Line 2 TLE information.
*/
type TleParams = {
sat?: Satellite;
inc: string | number;
meanmo: string | number;
rasc: string | number;
argPe: string | number;
meana: string | number;
ecen: string | number;
epochyr: string | number;
epochday: string | number;
/** COSPAR International Designator */
intl: string;
/** alpha 5 satellite number */
scc: string;
/** B* drag term (1/Earth radii). Used when `sat` is not provided. */
bstar?: number;
/** First derivative of mean motion / 2 (rev/day^2). Used when `sat` is not provided. */
meanMotionDot?: number;
/** Second derivative of mean motion / 6 (rev/day^3). Used when `sat` is not provided. */
meanMotionDdot?: number;
/** Classification type (default 'U'). Used when `sat` is not provided. */
classification?: string;
/** Revolution number at epoch. Used when `sat` is not provided. */
revAtEpoch?: number;
/** Element set number (default 999). Used when `sat` is not provided. */
elementSetNo?: number;
/** Ephemeris type (default 0). Used when `sat` is not provided. */
ephemerisType?: number;
};
type PositionVelocity = {
position: Vector3D;
velocity: Vector3D;
};
declare enum ZoomValue {
LEO = 0.45,
GEO = 0.82,
MAX = 1
}
/**
* The RUV coordinate system is a spherical coordinate system with the origin at
* the radar. The RUV coordinate system is defined with respect to the radar
* boresight. The R-axis points outward along the boresight with the origin at
* the radar. The U-axis is in the horizontal plane and points to the right of
* the boresight. The V-axis is in the vertical plane and points down from the
* boresight.
* @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.
*/
type RuvVec3 = {
rng: DistanceUnit;
u: number;
v: number;
};
/**
* Phased Array Radar Face Cartesian Coordinates The cartesian coordinates (XRF,
* YRF ZRF) are defined with respect to the phased array radar face. The radar
* face lies in the XRF-YRF plane, with the XRF-axis horizontal and the YRF-axis
* pointing upward. The ZRF-axis points outward along the normal to the array
* face.
*
* The orientation of the phased array face is defined by the azimuth and the
* elevation of the phased array boresight (i.e., the phased array Z-axis).
*/
type RfVec3 = Vec3;
/**
* Represents a function that calculates the Jacobian matrix.
* @param xs - The input values as a Float64Array. @returns The Jacobian matrix
* as a Float64Array.
*/
type JacobianFunction = (xs: Float64Array) => Float64Array;
/**
* Represents a differentiable function.
* @param x The input value. @returns The output value.
*/
type DifferentiableFunction = (x: number) => number;
/**
* @author 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-2026 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 .
*/
interface GroundPositionParams {
lat: Degrees;
lon: Degrees;
alt: Kilometers;
}
interface StarObjectParams extends BaseObjectParams {
ra: Radians;
dec: Radians;
bf?: string;
h?: string;
pname?: string;
vmag?: number;
constellation?: string;
colorTemp?: number;
hr?: number;
flamsteed?: string;
bayer?: string;
}
/**
* @author 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-2026 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 .
*/
declare class TimeStamped {
/**
* Timestamped value.
*/
private readonly value_;
/**
* Timestamp epoch.
*/
readonly epoch_: EpochUTC;
/**
* Create a new time stamped value container at the provided epoch.
* @param epoch The timestamp epoch.
* @param value The timestamped value.
*/
constructor(epoch: EpochUTC, value: T);
/**
* Get the timestamped value.
* @returns The timestamped value.
*/
get value(): T;
/**
* Set the timestamped value.
* @param _ The timestamped value.
* @throws Cannot set value of TimeStamped object; it is readonly.
*/
set value(_: T);
/**
* Get the timestamp epoch.
* @returns The timestamp epoch.
*/
get epoch(): EpochUTC;
/**
* Set the timestamp epoch.
* @param _ The timestamp epoch.
* @throws Cannot set epoch of TimeStamped object; it is readonly.
*/
set epoch(_: EpochUTC);
}
/**
* @author 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-2026 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 .
*/
/**
* Converts radians to degrees.
* @param radians The value in radians to be converted.
* @returns The value in degrees.
*/
declare function rad2deg(radians: Radians): Degrees;
/**
* Converts degrees to radians.
* @param degrees The value in degrees to be converted.
* @returns The value in radians.
*/
declare function deg2rad(degrees: Degrees): Radians;
/**
* Converts radians to degrees latitude.
* @param radians The radians value to convert.
* @returns The corresponding degrees latitude.
* @throws RangeError if the radians value is outside the range [-PI/2; PI/2].
*/
declare function getDegLat(radians: Radians): Degrees;
/**
* Converts radians to degrees for longitude.
* @param radians The value in radians to be converted.
* @returns The converted value in degrees.
* @throws {RangeError} If the input radians is not within the range [-PI; PI].
*/
declare function getDegLon(radians: Radians): Degrees;
/**
* Converts degrees to radians for latitude.
* @param degrees The degrees value to convert.
* @returns The equivalent radians value.
* @throws {RangeError} If the degrees value is not within the range [-90, 90].
*/
declare function getRadLat(degrees: Degrees): Radians;
/**
* Converts degrees to radians.
* @param degrees The value in degrees to be converted.
* @returns The value in radians.
* @throws {RangeError} If the input degrees are not within the range [-180; 180].
*/
declare function getRadLon(degrees: Degrees): Radians;
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Azimuth-dependent elevation mask for terrain/obstructions.
* Used to define regions where the minimum elevation is higher than the global minimum
* due to buildings, mountains, or other obstructions.
*/
interface ElevationMask {
/** Start of azimuth range in degrees (inclusive) */
startAz: Degrees;
/** End of azimuth range in degrees (inclusive), handles wraparound */
stopAz: Degrees;
/** Minimum elevation in degrees for this azimuth range */
minEl: Degrees;
}
/**
* Parameters for constructing a FieldOfView.
*/
interface FieldOfViewParams {
/** Boresight azimuth in degrees (default: 0° = North) */
boresightAz?: Degrees;
/** Boresight elevation in degrees (default: 90° = zenith) */
boresightEl?: Degrees;
/** Half-angle of FOV cone in degrees (major axis for elliptical) */
halfAngle: Degrees;
/** Minor half-angle for elliptical cone (defaults to halfAngle for circular) */
minorHalfAngle?: Degrees;
/** Roll angle for elliptical cone orientation in degrees (default: 0°) */
rollAngle?: Degrees;
/** Minimum range in kilometers */
minRange: Kilometers;
/** Maximum range in kilometers */
maxRange: Kilometers;
/** Global minimum elevation in degrees (default: 0°) */
minElevation?: Degrees;
/** Azimuth-specific elevation masks for terrain/buildings */
elevationMasks?: ElevationMask[];
/** FOV shape type (default: ELLIPTICAL_CONE) */
shape?: FovShape;
/** Reference frame for boresight (default: TOPOCENTRIC) */
frame?: FovFrame;
}
/**
* Orthonormal basis representing the boresight frame.
* Used for transforming target directions into boresight-relative coordinates.
*/
interface BoresightFrame {
/** Boresight direction (unit vector) */
b: Vector3D;
/** Major axis direction (unit vector, perpendicular to boresight) */
u: Vector3D;
/** Minor axis direction (unit vector, perpendicular to both b and u) */
v: Vector3D;
}
/**
* Constructs a boresight frame from azimuth, elevation, and roll angles.
*
* The frame is constructed using the ENU (East-North-Up) convention:
* - Azimuth 0° is North, 90° is East
* - Elevation 0° is horizontal, 90° is zenith
* - Roll 0° means major axis aligns with the projection of "up" onto the
* plane perpendicular to boresight
*
* @param az - Boresight azimuth in radians
* @param el - Boresight elevation in radians
* @param roll - Roll angle in radians
* @returns Orthonormal boresight frame
*/
declare function boresightFrameFromAzElRoll(az: Radians, el: Radians, roll: Radians): BoresightFrame;
/**
* Boresight-centric field of view using elliptical cone geometry.
*
* Defines a sensor's FOV as an elliptical cone around a boresight direction,
* with optional azimuth-dependent elevation masking for terrain/obstructions.
*
* @example
* ```typescript
* // Circular cone pointing at zenith
* const fov = new FieldOfView({
* halfAngle: 45 as Degrees,
* minRange: 100 as Kilometers,
* maxRange: 50000 as Kilometers,
* });
*
* // Elliptical fan-shaped FOV (phased array radar)
* const fanFov = new FieldOfView({
* boresightEl: 90 as Degrees,
* halfAngle: 90 as Degrees, // 90° in major direction
* minorHalfAngle: 2 as Degrees, // 2° in minor direction
* rollAngle: 0 as Degrees, // Major axis aligned N-S
* minRange: 100 as Kilometers,
* maxRange: 50000 as Kilometers,
* });
*
* // Check if target is visible
* const rae = { rng: 1000, az: 45, el: 30 };
* if (fov.contains(rae)) {
* console.log('Target is in FOV');
* }
* ```
*/
declare class FieldOfView {
/** Boresight azimuth in degrees */
readonly boresightAz: Degrees;
/** Boresight elevation in degrees */
readonly boresightEl: Degrees;
/** Major half-angle in degrees */
readonly halfAngle: Degrees;
/** Minor half-angle in degrees */
readonly minorHalfAngle: Degrees;
/** Roll angle in degrees */
readonly rollAngle: Degrees;
/** Minimum range in kilometers */
readonly minRange: Kilometers;
/** Maximum range in kilometers */
readonly maxRange: Kilometers;
/** Global minimum elevation in degrees */
readonly minElevation: Degrees;
/** Azimuth-specific elevation masks */
readonly elevationMasks: ElevationMask[];
/** FOV shape type */
readonly shape: FovShape;
/** Reference frame for boresight */
readonly frame: FovFrame;
/** Cached boresight frame for performance */
private readonly boresightFrame_;
/** Cached half angles in radians */
private readonly halfAngleRad_;
private readonly minorHalfAngleRad_;
constructor(params: FieldOfViewParams);
/**
* Creates a hemisphere FOV (all-sky coverage above minimum elevation).
* @param minRange - Minimum range in kilometers
* @param maxRange - Maximum range in kilometers
* @param minEl - Minimum elevation (default: 0°)
* @returns FieldOfView covering the hemisphere
*/
static hemisphere(minRange: Kilometers, maxRange: Kilometers, minEl?: Degrees): FieldOfView;
/**
* Creates a circular cone FOV.
* @param boresightAz - Boresight azimuth in degrees
* @param boresightEl - Boresight elevation in degrees
* @param halfAngle - Cone half-angle in degrees
* @param minRange - Minimum range in kilometers
* @param maxRange - Maximum range in kilometers
* @returns FieldOfView with circular cone
*/
static circularCone(boresightAz: Degrees, boresightEl: Degrees, halfAngle: Degrees, minRange: Kilometers, maxRange: Kilometers): FieldOfView;
/**
* Checks if the given RAE coordinates are within this field of view.
*
* Performs the following checks in order:
* 1. Range bounds
* 2. Elevation masking (global and azimuth-specific)
* 3. Elliptical cone containment
*
* @param rae - The RAE coordinates to check
* @returns True if the coordinates are within the FOV
*/
contains(rae: RaeVec3): boolean;
/**
* Checks if a direction vector is within the FOV angular bounds.
* For body-frame sensors receiving body-frame directions.
*
* @param direction - Direction vector to target (will be normalized)
* @param range - Range to target in kilometers
* @returns True if within FOV
*/
containsDirection(direction: Vector3D, range: Kilometers): boolean;
/**
* Gets the effective minimum elevation at a given azimuth.
* Considers all applicable elevation masks and returns the most restrictive.
*
* @param az - Azimuth in degrees
* @returns Effective minimum elevation in degrees
*/
getMinElevation(az: Degrees): Degrees;
/**
* Returns the boresight as a unit vector in the topocentric (ENU) frame.
*/
get boresightVector(): Vector3D;
/**
* Calculates the angular offset from boresight to a target.
* @param az - Target azimuth in degrees
* @param el - Target elevation in degrees
* @returns Angular offset in degrees
*/
angularOffset(az: Degrees, el: Degrees): Degrees;
/**
* Returns true if the FOV is circular (major = minor half-angle).
*/
get isCircular(): boolean;
/**
* Gets the full angular coverage (2 * halfAngle) in degrees.
* For scanning radars, this represents the sweep width.
*/
get angularCoverage(): Degrees;
/**
* Checks if this FOV is configured for deep space observation.
* Deep space is defined as max range > 6000 km.
*/
isDeepSpace(): boolean;
/**
* Checks if this FOV is configured for near-Earth observation.
* Near Earth is defined as max range <= 6000 km.
*/
isNearEarth(): boolean;
/**
* Creates a serializable representation of this FOV.
*/
serialize(): FieldOfViewParams;
/**
* Returns a string representation of this FOV.
*/
toString(): string;
/**
* Checks if an azimuth falls within an elevation mask's range.
* Handles wraparound (e.g., 350° to 10°).
*/
private isAzimuthInMaskRange;
/**
* Core containment check for cone geometry using az/el.
*/
private isWithinCone;
/**
* Core containment check for cone geometry using direction vector.
*/
private isDirectionWithinCone;
/**
* Validates FOV parameters.
*/
private validate;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
declare class RandomGaussianSource {
private readonly boxMuller_;
constructor(seed?: number);
nextGauss(): number;
gaussVector(n: number): Vector;
gaussSphere(radius?: number): Vector3D;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
declare class PropagatorPairs {
private readonly posStep_;
private readonly velStep_;
constructor(posStep_: number, velStep_: number);
private _high;
private _low;
set(index: number, high: Propagator, low: Propagator): void;
get(index: number): [Propagator, Propagator];
/**
* Get the step size at the provided index.
* @param index The index.
* @returns The step size.
*/
step(index: number): number;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Observation data.
*/
declare abstract class Observation {
/** Observation epoch. */
abstract get epoch(): EpochUTC;
/** Inertial observer location. */
abstract get site(): J2000;
/** Observation noise matrix. */
abstract get noise(): Matrix;
/**
* Return range-normalized cross line-of-sight residual for the observation
* when compared against a nominal state propagator.
* @param propagator Propagator to compare against.
* @throws Not implemented.
*/
abstract clos(propagator: Propagator): number;
/**
* Return relative state residual for the observation when compared against
* a nominal state propagator.
* @param propagator Propagator to compare against.
* @throws Not implemented.
*/
abstract ricDiff(propagator: Propagator): Vector3D;
/**
* Convert this observation to vector form.
* @throws Not implemented.
*/
abstract toVector(): Vector;
/**
* Compute the state derivative matrix for this observation.
* @param propPairs Propagator pairs to compare against.
* @throws Not implemented.
*/
abstract jacobian(propPairs: PropagatorPairs): Matrix;
/**
* Compute the state residual matrix for this observation.
* @param propagator Propagator to compare against.
* @throws Not implemented.
*/
abstract residual(propagator: Propagator): Matrix;
/**
* Convert this observation's noise matrix into a covariance matrix.
* @returns A matrix representing the noise covariance.
*/
noiseCovariance(): Matrix;
/**
* Generates a noise sample from the noise covariance matrix.
* @param sigma - The scaling factor for the noise covariance matrix.
* @returns A matrix representing the noise sample.
*/
noiseSample_(sigma: number): Matrix;
/**
* Randomly sample this observation in vector form within the
* observation noise.
* @param random Random number generator.
* @param sigma Sigma value to scale the noise by.
* @returns Sampled observation.
*/
sampleVector(random: RandomGaussianSource, sigma: number): Vector;
/**
* Randomly sample this observation within the observation noise, scaled to
* the provided sigma value.
* @param random Random number generator.
* @param sigma Sigma value to scale the noise by.
* @throws Not implemented.
*/
abstract sample(random: RandomGaussianSource, sigma: number): Observation;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
declare class ObservationRadar extends Observation {
private readonly site_;
observation: RAE;
private readonly noise_;
constructor(site_: J2000, observation: RAE, noise_?: Matrix);
private static readonly defaultNoise;
get epoch(): EpochUTC;
get site(): J2000;
get noise(): Matrix;
toVector(): Vector;
clos(propagator: Propagator): number;
ricDiff(propagator: Propagator): Vector3D;
sample(random: RandomGaussianSource, sigma?: number): Observation;
jacobian(propPairs: PropagatorPairs): Matrix;
residual(propagator: Propagator): Matrix;
/**
* Create a noise matrix from the range, azimuth, and elevation standard
* deviations _(kilometers/radians)_.
* @param rngSigma - The range standard deviation _(kilometers)_.
* @param azSigma - The azimuth standard deviation _(radians)_.
* @param elSigma - The elevation standard deviation _(radians)_.
* @returns The noise matrix.
*/
static noiseFromSigmas(rngSigma: Kilometers, azSigma: Radians, elSigma: Radians): Matrix;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Union type representing valid sensor platforms.
* Sensors can be mounted on ground objects (stations) or space objects (satellites).
*/
type SensorPlatform = GroundObject | SpaceObject;
/**
* Parameters for constructing a Sensor.
*/
interface SensorParams {
/** Unique identifier for the sensor */
id: number;
/** Human-readable name */
name: string;
/** Type of sensor */
sensorType: SensorType;
/** Field of view constraints */
fieldOfView: FieldOfViewParams;
/** Short name or abbreviation */
shortName?: string;
/** Sensor system identifier */
system?: string;
/** Country of operation */
country?: string;
/** Operating organization */
operator?: string;
/** Dwell time for target acquisition */
dwellTime?: Milliseconds;
/** Frequency band (for RF sensors) */
freqBand?: string;
/** Whether sensor is volumetric */
isVolumetric?: boolean;
/** URL for more information */
url?: string;
/** Additional metadata */
metadata?: Record;
}
/**
* Serialized representation of a sensor.
*/
interface SerializedSensor {
id: number;
name: string;
sensorType: SensorType;
fieldOfView: ReturnType;
shortName?: string;
system?: string;
country?: string;
operator?: string;
dwellTime?: Milliseconds;
freqBand?: string;
isVolumetric?: boolean;
url?: string;
metadata?: Record;
[key: string]: unknown;
}
/**
* Abstract base class for all sensor types.
*
* Sensors are components that attach to platforms (ground stations or satellites)
* rather than being location-based objects themselves. Position is delegated to
* the parent platform.
*
* @example
* ```typescript
* // Create a sensor attached to a ground station
* const radar = new PhasedArrayRadar({
* id: 'eglin-radar',
* name: 'Eglin SSPARS',
* sensorType: SensorType.PHASED_ARRAY_RADAR,
* fieldOfView: { ... },
* });
*
* groundStation.addSensor(radar);
* radar.setParent(groundStation);
*
* // Check if satellite is in FOV
* if (radar.canObserve(satellite)) {
* const observation = radar.observe(satellite);
* }
* ```
*/
declare abstract class Sensor {
/** Unique identifier */
readonly id: number;
/** Human-readable name */
name: string;
/** Type of sensor */
readonly sensorType: SensorType;
/** Field of view constraints */
fieldOfView: FieldOfView;
/** Short name or abbreviation */
shortName?: string;
/** Sensor system identifier */
system?: string;
/** Country of operation */
country?: string;
/** Operating organization */
operator?: string;
/** Dwell time for target acquisition */
dwellTime?: Milliseconds;
/** Frequency band (for RF sensors) */
freqBand?: string;
/** Whether sensor is volumetric */
isVolumetric?: boolean;
/** URL for more information */
url?: string;
/** Additional metadata */
metadata?: Record;
/** Parent platform this sensor is attached to */
private parent_?;
constructor(params: SensorParams);
/**
* Gets the parent platform this sensor is attached to.
* @throws {ValidationError} If sensor has no parent assigned
*/
get parent(): SensorPlatform;
/**
* Sets the parent platform for this sensor.
* @param platform - The ground object or space object to attach to
*/
setParent(platform: SensorPlatform): void;
/**
* Checks if this sensor has a parent platform assigned.
*/
hasParent(): boolean;
/**
* Validates that this sensor has a parent platform.
* Call at the start of methods that require a parent.
* @param methodName - Name of the calling method (for error context)
* @throws {ValidationError} If no parent is assigned
*/
protected requireParent(methodName: string): SensorPlatform;
/**
* Gets the sensor's position in J2000 coordinates.
* Delegates to the parent platform.
* @param date - Time for position calculation (defaults to now)
* @returns J2000 state vector
* @throws {ValidationError} If sensor has no parent platform assigned
*/
getJ2000(date?: Date): J2000;
/**
* Checks if RAE coordinates are within the sensor's field of view.
* @param rae - Range, azimuth, elevation coordinates
* @returns True if within FOV
*/
isInFov(rae: RaeVec3): boolean;
/**
* Checks if a target can be observed by this sensor at the given time.
* @param target - The space object to check
* @param date - Time for the calculation (defaults to now)
* @returns True if target is in FOV
*/
canObserve(target: SpaceObject, date?: Date): boolean;
/**
* Gets the RAE (Range, Azimuth, Elevation) of a target relative to this sensor.
* @param target - The space object to observe
* @param date - Time for the calculation (defaults to now)
* @returns RAE coordinates or null if calculation fails
* @throws {ValidationError} If sensor has no parent platform assigned
*/
getRae(target: SpaceObject, date?: Date): RaeVec3 | null;
/**
* Calculates satellite passes over a planning interval.
* Identifies when a satellite enters and exits the sensor's FOV.
*
* @param target - The satellite to track
* @param planningInterval - Duration in seconds to plan
* @param date - Start time (defaults to now)
* @example
* ```typescript
* import { Sensor, Satellite, GroundObject, FieldOfView, PassType, Degrees, Kilometers } from 'ootk';
*
* // Create ground station with sensor
* const station = new GroundObject({
* lat: 40.0 as Degrees,
* lon: -75.0 as Degrees,
* alt: 0.1 as Kilometers,
* });
*
* const sensor = new Sensor({
* id: 'radar-1',
* name: 'Tracking Radar',
* fov: new FieldOfView({
* boresightEl: 45 as Degrees,
* halfAngle: 30 as Degrees,
* maxRange: 5000 as Kilometers,
* }),
* });
* sensor.setParent(station);
*
* // Find all passes in next 24 hours (86400 seconds)
* const passes = sensor.calculatePasses(satellite, 86400);
*
* // Process pass events
* passes.forEach(event => {
* if (event.type === PassType.ENTER) {
* console.log(`Pass starts at ${event.time.toISOString()}`);
* console.log(` AOS Az/El: ${event.az.toFixed(1)}° / ${event.el.toFixed(1)}°`);
* } else if (event.type === PassType.EXIT) {
* console.log(`Pass ends at ${event.time.toISOString()}`);
* console.log(` Max elevation: ${event.maxElPass?.toFixed(1)}°`);
* }
* });
* ```
* @returns Array of lookangle events (ENTER/EXIT with RAE data)
* @throws {ValidationError} If sensor has no parent platform assigned
*/
calculatePasses(target: Satellite, planningInterval: number, date?: Date): Lookangle[];
/**
* Creates an observation of a target space object.
* Each sensor type implements this to return the appropriate observation type.
* @param target - The space object to observe
* @param date - Time of observation (defaults to now)
* @returns Observation data or null if observation not possible
*/
abstract observe(target: SpaceObject, date?: Date): unknown | null;
/**
* Creates a deep copy of this sensor.
* The cloned sensor will not have a parent assigned.
* @returns A new Sensor instance with the same properties
*/
abstract clone(): Sensor;
/**
* Checks if this sensor is configured for deep space observation.
*/
isDeepSpace(): boolean;
/**
* Checks if this sensor is configured for near-Earth observation.
*/
isNearEarth(): boolean;
/**
* Creates a serializable representation of this sensor.
*/
serialize(): SerializedSensor;
/**
* Returns sensor-type-specific serialization data.
* Override in subclasses to add additional fields.
*/
protected serializeSpecific(): Record;
/**
* Returns a string representation of this sensor.
*/
toString(): string;
/**
* Determines the pass type based on current and previous visibility.
*/
private static getPassType_;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Parameters for constructing a RadarSensor.
*/
interface RadarSensorParams extends SensorParams {
/** Radar beamwidth in degrees */
beamwidth: Degrees;
/** Radar frequency band (e.g., "X-band", "S-band") */
frequency?: string;
/** Peak transmit power in watts */
peakPower?: number;
}
/**
* Abstract base class for radar sensors.
*
* Provides common radar functionality including beamwidth handling
* and default RAE-based observation generation.
*
* @example
* ```typescript
* // Concrete radar implementations extend this class
* class MyRadar extends RadarSensor {
* observe(target: SpaceObject, date?: Date): ObservationRadar | null {
* return super.observe(target, date);
* }
* }
* ```
*/
declare abstract class RadarSensor extends Sensor {
/** Radar beamwidth in degrees */
readonly beamwidth: Degrees;
/** Radar frequency band */
frequency?: string;
/** Peak transmit power in watts */
peakPower?: number;
constructor(params: RadarSensorParams);
/**
* Gets the beamwidth in radians.
*/
get beamwidthRad(): Radians;
/**
* Creates a radar observation (RAE) of a target.
* @param target - The space object to observe
* @param date - Time of observation (defaults to now)
* @returns ObservationRadar or null if target not in FOV
*/
observe(target: SpaceObject, date?: Date): ObservationRadar | null;
/**
* Creates a RAE observation without wrapping in ObservationRadar.
* Useful for simpler use cases that don't need the full observation class.
* @param target - The space object to observe
* @param date - Time of observation (defaults to now)
* @returns RAE or null if target not in FOV
*/
observeRae(target: SpaceObject, date?: Date): RAE | null;
/**
* Creates a RAE object from epoch and raw values.
* Convenience factory for creating observations programmatically.
* @param epoch - Observation epoch
* @param range - Range in kilometers
* @param azimuth - Azimuth in degrees
* @param elevation - Elevation in degrees
* @returns RAE observation
*/
protected createRae(epoch: EpochUTC, range: number, azimuth: Degrees, elevation: Degrees): RAE;
protected serializeSpecific(): Record;
/**
* Creates a deep copy of this radar sensor.
* The cloned sensor will not have a parent assigned.
* @returns A new RadarSensor instance with the same properties
*/
abstract clone(): RadarSensor;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Parameters for constructing a PhasedArrayRadar.
*/
interface PhasedArrayRadarParams extends RadarSensorParams {
/** Boresight azimuth angles for each face (degrees) */
boresightAz: Degrees[];
/** Boresight elevation angles for each face (degrees) */
boresightEl: Degrees[];
}
/**
* Phased array radar sensor with electronic beam steering.
*
* Supports multi-face configurations with UV coordinate transformations
* relative to boresight directions. Ported from the legacy RfSensor class.
*
* @example
* ```typescript
* const radar = new PhasedArrayRadar({
* id: 'pave-paws',
* name: 'PAVE PAWS',
* sensorType: SensorType.PHASED_ARRAY_RADAR,
* beamwidth: 2.0 as Degrees,
* boresightAz: [0 as Degrees, 180 as Degrees], // Two faces
* boresightEl: [45 as Degrees, 45 as Degrees],
* fieldOfView: { ... },
* });
*
* // Convert target Az/El to UV coordinates
* const uv = radar.uvFromAzEl(45 as Degrees, 30 as Degrees, 0);
* ```
*/
declare class PhasedArrayRadar extends RadarSensor {
/** Boresight azimuth angles for each face */
readonly boresightAz: Degrees[];
/** Boresight elevation angles for each face */
readonly boresightEl: Degrees[];
/** Number of radar faces */
readonly faceCount: number;
/** Field of view for each face */
readonly faceFovs: FieldOfView[];
constructor(params: PhasedArrayRadarParams);
/**
* Checks if RAE coordinates are within any face's field of view.
* @param rae - Range, azimuth, elevation coordinates
* @returns True if within any face's FOV
*/
isInFov(rae: RaeVec3): boolean;
/**
* Gets the indices of faces that can see the given RAE coordinates.
* @param rae - Range, azimuth, elevation coordinates
* @returns Array of face indices where target is in FOV
*/
getFacesInFov(rae: RaeVec3): number[];
/**
* Converts azimuth and elevation angles to UV coordinates relative to boresight.
*
* UV coordinates represent the angular deviation from the radar's boresight
* direction, normalized by the beamwidth.
*
* @param az - Azimuth angle in degrees
* @param el - Elevation angle in degrees
* @param face - Face number (0-indexed), defaults to 0
* @returns UV coordinates { u, v }
* @throws Error if face number is invalid
*/
uvFromAzEl(az: Degrees, el: Degrees, face?: number): {
u: number;
v: number;
};
/**
* Converts UV coordinates back to azimuth and elevation angles.
*
* @param u - U coordinate
* @param v - V coordinate
* @param face - Face number (0-indexed), required for multi-face sensors
* @returns Az/El in degrees { az, el }
* @throws Error if face number not specified for multi-face sensors
*/
azElFromUV(u: number, v: number, face?: number): {
az: Degrees;
el: Degrees;
};
/**
* Gets the boresight azimuth in radians for the specified face.
* @param face - Face number (0-indexed)
* @returns Boresight azimuth in radians
*/
boresightAzRad(face?: number): Radians;
/**
* Gets the boresight elevation in radians for the specified face.
* @param face - Face number (0-indexed)
* @returns Boresight elevation in radians
*/
boresightElRad(face?: number): Radians;
/**
* Generates an RUV (Range-U-V) observation vector for a target.
*
* RUV observations are commonly used in radar tracking as they
* linearize near the boresight direction.
*
* @param range - Range to target in kilometers
* @param az - Azimuth to target in degrees
* @param el - Elevation to target in degrees
* @param face - Face number for multi-face radar (defaults to 0)
* @returns RUV vector { rng, u, v }
*/
generateRuv(range: Kilometers, az: Degrees, el: Degrees, face?: number): RuvVec3;
/**
* Converts RUV observation back to RAE (Range-Azimuth-Elevation).
*
* @param ruv - RUV observation vector
* @param face - Face number for multi-face radar
* @returns RAE values { rng, az, el }
*/
ruvToRae(ruv: RuvVec3, face?: number): {
rng: Kilometers;
az: Degrees;
el: Degrees;
};
/**
* Determines which face(s) can see a target at the given azimuth/elevation.
*
* A face can see a target if the angular deviation from its boresight
* is within some multiple of the beamwidth (typically 60° for phased arrays).
*
* @param az - Target azimuth in degrees
* @param el - Target elevation in degrees
* @param maxAngle - Maximum angle from boresight in degrees (default: 60°)
* @returns Array of face indices that can see the target
*/
getVisibleFaces(az: Degrees, el: Degrees, maxAngle?: Degrees): number[];
/**
* Gets the face with the smallest angular deviation from the target.
* @param az - Target azimuth in degrees
* @param el - Target elevation in degrees
* @returns Best face index, or -1 if no face is within 90° of target
*/
getBestFace(az: Degrees, el: Degrees): number;
protected serializeSpecific(): Record;
/**
* Creates a deep copy of this phased array radar.
* The cloned sensor will not have a parent assigned.
* @returns A new PhasedArrayRadar instance with the same properties
*/
clone(): PhasedArrayRadar;
toString(): string;
/**
* Validates that a face index is within bounds.
*/
private validateFace_;
}
/**
* Converts ECEF (Earth-Centered Earth-Fixed) to TEME (True Equator Mean Equinox) coordinates.
*
* **Coordinate Frame Transformation: ECEF → TEME**
*
* This is a simplified transformation that rotates by GMST (Greenwich Mean Sidereal Time)
* around the Z-axis. It does not account for precession, nutation, or polar motion.
*
* For high-precision transformations, use the ITRF class methods instead.
*
* [X] [C -S 0][X]
* [Y] = [S C 0][Y]
* [Z]eci [0 0 1][Z]ecef
*
* @param ecef - ECEF coordinates (Earth-fixed)
* @param gmst - Greenwich Mean Sidereal Time in radians
* @returns TEME coordinates (inertial)
*/
declare function ecef2eci(ecef: EcefVec3, gmst: number): TemeVec3;
/**
* Converts ECEF coordinates to ENU coordinates.
* @param ecef - The ECEF coordinates.
* @param lla - The LLA coordinates.
* @returns The ENU coordinates.
*/
declare function ecef2enu(ecef: EcefVec3, lla: LlaVec3): EnuVec3;
/**
* Converts TEME (True Equator Mean Equinox) to ECEF (Earth-Centered Earth-Fixed) coordinates.
*
* **Coordinate Frame Transformation: TEME → ECEF**
*
* This is a simplified transformation that rotates by GMST (Greenwich Mean Sidereal Time)
* around the Z-axis. It does not account for precession, nutation, or polar motion.
*
* For high-precision transformations, use J2000.toITRF() instead.
*
* [X] [C S 0][X]
* [Y] = [-S C 0][Y]
* [Z]ecef [0 0 1][Z]eci
*
* @param eci - TEME coordinates (inertial, from SGP4)
* @param gmst - Greenwich Mean Sidereal Time in radians
* @returns ECEF coordinates (Earth-fixed)
*/
declare function eci2ecef(eci: TemeVec3, gmst: number): EcefVec3;
/**
* Converts TEME (True Equator Mean Equinox) coordinates to geodetic (lat/lon/alt) coordinates.
*
* **Coordinate Frame Transformation: TEME → Geodetic (WGS84)**
*
* Internally converts TEME to ECEF via GMST rotation, then iteratively solves
* for geodetic latitude on the WGS84 ellipsoid.
*
* @variation cached - results are cached
* @param eci - TEME coordinates (inertial, from SGP4)
* @param gmst - Greenwich Mean Sidereal Time in radians
* @returns Geodetic coordinates (lat/lon in degrees, alt in km on WGS84)
*/
declare function eci2lla(eci: TemeVec3, gmst: number): LlaVec3;
/**
* Converts geodetic coordinates (longitude, latitude, altitude) to Earth-Centered Earth-Fixed (ECEF) coordinates.
* @param lla The geodetic coordinates in radians and meters.
* @returns The ECEF coordinates in meters.
*/
declare function llaRad2ecef(lla: LlaVec3): EcefVec3;
/**
* Converts geodetic coordinates (longitude, latitude, altitude) to Earth-Centered Earth-Fixed (ECEF) coordinates.
* @param lla The geodetic coordinates in degrees and meters.
* @returns The ECEF coordinates in meters.
*/
declare function lla2ecef(lla: LlaVec3): EcefVec3;
/**
* Converts geodetic coordinates (lat/lon/alt) to TEME (True Equator Mean Equinox) coordinates.
*
* **Coordinate Frame Transformation: Geodetic → TEME**
*
* Converts WGS84 geodetic coordinates to inertial TEME coordinates via ECEF
* and GMST rotation. Uses spherical Earth approximation (Earth.radiusMean).
*
* @variation cached - results are cached
* @param lla - Geodetic coordinates (lat/lon in radians, alt in km)
* @param gmst - Greenwich Mean Sidereal Time in radians
* @returns TEME coordinates (inertial)
*/
declare function lla2eci(lla: LlaVec3, gmst: GreenwichMeanSiderealTime): TemeVec3;
/**
* Converts LLA to SEZ coordinates.
* @see http://www.celestrak.com/columns/v02n02/
* @param lla The LLA coordinates.
* @param ecef The ECEF coordinates.
* @returns The SEZ coordinates.
*/
declare function lla2sez(lla: LlaVec3, ecef: EcefVec3): SezVec3;
/**
* Converts a vector in Right Ascension, Elevation, and Range (RAE) coordinate system
* to a vector in South, East, and Zenith (SEZ) coordinate system.
* @param rae The vector in RAE coordinate system.
* @returns The vector in SEZ coordinate system.
*/
declare function rae2sez(rae: RaeVec3): SezVec3;
/**
* Converts a vector in Right Ascension, Elevation, and Range (RAE) coordinate system
* to Earth-Centered Earth-Fixed (ECEF) coordinate system.
* @template D - The dimension of the RAE vector.
* @template A - The dimension of the LLA vector.
* @param rae - The vector in RAE coordinate system.
* @param lla - The vector in LLA coordinate system.
* @returns The vector in ECEF coordinate system.
*/
declare function rae2ecef(rae: RaeVec3, lla: LlaVec3): EcefVec3;
/**
* Converts a vector from RAE (Range, Azimuth, Elevation) coordinates to ECI (Earth-Centered Inertial) coordinates.
* @variation cached - results are cached
* @param rae The vector in RAE coordinates.
* @param lla The vector in LLA (Latitude, Longitude, Altitude) coordinates.
* @param gmst The Greenwich Mean Sidereal Time.
* @returns The vector in ECI coordinates.
*/
declare function rae2eci(rae: RaeVec3, lla: LlaVec3, gmst: number): TemeVec3;
/**
* Converts a vector in RAE (Range, Azimuth, Elevation) coordinates to ENU (East, North, Up) coordinates.
* @param rae - The vector in RAE coordinates.
* @returns The vector in ENU coordinates.
*/
declare function rae2enu(rae: RaeVec3): EnuVec3;
/**
* Converts South, East, and Zenith (SEZ) coordinates to Right Ascension, Elevation, and Range (RAE) coordinates.
* @param sez The SEZ coordinates.
* @returns Rng, Az, El array
*/
declare function sez2rae(sez: SezVec3): RaeVec3;
/**
* Converts Earth-Centered Earth-Fixed (ECEF) coordinates to Right Ascension (RA),
* Elevation (E), and Azimuth (A) coordinates.
* @param lla The Latitude, Longitude, and Altitude (LLA) coordinates.
* @param ecef The Earth-Centered Earth-Fixed (ECEF) coordinates.
* @returns The Right Ascension (RA), Elevation (E), and Azimuth (A) coordinates.
*/
declare function ecefRad2rae(lla: LlaVec3, ecef: EcefVec3): RaeVec3;
/**
* Converts Earth-Centered Earth-Fixed (ECEF) coordinates to Right Ascension (RA),
* Elevation (E), and Azimuth (A) coordinates.
* @variation cached - results are cached
* @param lla The Latitude, Longitude, and Altitude (LLA) coordinates.
* @param ecef The Earth-Centered Earth-Fixed (ECEF) coordinates.
* @returns The Right Ascension (RA), Elevation (E), and Azimuth (A) coordinates.
*/
declare function ecef2rae(lla: LlaVec3, ecef: EcefVec3): RaeVec3;
declare const jday: (year?: number, mon?: number, day?: number, hr?: number, minute?: number, sec?: number) => number;
/**
* Calculates the Greenwich Mean Sidereal Time (GMST) for a given date.
* @param date - The date for which to calculate the GMST.
* @returns An object containing the GMST value and the Julian date.
*/
declare function calcGmst(date: Date): {
gmst: GreenwichMeanSiderealTime;
j: number;
};
/**
* Converts ECI coordinates to RAE (Right Ascension, Azimuth, Elevation) coordinates.
* @variation cached - results are cached
* @param now - Current date and time.
* @param eci - ECI coordinates of the satellite.
* @param observer - Ground object or LLA coordinates of the observer.
* @returns Object containing azimuth, elevation and range in degrees and kilometers respectively.
*/
declare function eci2rae(now: Date, eci: TemeVec3, observer: GroundObject | LlaVec3): RaeVec3;
/**
* Calculates the inertial azimuth of a satellite given its latitude and inclination.
* @param lat - The latitude of the satellite in degrees.
* @param inc - The inclination of the satellite in degrees.
* @returns The inertial azimuth of the satellite in degrees.
*/
declare function calcInertAz(lat: Degrees, inc: Degrees): Degrees;
/**
* Calculates the inclination angle of a satellite from its launch azimuth and latitude.
* @param lat - The latitude of the observer in degrees.
* @param az - The launch azimuth angle of the satellite in degrees clockwise from north.
* @returns The inclination angle of the satellite in degrees.
*/
declare function calcIncFromAz(lat: number, az: number): number;
/**
* Converts Azimuth and Elevation to U and V.
* Azimuth is the angle off of boresight in the horizontal plane.
* Elevation is the angle off of boresight in the vertical plane.
* Cone half angle is the angle of the cone of the radar max field of view.
* @param az - Azimuth in radians
* @param el - Elevation in radians
* @param coneHalfAngle - Cone half angle in radians
* @returns U and V in radians
*/
declare function azel2uv(az: Radians, el: Radians, coneHalfAngle: Radians): {
u: number;
v: number;
};
/**
* Determine azimuth and elevation off of boresight based on sensor orientation and RAE.
* @param rae Range, Azimuth, Elevation
* @param sensor Phased array radar sensor object
* @param face Face number of the sensor
* @param maxSensorAz Maximum sensor azimuth
* @returns Azimuth and Elevation off of boresight
*/
declare function rae2raeOffBoresight(rae: RaeVec3, sensor: PhasedArrayRadar, face: number, maxSensorAz: Degrees): {
az: Radians;
el: Radians;
};
/**
* Converts Range Az El to Range U V.
* @param rae Range, Azimuth, Elevation
* @param sensor Phased array radar sensor object
* @param face Face number of the sensor
* @param maxSensorAz Maximum sensor azimuth
* @returns Range, U, V
*/
declare function rae2ruv(rae: RaeVec3, sensor: PhasedArrayRadar, face: number, maxSensorAz: Degrees): RuvVec3;
/**
* Converts U and V to Azimuth and Elevation off of boresight.
* @param u The U coordinate.
* @param v The V coordinate.
* @param coneHalfAngle The cone half angle of the radar.
* @returns Azimuth and Elevation off of boresight.
*/
declare function uv2azel(u: number, v: number, coneHalfAngle: Radians): {
az: Radians;
el: Radians;
};
/**
* Converts coordinates from East-North-Up (ENU) to Right-Front-Up (RF) coordinate system.
* @param enu - The ENU coordinates to be converted.
* @param enu.x - The east coordinate.
* @param enu.y - The north coordinate.
* @param enu.z - The up coordinate.
* @param az - The azimuth angle in radians.
* @param el - The elevation angle in radians.
* @returns The converted RF coordinates.
*/
declare function enu2rf({ x, y, z }: EnuVec3, az: A, el: A): RfVec3;
/**
* Full circle in radians (PI * 2)
*
* https://tauday.com/tau-manifesto
*/
declare const TAU: Radians;
/**
* Represents half of the mathematical constant PI.
*/
declare const halfPi: Radians;
/**
* Converts degrees to radians.
*/
declare const DEG2RAD: Radians;
/**
* Converts radians to degrees.
*/
declare const RAD2DEG: Degrees;
/**
* Conversion factor from seconds to degrees.
*/
declare const sec2deg: Degrees;
/**
* Conversion factor from seconds to days.
*/
declare const sec2day: number;
/**
* Conversion factor from arcseconds to radians.
*/
declare const asec2rad: Radians;
/**
* Convert ten-thousandths of an arcsecond to radians.
*/
declare const ttasec2rad: Radians;
/**
* Convert milliarcseconds to radians.
*/
declare const masec2rad: Radians;
/**
* The angular velocity of the Earth in radians per second.
*/
declare const angularVelocityOfEarth = 0.00007292115;
/**
* Astronomical unit in kilometers.
*/
declare const KM_PER_AU = 149597870;
declare const msec2sec: Seconds;
declare const cMPerSec = 299792458;
declare const cKmPerSec: number;
declare const cKmPerMs: number;
declare const MS_PER_DAY = 86400000;
declare const secondsPerDay = 86400;
declare const sec2min: Minutes;
declare const secondsPerSiderealDay = 86164.0905;
declare const secondsPerWeek: number;
/**
* Half the number of radians in a circle.
*/
declare const PI: Radians;
declare const x2o3: number;
declare const temp4 = 1.5e-12;
/**
* The number of minutes in a day.
*/
declare const MINUTES_PER_DAY: Minutes;
/**
* The number of milliseconds in a day.
*/
declare const MILLISECONDS_TO_DAYS = 1.15741e-8;
/**
* The number of milliseconds in a day.
*/
declare const MILLISECONDS_PER_DAY: number;
/**
* The number of milliseconds in a second.
*/
declare const MILLISECONDS_PER_SECOND: Milliseconds;
declare const RADIUS_OF_EARTH = 6371;
declare const earthGravityParam = 398600.4415;
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/** Covariance Frame */
declare enum CovarianceFrame {
/** Earth-centered inertial */
ECI = "eci",
/** Radial-Intrack-Crosstrack */
RIC = "ric"
}
declare class StateCovariance {
matrix: Matrix;
frame: CovarianceFrame;
/**
* Create a new [StateCovariance] object given its covariance [matrix] and
* [CovarianceFrame].
* @param matrix The covariance matrix.
* @param frame The covariance frame.
* @returns A new [StateCovariance] object.
*/
constructor(matrix: Matrix, frame: CovarianceFrame);
static fromSigmas(sigmas: number[], frame: CovarianceFrame): StateCovariance;
/**
* Calculates the standard deviations (sigmas) of each element in the covariance matrix.
* @returns A vector containing the standard deviations of each element in the covariance matrix.
*/
sigmas(): Vector;
}
/**
* Creates a 6x6 state covariance matrix from a TLE
* @param tleLine1 The first line of the TLE
* @param tleLine2 The second line of the TLE
* @param frame The covariance frame (CovarianceFrame.ECI or CovarianceFrame.RIC)
* @param sigmaScale Scaling factor for the sigmas (default: 1.0)
* @returns A StateCovariance object containing the 6x6 covariance matrix
*/
declare function createCovarianceFromTle(tleLine1: string, tleLine2: string, frame?: CovarianceFrame, sigmaScale?: number): StateCovariance;
/**
* Creates a sample-based covariance from a TLE with more realistic uncertainties
* @param tleLine1 The first line of the TLE
* @param tleLine2 The second line of the TLE
* @param frame The covariance frame (CovarianceFrame.ECI or CovarianceFrame.RIC)
* @returns A StateCovariance object
*/
declare function createSampleCovarianceFromTle(tleLine1: string, tleLine2: string, frame?: CovarianceFrame): StateCovariance;
/**
* Build a position covariance for conjunction screening from a TLE.
*
* Starts from {@link createSampleCovarianceFromTle}, converts the radial,
* in-track and cross-track *variances* on the diagonal into 1-sigma values
* scaled by `confidenceLevel`, and caps each so a single bad TLE cannot produce
* an enormous covariance bubble. The capped sigmas are written to the [0][0]
* (radial), [1][1] (cross-track) and [2][2] (in-track) diagonal slots; all
* other matrix terms are preserved.
*
* Note the cross-track / in-track slots are intentionally swapped relative to
* the source RIC ordering. The original sigmas are cached before any write so
* the swap reads source values, not values it just overwrote.
* @param tleLine1 First line of the TLE
* @param tleLine2 Second line of the TLE
* @param confidenceLevel Sigma multiplier (e.g. settingsManager.covarianceConfidenceLevel)
* @param caps Optional [radial, crossTrack, inTrack] sigma caps in km
* @returns A StateCovariance in the ECI frame, or a safe fallback if the
* TLE-based computation fails or yields a degenerate diagonal.
*/
declare function cappedScreeningCovarianceFromTle(tleLine1: string, tleLine2: string, confidenceLevel: number, caps?: readonly [number, number, number]): StateCovariance;
/**
* Converts magnitude to decibels.
* @param magnitude - The magnitude to convert (must be positive).
* @returns The value in decibels.
* @throws Error if magnitude is not positive.
* @example
* ```typescript
* const db = mag2db(1000); // Returns 30
* const db2 = mag2db(100); // Returns 20
* ```
*/
declare function mag2db(magnitude: number): number;
/**
* Calculates the relative velocity between two velocity vectors.
* @param vel1 - First velocity vector in km/s.
* @param vel2 - Second velocity vector in km/s.
* @returns The magnitude of the relative velocity in km/s.
* @example
* ```typescript
* const v1 = { x: 7.0, y: 0.5, z: 0.1 };
* const v2 = { x: 6.8, y: 0.6, z: 0.2 };
* const relVel = relativeVelocity(v1, v2); // ~0.24 km/s
* ```
*/
declare function relativeVelocity(vel1: Vec3, vel2: Vec3): T;
/**
* Shape type for RCS estimation.
*/
type RcsShape = 'sphere' | 'cylinder' | 'cone' | 'hexagon' | 'cube';
/**
* Estimates the Radar Cross Section (RCS) of an object based on its dimensions and shape.
* @param length - Length in meters.
* @param width - Width in meters.
* @param height - Height in meters.
* @param shape - The shape type ('sphere', 'cylinder', 'cone', 'hexagon', 'cube').
* @returns Estimated RCS in square meters.
* @example
* ```typescript
* const rcs = estimateRcs(2.0, 1.5, 1.5, 'cylinder');
* console.log(`Estimated RCS: ${rcs.toFixed(2)} m²`);
* ```
*/
declare function estimateRcs(length: number, width: number, height: number, shape: string): number;
/**
* Calculates the factorial of a given number.
* @param n - The number to calculate the factorial for.
* @returns The factorial of the given number.
*/
declare function factorial(n: number): number;
/**
* Calculates the base 10 logarithm of a number.
* @param x - The number to calculate the logarithm for.
* @returns The base 10 logarithm of the input number.
*/
declare function log10(x: number): number;
/**
* Calculates the hyperbolic secant of a number.
* @param x - The number to calculate the hyperbolic secant of.
* @returns The hyperbolic secant of the given number.
*/
declare function sech(x: number): number;
/**
* Calculates the hyperbolic cosecant of a number.
* @param x - The number for which to calculate the hyperbolic cosecant.
* @returns The hyperbolic cosecant of the given number.
*/
declare function csch(x: number): number;
/**
* Returns the inverse hyperbolic cosecant of a number.
* @param x - The number to calculate the inverse hyperbolic cosecant of.
* @returns The inverse hyperbolic cosecant of the given number.
*/
declare function acsch(x: number): number;
/**
* Calculates the inverse hyperbolic secant (asech) of a number.
* @param x - The number to calculate the inverse hyperbolic secant of.
* @returns The inverse hyperbolic secant of the given number.
*/
declare function asech(x: number): number;
/**
* Calculates the inverse hyperbolic cotangent (acoth) of a number.
* @param x - The number to calculate the acoth of.
* @returns The inverse hyperbolic cotangent of the given number.
*/
declare function acoth(x: number): number;
/**
* Copies the sign of the second number to the first number.
* @param mag - The magnitude of the number.
* @param sgn - The sign of the number.
* @returns The number with the magnitude of `mag` and the sign of `sgn`.
*/
declare function copySign(mag: number, sgn: number): number;
/**
* Evaluates a polynomial function at a given value.
* @param x - The value at which to evaluate the polynomial.
* @param coeffs - The coefficients of the polynomial.
* @returns The result of evaluating the polynomial at the given value.
*/
declare function evalPoly(x: number, coeffs: Float64Array): number;
/**
* Concatenates two Float64Arrays into a new Float64Array.
* @param a - The first Float64Array.
* @param b - The second Float64Array.
* @returns A new Float64Array containing the concatenated values of `a` and `b`.
*/
declare function concat(a: Float64Array, b: Float64Array): Float64Array;
/**
* Calculates the angle in the half-plane that best matches the given angle.
* @param angle - The angle to be matched.
* @param match - The angle to be matched against.
* @returns The angle in the half-plane that best matches the given angle.
*/
declare function matchHalfPlane(angle: number, match: number): number;
/**
* Wraps an angle to the range [-π, π].
* @param theta - The angle to wrap.
* @returns The wrapped angle.
*/
declare function wrapAngle(theta: Radians): Radians;
/**
* Calculates the angular distance between two points on a sphere.
* @param lam1 The longitude of the first point.
* @param phi1 The latitude of the first point.
* @param lam2 The longitude of the second point.
* @param phi2 The latitude of the second point.
* @param method The method to use for calculating the angular distance. Defaults to AngularDistanceMethod.Cosine.
* @returns The angular distance between the two points.
* @throws Error if an invalid angular distance method is provided.
*/
declare function angularDistance(lam1: number, phi1: number, lam2: number, phi2: number, method?: AngularDistanceMethod): Radians;
/**
* Calculates the angular diameter of an object.
* @param diameter - The diameter of the object.
* @param distance - The distance to the object.
* @param method - The method used to calculate the angular diameter. Defaults to AngularDiameterMethod.Sphere.
* @returns The angular diameter of the object.
* @throws Error if an invalid angular diameter method is provided.
*/
declare function angularDiameter(diameter: number, distance: number, method?: AngularDiameterMethod): number;
/**
* Performs linear interpolation between two points.
* @param x - The x-coordinate to interpolate.
* @param x0 - The x-coordinate of the first point.
* @param y0 - The y-coordinate of the first point.
* @param x1 - The x-coordinate of the second point.
* @param y1 - The y-coordinate of the second point.
* @returns The interpolated y-coordinate corresponding to the given x-coordinate.
*/
declare function linearInterpolate(x: number, x0: number, y0: number, x1: number, y1: number): number;
/**
* Calculates the mean value of an array of numbers.
* @param values - The array of numbers.
* @returns The mean value of the numbers.
*/
declare function mean(values: number[]): number;
/**
* Calculates the standard deviation of an array of numbers.
* @param values - The array of numbers.
* @param isSample - Optional. Specifies whether the array represents a sample. Default is false.
* @returns The standard deviation of the array.
*/
declare function std(values: number[], isSample?: boolean): number;
/**
* Calculates the covariance between two arrays.
* @param a - The first array.
* @param b - The second array.
* @param isSample - Optional. Specifies whether the arrays represent a sample. Default is false.
* @returns The covariance between the two arrays.
*/
declare function covariance(a: number[], b: number[], isSample?: boolean): number;
/**
* Calculates the gamma function of a number.
* @param n - The input number.
* @returns The gamma function value.
*/
declare function gamma(n: number): number;
/**
* Calculates the eccentric anomaly (e0) and true anomaly (nu) using Newton's method
* for a given eccentricity (ecc) and mean anomaly (m).
* @param ecc - The eccentricity of the orbit.
* @param m - The mean anomaly.
* @returns An object containing the eccentric anomaly (e0) and true anomaly (nu).
*/
declare function newtonM(ecc: number, m: number): {
e0: number;
nu: number;
};
/**
* Calculates the eccentric anomaly (e0) and mean anomaly (m) using Newton's method
* for a given eccentricity (ecc) and true anomaly (nu).
* @param ecc - The eccentricity of the orbit.
* @param nu - The true anomaly.
* @returns An object containing the calculated eccentric anomaly (e0) and mean anomaly (m).
*/
declare function newtonNu(ecc: number, nu: number): {
e0: number;
m: Radians;
};
/**
* Creates a 2D array with the specified number of rows and columns, filled with the same given value.
* @template T The type of elements in the array.
* @param rows The number of rows in the 2D array.
* @param columns The number of columns in the 2D array.
* @param value The value to fill the array with.
* @returns The 2D array with the specified number of rows and columns, filled with the given value.
*/
declare function array2d(rows: number, columns: number, value: T): T[][];
/**
* Clamps a number between a minimum and maximum value.
* @param x The number to clamp.
* @param min The minimum value.
* @param max The maximum value.
* @returns The clamped number.
*/
declare function clamp(x: number, min: number, max: number): number;
/**
* Determines whether a given year is a leap year.
* @param dateIn The date to check.
* @returns `true` if the year is a leap year, `false` otherwise.
*/
declare function isLeapYear(dateIn: Date): boolean;
/**
* Calculates the day of the year for a given date.
* If no date is provided, the current date is used.
*
* This is sometimes referred to as the Jday, but is
* very different from the Julian day used in astronomy.
* @param date - The date for which to calculate the day of the year.
* @returns The day of the year as a number.
*/
declare function getDayOfYear(date?: Date): number;
/**
* Rounds a number to a specified number of decimal places.
* @param value - The number to round.
* @param places - The number of decimal places to round to.
* @returns The rounded number.
*/
declare function toPrecision(value: number, places: number): number;
/**
* Returns the sign of a number.
* @param value - The number to determine the sign of.
* @returns 1 if the number is positive, -1 if the number is negative.
*/
declare function sign(value: number): 1 | -1;
/**
* Converts a SpaceObjectType to a string representation.
* @param spaceObjType - The SpaceObjectType to convert.
* @returns The string representation of the SpaceObjectType.
*/
declare const spaceObjType2Str: (spaceObjType: SpaceObjectType) => string;
/**
* Calculates the Doppler factor for a given location, position, and velocity.
* The Doppler factor is a measure of the change in frequency or wavelength of a wave
* as observed by an observer moving relative to the source of the wave.
* @param location - The location vector of the observer.
* @param position - The position vector of the source.
* @param velocity - The velocity vector of the source.
* @returns The calculated Doppler factor.
*/
declare const dopplerFactor: (location: EcefVec3, position: EcefVec3, velocity: EcefVec3) => number;
/**
* Creates an array of numbers from start to stop (inclusive) with the specified step.
* @param start The starting number.
* @param stop The ending number.
* @param step The step value.
* @returns An array of numbers.
*/
declare function createVec(start: number, stop: number, step: number): number[];
/**
* Calculates the derivative of a differentiable function.
* @param f The differentiable function.
* @param h The step size for numerical differentiation. Default value is 1e-3.
* @returns The derivative function.
*/
declare function derivative(f: DifferentiableFunction, h?: number): DifferentiableFunction;
/**
* Calculates the Jacobian matrix of a given Jacobian function.
*
* The function calculates how small perturbations in each input variable affect all output variables,
* using a second-order accurate central difference approximation.
*
* In orbital mechanics applications, this matrix is essential for solving complex problems like
* orbit transfers, trajectory optimization, and precise orbital determination.
* @param f The Jacobian function.
* @param m The number of rows in the Jacobian matrix.
* @param x0 The initial values of the variables.
* @param step The step size for numerical differentiation (default: 1e-5).
* @returns The Jacobian matrix.
*/
declare const jacobian: (f: JacobianFunction, m: number, x0: Float64Array, step?: number) => Matrix;
/**
* Calculates the linear distance between two points in three-dimensional space.
* @param pos1 The first position.
* @param pos2 The second position.
* @returns The linear distance between the two positions in kilometers.
*/
declare function linearDistance(pos1: Vec3, pos2: Vec3): D;
/**
* @author Theodore Kruczek.
* @description Orbital Object ToolKit (ootk) is a collection of tools for working
* with satellites and other orbital objects.
*
* @license MIT License
*
* @Copyright (c) 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.
*/
/**
* Photometry helpers for estimating the apparent brightness of resident space
* objects from radar observables.
*/
/** Brightest standard magnitude the RCS estimator will report. */
declare const RCS_VMAG_ESTIMATE_MIN = -5;
/** Faintest standard magnitude the RCS estimator will report. */
declare const RCS_VMAG_ESTIMATE_MAX = 15;
/**
* Estimates a standard (intrinsic) visual magnitude from a radar cross
* section.
*
* Uses the common first-order approximation that reflected optical flux scales
* with the projected area a radar sees:
*
* vmag = -1.3 - 2.5 * log10(rcs)
*
* where `rcs` is in square meters. This assumes a diffuse sphere with an
* average albedo and ignores shape/material effects, so the result is only a
* coarse estimate. The output is clamped to
* [{@link RCS_VMAG_ESTIMATE_MIN}, {@link RCS_VMAG_ESTIMATE_MAX}] so degenerate
* radar cross sections cannot produce absurd magnitudes.
* @param rcs Radar cross section in square meters.
* @returns The estimated standard visual magnitude, or null when the RCS is
* not a finite positive number.
*/
declare function estimateVmagFromRcs(rcs: number): number | null;
/**
* @author 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-2026 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 .
*/
/**
* A generator of random bool, int, or double values.
*
* The default implementation supplies a stream of pseudo-random bits that are not suitable for cryptographic purposes.
*/
declare class Random {
private _seed;
constructor(seed?: number);
nextFloat(max?: number): number;
/**
* To create a non-negative random integer uniformly distributed in the range from 0,
* inclusive, to max, exclusive, use nextInt(int max).
* @param max The bound on the random number to be returned. Must be positive.
* @returns A pseudorandom, uniformly distributed int value between 0 (inclusive) and the specified value (exclusive).
*/
nextInt(max?: number): number;
nextBool(): boolean;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Parameters for constructing an AccessWindow.
*/
interface AccessWindowParams {
/** Start time of the access window */
start: Date;
/** End time of the access window */
end: Date;
/** Duration in milliseconds */
duration: number;
/** Maximum elevation achieved during the pass */
maxElevation: Degrees;
/** Time of maximum elevation */
maxElevationTime: Date;
/** Range at maximum elevation */
rangeAtMaxEl: Kilometers;
/** The observing ground object */
observer: GroundObject;
/** The observed space object */
target: SpaceObject;
}
/**
* Represents a single access window (visibility period) between
* a ground observer and a space object.
*/
declare class AccessWindow {
/** Start time of the access window */
readonly start: Date;
/** End time of the access window */
readonly end: Date;
/** Duration in milliseconds */
readonly duration: number;
/** Maximum elevation achieved during the pass */
readonly maxElevation: Degrees;
/** Time of maximum elevation */
readonly maxElevationTime: Date;
/** Range at maximum elevation */
readonly rangeAtMaxEl: Kilometers;
/** The observing ground object */
readonly observer: GroundObject;
/** The observed space object */
readonly target: SpaceObject;
constructor(params: AccessWindowParams);
/**
* Formats a Date as HH:MM:SS.
*/
private static formatTime_;
toString(): string;
}
/**
* Constraints for access window calculations.
* All constraints are optional - if omitted, default values are used.
*/
interface AccessConstraints {
/** Minimum elevation angle above horizon (default: 0°) */
minElevation?: Degrees;
/** Maximum slant range (default: unlimited) */
maxRange?: Kilometers;
/** Minimum slant range (default: 0) */
minRange?: Kilometers;
/** Require target to be sunlit (not in Earth's shadow) */
requireSunlit?: boolean;
/** Require observer to be in darkness (for optical observations) */
requireObserverDark?: boolean;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Static utility class for calculating access windows between
* ground observers and space objects.
*
* An access window is a period during which a space object is visible
* from a ground observer, subject to optional constraints such as
* minimum elevation, range limits, and illumination requirements.
*
* @example
* ```typescript
* // Find all passes over 24 hours
* const windows = AccessCalculator.calculateAccess(
* groundStation,
* satellite,
* new Date(),
* new Date(Date.now() + 86400000)
* );
*
* // Find next pass with constraints
* const nextPass = AccessCalculator.getNextAccess(
* groundStation,
* satellite,
* new Date(),
* { minElevation: 10 as Degrees, requireSunlit: true }
* );
* ```
*/
declare class AccessCalculator {
/** Default calculation time step in milliseconds (10 seconds) */
private static readonly DEFAULT_STEP_MS_;
/** Default max search duration in days */
private static readonly DEFAULT_MAX_SEARCH_DAYS_;
/** Milliseconds per day */
private static readonly MS_PER_DAY_;
/** Prevent instantiation */
private constructor();
/**
* Calculates all access windows between a ground observer and a space object
* within a specified time interval.
*
* @param observer - The ground-based observer
* @param target - The space object to track
* @param start - Start of the search interval
* @param end - End of the search interval
* @param constraints - Optional visibility constraints
* @param stepMs - Time step in milliseconds (default: 10000)
* @returns Array of access windows found within the interval
*/
static calculateAccess(observer: GroundObject, target: SpaceObject, start: Date, end: Date, constraints?: AccessConstraints, stepMs?: number): AccessWindow[];
/**
* Finds the next access window after a specified time.
*
* @param observer - The ground-based observer
* @param target - The space object to track
* @param after - Search for windows starting after this time
* @param constraints - Optional visibility constraints
* @param maxSearchDays - Maximum number of days to search (default: 7)
* @returns The next access window, or null if none found within search period
*/
static getNextAccess(observer: GroundObject, target: SpaceObject, after: Date, constraints?: AccessConstraints, maxSearchDays?: number): AccessWindow | null;
/**
* Calculates access windows for multiple targets from a single observer.
*
* @param observer - The ground-based observer
* @param targets - Array of space objects to track
* @param start - Start of the search interval
* @param end - End of the search interval
* @param constraints - Optional visibility constraints (applied to all targets)
* @returns Map from target ID to array of access windows
*/
static calculateMultiTargetAccess(observer: GroundObject, targets: SpaceObject[], start: Date, end: Date, constraints?: AccessConstraints): Map;
/**
* Gets the Range-Azimuth-Elevation from observer to target at the given time.
* @internal
*/
private static getRae_;
/**
* Checks if the current observation meets all constraints.
* @internal
*/
private static isAccessible_;
/**
* Creates an AccessWindow from the current state.
* @internal
*/
private static createWindow_;
/**
* Resets the state for tracking a new access window.
* @internal
*/
private static resetState_;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Center body for ephemeris data.
* Extends beyond Earth to support interplanetary missions.
* Will be extended for AstronomyEngine integration in future.
*/
declare enum CenterBody {
EARTH = "EARTH",
MOON = "MOON",
SUN = "SUN",
MARS = "MARS",
MARS_BARYCENTER = "MARS_BARYCENTER",
JUPITER_BARYCENTER = "JUPITER_BARYCENTER",
SATURN_BARYCENTER = "SATURN_BARYCENTER"
}
/**
* Gravitational parameters (km³/s²) for supported bodies.
*/
declare const CenterBodyMu: Record;
/**
* Maps OEM CENTER_NAME strings to CenterBody enum.
* Handles various string formats from CCSDS OEM files.
* @param centerName - The CENTER_NAME value from OEM metadata
* @returns The corresponding CenterBody enum value, defaults to EARTH
*/
declare function parseCenterBody(centerName: string): CenterBody;
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Data for a single waypoint in a dynamic ground object's path.
*/
interface WaypointData {
/** The time at which the object is at this waypoint */
time: Date;
/** Latitude in degrees */
lat: Degrees;
/** Longitude in degrees */
lon: Degrees;
/** Altitude in kilometers */
alt: Kilometers;
/** Optional metadata associated with this waypoint */
metadata?: Record;
}
/**
* Interpolation method for calculating positions between waypoints.
* - 'linear': Simple linear interpolation of lat/lon/alt (fastest, least accurate)
* - 'greatCircle': Spherical linear interpolation along great circle path (recommended for surface objects)
* - 'spline': Cubic spline interpolation for smooth paths through all waypoints
*/
type GroundInterpolationMethod = 'linear' | 'greatCircle' | 'spline';
/**
* Parameters for constructing a DynamicGroundObject.
*/
interface DynamicGroundObjectParams extends Omit {
/** Array of waypoints defining the object's path */
waypoints: WaypointData[];
/** Interpolation method to use (defaults to 'greatCircle') */
interpolationMethod?: GroundInterpolationMethod;
/** Optional history configuration for position tracking */
historyConfig?: HistoryConfig;
}
/**
* Options for the DynamicGroundObject.clone() method.
*/
interface DynamicGroundObjectCloneOptions {
/** If true, clone history entries. If false (default), start with empty history but same config. */
cloneHistory?: boolean;
}
/**
* A ground object that moves along Earth's surface following a series of waypoints.
* Useful for tracking aircraft, ships, vehicles, or special events like Santa tracking.
*
* Unlike static GroundObject, DynamicGroundObject's position is time-dependent and
* must be queried with a specific time.
*
* @example
* ```typescript
* // Track Santa's journey
* const santa = new DynamicGroundObject({
* id: 'SANTA-2025',
* name: 'Santa Claus',
* waypoints: [
* { time: new Date('2025-12-24T22:00:00Z'), lat: 90 as Degrees, lon: 0 as Degrees, alt: 10 as Kilometers },
* { time: new Date('2025-12-24T23:00:00Z'), lat: 64.1 as Degrees, lon: -21.9 as Degrees, alt: 10 as Kilometers },
* ],
* interpolationMethod: 'greatCircle'
* });
*
* // Get position at specific time
* const position = santa.getLLA(new Date('2025-12-24T22:30:00Z'));
* ```
*/
declare class DynamicGroundObject extends GroundObject {
private waypoints_;
private interpolationMethod_;
private positionHistory_;
private splineCoeffs_;
constructor(params: DynamicGroundObjectParams);
/**
* Throws an error - use getLLA(time) for DynamicGroundObject.
* @throws Error always
*/
lla(): LlaVec3;
/**
* Throws an error - use getEcef(time) for DynamicGroundObject.
* @throws Error always
*/
ecef(): EcefVec3;
/**
* Throws an error - use getEci(time) for DynamicGroundObject.
* @throws Error always
*/
eci(): TemeVec3;
/**
* Gets the latitude, longitude, and altitude at a specific time.
* Interpolates between waypoints using the configured method.
* @param time - The time to get position for
* @returns Position as lat/lon/alt, or null if time is outside waypoint range
*/
getLLA(time: Date): LlaVec3 | null;
/**
* Gets the ECEF (Earth-Centered Earth-Fixed) position at a specific time.
* @param time - The time to get position for
* @returns ECEF position vector, or null if time is outside waypoint range
*/
getEcef(time: Date): EcefVec3 | null;
/**
* Gets the ECI (Earth-Centered Inertial) position at a specific time.
* @param time - The time to get position for
* @returns ECI position vector, or null if time is outside waypoint range
*/
getEci(time: Date): TemeVec3 | null;
/**
* Converts position at a specific time to J2000 inertial coordinates.
* Ground objects have zero velocity in the inertial frame (ignoring Earth rotation).
* @param time - The time for the conversion
* @returns J2000 state vector, or null if time is outside waypoint range
*/
getJ2000(time: Date): J2000 | null;
/**
* Converts position at a specific time to Geodetic coordinates.
* @param time - The time for the conversion
* @returns Geodetic position, or null if time is outside waypoint range
*/
getGeodetic(time: Date): Geodetic | null;
/**
* Gets the current position (using system time).
* @returns Current lat/lon/alt, or null if current time is outside waypoint range
*/
getCurrentLLA(): LlaVec3 | null;
/**
* Gets the current ECI position (using system time).
* @returns Current ECI position, or null if current time is outside waypoint range
*/
getCurrentEci(): TemeVec3 | null;
/**
* Adds a new waypoint to the path.
* Waypoints are automatically sorted by time.
* @param waypoint - The waypoint to add
*/
addWaypoint(waypoint: WaypointData): void;
/**
* Removes a waypoint at a specific time.
* @param time - The exact time of the waypoint to remove
* @returns true if a waypoint was removed, false otherwise
*/
removeWaypoint(time: Date): boolean;
/**
* Returns all waypoints (copy to prevent external modification).
*/
get waypoints(): WaypointData[];
/**
* Returns the number of waypoints.
*/
get waypointCount(): number;
/**
* Returns the start time of the waypoint path.
*/
get startTime(): Date;
/**
* Returns the end time of the waypoint path.
*/
get endTime(): Date;
/**
* Checks if a given time is within the waypoint path time range.
* @param time - The time to check
*/
isValidAt(time: Date): boolean;
/**
* Returns the total duration of the waypoint path in milliseconds.
*/
get duration(): number;
/**
* Enables position history tracking.
* @param config - History configuration options
*/
enableHistory(config?: HistoryConfig): void;
/**
* Disables position history tracking and clears existing history.
*/
disableHistory(): void;
/**
* Returns the position history, or null if not enabled.
* Note: This is separate from the base class history which tracks HistoricalState.
*/
get positionHistory(): History> | null;
/**
* Alias for positionHistory for API consistency with Satellite.
* Returns the position history (LLA), or null if not enabled.
*
* Note: Unlike Satellite.history which stores ECI state (position + velocity),
* DynamicGroundObject stores LLA positions since it moves along Earth's surface.
*
* @remarks
* This shadows the base class `history` property because the types are different.
* DynamicGroundObject tracks LLA coordinates while Satellite tracks ECI state.
*/
get history(): History> | null;
/**
* Returns true if position history tracking is enabled.
*/
get isHistoryEnabled(): boolean;
/**
* Override to prevent use of base class history recording.
* DynamicGroundObject uses recordPosition_ for LLA tracking instead.
*/
protected recordToHistory(_time: Date, _state: HistoricalState): void;
/**
* Returns recent positions as a trail.
* Uses history if enabled, otherwise samples from waypoints.
* @param maxPoints - Maximum number of points to return (defaults to 100)
* @returns Array of time/position pairs
*/
getTrail(maxPoints?: number): Array<{
time: Date;
lla: LlaVec3;
}>;
/**
* Returns the current interpolation method.
*/
get interpolationMethod(): GroundInterpolationMethod;
/**
* Sets the interpolation method.
* @param method - The new interpolation method
*/
set interpolationMethod(method: GroundInterpolationMethod);
isGroundObject(): boolean;
/**
* Creates a deep copy of this dynamic ground object.
*
* By default, history configuration is preserved but starts empty.
* Pass `{ cloneHistory: true }` to also clone the history entries.
*
* @param options - Clone options
*/
clone(options?: DynamicGroundObjectCloneOptions): DynamicGroundObject;
protected serializeSpecific(): Record;
/**
* Finds the two waypoints that bracket the given time.
*/
private findBracketingWaypoints_;
/**
* Interpolates position between two waypoints.
*/
private interpolate_;
/**
* Simple linear interpolation of lat/lon/alt.
*/
private linearInterpolate_;
/**
* Great circle (spherical linear) interpolation.
* Uses SLERP for accurate surface paths.
*/
private greatCircleInterpolate_;
/**
* Cubic spline interpolation for smooth paths.
*/
private splineInterpolate_;
/**
* Computes cubic spline coefficients for all segments.
* Uses natural cubic spline (second derivative = 0 at endpoints).
*/
private computeSplineCoefficients_;
/**
* Computes natural cubic spline coefficients for a series of values.
* Returns coefficients for each segment in the form [a, b, c, d] where
* f(u) = a + b*u + c*u^2 + d*u^3, u in [0, 1]
*/
private computeNaturalCubicSpline_;
/**
* Evaluates a cubic polynomial.
*/
private evalCubic_;
/**
* Unwraps longitudes to avoid discontinuities at -180/180 boundary.
*/
private unwrapLongitudes_;
/**
* Normalizes longitude to [-180, 180] range.
*/
private normalizeLongitude_;
/**
* Interpolates longitude with proper handling of -180/180 wrap.
*/
private interpolateLongitude_;
/**
* Calculates angular distance between two points using Haversine formula.
*/
private angularDistance_;
/**
* Records a position to history if enabled.
*/
private recordPosition_;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* OEM file header information from CCSDS format.
*/
interface OemHeader {
/** OEM version number */
CCSDS_OEM_VERS: string;
/** Creation date of the file */
CREATION_DATE: string;
/** Originator of the file */
ORIGINATOR: string;
/** Optional message identifier */
MESSAGE_ID?: string;
/** Optional classification */
CLASSIFICATION?: string;
/** Optional comment lines from header */
COMMENT?: string[];
}
/**
* OEM metadata block containing object and reference frame information.
*/
interface OemMetadata {
/** Name of the space object */
OBJECT_NAME: string;
/** International designator or catalog ID */
OBJECT_ID: string;
/** Center body name (e.g., 'EARTH', 'MARS BARYCENTER') */
CENTER_NAME: string;
/** Reference frame (e.g., 'EME2000', 'ICRF', 'TEME') */
REF_FRAME: string;
/** Time system (e.g., 'UTC', 'TDB') */
TIME_SYSTEM: string;
/** Start time of the data span */
START_TIME: string;
/** Stop time of the data span */
STOP_TIME: string;
/** Optional useable start time */
USEABLE_START_TIME?: string;
/** Optional useable stop time */
USEABLE_STOP_TIME?: string;
/** Optional interpolation method */
INTERPOLATION?: string;
/** Optional interpolation degree */
INTERPOLATION_DEGREE?: number;
/** Optional reference frame epoch */
REF_FRAME_EPOCH?: string;
/** Optional comment lines from metadata */
COMMENT?: string[];
/**
* User-defined parameters from CCSDS OEM USER_DEFINED_ keywords.
* @see CCSDS 502.0-B-3 Section 7.5.1
*/
USER_DEFINED?: Record;
}
/**
* Covariance matrix data from OEM file.
* Stores the lower triangular portion of a 6x6 covariance matrix.
*
* @deferred Full covariance processing deferred to future enhancement.
* Currently only parsed and stored, not processed.
*/
interface OemCovarianceMatrix {
/** Epoch of the covariance matrix */
epoch: Date;
/** Optional reference frame for covariance */
refFrame?: string;
/** 6x6 lower triangular matrix stored as 21 values */
values: number[];
}
/**
* A single OEM data block containing metadata and ephemeris.
*/
interface OemDataBlock {
/** Metadata for this block */
metadata: OemMetadata;
/** Array of J2000 state vectors */
ephemeris: J2000[];
/** Optional covariance data (parsed but not processed) */
covariance?: OemCovarianceMatrix[];
}
/**
* Fully parsed OEM file structure.
*/
interface ParsedOem {
/** File header information */
header: OemHeader;
/** Array of data blocks (one OEM file may contain multiple) */
dataBlocks: OemDataBlock[];
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Supported interpolator types for ephemeris satellites.
*
* Each type has different trade-offs:
* - LAGRANGE: General purpose, good accuracy, moderate speed
* - CHEBYSHEV: Compressed storage, very fast lookup, slightly reduced accuracy
* - CUBIC_SPLINE: Fast and accurate, higher memory usage
* - VERLET_BLEND: Physics-aware, highest accuracy, slowest
*/
declare enum InterpolatorType {
/** Lagrange polynomial interpolation (default) */
LAGRANGE = "lagrange",
/** Chebyshev polynomial interpolation (compressed) */
CHEBYSHEV = "chebyshev",
/** Cubic spline interpolation */
CUBIC_SPLINE = "cubic-spline",
/** Verlet blend interpolation (physics-aware) */
VERLET_BLEND = "verlet-blend"
}
/** Default interpolator type for EphemerisSatellite */
declare const DEFAULT_INTERPOLATOR = InterpolatorType.LAGRANGE;
/** Default Lagrange interpolation order */
declare const DEFAULT_LAGRANGE_ORDER = 10;
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Parameters for constructing an EphemerisSatellite.
*/
interface EphemerisSatelliteParams extends Omit {
/** Array of J2000 state vectors forming the ephemeris */
ephemeris: J2000[];
/** Center body for the ephemeris (defaults to EARTH) */
centerBody?: CenterBody;
/** Reference frame of the ephemeris data (defaults to J2000) */
referenceFrame?: 'J2000' | 'TEME';
/** Interpolator type to use (defaults to LAGRANGE) */
interpolatorType?: InterpolatorType;
/** Interpolation order for Lagrange (defaults to 10) */
interpolatorOrder?: number;
/** Optional metadata */
metadata?: Record;
}
/**
* A satellite with position determined by interpolation of pre-computed ephemeris data.
*
* Unlike TLE-based satellites that use SGP4 propagation, EphemerisSatellite stores
* a set of state vectors and interpolates between them to determine position at
* any given time within the coverage window.
*
* @example
* ```typescript
* // Create from OEM file
* const oemContent = fs.readFileSync('orbit.oem', 'utf-8');
* const parsed = OemParser.parse(oemContent);
* const sat = EphemerisSatellite.fromParsedOem(parsed);
*
* // Get position at specific time
* const state = sat.getJ2000(EpochUTC.fromDateTimeString('2024-06-15T12:00:00Z'));
* ```
*/
declare class EphemerisSatellite extends SpaceObject {
private readonly interpolator_;
private readonly interpolatorType_;
private readonly ephemeris_;
private readonly centerBody_;
private readonly referenceFrame_;
constructor(params: EphemerisSatelliteParams);
/**
* Create from parsed OEM data.
* @param oem - Parsed OEM structure
* @param options - Optional configuration
* @returns New EphemerisSatellite instance
*/
static fromParsedOem(oem: ParsedOem, options?: {
id?: number;
interpolatorType?: InterpolatorType;
}): EphemerisSatellite;
/**
* Create from raw ephemeris array (simple factory).
* @param name - Name for the satellite
* @param ephemeris - Array of J2000 state vectors
* @param options - Optional configuration
* @returns New EphemerisSatellite instance
*/
static fromEphemeris(name: string, ephemeris: J2000[], options?: {
id?: number;
centerBody?: CenterBody;
interpolatorType?: InterpolatorType;
}): EphemerisSatellite;
/**
* Returns the position and velocity in TEME frame at the given time.
* @param date - The time to calculate position for (defaults to now)
* @returns Position and velocity, or null if outside coverage window
*/
eci(date?: Date): PosVel | null;
/**
* Returns the ECEF position at the given time.
* @param date - The time to calculate position for (defaults to now)
*/
ecef(date?: Date): EcefVec3 | null;
/**
* Returns the geodetic position (lat/lon/alt) at the given time.
* @param date - The time to calculate position for (defaults to now)
*/
lla(date?: Date): LlaVec3 | null;
/**
* Get state in J2000 frame at given epoch.
* @param epoch - The epoch to interpolate at
* @returns J2000 state vector or null if outside coverage
*/
getJ2000(epoch: EpochUTC): J2000 | null;
/**
* Get state in TEME frame at given epoch.
* @param epoch - The epoch to interpolate at
* @returns TEME state vector or null if outside coverage
*/
getTEME(epoch: EpochUTC): TEME | null;
/**
* Returns J2000 coordinates at the given time.
* @param date - The time to calculate for (defaults to now)
* @throws Error if the date is outside the coverage window
*/
toJ2000(date?: Date): J2000;
/**
* Returns ITRF coordinates at the given time.
* @param date - The time to calculate for (defaults to now)
* @throws Error if the date is outside the coverage window
*/
toITRF(date?: Date): ITRF;
/**
* Returns classical orbital elements at the given time.
* @param date - The time to calculate for (defaults to now)
* @throws Error if the date is outside the coverage window
*/
toClassicalElements(date?: Date): ClassicalElements;
/**
* Returns the time window covered by the ephemeris data.
*/
get coverageWindow(): EpochWindow;
/**
* Check if a given epoch is within the coverage window.
* @param epoch - The epoch to check
*/
inCoverage(epoch: EpochUTC): boolean;
/** The center body for this ephemeris */
get centerBody(): CenterBody;
/** Gravitational parameter (km³/s²) for the center body */
get mu(): number;
/**
* Generate orbit path as Float32Array for WebGL rendering.
* Format: [x0, y0, z0, t0, x1, y1, z1, t1, ...] (4 floats per point)
*
* @param sampleCount - Number of points to generate
* @param startEpoch - Start of path (defaults to coverage start)
* @param endEpoch - End of path (defaults to coverage end)
* @returns Float32Array with position and time data
*/
getOrbitPath(sampleCount: number, startEpoch?: EpochUTC, endEpoch?: EpochUTC): Float32Array;
/**
* Get raw ephemeris points as Float32Array for WebGL.
* More efficient than interpolated path when original points suffice.
* Format: [x0, y0, z0, t0, x1, y1, z1, t1, ...] (4 floats per point)
*/
getEphemerisAsFloat32(): Float32Array;
/**
* Fast linear interpolation between adjacent ephemeris points.
* Use for real-time animation where speed > accuracy.
* For analysis, use getJ2000() which uses the configured StateInterpolator.
*
* @param epoch - The epoch to interpolate at
* @returns Position, velocity, and state vector index, or null if outside coverage
*/
getLinearInterpolatedState(epoch: EpochUTC): {
position: {
x: Kilometers;
y: Kilometers;
z: Kilometers;
};
velocity: {
x: KilometersPerSecond;
y: KilometersPerSecond;
z: KilometersPerSecond;
};
stateVectorIndex: number;
} | null;
private findBracketingIndex_;
/** Number of state vectors in the ephemeris */
get ephemerisLength(): number;
/**
* Get original ephemeris point closest to given epoch.
* Useful for accessing "truth" data without interpolation.
* @param epoch - The epoch to find the nearest point for
*/
getNearestEphemerisPoint(epoch: EpochUTC): J2000 | null;
/** Size in bytes of the interpolator's cached data */
get interpolatorSizeBytes(): number;
/**
* Creates a deep copy of this satellite.
* @param _options - Unused, provided for compatibility with base class
*/
clone(_options?: Record): EphemerisSatellite;
protected serializeSpecific(): Record;
toString(): string;
private createInterpolator_;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
interface LandObjectParams extends BaseObjectParams {
lat: Degrees;
lon: Degrees;
alt: Kilometers;
country?: string;
Code?: string;
}
declare class LandObject extends BaseObject {
readonly lat: Degrees;
readonly lon: Degrees;
readonly alt: Kilometers;
country?: string;
Code?: string;
constructor(info: LandObjectParams);
isLandObject(): boolean;
/**
* Returns type-specific serialization data.
*/
protected serializeSpecific(): Record;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
declare class Marker extends BaseObject {
isMarker(): boolean;
/**
* Returns type-specific serialization data.
*/
protected serializeSpecific(): Record;
}
/**
* @author 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-2026 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 .
*/
declare class Star extends BaseObject {
ra: Radians;
dec: Radians;
bf: string;
h: string;
pname: string;
vmag?: number;
constellation?: string;
colorTemp?: number;
hr?: number;
flamsteed?: string;
bayer?: string;
constructor(info: StarObjectParams);
eci(lla?: LlaVec3, date?: Date): TemeVec3;
rae(lla?: LlaVec3, date?: Date): RaeVec3;
/**
* Creates a deep copy of this star.
*/
clone(): Star;
/**
* Returns type-specific serialization data.
*/
protected serializeSpecific(): Record;
private static calculateTimeVariables_;
}
/**
* @author 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-2026 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
* 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 .
*/
/**
* A point on an orbit track with position, velocity, and altitude.
*/
interface OrbitTrackPoint {
time: Date;
position: TemeVec3;
velocity: TemeVec3;
altitude: Kilometers;
}
/**
* A point on a ground track with geodetic coordinates.
*/
interface GroundTrackPoint {
time: Date;
lat: Degrees;
lon: Degrees;
alt: Kilometers;
}
/**
* A point on a field of view boundary with cached ECEF coordinates.
* ECEF coordinates are cached for fast conversion to TEME at render time
* using `ecef2eci(point.ecef, gmst)`.
*/
interface FovBoundaryPoint {
az: Degrees;
el: Degrees;
range: Kilometers;
ecef: EcefVec3;
}
/**
* Static utility class for generating visualization data for satellites, ground tracks,
* and sensor fields of view.
*/
declare class VisualizationHelpers {
private constructor();
/**
* Converts history entries to a time series using an extractor function.
* @param history - The history object to convert
* @param extractor - Function to extract a value from each history entry
* @returns Array of time-value pairs
* @example
* ```typescript
* // Extract altitude over time
* const altitudes = VisualizationHelpers.historyToTimeSeries(
* satellite.history!,
* (entry) => Math.sqrt(
* entry.data.position.x ** 2 +
* entry.data.position.y ** 2 +
* entry.data.position.z ** 2
* ) - 6378.137 as Kilometers
* );
* ```
*/
static historyToTimeSeries(history: History, extractor: (entry: {
time: Date;
data: T;
}) => R): Array<{
time: Date;
value: R;
}>;
/**
* Generates orbit track points for a satellite over multiple orbital periods.
* @param satellite - The satellite to generate the orbit track for
* @param start - Start time for the orbit track
* @param periods - Number of orbital periods to generate (default: 1)
* @param samplesPerPeriod - Number of sample points per period (default: 90)
* @example
* ```typescript
* import { Satellite, VisualizationHelpers } from 'ootk';
*
* const satellite = new Satellite({ tle });
*
* // Generate one full orbit with 90 points
* const track = VisualizationHelpers.generateOrbitTrack(
* satellite,
* new Date(),
* 1, // 1 orbital period
* 90 // 90 sample points (4-degree spacing)
* );
*
* // Use points for 3D visualization (e.g., Three.js, Cesium)
* track.forEach(point => {
* console.log(`Time: ${point.time.toISOString()}`);
* console.log(` Position: [${point.position.x}, ${point.position.y}, ${point.position.z}] km`);
* console.log(` Altitude: ${point.altitude.toFixed(1)} km`);
* });
*
* // Generate 3 orbits for longer visualization
* const extendedTrack = VisualizationHelpers.generateOrbitTrack(satellite, new Date(), 3, 120);
* ```
* @returns Array of orbit track points with position, velocity, and altitude
*/
static generateOrbitTrack(satellite: Satellite, start: Date, periods?: number, samplesPerPeriod?: number): OrbitTrackPoint[];
/**
* Generates ground track points (sub-satellite points) for a satellite.
* @param satellite - The satellite to generate the ground track for
* @param start - Start time for the ground track
* @param end - End time for the ground track
* @param stepMs - Time step in milliseconds (default: 60000 = 1 minute)
* @returns Array of ground track points with lat/lon/alt
*/
static generateGroundTrack(satellite: Satellite, start: Date, end: Date, stepMs?: number): GroundTrackPoint[];
/**
* Generates FOV boundary points for a sensor in ECEF coordinates.
* The ECEF coordinates are cached for fast conversion to TEME at render time.
*
* @param sensor - The sensor to generate the FOV boundary for (must have a parent platform)
* @param samples - Number of sample points around the boundary (default: 72)
* @param atRange - Range at which to sample the boundary (default: sensor's maxRange)
* @returns Array of FOV boundary points with az/el and cached ECEF coordinates
* @throws Error if sensor has no parent platform
* @example
* ```typescript
* // Generate boundary once (cached in ECEF)
* const boundary = VisualizationHelpers.generateFOVBoundary(sensor, 72);
*
* // Convert to TEME at any time
* const gmst = gstime(jday(renderDate));
* const temePoints = boundary.map(pt => ({
* ...pt,
* teme: ecef2eci(pt.ecef, gmst)
* }));
* ```
*/
static generateFOVBoundary(sensor: Sensor, samples?: number, atRange?: Kilometers): FovBoundaryPoint[];
}
/**
* @author 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-2026 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 .
*/
/** Represents the nutation angles. */
type NutationAngles = {
/** The nutation in longitude (Δψ) in radians. */
dPsi: Radians;
/** The nutation in obliquity (Δε) in radians. */
dEps: Radians;
/** The mean obliquity of the ecliptic (ε₀) in radians. */
mEps: Radians;
/** The true obliquity of the ecliptic (ε) in radians. */
eps: Radians;
/** The equation of the equinoxes (ΔΔt) in radians. */
eqEq: Radians;
/** The Greenwich Apparent Sidereal Time (GAST) in radians. */
gast: Radians;
};
/**
* @author 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-2026 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 .
*/
/** Represents the precession angles in radians. */
type PrecessionAngles = {
zeta: Radians;
theta: Radians;
zed: Radians;
};
/**
* @author 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-2026 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 .
*/
declare class Earth {
private constructor();
static readonly mu: number;
static readonly radiusEquator: Kilometers;
static readonly flattening: number;
static readonly radiusPolar: Kilometers;
static readonly radiusMean: Kilometers;
static readonly eccentricitySquared: number;
static readonly j2: number;
static readonly j3: number;
static readonly j4: number;
static readonly j5: number;
static readonly j6: number;
static readonly rotation: Vector3D;
static smaToMeanMotion(semimajorAxis: Kilometers): 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;
static precession(epoch: EpochUTC): PrecessionAngles;
static nutation(epoch: EpochUTC): NutationAngles;
static smaToDrift(semimajorAxis: number): number;
static smaToDriftDegrees(semimajorAxis: number): number;
static driftToSemimajorAxis(driftRate: number): number;
static driftDegreesToSma(driftRate: number): number;
/**
* 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;
private static readonly zetaPoly_;
private static readonly thetaPoly_;
private static readonly zedPoly_;
private static readonly moonAnomPoly_;
private static readonly sunAnomPoly_;
private static readonly moonLatPoly_;
private static readonly sunElongPoly_;
private static readonly moonRaanPoly_;
private static readonly meanEpsilonPoly_;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Classification of celestial bodies in the solar system.
*/
declare enum CelestialBodyType {
/** The Sun - center of the solar system */
STAR = "star",
/** Mercury, Venus, Earth, Mars */
TERRESTRIAL_PLANET = "terrestrial_planet",
/** Jupiter, Saturn */
GAS_GIANT = "gas_giant",
/** Uranus, Neptune */
ICE_GIANT = "ice_giant",
/** Pluto, Ceres, Eris, Makemake, Haumea */
DWARF_PLANET = "dwarf_planet",
/** Natural satellites (Earth's Moon, Jupiter's moons, etc.) */
MOON = "moon",
/** Minor planets, NEOs */
ASTEROID = "asteroid",
/** Periodic and non-periodic comets */
COMET = "comet"
}
/**
* Maps astronomy-engine Body enum to CelestialBodyType.
*/
declare const bodyTypeLookup: Record;
/**
* @brief String constants that represent the solar system bodies supported by Astronomy Engine.
*
* The following strings represent solar system bodies supported by various Astronomy Engine functions.
* Not every body is supported by every function; consult the documentation for each function
* to find which bodies it supports.
*
* "Sun", "Moon", "Mercury", "Venus", "Earth", "Mars", "Jupiter",
* "Saturn", "Uranus", "Neptune", "Pluto",
* "SSB" (Solar System Barycenter),
* "EMB" (Earth/Moon Barycenter)
*
* You can also use enumeration syntax for the bodies, like
* `Astronomy.Body.Moon`, `Astronomy.Body.Jupiter`, etc.
*
* @enum {string}
*/
declare enum Body {
Sun = "Sun",
Moon = "Moon",
Mercury = "Mercury",
Venus = "Venus",
Earth = "Earth",
Mars = "Mars",
Jupiter = "Jupiter",
Saturn = "Saturn",
Uranus = "Uranus",
Neptune = "Neptune",
Pluto = "Pluto",
SSB = "SSB",
EMB = "EMB",
Star1 = "Star1",
Star2 = "Star2",
Star3 = "Star3",
Star4 = "Star4",
Star5 = "Star5",
Star6 = "Star6",
Star7 = "Star7",
Star8 = "Star8"
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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 .
*/
/**
* Configuration options for CelestialBody.
*/
interface CelestialBodyParams extends BaseObjectParams {
/** The celestial body type */
bodyType: CelestialBodyType;
/** Gravitational parameter (km³/s²) */
mu?: number;
/** Mean radius (km) */
radius?: Kilometers;
/** astronomy-engine Body identifier */
astronomyBody?: Body;
}
/**
* Rise/set/transit times for a celestial body.
*/
interface RiseSetTimes {
/** Time when body rises above horizon (null if circumpolar or never rises) */
rise: Date | null;
/** Time when body reaches highest point */
transit: Date | null;
/** Time when body sets below horizon (null if circumpolar or never sets) */
set: Date | null;
}
/**
* Abstract base class for all celestial bodies in the solar system.
*
* CelestialBody uses astronomy-engine for high-precision calculations of
* positions, rise/set times, and other astronomical phenomena.
*
* @example
* ```typescript
* // Get the Sun's position
* const sunPos = Sun.eci(new Date());
*
* // Get rise/set times for Mars
* const marsRiseSet = Mars.getRiseSetTimes(groundStation, new Date());
* ```
*/
declare abstract class CelestialBody extends BaseObject {
/** The type of celestial body */
bodyType: CelestialBodyType;
/** Gravitational parameter (km³/s²) */
mu?: number;
/** Mean radius (km) */
radius?: Kilometers;
/** astronomy-engine Body identifier for calculated bodies */
protected astronomyBody_?: Body;
constructor(params: CelestialBodyParams);
/**
* Gets the body's position in Earth-Centered Inertial (J2000) coordinates.
* @param date - The date/time for the position calculation
* @returns Position vector in kilometers
*/
abstract eci(date?: Date): Vector3D;
/**
* Gets the body's position in heliocentric coordinates.
* @param date - The date/time for the position calculation
* @returns Position vector in kilometers (Sun-centered)
*/
abstract heliocentric(date?: Date): Vector3D;
/**
* Gets the body's velocity vector if available.
* @param date - The date/time for the velocity calculation
* @returns Velocity vector in km/s, or null if not available
*/
abstract velocity(date?: Date): Vector3D | null;
/**
* Gets the right ascension of the body as seen from Earth.
* @param date - The date/time for the calculation
* @returns Right ascension in radians
*/
getRightAscension(date?: Date): Radians;
/**
* Gets the declination of the body as seen from Earth.
* @param date - The date/time for the calculation
* @returns Declination in radians
*/
getDeclination(date?: Date): Radians;
/**
* Gets the azimuth and altitude of the body as seen from a ground location.
* @param observer - The ground observer location
* @param date - The date/time for the calculation
* @param refraction - Whether to apply atmospheric refraction correction
* @returns Object with azimuth and altitude in degrees
*/
getAzEl(observer: GroundObject, date?: Date, refraction?: boolean): {
az: Degrees;
el: Degrees;
};
/**
* Gets the distance from Earth to this body.
* @param date - The date/time for the calculation
* @returns Distance in kilometers
*/
getDistanceFromEarth(date?: Date): Kilometers;
/**
* Gets the distance from the Sun to this body.
* @param date - The date/time for the calculation
* @returns Distance in kilometers
*/
getDistanceFromSun(date?: Date): Kilometers;
/**
* Gets rise, transit, and set times for this body as seen from a ground location.
* @param observer - The ground observer location
* @param date - The starting date for the search
* @param minElevation - Minimum elevation angle in degrees (default 0)
* @returns Rise, transit, and set times (null if body doesn't rise/set)
*/
getRiseSetTimes(observer: GroundObject, date?: Date, minElevation?: Degrees): RiseSetTimes;
/**
* Calculates the angular diameter of this body as seen from a given position.
* @param observerPos - The observer's position in km
* @returns Angular diameter in radians
*/
getAngularDiameter(observerPos: Vector3D): Radians;
/**
* Calculates the angular separation between this body and a target position.
* @param targetPos - The target position in ECI coordinates (km)
* @param date - The date/time for the calculation
* @returns Angular separation in degrees
*/
getAngularSeparation(targetPos: Vector3D, date?: Date): Degrees;
/**
* Converts astronomy-engine GeoVector (AU) to Vector3D (km).
*/
protected geoVectorToKm(body: Body, date: Date): Vector3D;
/**
* Converts astronomy-engine HelioVector (AU) to Vector3D (km).
*/
protected helioVectorToKm(body: Body, date: Date): Vector3D;
protected serializeSpecific(): Record;
}
/**
* @author Theodore Kruczek
* @license AGPL-3.0-or-later
* @copyright (c) 2025-2026 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
* 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