@spacexr/geodesy 0.1.0

package/dist/ellipsoid.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Immutable oblate ellipsoid of revolution.
+ *
+ * Axis lengths are expressed in metres. The semi-major axis lies in the
+ * equatorial plane and the semi-minor axis follows the polar axis. Instances
+ * validate their dimensions and precompute the coefficients required by
+ * geodetic conversions.
+ */
+declare class Ellipsoid {
+    private readonly identifier;
+    private readonly major;
+    private readonly minor;
+    /** WGS 84 reference ellipsoid used by EPSG:4978 and EPSG:4979. */
+    static readonly WGS84: Ellipsoid;
+    /** Geodetic Reference System 1980 ellipsoid. */
+    static readonly GRS80: Ellipsoid;
+    /** Geodetic Reference System 1967 ellipsoid. */
+    static readonly GRS67: Ellipsoid;
+    /** Australian National Spheroid. */
+    static readonly ANS: Ellipsoid;
+    /** World Geodetic System 1972 ellipsoid. */
+    static readonly WGS72: Ellipsoid;
+    /** Clarke 1858 ellipsoid. */
+    static readonly Clarke1858: Ellipsoid;
+    /** Clarke 1880 ellipsoid. */
+    static readonly Clarke1880: Ellipsoid;
+    private constructor();
+    /**
+     * Creates an ellipsoid from its semi-major axis and inverse flattening.
+     *
+     * `Infinity` represents a sphere.
+     *
+     * @param name - Stable human-readable ellipsoid name.
+     * @param semiMajorAxis - Equatorial semi-major axis in metres.
+     * @param inverseFlattening - Reciprocal flattening, or `Infinity` for a sphere.
+     * @returns A validated immutable ellipsoid.
+     */
+    static fromSemiMajorAxisAndInverseFlattening(name: string, semiMajorAxis: number, inverseFlattening: number): Ellipsoid;
+    /**
+     * Creates an ellipsoid from its semi-major axis and flattening.
+     *
+     * @param name - Stable human-readable ellipsoid name.
+     * @param semiMajorAxis - Equatorial semi-major axis in metres.
+     * @param flattening - Flattening in the interval `[0, 1)`.
+     * @returns A validated immutable ellipsoid.
+     */
+    static fromSemiMajorAxisAndFlattening(name: string, semiMajorAxis: number, flattening: number): Ellipsoid;
+    /**
+     * Creates an ellipsoid from its semi-major and semi-minor axes.
+     *
+     * @param name - Stable human-readable ellipsoid name.
+     * @param semiMajorAxis - Equatorial semi-major axis in metres.
+     * @param semiMinorAxis - Polar semi-minor axis in metres.
+     * @returns A validated immutable ellipsoid.
+     */
+    static fromAxes(name: string, semiMajorAxis: number, semiMinorAxis: number): Ellipsoid;
+    /**
+     * Creates a spherical reference surface.
+     *
+     * @param name - Stable human-readable sphere name.
+     * @param radius - Radius in metres.
+     * @returns An ellipsoid with zero flattening.
+     */
+    static sphere(name: string, radius: number): Ellipsoid;
+    /** Stable human-readable identifier. */
+    get name(): string;
+    /** Equatorial semi-major axis in metres. */
+    get semiMajorAxis(): number;
+    /** Polar semi-minor axis in metres. */
+    get semiMinorAxis(): number;
+    /** Largest ellipsoid radius in metres. */
+    get maximumRadius(): number;
+    /** Smallest ellipsoid radius in metres. */
+    get minimumRadius(): number;
+    /** Ellipsoid flattening `(a - b) / a`. */
+    get flattening(): number;
+    /** Reciprocal flattening, or `Infinity` for a sphere. */
+    get inverseFlattening(): number;
+    /** First eccentricity squared `e^2`. */
+    get squaredEccentricity(): number;
+    /** Compatibility alias for {@link squaredEccentricity}. */
+    get sqrEccentricity(): number;
+    /** First eccentricity `e`. */
+    get eccentricity(): number;
+    /** Second eccentricity squared `e'^2`. */
+    get secondSquaredEccentricity(): number;
+    /** Linear eccentricity in metres. */
+    get linearEccentricity(): number;
+    /** Precomputed coefficient `1 - e^2`. */
+    get oneMinusSquaredEccentricity(): number;
+    /** Compatibility alias for {@link oneMinusSquaredEccentricity}. */
+    get oneMinusSqrEccentricity(): number;
+    /** Semi-latus rectum in metres. */
+    get semiLatusRectum(): number;
+    /**
+     * Returns the prime-vertical radius of curvature at a geodetic latitude.
+     *
+     * @param latitudeRadians - Geodetic latitude in radians.
+     * @returns Prime-vertical radius in metres.
+     */
+    primeVerticalRadius(latitudeRadians: number): number;
+    /**
+     * Returns the meridional radius of curvature at a geodetic latitude.
+     *
+     * @param latitudeRadians - Geodetic latitude in radians.
+     * @returns Meridional radius in metres.
+     */
+    meridionalRadius(latitudeRadians: number): number;
+    /**
+     * Returns the geocentric surface radius at a latitude.
+     *
+     * @param latitudeRadians - Geocentric latitude in radians.
+     * @returns Distance from the ellipsoid centre to its surface in metres.
+     */
+    radiusAtLatitude(latitudeRadians: number): number;
+    /**
+     * Intersects a normalized geocentric direction with the ellipsoid surface.
+     *
+     * @param x - ECEF X component of a normalized direction.
+     * @param y - ECEF Y component of a normalized direction.
+     * @param z - ECEF Z component of a normalized direction.
+     * @returns Distance from the centre to the surface in metres.
+     */
+    radiusAtPosition(x: number, y: number, z: number): number;
+    /**
+     * Tests geometric equality independently from the ellipsoid name.
+     *
+     * @param other - Ellipsoid to compare.
+     * @returns `true` when both axes are exactly equal.
+     */
+    equals(other: Ellipsoid): boolean;
+    /**
+     * Creates a uniformly scaled ellipsoid.
+     *
+     * @param scale - Positive uniform scale applied to both axes.
+     * @param name - Name assigned to the scaled instance.
+     * @returns A new ellipsoid with unchanged flattening.
+     */
+    scaled(scale: number, name?: string): Ellipsoid;
+    /**
+     * Compatibility alias for {@link scaled}.
+     *
+     * @param name - Name assigned to the cloned instance.
+     * @param scale - Positive uniform scale applied to both axes.
+     * @returns A new ellipsoid.
+     */
+    clone(name: string, scale?: number): Ellipsoid;
+}
+
+export { Ellipsoid };

package/dist/ellipsoid.js

@@ -0,0 +1,3 @@
+export { Ellipsoid } from './chunk-RJFTT4KI.js';
+//# sourceMappingURL=ellipsoid.js.map
+//# sourceMappingURL=ellipsoid.js.map

package/dist/ellipsoid.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"ellipsoid.js"}

package/dist/geodetic-system-DRpWY8qG.d.ts

@@ -0,0 +1,257 @@
+import { Ellipsoid } from './ellipsoid.js';
+
+/**
+ * Mutable three-dimensional Cartesian coordinate.
+ *
+ * Axis meaning depends on the coordinate system that produces the value. ECEF
+ * uses metres along the conventional Earth-fixed X, Y and Z axes. ENU uses
+ * metres along east, north and up. NED uses metres along north, east and down.
+ */
+interface ICartesian3 {
+    /** First Cartesian component in metres. */
+    x: number;
+    /** Second Cartesian component in metres. */
+    y: number;
+    /** Third Cartesian component in metres. */
+    z: number;
+}
+/**
+ * Mutable geodetic coordinate on a reference ellipsoid.
+ *
+ * The angular unit is determined by the method returning or accepting the
+ * object. Methods are explicitly suffixed with `Degrees` or `Radians`.
+ */
+interface IGeodeticCoordinates {
+    /** Geodetic latitude, not geocentric latitude. */
+    latitude: number;
+    /** Longitude east of the reference meridian. */
+    longitude: number;
+    /** Ellipsoidal height in metres. */
+    height: number;
+}
+/**
+ * Canonical local tangent basis expressed as ECEF unit vectors.
+ *
+ * The basis describes physical directions independently from a coordinate
+ * convention. ENU orders it as east, north, up. NED orders it as north, east,
+ * down, where down is the opposite of up.
+ */
+interface ILocalTangentBasis {
+    /** Unit vector pointing east. */
+    east: ICartesian3;
+    /** Unit vector pointing north. */
+    north: ICartesian3;
+    /** Unit vector normal to the ellipsoid and pointing up. */
+    up: ICartesian3;
+}
+
+/**
+ * Immutable geodetic reference system backed by one reference ellipsoid.
+ *
+ * ECEF follows EPSG:4978 axis conventions: X crosses latitude 0 and longitude
+ * 0, Y crosses latitude 0 and longitude 90 degrees east, and Z crosses the
+ * north pole. Cartesian distances and ellipsoidal heights are expressed in
+ * metres.
+ */
+declare class GeodeticSystem {
+    readonly ellipsoid: Ellipsoid;
+    /** Shared WGS84 geodetic system. The instance is immutable. */
+    static readonly WGS84: GeodeticSystem;
+    /**
+     * Creates a geodetic system.
+     *
+     * @param ellipsoid - Reference ellipsoid. Defaults to WGS84.
+     */
+    constructor(ellipsoid?: Ellipsoid);
+    /**
+     * Converts geodetic coordinates in radians to ECEF.
+     *
+     * @param latitudeRadians - Geodetic latitude in radians.
+     * @param longitudeRadians - Longitude in radians east of the reference meridian.
+     * @param height - Ellipsoidal height in metres.
+     * @param target - Optional mutable output object, used to avoid an allocation.
+     * @returns The target populated with ECEF metres.
+     */
+    geodeticRadiansToEcef(latitudeRadians: number, longitudeRadians: number, height?: number, target?: ICartesian3): ICartesian3;
+    /**
+     * Converts geodetic coordinates in degrees to ECEF.
+     *
+     * @param latitudeDegrees - Geodetic latitude in degrees.
+     * @param longitudeDegrees - Longitude in degrees east of the reference meridian.
+     * @param height - Ellipsoidal height in metres.
+     * @param target - Optional mutable output object, used to avoid an allocation.
+     * @returns The target populated with ECEF metres.
+     */
+    geodeticDegreesToEcef(latitudeDegrees: number, longitudeDegrees: number, height?: number, target?: ICartesian3): ICartesian3;
+    /**
+     * Converts ECEF coordinates to geodetic coordinates in radians.
+     *
+     * Bowring initialization followed by a bounded fixed-point refinement gives
+     * stable results at the equator, at the poles, below the ellipsoid and at
+     * orbital altitudes. The ellipsoid centre is rejected because it has no
+     * unique latitude or longitude.
+     *
+     * @param position - ECEF coordinate in metres.
+     * @param target - Optional mutable output object, used to avoid an allocation.
+     * @returns Geodetic latitude and longitude in radians, with height in metres.
+     */
+    ecefToGeodeticRadians(position: ICartesian3, target?: IGeodeticCoordinates): IGeodeticCoordinates;
+    /**
+     * Converts ECEF coordinates to geodetic coordinates in degrees.
+     *
+     * @param position - ECEF coordinate in metres.
+     * @param target - Optional mutable output object, used to avoid an allocation.
+     * @returns Geodetic latitude and longitude in degrees, with height in metres.
+     */
+    ecefToGeodeticDegrees(position: ICartesian3, target?: IGeodeticCoordinates): IGeodeticCoordinates;
+    /**
+     * Returns the outward ellipsoid-normal unit vector at geodetic coordinates.
+     *
+     * @param latitudeRadians - Geodetic latitude in radians.
+     * @param longitudeRadians - Longitude in radians.
+     * @param target - Optional mutable output object.
+     * @returns Unit vector expressed in ECEF axes.
+     */
+    geodeticSurfaceNormalRadians(latitudeRadians: number, longitudeRadians: number, target?: ICartesian3): ICartesian3;
+    /**
+     * Returns the outward ellipsoid-normal unit vector at geodetic coordinates.
+     *
+     * @param latitudeDegrees - Geodetic latitude in degrees.
+     * @param longitudeDegrees - Longitude in degrees.
+     * @param target - Optional mutable output object.
+     * @returns Unit vector expressed in ECEF axes.
+     */
+    geodeticSurfaceNormalDegrees(latitudeDegrees: number, longitudeDegrees: number, target?: ICartesian3): ICartesian3;
+    /**
+     * Creates an immutable local east, north, up tangent plane.
+     *
+     * @param latitudeRadians - Origin geodetic latitude in radians.
+     * @param longitudeRadians - Origin longitude in radians.
+     * @param height - Origin ellipsoidal height in metres.
+     * @returns A local tangent plane bound to this geodetic system.
+     */
+    createLocalTangentPlaneRadians(latitudeRadians: number, longitudeRadians: number, height?: number): LocalTangentPlane;
+    /**
+     * Creates an immutable local east, north, up tangent plane.
+     *
+     * @param latitudeDegrees - Origin geodetic latitude in degrees.
+     * @param longitudeDegrees - Origin longitude in degrees.
+     * @param height - Origin ellipsoidal height in metres.
+     * @returns A local tangent plane bound to this geodetic system.
+     */
+    createLocalTangentPlaneDegrees(latitudeDegrees: number, longitudeDegrees: number, height?: number): LocalTangentPlane;
+}
+/**
+ * Immutable local tangent plane anchored to a geodetic coordinate.
+ *
+ * ENU axes are X east, Y north and Z up. NED axes are X north, Y east and Z
+ * down. All local values are metres. The stored matrices use column-major
+ * order and multiply column vectors, matching glTF and 3D Tiles transforms.
+ */
+declare class LocalTangentPlane {
+    readonly system: GeodeticSystem;
+    private readonly origin;
+    private readonly originCartesian;
+    private readonly tangentBasis;
+    private readonly toEnu;
+    private readonly fromEnu;
+    private readonly toNed;
+    private readonly fromNed;
+    /**
+     * Creates a local tangent plane.
+     *
+     * Prefer {@link GeodeticSystem.createLocalTangentPlaneRadians} or
+     * {@link GeodeticSystem.createLocalTangentPlaneDegrees}, which make the
+     * angular unit explicit at the call site.
+     *
+     * @param system - Geodetic reference system.
+     * @param originRadians - Origin with angular components in radians.
+     */
+    constructor(system: GeodeticSystem, originRadians: IGeodeticCoordinates);
+    /** Origin geodetic coordinate with latitude and longitude in radians. */
+    get originRadians(): IGeodeticCoordinates;
+    /** Origin geodetic coordinate with latitude and longitude in degrees. */
+    get originDegrees(): IGeodeticCoordinates;
+    /** Origin expressed as ECEF metres. */
+    get originEcef(): ICartesian3;
+    /** Canonical east, north and up tangent basis expressed as ECEF unit vectors. */
+    get basis(): ILocalTangentBasis;
+    /** Column-major matrix transforming ECEF positions to ENU positions. */
+    get ecefToEnuMatrix(): Float64Array;
+    /** Column-major matrix transforming ENU positions to ECEF positions. */
+    get enuToEcefMatrix(): Float64Array;
+    /** Column-major matrix transforming ECEF positions to NED positions. */
+    get ecefToNedMatrix(): Float64Array;
+    /** Column-major matrix transforming NED positions to ECEF positions. */
+    get nedToEcefMatrix(): Float64Array;
+    /**
+     * Converts an ECEF position to local ENU metres.
+     *
+     * @param position - ECEF position in metres.
+     * @param target - Optional mutable output object.
+     * @returns Local coordinate with X east, Y north and Z up.
+     */
+    ecefToEnu(position: ICartesian3, target?: ICartesian3): ICartesian3;
+    /**
+     * Converts a local ENU position to ECEF metres.
+     *
+     * @param position - Local coordinate with X east, Y north and Z up.
+     * @param target - Optional mutable output object.
+     * @returns ECEF coordinate in metres.
+     */
+    enuToEcef(position: ICartesian3, target?: ICartesian3): ICartesian3;
+    /**
+     * Converts an ECEF position to local NED metres.
+     *
+     * @param position - ECEF position in metres.
+     * @param target - Optional mutable output object.
+     * @returns Local coordinate with X north, Y east and Z down.
+     */
+    ecefToNed(position: ICartesian3, target?: ICartesian3): ICartesian3;
+    /**
+     * Converts a local NED position to ECEF metres.
+     *
+     * @param position - Local coordinate with X north, Y east and Z down.
+     * @param target - Optional mutable output object.
+     * @returns ECEF coordinate in metres.
+     */
+    nedToEcef(position: ICartesian3, target?: ICartesian3): ICartesian3;
+    /**
+     * Converts geodetic radians directly to local ENU metres.
+     *
+     * @param latitudeRadians - Geodetic latitude in radians.
+     * @param longitudeRadians - Longitude in radians.
+     * @param height - Ellipsoidal height in metres.
+     * @param target - Optional mutable output object.
+     * @returns Local coordinate with X east, Y north and Z up.
+     */
+    geodeticRadiansToEnu(latitudeRadians: number, longitudeRadians: number, height?: number, target?: ICartesian3): ICartesian3;
+    /**
+     * Converts geodetic degrees directly to local ENU metres.
+     *
+     * @param latitudeDegrees - Geodetic latitude in degrees.
+     * @param longitudeDegrees - Longitude in degrees.
+     * @param height - Ellipsoidal height in metres.
+     * @param target - Optional mutable output object.
+     * @returns Local coordinate with X east, Y north and Z up.
+     */
+    geodeticDegreesToEnu(latitudeDegrees: number, longitudeDegrees: number, height?: number, target?: ICartesian3): ICartesian3;
+    /**
+     * Converts local ENU metres directly to geodetic radians.
+     *
+     * @param position - Local coordinate with X east, Y north and Z up.
+     * @param target - Optional mutable output object.
+     * @returns Geodetic latitude and longitude in radians, with height in metres.
+     */
+    enuToGeodeticRadians(position: ICartesian3, target?: IGeodeticCoordinates): IGeodeticCoordinates;
+    /**
+     * Converts local ENU metres directly to geodetic degrees.
+     *
+     * @param position - Local coordinate with X east, Y north and Z up.
+     * @param target - Optional mutable output object.
+     * @returns Geodetic latitude and longitude in degrees, with height in metres.
+     */
+    enuToGeodeticDegrees(position: ICartesian3, target?: IGeodeticCoordinates): IGeodeticCoordinates;
+}
+
+export { GeodeticSystem as G, type ICartesian3 as I, LocalTangentPlane as L, type IGeodeticCoordinates as a, type ILocalTangentBasis as b };

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+export { Ellipsoid } from './ellipsoid.js';
+export { G as GeodeticSystem, I as ICartesian3, a as IGeodeticCoordinates, b as ILocalTangentBasis, L as LocalTangentPlane } from './geodetic-system-DRpWY8qG.js';
+
+/** Number of radians in one degree. */
+declare const DEGREES_TO_RADIANS: number;
+/** Number of degrees in one radian. */
+declare const RADIANS_TO_DEGREES: number;
+/** Full turn in radians. */
+declare const TWO_PI: number;
+/**
+ * Converts an angle from degrees to radians.
+ *
+ * @param degrees - Angle in degrees.
+ * @returns The equivalent angle in radians.
+ */
+declare function toRadians(degrees: number): number;
+/**
+ * Converts an angle from radians to degrees.
+ *
+ * @param radians - Angle in radians.
+ * @returns The equivalent angle in degrees.
+ */
+declare function toDegrees(radians: number): number;
+/**
+ * Normalizes a longitude to the half-open interval `[-PI, PI)`.
+ *
+ * @param longitudeRadians - Longitude in radians.
+ * @returns Normalized longitude in radians.
+ */
+declare function normalizeLongitudeRadians(longitudeRadians: number): number;
+/**
+ * Normalizes a longitude to the half-open interval `[-180, 180)`.
+ *
+ * @param longitudeDegrees - Longitude in degrees.
+ * @returns Normalized longitude in degrees.
+ */
+declare function normalizeLongitudeDegrees(longitudeDegrees: number): number;
+
+export { DEGREES_TO_RADIANS, RADIANS_TO_DEGREES, TWO_PI, normalizeLongitudeDegrees, normalizeLongitudeRadians, toDegrees, toRadians };

package/dist/index.js

@@ -0,0 +1,4 @@
+export { DEGREES_TO_RADIANS, GeodeticSystem, LocalTangentPlane, RADIANS_TO_DEGREES, TWO_PI, normalizeLongitudeDegrees, normalizeLongitudeRadians, toDegrees, toRadians } from './chunk-WYCQOUE7.js';
+export { Ellipsoid } from './chunk-RJFTT4KI.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/system.d.ts

@@ -0,0 +1,2 @@
+import './ellipsoid.js';
+export { G as GeodeticSystem, L as LocalTangentPlane } from './geodetic-system-DRpWY8qG.js';

package/dist/system.js

@@ -0,0 +1,4 @@
+export { GeodeticSystem, LocalTangentPlane } from './chunk-WYCQOUE7.js';
+import './chunk-RJFTT4KI.js';
+//# sourceMappingURL=system.js.map
+//# sourceMappingURL=system.js.map

package/dist/system.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"system.js"}

package/package.json

@@ -0,0 +1,89 @@
+{
+    "name": "@spacexr/geodesy",
+    "version": "0.1.0",
+    "description": "Renderer-neutral ellipsoid, geodetic, ECEF and local tangent frame primitives for SpaceXR.",
+    "type": "module",
+    "license": "Apache-2.0",
+    "author": "Guillaume Pelletier (SpaceXR)",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/pandaGaume/geodesy_ts.git"
+    },
+    "homepage": "https://github.com/pandaGaume/geodesy_ts#readme",
+    "bugs": {
+        "url": "https://github.com/pandaGaume/geodesy_ts/issues"
+    },
+    "keywords": [
+        "geodesy",
+        "ecef",
+        "ellipsoid",
+        "wgs84",
+        "enu",
+        "ned",
+        "spacexr"
+    ],
+    "engines": {
+        "node": ">=20.11.0"
+    },
+    "sideEffects": false,
+    "files": [
+        "dist",
+        "src",
+        "LICENSE",
+        "README.md",
+        "CHANGELOG.md"
+    ],
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        },
+        "./ellipsoid": {
+            "types": "./dist/ellipsoid.d.ts",
+            "import": "./dist/ellipsoid.js",
+            "default": "./dist/ellipsoid.js"
+        },
+        "./system": {
+            "types": "./dist/system.d.ts",
+            "import": "./dist/system.js",
+            "default": "./dist/system.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "build": "tsup",
+        "clean": "rimraf dist coverage docs/api",
+        "typecheck": "tsc -p tsconfig.json --noEmit",
+        "test": "vitest run --coverage.enabled=false",
+        "test:watch": "vitest",
+        "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\"",
+        "lint:fix": "eslint \"src/**/*.ts\" \"tests/**/*.ts\" --fix",
+        "format": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\" \"*.{json,md}\"",
+        "format:fix": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\" \"*.{json,md}\"",
+        "docs": "typedoc --options typedoc.json",
+        "check": "npm run format && npm run lint && npm run typecheck && npm run test && npm run build && npm run docs",
+        "prepublishOnly": "npm run check"
+    },
+    "devDependencies": {
+        "@types/node": "^20.11.0",
+        "@typescript-eslint/eslint-plugin": "^7.0.0",
+        "@typescript-eslint/parser": "^7.0.0",
+        "eslint": "^8.57.0",
+        "eslint-config-prettier": "^9.1.0",
+        "eslint-plugin-prettier": "^5.1.0",
+        "prettier": "^3.2.0",
+        "rimraf": "~6.0.1",
+        "tslib": "^2.8.1",
+        "tsup": "^8.5.1",
+        "typedoc": "^0.28.0",
+        "typescript": "^5.4.0",
+        "vitest": "4.1.11"
+    }
+}

package/src/angles.ts

@@ -0,0 +1,48 @@
+/** Number of radians in one degree. */
+export const DEGREES_TO_RADIANS = Math.PI / 180;
+
+/** Number of degrees in one radian. */
+export const RADIANS_TO_DEGREES = 180 / Math.PI;
+
+/** Full turn in radians. */
+export const TWO_PI = Math.PI * 2;
+
+/**
+ * Converts an angle from degrees to radians.
+ *
+ * @param degrees - Angle in degrees.
+ * @returns The equivalent angle in radians.
+ */
+export function toRadians(degrees: number): number {
+    return degrees * DEGREES_TO_RADIANS;
+}
+
+/**
+ * Converts an angle from radians to degrees.
+ *
+ * @param radians - Angle in radians.
+ * @returns The equivalent angle in degrees.
+ */
+export function toDegrees(radians: number): number {
+    return radians * RADIANS_TO_DEGREES;
+}
+
+/**
+ * Normalizes a longitude to the half-open interval `[-PI, PI)`.
+ *
+ * @param longitudeRadians - Longitude in radians.
+ * @returns Normalized longitude in radians.
+ */
+export function normalizeLongitudeRadians(longitudeRadians: number): number {
+    return ((((longitudeRadians + Math.PI) % TWO_PI) + TWO_PI) % TWO_PI) - Math.PI;
+}
+
+/**
+ * Normalizes a longitude to the half-open interval `[-180, 180)`.
+ *
+ * @param longitudeDegrees - Longitude in degrees.
+ * @returns Normalized longitude in degrees.
+ */
+export function normalizeLongitudeDegrees(longitudeDegrees: number): number {
+    return ((((longitudeDegrees + 180) % 360) + 360) % 360) - 180;
+}