Astrospatial Core

Astrospatial Core is a TypeScript computational library for satellite observation analysis.

It provides orbit propagation, ground-track generation, nadir sensor footprint projection, GeoJSON intersection, HEALPix spatial indexing, and observation-track data models for applications such as Astrobrowser and AstroViewer.

The library is intentionally render-free. It does not contain WebGL, UI widgets, map tile loading, DOM code, or AstroViewer classes. Rendering and user workflows belong in higher-level packages.

Licensing

Astrospatial Core is dual-licensed under:

• the GNU Affero General Public License version 3 (AGPL-3.0); or
• a separate commercial license.

The AGPL-3.0 option is open source and permits both commercial and non-commercial use, subject to its terms.

The commercial license is an alternative for organizations that need to use Astrospatial Core in proprietary products, closed-source services, or other contexts where the AGPL-3.0 requirements are not suitable.

See:

• LICENSE.md for an overview of the dual-license model
• LICENSE-AGPL.md for the complete AGPL-3.0 license text
• LICENSE-COMMERCIAL.md for commercial licensing information
• DEPENDENCY-LICENSING.md for third-party dependency licensing

Installation

For the private GitHub Packages release:

npm install @fab77/astrospatial-core

Configure npm for GitHub Packages when needed:

@fab77:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

The package is ESM-only:

import {
  createSGP4Propagator,
  computeGroundTrack,
  computeSensorFootprint,
  intersectsGeoJSON,
} from "@fab77/astrospatial-core";

Quick Start

This example propagates an ISS TLE, samples a short ground track, computes nadir sensor footprints, and checks whether any footprint intersects a Spain-like GeoJSON target.

import {
  computeGroundTrack,
  computeSensorFootprint,
  createSGP4Propagator,
  intersectsGeoJSON,
} from "@fab77/astrospatial-core";

const tle = {
  name: "ISS (ZARYA)",
  line1: "1 25544U 98067A   19156.50900463  .00003075  00000-0  59442-4 0  9992",
  line2: "2 25544  51.6433  59.2583 0008217  16.4489 347.6017 15.51174618173442",
};

const interval = {
  start: new Date("2019-06-24T06:16:00.000Z"),
  end: new Date("2019-06-24T06:24:00.000Z"),
  stepSeconds: 60,
};

const sensor = {
  name: "Example nadir optical sensor",
  fieldOfViewDeg: 30,
  pointingMode: "nadir",
};

const spainLikeArea = {
  type: "Feature",
  properties: { name: "Spain-like rectangle" },
  geometry: {
    type: "Polygon",
    coordinates: [[
      [-10.0, 35.5],
      [4.5, 35.5],
      [4.5, 44.5],
      [-10.0, 44.5],
      [-10.0, 35.5],
    ]],
  },
};

const propagator = createSGP4Propagator(tle);
const groundTrack = computeGroundTrack(propagator, interval);

const samples = groundTrack.map((groundTrackPoint) => {
  const state = propagator.propagate(groundTrackPoint.timestamp);
  const footprint = computeSensorFootprint(state, sensor, {
    maxVertices: 16,
  });

  return {
    timestamp: groundTrackPoint.timestamp,
    state,
    groundTrackPoint,
    footprint,
    intersectsTarget: intersectsGeoJSON(footprint, spainLikeArea),
  };
});

console.log("samples:", samples.length);
console.log("intersects target:", samples.some((sample) => sample.intersectsTarget));

What It Computes

Astrospatial Core currently supports:

• TLE propagation through an SGP4 adapter
• ECI SatelliteState generation
• ground-track sampling in geodetic longitude/latitude
• simplified nadir-pointing sensor footprint projection on a spherical Earth
• GeoJSON parsing and intersection against footprint polygons
• HEALPix NESTED indexing, pixel geometry, neighbor lookup, disc queries, and polygon queries
• high-level single-observation analysis
• plain TypeScript observation configuration and ObservationTrack data models

Current footprint assumptions:

• nadir pointing only
• spherical Earth
• no Earth rotation during exposure
• rectangular field of view sampled as boundary rays

Module Overview

| Module | Purpose | | --- | --- | | orbit | TLE, SGP4 propagator, satellite state, ground track | | sensor | sensor model and nadir footprint projection | | geometry | geographic primitives, rings, polygon helpers | | geo | GeoJSON parsing and intersection | | analysis | high-level observation helper | | observation | satellite/sensor/target/track configuration types | | healpix | HEALPix NESTED indexing, geometry, neighbors, and region queries |

All public APIs are exported from the package root.

API Overview

Orbit

createSGP4Propagator(tle)
propagateTLE(tle, timestamp, options?)
computeGroundTrack(propagatorOrTle, interval)

Core orbit types:

TLE
SatelliteState
GroundTrackPoint
TimeRange
OrbitPropagator
PropagationOptions

Sensor

computeSensorFootprint(state, sensor, options?)

Core sensor types:

SensorModel
SensorPointingMode
SensorFootprintOptions
FootprintPolygon

GeoJSON

parseGeoJSON(geojson)
intersectsGeoJSON(footprint, geojson)
analyzeGeoJSONIntersection(footprint, geojson)

Core GeoJSON types:

GeoJSONLike
GeoJSONIntersectionResult
ParsedGeoJSONFeature
ParsedGeoJSONPolygon

HEALPix

const healpix = new Healpix(2 ** order);

healpix.ang2pix(pointing)
healpix.pix2ang(pixel)
healpix.pix2vec(pixel)
healpix.getBoundaries(pixel)
healpix.getBoundariesWithStep(pixel, step)
healpix.getPointsForXyfNoStep(x, y, face)
healpix.neighbours(pixel)
healpix.queryDiscInclusive(pointing, radiusRad, fact)
healpix.queryPolygonInclusive(vertices, fact)

High-Level Observation

analyzeSatelliteObservation({
  state,
  sensor,
  area,
  footprintOptions,
  includeDiagnostics,
});

This computes a footprint for one SatelliteState, intersects it with a GeoJSON area, and returns the footprint plus intersection status.

Observation Track Model

Astrospatial Core also exports plain data model types for UI/viewer integration:

SatelliteConfig
SensorConfig
ObservationTargetConfig
ObservationSample
ObservationTrack
ObservationVisualisationConfig

These types are intended to be consumed by orchestration layers such as astrobrowser-ui and rendered by viewer packages such as astro-viewer.

Examples

Build and run the basic mock-state example:

npm run example:basic

Build and run the real TLE Spain observation example:

npm run example:real-tle

The real TLE example:

• creates an ISS TLE propagator
• computes a short ground track
• computes nadir sensor footprints
• tests intersection with a Spain-like GeoJSON polygon
• builds an ObservationTrack
• prints sample and intersection summaries

Development

Astrospatial Core requires Node.js and TypeScript.

Install dependencies:

npm install

Build:

npm run build

Run tests:

npm test

The build output is written to:

lib-esm/

The package exports ESM JavaScript and TypeScript declaration files from lib-esm.

Coordinate Frame Convention

The public SatelliteState is always ECI:

state.positionEciKm
state.velocityEciKmPerSec

Geographic outputs are lon/lat degrees:

• GroundTrackPoint.longitudeDeg
• GroundTrackPoint.latitudeDeg
• FootprintPolygon.coordinates[].longitudeDeg
• FootprintPolygon.coordinates[].latitudeDeg

Current conventions:

• propagation output: ECI
• ground track: ECI to geodetic
• footprint projection: ECI to ECF to geodetic

Regression tests verify that nadir footprint centroids align with corresponding ground-track points within the expected tolerance.

Integration Boundaries

Astrospatial Core computes:

• satellite states
• ground tracks
• sensor footprints
• GeoJSON intersections
• observation-track data

It does not render anything.

Recommended architecture:

astrobrowser-ui
  -> calls astrospatial-core
  -> builds ObservationTrack
  -> passes plain data to astro-viewer

astro-viewer
  -> renders Earth layers, tracks, footprints, overlays, cones, and satellite models

Limitations

Current MVP limitations:

• SGP4/TLE propagation only
• nadir sensor pointing only
• spherical Earth footprint model
• no WGS84 ellipsoid footprint projection yet
• no off-nadir/custom pointing footprint projection yet
• no real attitude dynamics
• no SAR-specific modelling
• no multi-satellite or multi-sensor analysis helper yet

These limitations are intentional for the current computational MVP.

Release Notes

The private package is intended to publish only build artifacts and type declarations.

Recommended release checks:

npm run build
npm test
npm pack --dry-run

For GitHub Packages:

npm publish --registry=https://npm.pkg.github.com

See docs/release-readiness-report.md for packaging details and risks.