Convert satellite orbits between Keplerian (classical) orbital elements and a Cartesian position and velocity state vector in the Earth-centred inertial (ECI) frame. Available as a dependency-free TypeScript library (the classic coe2rv / rv2coe conversions) and as an online converter.
Live app: https://coding-oksana.github.io/orbital-convert/
npm package: https://www.npmjs.com/package/orbital-convert
The web app converts an orbit between two descriptions:
- Keplerian elements: semi-major axis
a, eccentricitye, inclinationi, right ascension of the ascending nodeΩ, argument of periapsisωand true anomalyν. - Cartesian state vector: position
x, y, zand velocityvx, vy, vz.
Edit either panel and the other one updates. Values that don't make physical sense (for example e ≥ 1, a position inside Earth or a speed above escape speed) are flagged and are not converted.
The conversion and validation code is published to npm as orbital-convert, with no dependencies and TypeScript types included.
npm install orbital-convertimport {
keplerianToCartesian,
cartesianToKeplerian,
checkKeplerian,
} from 'orbital-convert';
// Keplerian elements → state vector (km, km/s)
const state = keplerianToCartesian({
a: 7000, // km
e: 0.01,
i: 51.6, // degrees
raan: 30,
omega: 40,
nu: 60,
});
// { x, y, z, vx, vy, vz, r, v }
// State vector → Keplerian elements
const elements = cartesianToKeplerian(state);
// { a, e, i, raan, omega, nu }
// Validate user input given as strings before converting
const { values, issues } = checkKeplerian({
a: '7000',
e: '1.2',
i: '51.6',
raan: '30',
omega: '40',
nu: '60',
});
// values is null when there is an error; issues explains what is wrong| Export | What it does |
|---|---|
keplerianToCartesian(elements, μ?) |
Keplerian elements → position, velocity, and their magnitudes r and v |
cartesianToKeplerian(state, μ?) |
Position and velocity → Keplerian elements |
checkKeplerian(strings) |
Parses and validates Keplerian input; returns { values, issues } |
checkCartesian(strings) |
Parses and validates a state vector; returns { values, issues } |
MU_EARTH, EARTH_RADIUS |
Constants used by default (see Conventions) |
parseNum, formatNum |
Number parsing that accepts Unicode minus signs, and formatting with a fixed number of decimals |
The converters default to Earth's μ. Pass your own as the second argument for another central body. They don't validate their input, so run the check* functions first if the values come from users.
| Frame | Earth-centred inertial (ECI): origin at Earth's centre, z toward the North Pole, x toward the vernal equinox |
| Units | km, km/s, degrees |
| Gravity | Two-body only, μ = 398600.4418 km³/s² |
| Earth radius | 6378.137 km (equatorial), used for the "inside Earth" checks |
| Orbits | Closed (elliptical) orbits only: 0 ≤ e < 1, a > 0 |
Undefined angles are handled as follows:
- Circular orbits have no periapsis, so
ω = 0andνis measured from the ascending node (argument of latitude). - Equatorial orbits have no ascending node, so
Ω = 0andωis measured from thexaxis (longitude of periapsis). - Circular equatorial orbits set
Ω = ω = 0, andνis measured from thexaxis (true longitude).
Requires Node.js 22 or later (the version is pinned in .nvmrc, so nvm use picks it up).
npm install
npm run devThen open http://localhost:5173.
| Command | What it does |
|---|---|
npm run dev |
Start the dev server |
npm run build |
Type-check and build for production into dist/ |
npm run build:lib |
Build the npm library into dist-lib/ |
npm run preview |
Serve the production build |
npm run typecheck |
Type-check the app, Vite config and Cypress tests |
npm run lint |
Run ESLint (includes Prettier formatting) |
npm run fix |
Fix lint and formatting problems where possible |
npm run prettier |
Format every file with Prettier |
npm run test |
Run the unit tests once |
npm run test:watch |
Run the unit tests and re-run them when files change |
npm run test:e2e |
Start the dev server and run the Cypress tests headlessly |
npm run cy:open |
Open the Cypress app to run tests interactively (start npm run dev first) |
src/
App.tsx page layout and state for both panels
components/Field.tsx one labelled numeric input
lib/orbital.ts conversion maths, parsing and formatting
lib/validation.ts checks for values that don't make physical sense
lib/*.test.ts unit tests
cypress/e2e/ end-to-end tests
Unit tests (Vitest) sit next to the code they test in src/lib/:
orbital.test.tschecks parsing and formatting, compares both conversions with Vallado's Fundamentals of Astrodynamics (Examples 2-5 and 2-6), checks physical laws (vis-viva, angular momentum), the handling of circular and equatorial orbits, and round trips for a set of named orbits plus 1000 random ones.validation.test.tschecks every validation rule, including edge values, and that the "would hit Earth" warning agrees with the conversion maths.
End-to-end tests live in cypress/e2e/. converter.cy.ts covers the conversions in both directions, a geostationary round trip, input filtering, every validation message, Reset and Copy JSON. layout.cy.ts checks the layout on phone, tablet and desktop widths. Elements are selected with data-cy attributes.
.github/workflows/ci.yml runs lint, the production build (including the type check) and the Cypress tests on every push to master and on pull requests. When all of them pass on master, the app is deployed to GitHub Pages.
Dependabot (.github/dependabot.yml) opens weekly pull requests for npm packages and GitHub Actions. Minor and patch npm updates are grouped into one pull request.
