ootk

Size

An Orbital Object Toolkit in Your Web Browser

ootk is a collection of libraries for doing math related to orbital objects written in TypeScript. ootk was developed to simplify the math and let you focus on using the results.

Most of the functionality was originally written for KeepTrack and then later refactored into this library for others to use.

🔧 Installation

Install the library with NPM:

npm i ootk

ootk requires Node.js 20 or later (or any modern browser bundler). It ships as ES modules with a CommonJS build and full TypeScript types.

Upgrading from ootk 7? Version 8 fixes a number of silently wrong results and changes a few API contracts (mag2db is now pow2db, Lambert posigrade is now shortWay, zenith field-of-view roll, CDM units and more). Read the v8 migration guide before upgrading.

Example Usage

Units are carried in the types. The branded types (Degrees, Radians, Kilometers, TleLine1, …) tell you what each parameter expects and make the compiler catch a mix-up: GroundStation, sensor and FieldOfView parameters are in degrees, while lower-level classes such as Geodetic, RAE and ClassicalElements take radians. Distances are kilometres throughout.

import {
  Degrees,
  GroundStation,
  Kilometers,
  PassType,
  PhasedArrayRadar,
  Satellite,
  SensorType,
  TleLine1,
  TleLine2,
} from 'ootk';

// A satellite from a TLE. SGP4 is only accurate near the TLE epoch, so use a
// current TLE (or a date close to its epoch, as here).
const iss = new Satellite({
  name: 'ISS',
  tle1: '1 25544U 98067A   24028.54545847  .00031576  00000-0  57240-3 0  9991' as TleLine1,
  tle2: '2 25544  51.6418 292.2590 0002595 167.5319 252.0460 15.49326324436741' as TleLine2,
});
const date = new Date('2024-01-28T12:00:00Z');

console.log(iss.inclination); // deg
console.log(iss.period); // min

// Position: eci() is TEME in km and km/s; lla() is degrees and km. Both return
// null if SGP4 fails (for example a decayed orbit), so check the result.
const eci = iss.eci(date);
const lla = iss.lla(date);

if (eci && lla) {
  console.log(eci.position.x, eci.velocity.x);
  console.log(lla.lat, lla.lon, lla.alt);
}

// A ground site. Latitude and longitude are degrees, altitude km above WGS-84.
const capeCod = new GroundStation({
  name: 'Cape Cod',
  lat: 41.754785 as Degrees,
  lon: -70.539151 as Degrees,
  alt: 0.060966 as Kilometers,
});

// Look angles from the site (azimuth and elevation in degrees, range in km).
const rae = iss.rae(capeCod, date);

if (rae) {
  console.log(rae.az, rae.el, rae.rng);
}

// A sensor is a component attached to a platform. Its field of view is a cone
// around each face boresight; halfAngle is required.
const radar = new PhasedArrayRadar({
  id: 1,
  name: 'Cape Cod Radar',
  sensorType: SensorType.PHASED_ARRAY_RADAR,
  beamwidth: 2 as Degrees,
  boresightAz: [47 as Degrees, 167 as Degrees],
  boresightEl: [20 as Degrees, 20 as Degrees],
  fieldOfView: {
    halfAngle: 60 as Degrees,
    minRange: 200 as Kilometers,
    maxRange: 5556 as Kilometers,
    minElevation: 3 as Degrees,
  },
});

capeCod.addSensor(radar);
radar.setParent(capeCod);

console.log(radar.canObserve(iss, date)); // inside the field of view right now?

// Pass events over the next 24 hours (1 s steps): ENTER and EXIT look angles.
const passes = radar.calculatePasses(iss, 24 * 60 * 60, date);

for (const pass of passes) {
  if (pass.type === PassType.ENTER) {
    console.log(`Enter ${pass.time.toISOString()} az ${pass.az.toFixed(1)} el ${pass.el.toFixed(1)}`);
  }
}

More runnable scripts live in examples/ (orbital elements, coordinate transforms, time systems, passes, sensors, observations, Doppler, integrators, IOD, Lambert, maneuvers, conjunction assessment, covariance, Sun and Moon). Each one is walked through on the documentation site.

Documentation

The documentation site is built from docs/ with VitePress (pnpm run docs:dev):

Getting Started Guide - installation and first steps
User Guide - reference for the main features
Advanced Features - force models, numerical propagation, covariance, conjunction assessment, orbit determination and optimizers
Lambert and Satellite Integration - from Lambert solutions to propagated satellites
Migrating to v8 - every breaking change in 8.0.0, with before/after code
Documentation Index - all documentation pages

The documentation covers:

Installation and setup
Satellite tracking and propagation
Ground sensor operations and pass predictions
Coordinate system transformations
Orbit determination methods
Maneuver planning
Advanced features (force models, interpolation, covariance)
Common use cases with complete examples

:desktop_computer: Building

Install Node.js and pnpm (corepack enable pnpm is enough; the required version is pinned by the packageManager field in package.json);
Install all required packages by running the following command from repository’s root directory:
```
pnpm install
```
Run the following script to build everything:
```
pnpm run build
```

Scripts

build bundles src/main.ts with tsup into ES module and CommonJS builds (plus type declarations) in dist.
typecheck runs tsc --noEmit over src and test.
lint lints the src directory with ESLint; lint:fix also applies automatic fixes.
test runs the unit tests with Vitest.
test:coverage runs the unit tests and writes a coverage report.
test:integration builds the package and runs the integration tests against dist.
docs:dev serves the VitePress documentation site locally; docs:build builds it.
bench builds the package and runs the benchmarks in benchmark/.

:man_teacher: Contributing

This repo follows Gitflow Workflow.

Before starting a work on new pull request, please, checkout your feature or bugfix branch from develop branch:

git checkout develop
git fetch origin
git merge origin/develop
git checkout -b my-feature

Make sure that your changes don’t break the existing code by running:

pnpm test

Check that your code follows the rules in eslint.config.js:

pnpm run lint

:man_scientist: Contributors

This whole project is an example of standing on the shoulder’s of giants. None of it would have been possible without the previous work of the following:

:balance_scale: License

I have placed the code under the AGPL License in order to ensure that good ideas can be shared and that the code is open for everyone to use. Learn more here.

8.0.0 (2026-11-06)