ootk 6.0.0-rc.3 → 6.0.0-rc.4

package/.claude/settings.local.json

@@ -5,7 +5,15 @@
       "Bash(dir:*)",
       "Bash(tree /f /a f:irissrc -L 3 -I node_modules 2)",
       "Bash(NUL)",
-      "Bash(npm test:*)"
+      "Bash(npm test:*)",
+      "Bash(node -e:*)",
+      "Bash(npm run build:*)",
+      "Bash(node test-radec-debug.js:*)",
+      "Bash(find:*)",
+      "Bash(npm ls:*)",
+      "Bash(cat:*)",
+      "Bash(grep:*)",
+      "Bash(npx jest:*)"
     ],
     "deny": [],
     "ask": []

package/CLAUDE.md

@@ -0,0 +1,67 @@
+# CLAUDE.md
+
+Project-specific guidance for Claude Code.
+
+## Project Overview
+
+ootk (Orbital Object Toolkit) is a TypeScript library for satellite tracking and orbital mechanics calculations.
+
+## Commands
+
+- `npm test` - Run tests
+- `npm run build` - Build the project
+
+## Code Style
+
+### Access Modifiers
+
+- **No `public` keyword** - Public access is implicit
+- **Private/protected static members** - Use trailing underscore suffix (`_`)
+- **Use `override` keyword** - Always use when overriding inherited methods
+
+```typescript
+// CORRECT
+class Example {
+  name: string;                                  // public (implicit)
+  private static readonly instance_: Example;   // private static with _
+  override toString(): string { ... }           // use override
+}
+```
+
+### Imports
+
+**No file extensions.** Project uses `moduleResolution: "Bundler"`.
+
+```typescript
+import { Satellite } from './Satellite';     // CORRECT
+import { Satellite } from './Satellite.js';  // WRONG
+```
+
+### Types
+
+- Use unit type aliases: `Kilometers`, `Radians`, `Degrees`, `Seconds`, `Milliseconds`
+- Cast values: `(value * DEG2RAD) as Radians`
+
+### Class Patterns
+
+- **Getters** for computed/derived values
+- **Static factory methods** use `fromX()` naming
+- **Private constructor** for static-only utility classes
+- **Singleton** uses `private static readonly instance_` with `getInstance()`
+
+### Naming
+
+- Single letter names OK for math: `a`, `e`, `i`, `h`, `n`, `v`
+- `toString()` returns multi-line strings via array join
+
+### Error Handling
+
+- Validate inputs in constructors with `RangeError` or `Error`
+- Return `null` for methods that may fail (e.g., propagation errors)
+
+## Module Documentation
+
+Detailed module-specific patterns are in design docs:
+
+- Sensor: [src/sensor/v2-docs/field-of-view-design-document.md](src/sensor/v2-docs/field-of-view-design-document.md)
+- Objects: [src/objects/v2-docs/objects-module-refactoring-design-document.md](src/objects/v2-docs/objects-module-refactoring-design-document.md)

package/FUTURE-WORK.md

@@ -0,0 +1,325 @@
+# ootk Roadmap
+
+Future improvements for the Orbital Object ToolKit (ootk) library, organized by priority.
+
+---
+
+## Priority 1: Performance Optimizations
+
+Critical for KeepTrack visualization and real-time operations.
+
+### 1.1 Propagation Caching
+
+Cache recent propagation results in Satellite to avoid redundant SGP4 calls.
+
+**Implementation:**
+
+- LRU cache keyed by timestamp (configurable size, default 100)
+- Invalidate on TLE update
+- Optional time-tolerance matching for near-miss hits
+
+**Files:** `src/objects/Satellite.ts`
+
+---
+
+### 1.2 Batch Propagation
+
+Propagate to multiple times efficiently with shared GMST calculations.
+
+**API:**
+
+```typescript
+class Satellite {
+  eciArray(times: Date[]): Array<PosVel | null>;
+  ecefArray(times: Date[]): Array<EcefVec3 | null>;
+}
+```
+
+**Files:** `src/objects/Satellite.ts`, `src/objects/SpaceObject.ts`
+
+---
+
+### 1.3 AccessCalculator Optimization
+
+Improve pass calculation performance:
+
+- Adaptive step size (larger when far from horizon)
+- Binary search for exact rise/set times
+- Early termination for non-intersecting orbits
+
+**Files:** `src/observation/AccessCalculator.ts`
+
+---
+
+### 1.4 WebWorker Support
+
+Offload heavy computations to background threads:
+
+- Propagation batches
+- Access calculations
+- Coverage analysis
+- Conjunction screening
+
+**API:**
+
+```typescript
+const worker = new OotkWorker();
+const results = await worker.calculateAccess(observer, targets, start, end);
+```
+
+**Files:** New `src/worker/` module
+
+---
+
+### 1.5 Lazy Computation
+
+Defer expensive calculations until first access:
+
+- `apogee`, `perigee` - compute on demand
+- `semiMajorAxis`, `semiMinorAxis` - compute on demand
+- Classical elements from TLE - compute on demand
+
+**Files:** `src/objects/Satellite.ts`
+
+---
+
+### 1.6 Transform Cache Improvements
+
+Upgrade the existing TransformCache (currently 1000-entry FIFO):
+
+- LRU eviction instead of FIFO
+- Configurable cache size
+- Cache statistics/hit rate tracking
+
+**Files:** `src/transforms/TransformCache.ts`
+
+---
+
+## Priority 2: Quality & Validation
+
+### 2.1 Increase Test Coverage
+
+Current: 49% file coverage (107/216 source files)
+
+Priority areas:
+
+- `src/sensor/` - 1 test for 9 source files
+- `src/observation/` - 3 tests for 9 source files
+
+Note: `src/sgp4/` has full coverage but tests are excluded from normal runs for efficiency.
+
+**Target:** 70% file coverage
+
+---
+
+### 2.2 Property-Based Testing
+
+Add fast-check for:
+
+- Coordinate transform round-trips (ECI → ECEF → ECI)
+- Time conversion accuracy (UTC → TT → UTC)
+- Propagation consistency checks
+
+**Files:** New `src/**/__tests__/*.property.test.ts`
+
+---
+
+### 2.3 Benchmark Suite
+
+Track performance regressions:
+
+```typescript
+benchmark('SGP4 single propagation', () => { });
+benchmark('SGP4 batch 1000 times', () => { });
+benchmark('RK4 1-day propagation', () => { });
+benchmark('Access calculation 24h', () => { });
+benchmark('Conjunction screening 1000 objects', () => { });
+```
+
+**Files:** New `benchmarks/` directory
+
+---
+
+### 2.4 Reference Tool Validation
+
+Compare results against:
+
+- STK (Ansys)
+- GMAT (NASA)
+- Orekit (Java library)
+- Vallado reference implementations
+
+Document accuracy bounds for each algorithm.
+
+**Files:** New `validation/` directory with reference data
+
+---
+
+## Priority 3: New Features
+
+### 3.1 Maneuver Planning
+
+Expand beyond `TwoBurnOrbitTransfer`:
+
+```typescript
+class ManeuverPlanner {
+  static hohmann(initial: ClassicalElements, targetAlt: Kilometers): Maneuver[];
+  static biElliptic(initial: ClassicalElements, targetAlt: Kilometers): Maneuver[];
+  static planeChange(initial: ClassicalElements, targetInc: Degrees): Maneuver;
+  static stationKeeping(satellite: Satellite, deadband: StationKeepingBox): Maneuver[];
+  static collisionAvoidance(conjunction: ConjunctionEvent, constraints: CAMConstraints): Maneuver;
+}
+```
+
+**Files:** `src/maneuver/ManeuverPlanner.ts`
+
+---
+
+### 3.2 Coverage Analysis
+
+Grid-based coverage and revisit analysis:
+
+```typescript
+class CoverageAnalyzer {
+  static analyzeCoverage(
+    satellites: Satellite[],
+    gridResolution: Degrees,
+    start: Date,
+    end: Date,
+    constraints?: CoverageConstraints
+  ): CoverageGrid;
+
+  static timeToFirstCoverage(
+    satellites: Satellite[],
+    target: GroundObject,
+    after: Date
+  ): Date | null;
+
+  static revisitStatistics(coverage: CoverageGrid): RevisitStats;
+}
+```
+
+**Files:** New `src/coverage/` module
+
+---
+
+### 3.3 TLE Fitting from State Vectors
+
+Generate TLEs from ephemeris data:
+
+```typescript
+class TleFitter {
+  static fromStateVector(state: StateVector, epoch: Date, options?: FitOptions): Tle;
+  static fromEphemeris(ephemeris: Array<{time: Date, state: StateVector}>, options?: FitOptions): Tle;
+}
+```
+
+**Files:** New `src/coordinate/TleFitter.ts`
+
+---
+
+## Priority 4: External Integration
+
+### 4.1 Space-Track.org Client
+
+```typescript
+class SpaceTrackClient {
+  constructor(credentials: SpaceTrackCredentials);
+
+  async getTle(noradId: number): Promise<Tle>;
+  async getTleHistory(noradId: number, start: Date, end: Date): Promise<Tle[]>;
+  async searchTle(query: TleQuery): Promise<Tle[]>;
+  async getCatalog(): Promise<SatelliteCatalogEntry[]>;
+}
+```
+
+**Files:** New `src/api/SpaceTrackClient.ts`
+
+---
+
+### 4.2 CelesTrak Client
+
+```typescript
+class CelesTrakClient {
+  async getGpData(group: string): Promise<Tle[]>;
+  async getSupTles(source: string): Promise<Tle[]>;
+  async getSpaceWeather(): Promise<SpaceWeatherData>;
+}
+```
+
+**Files:** New `src/api/CelesTrakClient.ts`
+
+---
+
+### 4.3 CCSDS Message Support
+
+Expand parser support (OEM and CDM already done):
+
+| Parser | Format | Status |
+|--------|--------|--------|
+| OemParser | Orbit Ephemeris Message | Done |
+| CdmParser | Conjunction Data Message | Done |
+| Sp3Parser | SP3 precise ephemerides | Planned |
+| TdmParser | Tracking Data Messages | Planned |
+| OpmParser | Orbit Parameter Message | Planned |
+| OmmParser | Orbit Mean Elements Message | Planned |
+
+**Files:** `src/parsers/`
+
+---
+
+### 4.4 FreeFlyer/STK Compatibility
+
+Import/export formats for commercial tools:
+
+- STK ephemeris files (.e)
+- FreeFlyer script generation
+- GMAT script generation
+
+**Files:** New `src/compat/` module
+
+---
+
+## Lower Priority
+
+### 5.1 Angles-Only Orbit Determination
+
+Add angles-only IOD methods:
+
+- Double-r iteration
+- Gooding angles-only
+- Statistical OD from optical observations
+
+**Files:** `src/orbit-determination/`
+
+---
+
+### 5.2 Atmospheric Density Models
+
+Additional models beyond Harris-Priester:
+
+- NRLMSISE-00
+- JB2008
+- DTM-2020
+
+**Files:** `src/force/`
+
+---
+
+### 5.3 Memory-Efficient History
+
+Optimize History for long simulations:
+
+- Store as typed arrays (Float64Array)
+- Compression for older entries
+- Tiered storage (recent=full, old=downsampled)
+
+**Files:** `src/objects/History.ts`
+
+---
+
+## Ideas for Future Consideration
+
+- **TypeDoc Generation** - Auto-generate API documentation
+- **Streaming TLE Catalogs** - Memory-efficient loading of large catalogs
+- **Node.js Fetch Polyfill** - Enable API clients in server environments

package/dist/body/CelestialBody.d.ts

@@ -0,0 +1,155 @@
+/**
+ * @author Theodore Kruczek
+ * @license AGPL-3.0-or-later
+ * @copyright (c) 2025 Kruczek Labs LLC
+ *
+ * Orbital Object ToolKit is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Affero General Public License as published by the Free Software
+ * 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 <http://www.gnu.org/licenses/>.
+ */
+import { Body } from 'astronomy-engine';
+import { BaseObject, BaseObjectParams } from '../objects/BaseObject';
+import { Vector3D } from '../operations/Vector3D';
+import { Degrees, Kilometers, Radians } from '../types/types';
+import { CelestialBodyType } from './CelestialBodyType';
+import { GroundObject } from '../objects/GroundObject';
+/**
+ * Configuration options for CelestialBody.
+ */
+export 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.
+ */
+export 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());
+ * ```
+ */
+export 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<Kilometers>;
+    /**
+     * 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<Kilometers>;
+    /**
+     * 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<Kilometers>): 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<Kilometers>, date?: Date): Degrees;
+    /**
+     * Converts astronomy-engine GeoVector (AU) to Vector3D (km).
+     */
+    protected geoVectorToKm(body: Body, date: Date): Vector3D<Kilometers>;
+    /**
+     * Converts astronomy-engine HelioVector (AU) to Vector3D (km).
+     */
+    protected helioVectorToKm(body: Body, date: Date): Vector3D<Kilometers>;
+    protected serializeSpecific(): Record<string, unknown>;
+}