npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@spacexr/geodesy

v0.4.0

Published

Renderer-neutral ellipsoid, geodetic, ECEF and local tangent frame primitives for SpaceXR.

Readme

npm CI License

@spacexr/geodesy

Renderer-neutral TypeScript primitives for ellipsoids, geodetic coordinates, Earth-centred Earth-fixed coordinates and local tangent frames.

The package is extracted from the geodesy work originally developed in SpaceXR Core. It removes dependencies on Babylon.js, SpaceXR geometry classes, observables, tile metrics and application state. The result is a small reusable numerical foundation for 3D Tiles, terrain, mining models, globe navigation and planetary visualization.

Design goals

  • one immutable Ellipsoid as the source of every planetary dimension;
  • one immutable GeodeticSystem for geodetic and ECEF conversions;
  • explicit degree and radian APIs, without ambiguous boolean unit arguments;
  • standard ECEF, ENU and NED axis conventions;
  • optional output targets for allocation-free hot paths;
  • no renderer, DOM, 3D Tiles or application dependency;
  • JSDoc-compatible TSDoc on every public API;
  • generated TypeDoc documentation;
  • support for Earth and arbitrary oblate planetary bodies.

Installation

npm install @spacexr/geodesy

The package is ESM and requires Node.js 20.11 or later when used directly in Node.js. Its runtime code has no external dependency.

Coordinate conventions

| System | X | Y | Z | Angular unit | | -------- | ----------------------- | ------------------------------------- | ------------------ | --------------------------- | | ECEF | latitude 0, longitude 0 | latitude 0, longitude 90 degrees east | north pole | none | | ENU | east | north | up | none | | NED | north | east | down | none | | Geodetic | longitude | latitude | ellipsoidal height | explicit degrees or radians |

Cartesian values and ellipsoidal heights are expressed in metres. GeodeticSystem follows the EPSG:4978 ECEF orientation. Geographic values correspond to ellipsoidal longitude, geodetic latitude and ellipsoidal height as used by EPSG:4979, with an explicit API method defining whether angles are degrees or radians.

Matrices are column-major and multiply column vectors. This matches glTF and 3D Tiles transform storage.

Ellipsoids

import { Ellipsoid } from "@spacexr/geodesy";

const earth = Ellipsoid.WGS84;

console.log(earth.semiMajorAxis); // 6378137 metres
console.log(earth.semiMinorAxis); // 6356752.314245179 metres
console.log(earth.inverseFlattening); // 298.257223563

const mars = Ellipsoid.fromAxes("Mars", 3396190, 3376200);
const moon = Ellipsoid.sphere("Moon", 1737400);

Included reference ellipsoids are WGS84, GRS80, GRS67, ANS, WGS72, Clarke 1858 and Clarke 1880. Applications can create additional oblate ellipsoids from axes, flattening or inverse flattening.

Geodetic to ECEF

import { GeodeticSystem } from "@spacexr/geodesy";

const system = GeodeticSystem.WGS84;

const ecef = system.geodeticDegreesToEcef(
    48.8566, // latitude
    2.3522, // longitude
    35, // ellipsoidal height
);

const geodetic = system.ecefToGeodeticDegrees(ecef);

Equivalent geodeticRadiansToEcef and ecefToGeodeticRadians methods are provided for formats such as 3D Tiles regions, whose longitudes and latitudes are serialized in radians.

Every conversion accepts an optional mutable target:

const target = { x: 0, y: 0, z: 0 };

system.geodeticRadiansToEcef(latitude, longitude, height, target);

This avoids temporary allocations during traversal, camera updates and terrain generation.

Local ENU and NED frames

const localFrame = system.createLocalTangentPlaneDegrees(48.8566, 2.3522, 35);

const localEnu = localFrame.ecefToEnu(ecefPoint);
const worldEcef = localFrame.enuToEcef(localEnu);

const localNed = localFrame.ecefToNed(ecefPoint);

The local frame is immutable. Its basis is the canonical east, north, up tangent basis expressed as ECEF unit vectors. ENU and NED are two coordinate conventions derived from that single basis, so they cannot drift apart.

It exposes defensive copies of its basis and transform matrices:

const basis = localFrame.basis;
const ecefToEnu = localFrame.ecefToEnuMatrix;
const enuToEcef = localFrame.enuToEcefMatrix;
const ecefToNed = localFrame.ecefToNedMatrix;
const nedToEcef = localFrame.nedToEcefMatrix;

The conventions are:

ENU = [east, north, up]
NED = [north, east, -up]

NED is the local navigation convention commonly used in aviation and inertial navigation. An aircraft body frame such as FRD, forward, right, down, is a separate orientation layer derived from NED through heading, pitch and roll. It is deliberately not embedded in the geodetic tangent basis.

This model replaces the mutable ENU state and event dependency that existed in the original SpaceXR implementation. Applications can create a new local frame when their floating origin changes without mutating the planetary reference system.

A map draped on a curved terrain by its east and north is a projection onto the tangent plane along the up axis of the origin. enuPlaneToGeodeticDegrees and enuPlaneToGeodeticRadians invert it: they return the point at a given ellipsoidal height on the vertical line of the origin through an east, north position, so that a map pixel lands on the ground right under it, also far from the origin where the surface falls below the plane.

const pixel = localFrame.enuPlaneToGeodeticDegrees(250000, -120000, 35);

Transverse Mercator and UTM

TransverseMercatorProjection implements the ellipsoidal transverse Mercator projection with the sixth-order Kruger series described by Karney (2011). The error stays below one millimetre across a UTM zone. UtmProjection specializes it with the UTM scale factor of 0.9996, a false easting of 500,000 m and a southern false northing of 10,000,000 m.

import { Ellipsoid, GeodeticSystem, UtmProjection, utmZoneFromDegrees } from "@spacexr/geodesy";

// NAD83 / UTM zone 18N (EPSG:26918) uses the GRS80 ellipsoid.
const utm = new UtmProjection(18, "N", Ellipsoid.GRS80);

const geodetic = utm.projectedToGeodeticDegrees(438705.189, 5830304.72, 254.085);
const projected = utm.geodeticDegreesToProjected(geodetic.latitude, geodetic.longitude);

const ecef = new GeodeticSystem(Ellipsoid.GRS80).geodeticDegreesToEcef(geodetic.latitude, geodetic.longitude, geodetic.height);

const zone = utmZoneFromDegrees(52.6, -75.9); // 18

Pass the ellipsoid of the horizontal datum: WGS84 for WGS 84, GRS80 for NAD83, NAD83(CSRS) and ETRS89. The projection does not perform datum transformations, and the height argument is copied unchanged, so an orthometric elevation remains orthometric.

A latitudeOfOriginRadians option counts northings from another parallel than the equator (EPSG method 9807), as national grids such as the British National Grid do.

Lambert conformal conic

LambertConformalConicProjection implements the ellipsoidal Lambert conformal conic projection with the closed formulas of IOGP Guidance Note 7-2. Give one standard parallel and a scale factor (EPSG method 9801), or two standard parallels (EPSG method 9802). Southern cones are supported.

import { DEGREES_TO_RADIANS, Ellipsoid, LambertConformalConicProjection } from "@spacexr/geodesy";

// NAD83 / Quebec Lambert (EPSG:32198).
const quebec = new LambertConformalConicProjection({
    ellipsoid: Ellipsoid.GRS80,
    latitudeOfOriginRadians: 44 * DEGREES_TO_RADIANS,
    centralMeridianRadians: -68.5 * DEGREES_TO_RADIANS,
    standardParallel1Radians: 60 * DEGREES_TO_RADIANS,
    standardParallel2Radians: 46 * DEGREES_TO_RADIANS,
});

const projected = quebec.geodeticDegreesToProjected(52.6, -75.9);
const geodetic = quebec.projectedToGeodeticDegrees(projected.easting, projected.northing);

Web Mercator

WebMercatorProjection is EPSG:3857, the system of web map tiles: geodetic coordinates projected with the spherical Mercator formulas on a sphere of the WGS84 semi-major axis. It is not conformal on the ellipsoid and is not meant for survey data. WEB_MERCATOR_MAX_LATITUDE_DEGREES is the latitude at which the tiled map is square.

Choosing a projection at run time

Every projection implements IMapProjection, so an application can resolve a coordinate reference system once, for example from an EPSG code or a .prj file, and convert through the interface without knowing the projection behind it.

Migration from SpaceXR Core

The package preserves the useful concepts while making units and state explicit:

| SpaceXR Core API | @spacexr/geodesy API | | ----------------------------------------------------- | ---------------------------------------------------------------------- | | Ellipsoid.FromAAndInverseF(...) | Ellipsoid.fromSemiMajorAxisAndInverseFlattening(...) | | Ellipsoid.FromAAndF(...) | Ellipsoid.fromSemiMajorAxisAndFlattening(...) | | GeodeticSystem.Default | GeodeticSystem.WGS84 | | geodeticFloatToCartesianToRef(..., deg) | geodeticDegreesToEcef(...) or geodeticRadiansToEcef(...) | | cartesianToGeodetic(...) | ecefToGeodeticDegrees(...) or ecefToGeodeticRadians(...) | | mutable ENUReference, transform and observable | immutable LocalTangentPlane returned by createLocalTangentPlane... | | public underscore-prefixed ellipsoid calculation data | documented immutable properties and curvature methods |

The old MapScale utility is not part of this numerical kernel because it depends on tile metrics, display resolution and level-of-detail policy. Those concerns belong to the tiling or presentation layer. The legacy flat-Earth and spherical route calculators are also outside version 0.1. Their distance approximations can be introduced later as an independent geodesic module with explicit angular units and dedicated accuracy tests.

3D Tiles integration

@spacexr/3d-tiles-runtime consumes this package through its ECEF spatial adapter:

import { Ellipsoid, GeodeticSystem } from "@spacexr/geodesy";
import { EcefSpatialMetric } from "@spacexr/3d-tiles-runtime";

const mars = Ellipsoid.fromAxes("Mars", 3396190, 3376200);
const metric = new EcefSpatialMetric({
    geodeticSystem: new GeodeticSystem(mars),
});

The geodesy package owns ellipsoid and coordinate mathematics. The 3D Tiles runtime remains responsible for tile transforms, bounding volumes, visibility, horizon culling and screen-space error.

API documentation

Every exported class, interface, constant and method carries JSDoc-compatible TSDoc, including parameter units, return units, coordinate axes and numerical edge cases.

Generate the browsable API site with:

npm run docs

The generated site is written to docs/api/.

Development

npm install
npm run check

npm run check verifies formatting, lint rules, TypeScript types, numerical tests, the production package and the generated API documentation.

The package can also be inspected before publishing:

npm pack --dry-run

Release

Publication is performed by the GitHub Actions release workflow with npm trusted publishing and provenance. See RELEASING.md.

Brand assets

The pixel-art globe represents an oblate reference ellipsoid, its geodetic grid and a local tangent frame.

License

Apache-2.0. See LICENSE.