satellite.js

Satellite.js provides a WebAssembly (WASM) implementation of SGP4/SDP4 designed for high-performance, real-time applications. Unlike the pure JavaScript implementation which relies on object allocation and garbage collection, the WASM version uses a C++ backend optimized for minimal overhead.

Key performance characteristics include:

• Zero-copy data access: Results are returned as TypedArray views (e.g., Float64Array) directly on the WASM linear memory, avoiding expensive serialization/marshalling.
• Minimal allocation: Uses a BulkPropagator pattern that allocates memory once and reuses it across multiple runs.
• SIMD acceleration: Compiled with 128-bit SIMD instructions to allow parallel processing of mathematical operations.
• Single boundary crossing: Entire calculation pipelines (from propagation to look angles) can be executed in a single call to the WASM module, preventing costly JS-WASM context switching.

const now = new Date();
const results = entireSatelliteDatabase
  .map(satRec => propagate(satRec, now));

A Runtime manages the WASM instance, its creation, and disposal. You must choose one based on your environment and performance needs.

• SingleThreadRuntime:

  • Synchronous execution (blocks the thread).
  • Best for: Workers, small batches, console apps, or environments without SharedArrayBuffer support.
  • Multiple BulkPropagator instances can exist, but only one calculation runs at a time because it is blocking.

• MultiThreadRuntime:

  • Asynchronous execution (uses separate threads).
  • Best for: High-performance bulk tasks where you don't want to block the main thread.
  • Requirement: Requires SharedArrayBuffer support (browsers must be cross-origin isolated and in a secure context).
  • Constraint: You can only run one BulkPropagator instance at a time on a single MultiThreadRuntime. Running more will throw an error.

import { createSingleThreadRuntime } from 'satellite.js';
using runtime = await createSingleThreadRuntime();

import { createMultiThreadRuntime } from 'satellite.js';
using runtime = await createMultiThreadRuntime({ threadsCount: 4 });

Satellite.js provides tools to transform ECI coordinates into other frames like ECF (Earth-Centered Fixed) or Geodetic (latitude, longitude, height).

To calculate Look Angles (azimuth, elevation, range) for an observer, you must:

1. Define the observer's geodetic position in radians.
2. Calculate the GMST (Greenwich Mean Sidereal Time) using gstime(date).
3. Convert the satellite's ECI position to ECF.
4. Convert the observer's geodetic position to ECF.
5. Use ecfToLookAngles(observerGd, positionEcf).

Commonly used functions:

• gstime(date): Get GMST.
• eciToEcf(positionEci, gmst): ECI to ECF.
• geodeticToEcf(observerGd): Geodetic to ECF.
• eciToGeodetic(positionEci, gmst): ECI to Geodetic.
• ecfToLookAngles(observerGd, positionEcf): ECF to Look Angles.
• dopplerFactor(observerEcf, positionEcf, velocityEcf): Calculate Doppler factor.

import * as satellite from 'satellite.js';

// 1. Setup Observer (in RADIANS)
const observerGd = {
  longitude: satellite.degreesToRadians(-122.0308),
  latitude: satellite.degreesToRadians(36.9613422),
  height: 0.370
};

// 2. Get GMST
const gmst = satellite.gstime(new Date());

// 3. Transform and Calculate
const positionEcf = satellite.eciToEcf(positionEci, gmst);
const observerEcf = satellite.geodeticToEcf(observerGd);
const positionGd = satellite.eciToGeodetic(positionEci, gmst);
const lookAngles = satellite.ecfToLookAngles(observerGd, positionEcf);

// 4. Access Results
console.log(`Azimuth: ${lookAngles.azimuth}, Elevation: ${lookAngles.elevation}, Range: ${lookAngles.rangeSat}`);
console.log(`Lat: ${satellite.degreesLat(positionGd.latitude)}, Lon: ${satellite.degreesLong(positionGd.longitude)}`);

The C++ source code in this repository is compiled into different WASM modules depending on the required performance and threading capabilities. The core logic is split between common.cpp (shared), base.cpp (single-threaded), and pthreads.cpp (multi-threaded).

Available compilation types:

• base: Single-threaded, SIMD-enabled.
• pthreads: Multi-threaded, SIMD-enabled.

Each type has a debug and a release version. Debug builds include debug.cpp (used for testing), while release builds exclude it for performance.

Compilation file mappings:

• base-debug: common.cpp + base.cpp + debug.cpp
• pthreads-debug: common.cpp + pthreads.cpp + debug.cpp
• base-release: common.cpp + base.cpp
• pthreads-release: common.cpp + pthreads.cpp

Note: The code is specifically written for Emscripten 6.0.3. Using different versions may cause breaking changes.

The Bulk Propagation API uses unmanaged memory. You must manually dispose of BulkPropagator and Runtime instances to prevent memory leaks.

Recommended: Using the using keyword

If your environment supports the Explicit Resource Management proposal (e.g., modern Node.js), use the using syntax to ensure automatic cleanup when the variable goes out of scope.

Manual Disposal

If you cannot use using, you must explicitly call the .dispose() method on both the BulkPropagator and the Runtime instances.

// Recommended approach
using runtime = await createSingleThreadRuntime();
using bulkPropagator = new BulkPropagator(options);
// Automatically disposed at end of scope

// Manual approach
const runtime = await createSingleThreadRuntime();
const bulkPropagator = new BulkPropagator(options);

// ... use them ...

bulkPropagator.dispose();
runtime.dispose();