@duxs365/space-wasm-core

高性能 SGP4 轨道传播器，编译为 WebAssembly，专为在 Web Worker 中批量计算数万颗卫星位置而设计。

特性

• SGP4 算法：标准 NORAD 双行轨道根数（TLE）传播
• 零分配热路径：add_satellite 时预计算所有常量与缓冲区，运行时无堆分配
• TEME → ECEF：内置 GMST 旋转，直接输出地固系坐标（米）
• f32 + Float32Array：低带宽输出，配合 SharedArrayBuffer 双缓冲可支撑 50K+ 卫星实时渲染
• 亚秒级历元精度：使用 timestamp_subsec_nanos()，避免整数秒截断导致的坐标抖动

安装

npm install @duxs365/space-wasm-core
# 或
pnpm add @duxs365/space-wasm-core

需要支持 WebAssembly.instantiateStreaming 的现代浏览器。若配合多 Worker 使用 SharedArrayBuffer，页面需配置跨域隔离响应头：

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp   # 或 credentialless

快速上手

1. 在 Web Worker 中初始化并加载 TLE

// propagate.worker.ts
import init, { Sgp4Universe } from '@duxs365/space-wasm-core';

// 1) 初始化 WASM（仅需一次）
await init();

// 2) 创建实例，预分配容量（卫星数上限）
const universe = Sgp4Universe.new(50_000);

// 3) 解析 TLE 并加入卫星
universe.add_satellite(
  '1 25544U 98067A   23123.45678901  .00012345  00000-0  12345-3 0  9999',
  '2 25544  51.6400 200.0000 0001234  10.0000 350.0000 15.50000000123456'
);

2. 计算某一时刻所有卫星的 ECEF 坐标

// 输出缓冲：每颗卫星 3 个 f32 (x, y, z)，单位：米
const satCount = universe.len();
const out = new Float32Array(satCount * 3);

// unix_sec：自 1970-01-01 00:00:00 UTC 起的秒数（可带小数）
const unixSec = Date.now() / 1000;

universe.compute_positions(unixSec, out);

// out[3*i .. 3*i+3] 即第 i 颗卫星的 ECEF (x, y, z)

3. 配合 SharedArrayBuffer 多 Worker 并行

主线程创建可共享缓冲，分发给多个 Worker 各算一部分卫星：

// 主线程
const SAB = new SharedArrayBuffer(50_000 * 3 * 4); // f32, 双缓冲可翻倍
const out = new Float32Array(SAB);
// 将 out 的子视图传给各 Worker

// Worker 内：把结果写回 SAB 视图
const view = new Float32Array(sab, byteOffset, mySatCount * 3);
universe.compute_positions(unixSec, view);

API

Sgp4Universe

new(max_capacity: number): Sgp4Universe

创建实例并预分配 max_capacity 颗卫星的存储空间。内部向量容量固定，后续添加卫星不会触发堆重分配。

add_satellite(line1: string, line2: string): void

解析一组 TLE 并加入实例。line1 以 "1 " 开头，line2 以 "2 " 开头，各 69 个 ASCII 字符。解析失败（校验和错误、字段非法等）会抛出异常。

compute_positions(unix_sec: number, out_view: Float32Array): void

计算 unix_sec 时刻所有卫星的 ECEF 坐标（米，f32），写入 out_view。每颗卫星占 3 个连续元素 [x, y, z]。传播失败的卫星对应位置被清零。要求 out_view.length >= len() * 3。

compute_step_teme(unix_sec: number, out_view: Float64Array): void

仅用于精度验证：输出原始 TEME 坐标（千米，f64），不做 GMST 旋转。可用作与其它 SGP4 实现的对比基准。

len(): number

当前已加载的卫星数。

capacity(): number

实例可容纳的最大卫星数（即 new(max_capacity) 的值）。

get_epoch_unix(index: number): number

返回第 index 颗卫星的历元 Unix 时间（秒，带小数）。越界返回 NaN。

calc_buffer_ptr(): number

返回内部计算缓冲区的指针，供零拷贝场景使用。通常无需直接调用。

发布产物说明

| 文件 | 说明 | |---|---| | space_wasm_core.js | 主入口，导出 init 与 Sgp4Universe；内部用 import.meta.url 定位 .wasm | | space_wasm_core.d.ts | JS 侧 TypeScript 类型声明 | | space_wasm_core_bg.wasm | 编译后的 WebAssembly 二进制 | | space_wasm_core_bg.wasm.d.ts | WASM 导出的类型声明 |

注意：不要单独使用 .wasm 文件。必须通过 space_wasm_core.js 的 init() 加载，否则无法正确解析模块导入与资源路径。

构建（开发者）

pnpm install
pnpm --filter @duxs365/space-wasm-core build

依赖 Rust 工具链与 wasm-pack，并需安装 wasm32-unknown-unknown target：

rustup target add wasm32-unknown-unknown
cargo install wasm-pack

License

MIT