@neilberkman/sidereon 0.15.0 → 0.16.0

package/pkg-node/sidereon.d.ts

@@ -1249,6 +1249,31 @@ export class CoverageGrid {
     readonly stationCount: number;
 }
 
+/**
+ * Stateful opt-in latch for SGP4 decay-like failures.
+ *
+ * Pass one latch per satellite to [`Tle.propagateWithDecayLatch`]. The first
+ * decay-like SGP4 failure records the requested epoch in minutes since the TLE
+ * epoch; later requests at the same or a later epoch throw immediately through
+ * the core latch instead of returning a raw post-decay state.
+ */
+export class DecayLatch {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Clear the recorded decay state.
+     */
+    clear(): void;
+    /**
+     * Construct an empty decay latch.
+     */
+    constructor();
+    /**
+     * First observed decay-like epoch, in minutes since the TLE epoch.
+     */
+    readonly firstFailingEpochMinutes: number | undefined;
+}
+
 /**
  * SBAS degradation terms used when deriving an error model from a store.
  */
@@ -1600,6 +1625,34 @@ export class DtedTerrain {
     constructor(root: string);
 }
 
+/**
+ * Earth figure used for conical eclipse shadow geometry.
+ */
+export enum EarthShadowModel {
+    /**
+     * Spherical Earth using the core mean Earth radius.
+     */
+    Spherical = 0,
+    /**
+     * WGS84 oblate Earth approximation by polar-axis scaling.
+     */
+    Wgs84Oblate = 1,
+}
+
+/**
+ * EGM2008 raster spacing for NGA row-framed interpolation grids.
+ */
+export enum Egm2008GridSpacing {
+    /**
+     * The 1-arcminute EGM2008 grid.
+     */
+    OneMinute = 0,
+    /**
+     * The 2.5-arcminute EGM2008 grid.
+     */
+    TwoPointFiveMinute = 1,
+}
+
 /**
  * Loaded EGM96 15-arcminute geoid grid for explicit terrain datum conversion.
  */
@@ -1905,6 +1958,17 @@ export class FrameStates {
     readonly velocityKmS: Float64Array;
 }
 
+/**
+ * WGS84 geodesic input failure class exposed as a stable enum symbol.
+ */
+export enum GeodesicError {
+    /**
+     * A latitude, longitude, azimuth, or distance was outside the accepted
+     * numeric domain.
+     */
+    InvalidInput = 0,
+}
+
 /**
  * A regular latitude/longitude grid of geoid undulation samples with bilinear
  * interpolation, wrapping a real (loaded) geoid model.
@@ -1920,6 +1984,23 @@ export class GeoidGrid {
      * Ellipsoidal height from orthometric height and radians.
      */
     ellipsoidalHeightRad(orthometric_height_m: number, lat_rad: number, lon_rad: number): number;
+    /**
+     * Parse a full NGA EGM2008 row-framed interpolation raster.
+     *
+     * The byte stream must contain one north-to-south Fortran sequential record
+     * per latitude row at the requested spacing. Use
+     * [`fromEgm2008RasterWindow`] for small cropped fixtures or partial loads.
+     */
+    static fromEgm2008Raster(bytes: Uint8Array, spacing: Egm2008GridSpacing): GeoidGrid;
+    /**
+     * Parse a cropped NGA EGM2008 row-framed interpolation raster window.
+     *
+     * `latMinDeg` and `lonMinDeg` are the southwest node of the loaded grid.
+     * `nLat` and `nLon` are the latitude and longitude node counts in the byte
+     * stream. Queries use the same undulation methods as every other
+     * [`GeoidGrid`].
+     */
+    static fromEgm2008RasterWindow(bytes: Uint8Array, spacing: Egm2008GridSpacing, lat_min_deg: number, lon_min_deg: number, n_lat: number, n_lon: number): GeoidGrid;
     /**
      * Parse an EGM96 `WW15MGH.DAC` byte buffer into a full-resolution grid.
      */
@@ -2230,6 +2311,93 @@ export class GroundTrack {
     readonly lonDeg: Float64Array;
 }
 
+/**
+ * Helmert parameters in the units used by the published catalog tables.
+ */
+export class HelmertParameters {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Construct Helmert parameters from translation millimetres, scale parts
+     * per billion, and rotation milliarcseconds.
+     */
+    constructor(translation_mm: Float64Array, scale_ppb: number, rotation_mas: Float64Array);
+    /**
+     * Rotation components `[Rx, Ry, Rz]`, in milliarcseconds.
+     */
+    readonly rotationMas: Float64Array;
+    /**
+     * Scale difference, in parts per billion.
+     */
+    readonly scalePpb: number;
+    /**
+     * Translation components `[Tx, Ty, Tz]`, in millimetres.
+     */
+    readonly translationMm: Float64Array;
+}
+
+/**
+ * Helmert parameter rates in the units used by the published catalog tables.
+ */
+export class HelmertRates {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Construct Helmert parameter rates from translation millimetres per year,
+     * scale parts per billion per year, and rotation milliarcseconds per year.
+     */
+    constructor(translation_mm_per_year: Float64Array, scale_ppb_per_year: number, rotation_mas_per_year: Float64Array);
+    /**
+     * Rotation rates `[Rx, Ry, Rz]`, in milliarcseconds per year.
+     */
+    readonly rotationMasPerYear: Float64Array;
+    /**
+     * Scale rate, in parts per billion per year.
+     */
+    readonly scalePpbPerYear: number;
+    /**
+     * Translation rates `[Tx, Ty, Tz]`, in millimetres per year.
+     */
+    readonly translationMmPerYear: Float64Array;
+}
+
+/**
+ * One published 14-parameter Helmert catalog entry.
+ */
+export class HelmertTransform {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Evaluate the seven Helmert parameters at a decimal year.
+     */
+    parametersAt(epoch_year: number): HelmertParameters;
+    /**
+     * Published source frame for the forward transform.
+     */
+    readonly from: TerrestrialFrame;
+    /**
+     * Parameters at `referenceEpochYear`.
+     */
+    readonly parameters: HelmertParameters;
+    /**
+     * Published table or memo that supplied this entry.
+     */
+    readonly provenance: string;
+    /**
+     * Linear rates of the seven Helmert parameters.
+     */
+    readonly rates: HelmertRates;
+    /**
+     * Parameter reference epoch, expressed as a decimal year.
+     */
+    readonly referenceEpochYear: number;
+    /**
+     * Published target frame for the forward transform.
+     */
+    readonly to: TerrestrialFrame;
+}
+
 /**
  * A point in time, tagged UTC, with the precise time scales resolved.
  *
@@ -6203,6 +6371,247 @@ export class SunMoon {
     readonly sun: Float64Array;
 }
 
+/**
+ * A parsed CCSDS Tracking Data Message.
+ */
+export class Tdm {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Encode this TDM as canonical CCSDS KVN text.
+     */
+    toKvnString(): string;
+    /**
+     * Header comments in parse order.
+     */
+    readonly comments: string[];
+    /**
+     * Optional `CREATION_DATE` header value.
+     */
+    readonly creationDate: string | undefined;
+    /**
+     * Header fields not part of the common modeled header.
+     */
+    readonly headerFields: TdmField[];
+    /**
+     * Optional `MESSAGE_ID` header value.
+     */
+    readonly messageId: string | undefined;
+    /**
+     * Optional `ORIGINATOR` header value.
+     */
+    readonly originator: string | undefined;
+    /**
+     * Number of segments in the message.
+     */
+    readonly segmentCount: number;
+    /**
+     * Metadata/data segments in message order.
+     */
+    readonly segments: TdmSegment[];
+    /**
+     * The `CCSDS_TDM_VERS` header value.
+     */
+    readonly version: string;
+}
+
+/**
+ * One time-tagged TDM tracking data record.
+ */
+export class TdmDataRecord {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Raw epoch string.
+     */
+    readonly epoch: string;
+    /**
+     * Original data keyword.
+     */
+    readonly keyword: string;
+    /**
+     * Observable family label such as `"range"` or `"receiveFreq"`.
+     */
+    readonly observableKind: string;
+    /**
+     * Participant suffix for frequency records, or `undefined`.
+     */
+    readonly observableParticipant: number | undefined;
+    /**
+     * Original name for a table-defined keyword modeled as `other`.
+     */
+    readonly otherObservable: string | undefined;
+    /**
+     * Numeric value plus exact decimal token.
+     */
+    readonly scalar: TdmScalar;
+    /**
+     * Canonical unit label assigned by CCSDS 503.0-B-2.
+     */
+    readonly unit: string;
+    /**
+     * Parsed numeric observable value.
+     */
+    readonly value: number;
+    /**
+     * Exact decimal token used for KVN encoding.
+     */
+    readonly valueText: string;
+}
+
+/**
+ * A TDM data block.
+ */
+export class TdmDataSection {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Data-section comments in parse order.
+     */
+    readonly comments: string[];
+    /**
+     * Data records in parse order.
+     */
+    readonly records: TdmDataRecord[];
+}
+
+/**
+ * A KVN key/value field preserved in parse order.
+ */
+export class TdmField {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * The KVN keyword.
+     */
+    readonly key: string;
+    /**
+     * The trimmed KVN value.
+     */
+    readonly value: string;
+}
+
+/**
+ * Metadata extracted from a TDM `META_START` / `META_STOP` block.
+ */
+export class TdmMetadata {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Return the last metadata value for `key`, or `undefined`.
+     */
+    getLast(key: string): string | undefined;
+    /**
+     * Metadata comments in parse order.
+     */
+    readonly comments: string[];
+    /**
+     * Raw metadata fields in parse order.
+     */
+    readonly fields: TdmField[];
+    /**
+     * Optional `MODE` value.
+     */
+    readonly mode: string | undefined;
+    /**
+     * Parsed `PARTICIPANT_n` entries.
+     */
+    readonly participants: TdmParticipant[];
+    /**
+     * Parsed `PATH`, `PATH_1`, and `PATH_2` entries.
+     */
+    readonly paths: TdmPath[];
+    /**
+     * Range unit label used by `RANGE` records.
+     */
+    readonly rangeUnits: string;
+    /**
+     * Optional `TIME_SYSTEM` value.
+     */
+    readonly timeSystem: string | undefined;
+    /**
+     * Optional `TIMETAG_REF` value.
+     */
+    readonly timetagRef: string | undefined;
+}
+
+/**
+ * One named TDM tracking participant.
+ */
+export class TdmParticipant {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Numeric suffix from `PARTICIPANT_n`.
+     */
+    readonly index: number;
+    /**
+     * Participant name.
+     */
+    readonly name: string;
+}
+
+/**
+ * A parsed TDM signal path from `PATH`, `PATH_1`, or `PATH_2`.
+ */
+export class TdmPath {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Path suffix for `PATH_n`, or `undefined` for unindexed `PATH`.
+     */
+    readonly index: number | undefined;
+    /**
+     * Original path keyword.
+     */
+    readonly key: string;
+    /**
+     * Participant indices listed in path order.
+     */
+    readonly participants: Uint8Array;
+}
+
+/**
+ * A numeric TDM record value plus its exact decimal token.
+ */
+export class TdmScalar {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Exact decimal or scientific-notation token read from the message.
+     */
+    readonly text: string;
+    /**
+     * Parsed finite `f64` value.
+     */
+    readonly value: number;
+}
+
+/**
+ * One TDM segment, consisting of metadata and data blocks.
+ */
+export class TdmSegment {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Tracking data records for this segment.
+     */
+    readonly data: TdmDataSection;
+    /**
+     * Metadata describing this segment's records.
+     */
+    readonly metadata: TdmMetadata;
+}
+
 /**
  * Terrain datum conversion and optional geoid-grid loading error variants.
  */
@@ -6336,6 +6745,28 @@ export class TerrainStoreTileIndex {
     readonly verticalDatum: VerticalDatum;
 }
 
+/**
+ * A supported terrestrial reference-frame realization.
+ */
+export enum TerrestrialFrame {
+    /**
+     * International Terrestrial Reference Frame 2020.
+     */
+    Itrf2020 = 0,
+    /**
+     * International Terrestrial Reference Frame 2014.
+     */
+    Itrf2014 = 1,
+    /**
+     * International Terrestrial Reference Frame 2008.
+     */
+    Itrf2008 = 2,
+    /**
+     * European Terrestrial Reference Frame 2020.
+     */
+    Etrf2020 = 3,
+}
+
 /**
  * A named time scale. The JS value matches the variant order below.
  */
@@ -6376,6 +6807,14 @@ export enum TimeScale {
      * QZSS system time (steered to GPST).
      */
     Qzsst = 8,
+    /**
+     * Geocentric Coordinate Time.
+     */
+    Tcg = 9,
+    /**
+     * Barycentric Coordinate Time.
+     */
+    Tcb = 10,
 }
 
 /**
@@ -6415,6 +6854,15 @@ export class Tle {
      * position (km) and velocity (km/s). Throws an `Error` on SGP4 failure.
      */
     propagate(epochs_unix_us: BigInt64Array): TlePropagation;
+    /**
+     * Propagate over unix-microsecond epochs with an opt-in decay latch.
+     *
+     * The returned TEME arrays match [`propagate`] until the first decay-like
+     * SGP4 failure. At that point the core latch records the failing epoch and
+     * this method throws. Later calls using the same latch at that epoch or a
+     * later one also throw, while raw [`propagate`] remains stateless.
+     */
+    propagateWithDecayLatch(epochs_unix_us: BigInt64Array, latch: DecayLatch): TlePropagation;
     /**
      * Re-encode the parsed elements as the two 69-character TLE lines (with
      * checksums), as a `[line1, line2]` string array. For a well-formed input
@@ -7393,6 +7841,14 @@ export function findTcaCandidates(primary_line1: string, primary_line2: string,
  */
 export function findTcaConjunctions(primary_line1: string, primary_line2: string, secondary_line1: string, secondary_line2: string, window_start_unix_micros: bigint, window_end_unix_micros: bigint, pc_options: any, options: any): any;
 
+/**
+ * Fit every satellite declared in a parsed ECEF SP3 precise product.
+ *
+ * The residual ledger is computed against the original Earth-fixed SP3
+ * observations by the core fit path.
+ */
+export function fitAllSp3EcefPreciseOrbits(sp3: Sp3, options: any): any;
+
 /**
  * Fit a piecewise reduced-orbit model: tile `[t0, t1]` into segments of
  * `segmentSeconds` and fit each independently.
@@ -7467,6 +7923,23 @@ export function fitReducedOrbitSp3(sp3: Sp3, satellite: string, options: any): R
  */
 export function fitReducedOrbitTle(tle: Tle, options: any): ReducedOrbitSourceFit;
 
+/**
+ * Fit one satellite orbit from a parsed ECEF SP3 precise product.
+ *
+ * `satellite` is an IGS token such as `"G01"`. SP3 position and optional
+ * velocity records are transformed from Earth-fixed coordinates through the
+ * core `TdbEarthOrientationProvider` before fitting.
+ */
+export function fitSp3EcefPreciseOrbit(sp3: Sp3, satellite: string, options: any): any;
+
+/**
+ * Fit selected satellite orbits from a parsed ECEF SP3 precise product.
+ *
+ * `satellites` is a string array of IGS tokens such as `["G01", "G02"]`.
+ * The Earth-fixed to inertial conversion is handled by the core provider.
+ */
+export function fitSp3EcefPreciseOrbits(sp3: Sp3, satellites: any, options: any): any;
+
 /**
  * Fit one satellite orbit from a parsed SP3 precise product.
  *
@@ -7520,6 +7993,43 @@ export function forceJ2Acceleration(position_km: Float64Array, velocity_km_s: Fl
  */
 export function forceTwoBodyAcceleration(position_km: Float64Array, velocity_km_s: Float64Array): Float64Array;
 
+/**
+ * Return the built-in terrestrial frame catalog entries.
+ */
+export function frameCatalog(): HelmertTransform[];
+
+/**
+ * Return the published catalog entry for the requested forward direction.
+ */
+export function frameCatalogEntry(from: TerrestrialFrame, to: TerrestrialFrame): HelmertTransform | undefined;
+
+/**
+ * Propagate a station position from one decimal year to another.
+ *
+ * `positionM` and `velocityMPerYear` are length-3 arrays in metres and metres
+ * per year. Returns a length-3 array in metres. Delegates to
+ * `sidereon_core::frame_catalog::propagate_position`.
+ */
+export function frameCatalogPropagatePosition(position_m: Float64Array, velocity_m_per_year: Float64Array, from_epoch_year: number, to_epoch_year: number): Float64Array;
+
+/**
+ * Transform a Cartesian station position and optional velocity between frames.
+ *
+ * `positionM` is a length-3 metre array. `velocityMPerYear` may be `undefined`
+ * or a length-3 metres-per-year array. Returns a plain object with
+ * `positionM` and `velocityMPerYear` (`null` when no velocity was supplied).
+ */
+export function frameCatalogTransform(position_m: Float64Array, velocity_m_per_year: Float64Array | null | undefined, from: TerrestrialFrame, to: TerrestrialFrame, epoch_year: number): any;
+
+/**
+ * Propagate a station to a transform epoch, then transform it between frames.
+ *
+ * `positionEpochYear` is the epoch of the input coordinates. The transform is
+ * evaluated at `transformEpochYear`. Returns a plain object with `positionM`
+ * and `velocityMPerYear`.
+ */
+export function frameCatalogTransformFromEpoch(position_m: Float64Array, velocity_m_per_year: Float64Array, position_epoch_year: number, from: TerrestrialFrame, to: TerrestrialFrame, transform_epoch_year: number): any;
+
 /**
  * Build constellation identity records from a CelesTrak OMM JSON-array text.
  *
@@ -7579,6 +8089,32 @@ export function gamma(f1_hz: number, f2_hz: number): number;
  */
 export function gcrsToItrs(position_km: Float64Array, epochs_unix_us: BigInt64Array, skyfield_compat?: boolean | null): Float64Array;
 
+/**
+ * Solve the WGS84 direct geodesic problem.
+ *
+ * Inputs are point 1 latitude, longitude, forward azimuth, and geodesic
+ * distance. Angles are degrees and `distanceM` is metres. Returns
+ * `{ lat2Deg, lon2Deg, finalAzimuthDeg }`. Delegates to
+ * `sidereon_core::geodesic::geodesic_direct`.
+ */
+export function geodesicDirect(lat1_deg: number, lon1_deg: number, initial_azimuth_deg: number, distance_m: number): any;
+
+/**
+ * Stable string label for a [`GeodesicError`] enum value.
+ */
+export function geodesicErrorLabel(error: GeodesicError): string;
+
+/**
+ * Solve the WGS84 inverse geodesic problem.
+ *
+ * Inputs are point 1 latitude and longitude followed by point 2 latitude and
+ * longitude, all in degrees. Longitudes may be outside `[-180, 180]`. Returns
+ * `{ distanceM, initialAzimuthDeg, finalAzimuthDeg }`, with distance in metres
+ * and azimuths in degrees. Delegates to
+ * `sidereon_core::geodesic::geodesic_inverse`.
+ */
+export function geodesicInverse(lat1_deg: number, lon1_deg: number, lat2_deg: number, lon2_deg: number): any;
+
 /**
  * Convert a batch of geodetic coordinates to ITRS (ECEF).
  *
@@ -8533,6 +9069,11 @@ export function parseSpaceWeatherCsv(text: string): SpaceWeatherTable;
  */
 export function parseSpaceWeatherTxt(text: string): SpaceWeatherTable;
 
+/**
+ * Parse a CCSDS Tracking Data Message in KVN form.
+ */
+export function parseTdmKvn(text: string): Tdm;
+
 /**
  * Parse a multi-record TLE file (CelesTrak / Space-Track style) into named,
  * initialized [`Tle`] instances. Handles bare 2-line sets, 3-line name+line1+line2
@@ -8927,6 +9468,16 @@ export function selectSp3OverRange(products: Sp3[], start_epoch_j2000_s: number,
  */
 export function shadowFraction(satellite_position_km: Float64Array, sun_position_km: Float64Array): Float64Array;
 
+/**
+ * Shadow fraction in `[0, 1]` for position batches with an explicit Earth
+ * shadow model.
+ *
+ * `satellitePositionKm` and `sunPositionKm` are flat row-major `(n, 3)`
+ * `Float64Array`s. `EarthShadowModel.Spherical` is bit-identical to
+ * [`shadowFraction`].
+ */
+export function shadowFractionWithModel(satellite_position_km: Float64Array, sun_position_km: Float64Array, model: EarthShadowModel): Float64Array;
+
 /**
  * Shapiro-Wilk normality test on a residual set.
  *
@@ -9274,6 +9825,11 @@ export function terminatorLatitudeDeg(sub_solar_latitude_deg: number, sub_solar_
  */
 export function terrainStoreChecksum64(bytes: Uint8Array): bigint;
 
+/**
+ * Stable string label for a [`TerrestrialFrame`] enum value.
+ */
+export function terrestrialFrameLabel(frame: TerrestrialFrame): string;
+
 /**
  * Time deviation for explicit averaging factors.
  *
@@ -9444,6 +10000,6 @@ export function writeDtedTreeToMmapStore(root: string, out_path: string): void;
  *
  * `alpha` is the two-sided false-alarm probability. `power` is detection power,
  * so the core missed-detection probability is `1 - power`. The returned object
- * contains `delta0` and `lambda0 = delta0 * delta0`.
+ * contains the core-provided `delta0` and `lambda0` values.
  */
 export function wtestNoncentrality(alpha: number, power: number): any;