@interstellar-tools/equations 1.3.0 → 1.5.0

package/dist/categories/cartography/body-fixed-to-geodetic.d.ts

@@ -0,0 +1,77 @@
+import type { GeodeticCoordinatesInterface } from '@interstellar-tools/types';
+/**
+ * Convert a **body-fixed Cartesian** position (ECEF for Earth) to **geodetic coordinates**: latitude, longitude and height.
+ *
+ * There's no closed form for the latitude. This uses Bowring's iteration on the parametric latitude $ \beta $:
+ *
+ * $$
+ * \tan\varphi = \frac{z + e'^2 b \sin^3\beta}{p - e^2 a \cos^3\beta},
+ * \qquad
+ * \tan\beta = \frac{b}{a}\tan\varphi
+ * $$
+ *
+ * and then
+ *
+ * $$
+ * \lambda = \operatorname{atan2}(y, x), \qquad
+ * h = p\cos\varphi + z\sin\varphi - a\sqrt{1 - e^2\sin^2\varphi}
+ * $$
+ *
+ * Where:
+ * - $ p = \sqrt{x^2 + y^2} $ is the distance from the rotation axis (m)
+ * - $ a $ is the equatorial radius, $ b = a\sqrt{1 - e^2} $ the polar radius (m)
+ * - $ e^2 $ is the first eccentricity squared, $ e'^2 = e^2 / (1 - e^2) $ the second
+ *
+ * **Units**
+ * - Inputs: `x`, `y`, `z` and `a` in **m**, `eSquared` dimensionless.
+ * - Output: `phi` and `lambda` in **radians**, `h` in **m**.
+ *
+ * ::: info Notes
+ *
+ * - Starting from $ \tan\beta = a z / (b p) $, two iterations reach sub-millimetre accuracy for points near Earth's surface; the loop runs until $ \beta $ stops changing, to at most 10 iterations.
+ * - The height formula is stable everywhere, the poles included. On the rotation axis, `phi` is ±π/2 and `lambda` is 0.
+ * - For a point on the surface, `phi` equals {@link planetographicLatitudeOblate}; this one also handles points above and below it.
+ * - {@link geodeticToBodyFixed} goes the other way.
+ *
+ * :::
+ *
+ * ::: practice Apollo 11, in Earth orbit
+ *
+ * **32.672° N, 191.1 km up**
+ *
+ * _At orbit insertion: 6 563.0 km from Earth's centre, at 32.502° N geocentric_
+ *
+ * Seen from Earth's centre, the insertion point was at 32.502°, the latitude that fixes the orbit's inclination. On a map it was 0.170° further north, the latitude the flight evaluation report gives.
+ *
+ * ```ts
+ * const lat = toRad(32.502);
+ * const r = 6_563_041;
+ * bodyFixedToGeodetic(r * Math.cos(lat), 0, r * Math.sin(lat), 6_378_137, 0.00669437999014);
+ * // phi ≈ 32.672°, h ≈ 191.1 km
+ * ```
+ *
+ * :::
+ *
+ * @param x - Body-fixed $ x $ in **m** (finite), through the prime meridian.
+ * @param y - Body-fixed $ y $ in **m** (finite), through 90° east.
+ * @param z - Body-fixed $ z $ in **m** (finite), along the rotation axis.
+ * @param a - Equatorial radius $ a $ in **m** (finite, > 0).
+ * @param eSquared - First eccentricity squared $ e^2 $ (finite, in [0, 1)).
+ * @returns The geodetic latitude, longitude and height.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `a <= 0`, `eSquared` is outside [0, 1), or the point is at the centre.
+ * @group Cartography
+ *
+ * @example
+ * ```ts
+ * // 1 km above the North Pole on WGS84
+ * const { phi, h } = bodyFixedToGeodetic(0, 0, 6_357_752.314, 6_378_137, 0.00669437999014);
+ * // phi = π/2, h ≈ 1 000 m
+ * ```
+ *
+ * @see {@link geodeticToBodyFixed}
+ * @see {@link planetographicLatitudeOblate}
+ * @see https://en.wikipedia.org/wiki/Geographic_coordinate_conversion Geographic coordinate conversion
+ */
+export declare const bodyFixedToGeodetic: (x: number, y: number, z: number, a: number, eSquared: number) => GeodeticCoordinatesInterface;
+//# sourceMappingURL=body-fixed-to-geodetic.d.ts.map

package/dist/categories/cartography/body-fixed-to-geodetic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"body-fixed-to-geodetic.d.ts","sourceRoot":"","sources":["../../../src/categories/cartography/body-fixed-to-geodetic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,4BAA4B,EAE7B,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,eAAO,MAAM,mBAAmB,GAC9B,GAAG,MAAM,EACT,GAAG,MAAM,EACT,GAAG,MAAM,EACT,GAAG,MAAM,EACT,UAAU,MAAM,KACf,4BAiDF,CAAC"}

package/dist/categories/cartography/body-fixed-to-geodetic.js

@@ -0,0 +1,111 @@
+/**
+ * Convert a **body-fixed Cartesian** position (ECEF for Earth) to **geodetic coordinates**: latitude, longitude and height.
+ *
+ * There's no closed form for the latitude. This uses Bowring's iteration on the parametric latitude $ \beta $:
+ *
+ * $$
+ * \tan\varphi = \frac{z + e'^2 b \sin^3\beta}{p - e^2 a \cos^3\beta},
+ * \qquad
+ * \tan\beta = \frac{b}{a}\tan\varphi
+ * $$
+ *
+ * and then
+ *
+ * $$
+ * \lambda = \operatorname{atan2}(y, x), \qquad
+ * h = p\cos\varphi + z\sin\varphi - a\sqrt{1 - e^2\sin^2\varphi}
+ * $$
+ *
+ * Where:
+ * - $ p = \sqrt{x^2 + y^2} $ is the distance from the rotation axis (m)
+ * - $ a $ is the equatorial radius, $ b = a\sqrt{1 - e^2} $ the polar radius (m)
+ * - $ e^2 $ is the first eccentricity squared, $ e'^2 = e^2 / (1 - e^2) $ the second
+ *
+ * **Units**
+ * - Inputs: `x`, `y`, `z` and `a` in **m**, `eSquared` dimensionless.
+ * - Output: `phi` and `lambda` in **radians**, `h` in **m**.
+ *
+ * ::: info Notes
+ *
+ * - Starting from $ \tan\beta = a z / (b p) $, two iterations reach sub-millimetre accuracy for points near Earth's surface; the loop runs until $ \beta $ stops changing, to at most 10 iterations.
+ * - The height formula is stable everywhere, the poles included. On the rotation axis, `phi` is ±π/2 and `lambda` is 0.
+ * - For a point on the surface, `phi` equals {@link planetographicLatitudeOblate}; this one also handles points above and below it.
+ * - {@link geodeticToBodyFixed} goes the other way.
+ *
+ * :::
+ *
+ * ::: practice Apollo 11, in Earth orbit
+ *
+ * **32.672° N, 191.1 km up**
+ *
+ * _At orbit insertion: 6 563.0 km from Earth's centre, at 32.502° N geocentric_
+ *
+ * Seen from Earth's centre, the insertion point was at 32.502°, the latitude that fixes the orbit's inclination. On a map it was 0.170° further north, the latitude the flight evaluation report gives.
+ *
+ * ```ts
+ * const lat = toRad(32.502);
+ * const r = 6_563_041;
+ * bodyFixedToGeodetic(r * Math.cos(lat), 0, r * Math.sin(lat), 6_378_137, 0.00669437999014);
+ * // phi ≈ 32.672°, h ≈ 191.1 km
+ * ```
+ *
+ * :::
+ *
+ * @param x - Body-fixed $ x $ in **m** (finite), through the prime meridian.
+ * @param y - Body-fixed $ y $ in **m** (finite), through 90° east.
+ * @param z - Body-fixed $ z $ in **m** (finite), along the rotation axis.
+ * @param a - Equatorial radius $ a $ in **m** (finite, > 0).
+ * @param eSquared - First eccentricity squared $ e^2 $ (finite, in [0, 1)).
+ * @returns The geodetic latitude, longitude and height.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `a <= 0`, `eSquared` is outside [0, 1), or the point is at the centre.
+ * @group Cartography
+ *
+ * @example
+ * ```ts
+ * // 1 km above the North Pole on WGS84
+ * const { phi, h } = bodyFixedToGeodetic(0, 0, 6_357_752.314, 6_378_137, 0.00669437999014);
+ * // phi = π/2, h ≈ 1 000 m
+ * ```
+ *
+ * @see {@link geodeticToBodyFixed}
+ * @see {@link planetographicLatitudeOblate}
+ * @see https://en.wikipedia.org/wiki/Geographic_coordinate_conversion Geographic coordinate conversion
+ */
+export const bodyFixedToGeodetic = (x, y, z, a, eSquared) => {
+    for (const [name, v] of [
+        ['x', x],
+        ['y', y],
+        ['z', z],
+        ['a', a],
+        ['eSquared', eSquared]
+    ]) {
+        if (!Number.isFinite(v))
+            throw new TypeError(`${name} must be a finite number. Received: ${v}`);
+    }
+    if (a <= 0)
+        throw new RangeError(`a must be > 0. Received: ${a}`);
+    if (eSquared < 0 || eSquared >= 1)
+        throw new RangeError(`eSquared must be in [0, 1). Received: ${eSquared}`);
+    const p = Math.hypot(x, y);
+    if (p === 0 && z === 0)
+        throw new RangeError('The point must not be at the centre of the body.');
+    const lambda = (p === 0 ? 0 : Math.atan2(y, x));
+    const b = a * Math.sqrt(1 - eSquared);
+    const ePrimeSquared = eSquared / (1 - eSquared);
+    let beta = Math.atan2(a * z, b * p);
+    let phi = 0;
+    for (let k = 0; k < 10; k++) {
+        phi = Math.atan2(z + ePrimeSquared * b * Math.sin(beta) ** 3, p - eSquared * a * Math.cos(beta) ** 3);
+        const next = Math.atan2(b * Math.sin(phi), a * Math.cos(phi));
+        if (Math.abs(next - beta) < 1e-15)
+            break;
+        beta = next;
+    }
+    const sinPhi = Math.sin(phi);
+    const h = p * Math.cos(phi) +
+        z * sinPhi -
+        a * Math.sqrt(1 - eSquared * sinPhi * sinPhi);
+    return { phi: phi, lambda, h };
+};
+//# sourceMappingURL=body-fixed-to-geodetic.js.map

package/dist/categories/cartography/body-fixed-to-geodetic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"body-fixed-to-geodetic.js","sourceRoot":"","sources":["../../../src/categories/cartography/body-fixed-to-geodetic.ts"],"names":[],"mappings":"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"}

package/dist/categories/cartography/geodetic-to-body-fixed.d.ts

@@ -0,0 +1,73 @@
+import type { Radians, Vector3DTupleType } from '@interstellar-tools/types';
+/**
+ * Convert **geodetic coordinates** (latitude, longitude, height) to a **body-fixed Cartesian** position, ECEF for Earth.
+ *
+ * $$
+ * \begin{aligned}
+ * x &= (N + h)\cos\varphi\cos\lambda \\
+ * y &= (N + h)\cos\varphi\sin\lambda \\
+ * z &= \big(N(1 - e^2) + h\big)\sin\varphi
+ * \end{aligned}
+ * \qquad
+ * N = \frac{a}{\sqrt{1 - e^2\sin^2\varphi}}
+ * $$
+ *
+ * Where:
+ * - $ \varphi $ is the geodetic latitude and $ \lambda $ the longitude (rad)
+ * - $ h $ is the height above the ellipsoid, along its normal (m)
+ * - $ a $ is the equatorial radius (m) and $ e^2 $ the first eccentricity squared
+ * - $ N $ is the prime vertical radius of curvature (m)
+ *
+ * **Units**
+ * - Inputs: `phi` and `lambda` in **radians**, `h` and `a` in **m**, `eSquared` dimensionless.
+ * - Output: `[x, y, z]` in **m**, with $ z $ along the rotation axis and $ x $ through the prime meridian.
+ *
+ * ::: info Notes
+ *
+ * - Geodetic latitude is the angle of the ellipsoid's normal, the latitude on maps. The geocentric latitude, the angle seen from the centre, is `atan2(z, hypot(x, y))` of the result, and is smaller everywhere but the equator and the poles.
+ * - WGS84: $ a = 6\,378\,137 $ m, $ e^2 = 0.00669437999014 $. Get $ e^2 $ from the radii with {@link eccentricitySquaredOblateSpheroid}.
+ * - {@link bodyFixedToGeodetic} goes the other way.
+ *
+ * :::
+ *
+ * ::: practice Apollo 11, on Pad 39A
+ *
+ * **6 373.3 km**
+ *
+ * _From Earth's centre, at 28.608° N geodetic, 80.604° W on the WGS84 ellipsoid_
+ *
+ * The geocentric latitude is 28.447°, 0.161° less than on the map. That's the latitude the launch-site formulas such as `surfaceRotationSpeed` need.
+ *
+ * ```ts
+ * const [x, y, z] = geodeticToBodyFixed(toRad(28.608422), toRad(-80.604133), 0, 6_378_137, 0.00669437999014);
+ * Math.hypot(x, y, z); // ≈ 6 373 266 m
+ * toDeg(Math.atan2(z, Math.hypot(x, y))); // ≈ 28.447°
+ * ```
+ *
+ * :::
+ *
+ * @param phi - Geodetic latitude $ \varphi $ in **radians** (finite, in [-π/2, π/2]).
+ * @param lambda - Longitude $ \lambda $ in **radians**, east positive (finite).
+ * @param h - Height $ h $ above the ellipsoid in **m** (finite; negative below it).
+ * @param a - Equatorial radius $ a $ in **m** (finite, > 0).
+ * @param eSquared - First eccentricity squared $ e^2 $ (finite, in [0, 1)).
+ * @returns Body-fixed position `[x, y, z]` in **m**.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `phi` is outside [-π/2, π/2], `a <= 0`, or `eSquared` is outside [0, 1).
+ * @group Cartography
+ *
+ * @example
+ * ```ts
+ * import type { Radians } from '@interstellar-tools/types';
+ *
+ * // On the equator at the prime meridian, 100 m up
+ * geodeticToBodyFixed(0 as Radians, 0 as Radians, 100, 6_378_137, 0.00669437999014);
+ * // [6 378 237, 0, 0]
+ * ```
+ *
+ * @see {@link bodyFixedToGeodetic}
+ * @see {@link eccentricitySquaredOblateSpheroid}
+ * @see https://en.wikipedia.org/wiki/Geographic_coordinate_conversion Geographic coordinate conversion
+ */
+export declare const geodeticToBodyFixed: (phi: Radians, lambda: Radians, h: number, a: number, eSquared: number) => Vector3DTupleType;
+//# sourceMappingURL=geodetic-to-body-fixed.d.ts.map

package/dist/categories/cartography/geodetic-to-body-fixed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geodetic-to-body-fixed.d.ts","sourceRoot":"","sources":["../../../src/categories/cartography/geodetic-to-body-fixed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,eAAO,MAAM,mBAAmB,GAC9B,KAAK,OAAO,EACZ,QAAQ,OAAO,EACf,GAAG,MAAM,EACT,GAAG,MAAM,EACT,UAAU,MAAM,KACf,iBA6BF,CAAC"}

package/dist/categories/cartography/geodetic-to-body-fixed.js

@@ -0,0 +1,97 @@
+/**
+ * Convert **geodetic coordinates** (latitude, longitude, height) to a **body-fixed Cartesian** position, ECEF for Earth.
+ *
+ * $$
+ * \begin{aligned}
+ * x &= (N + h)\cos\varphi\cos\lambda \\
+ * y &= (N + h)\cos\varphi\sin\lambda \\
+ * z &= \big(N(1 - e^2) + h\big)\sin\varphi
+ * \end{aligned}
+ * \qquad
+ * N = \frac{a}{\sqrt{1 - e^2\sin^2\varphi}}
+ * $$
+ *
+ * Where:
+ * - $ \varphi $ is the geodetic latitude and $ \lambda $ the longitude (rad)
+ * - $ h $ is the height above the ellipsoid, along its normal (m)
+ * - $ a $ is the equatorial radius (m) and $ e^2 $ the first eccentricity squared
+ * - $ N $ is the prime vertical radius of curvature (m)
+ *
+ * **Units**
+ * - Inputs: `phi` and `lambda` in **radians**, `h` and `a` in **m**, `eSquared` dimensionless.
+ * - Output: `[x, y, z]` in **m**, with $ z $ along the rotation axis and $ x $ through the prime meridian.
+ *
+ * ::: info Notes
+ *
+ * - Geodetic latitude is the angle of the ellipsoid's normal, the latitude on maps. The geocentric latitude, the angle seen from the centre, is `atan2(z, hypot(x, y))` of the result, and is smaller everywhere but the equator and the poles.
+ * - WGS84: $ a = 6\,378\,137 $ m, $ e^2 = 0.00669437999014 $. Get $ e^2 $ from the radii with {@link eccentricitySquaredOblateSpheroid}.
+ * - {@link bodyFixedToGeodetic} goes the other way.
+ *
+ * :::
+ *
+ * ::: practice Apollo 11, on Pad 39A
+ *
+ * **6 373.3 km**
+ *
+ * _From Earth's centre, at 28.608° N geodetic, 80.604° W on the WGS84 ellipsoid_
+ *
+ * The geocentric latitude is 28.447°, 0.161° less than on the map. That's the latitude the launch-site formulas such as `surfaceRotationSpeed` need.
+ *
+ * ```ts
+ * const [x, y, z] = geodeticToBodyFixed(toRad(28.608422), toRad(-80.604133), 0, 6_378_137, 0.00669437999014);
+ * Math.hypot(x, y, z); // ≈ 6 373 266 m
+ * toDeg(Math.atan2(z, Math.hypot(x, y))); // ≈ 28.447°
+ * ```
+ *
+ * :::
+ *
+ * @param phi - Geodetic latitude $ \varphi $ in **radians** (finite, in [-π/2, π/2]).
+ * @param lambda - Longitude $ \lambda $ in **radians**, east positive (finite).
+ * @param h - Height $ h $ above the ellipsoid in **m** (finite; negative below it).
+ * @param a - Equatorial radius $ a $ in **m** (finite, > 0).
+ * @param eSquared - First eccentricity squared $ e^2 $ (finite, in [0, 1)).
+ * @returns Body-fixed position `[x, y, z]` in **m**.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `phi` is outside [-π/2, π/2], `a <= 0`, or `eSquared` is outside [0, 1).
+ * @group Cartography
+ *
+ * @example
+ * ```ts
+ * import type { Radians } from '@interstellar-tools/types';
+ *
+ * // On the equator at the prime meridian, 100 m up
+ * geodeticToBodyFixed(0 as Radians, 0 as Radians, 100, 6_378_137, 0.00669437999014);
+ * // [6 378 237, 0, 0]
+ * ```
+ *
+ * @see {@link bodyFixedToGeodetic}
+ * @see {@link eccentricitySquaredOblateSpheroid}
+ * @see https://en.wikipedia.org/wiki/Geographic_coordinate_conversion Geographic coordinate conversion
+ */
+export const geodeticToBodyFixed = (phi, lambda, h, a, eSquared) => {
+    for (const [name, x] of [
+        ['phi', phi],
+        ['lambda', lambda],
+        ['h', h],
+        ['a', a],
+        ['eSquared', eSquared]
+    ]) {
+        if (!Number.isFinite(x))
+            throw new TypeError(`${name} must be a finite number. Received: ${x}`);
+    }
+    if (Math.abs(phi) > Math.PI / 2)
+        throw new RangeError(`phi must be in [-π/2, π/2]. Received: ${phi}`);
+    if (a <= 0)
+        throw new RangeError(`a must be > 0. Received: ${a}`);
+    if (eSquared < 0 || eSquared >= 1)
+        throw new RangeError(`eSquared must be in [0, 1). Received: ${eSquared}`);
+    const sinPhi = Math.sin(phi);
+    const cosPhi = Math.cos(phi);
+    const N = a / Math.sqrt(1 - eSquared * sinPhi * sinPhi);
+    return [
+        (N + h) * cosPhi * Math.cos(lambda),
+        (N + h) * cosPhi * Math.sin(lambda),
+        (N * (1 - eSquared) + h) * sinPhi
+    ];
+};
+//# sourceMappingURL=geodetic-to-body-fixed.js.map

package/dist/categories/cartography/geodetic-to-body-fixed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"geodetic-to-body-fixed.js","sourceRoot":"","sources":["../../../src/categories/cartography/geodetic-to-body-fixed.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,GAAY,EACZ,MAAe,EACf,CAAS,EACT,CAAS,EACT,QAAgB,EACG,EAAE;IACrB,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI;QACtB,CAAC,KAAK,EAAE,GAAG,CAAC;QACZ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAClB,CAAC,GAAG,EAAE,CAAC,CAAC;QACR,CAAC,GAAG,EAAE,CAAC,CAAC;QACR,CAAC,UAAU,EAAE,QAAQ,CAAC;KACd,EAAE,CAAC;QACX,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YACrB,MAAM,IAAI,SAAS,CAAC,GAAG,IAAI,uCAAuC,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,CAAC;QAC7B,MAAM,IAAI,UAAU,CAAC,yCAAyC,GAAG,EAAE,CAAC,CAAC;IAEvE,IAAI,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,4BAA4B,CAAC,EAAE,CAAC,CAAC;IAElE,IAAI,QAAQ,GAAG,CAAC,IAAI,QAAQ,IAAI,CAAC;QAC/B,MAAM,IAAI,UAAU,CAAC,yCAAyC,QAAQ,EAAE,CAAC,CAAC;IAE5E,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC;IAExD,OAAO;QACL,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;QACnC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;QACnC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM;KAClC,CAAC;AACJ,CAAC,CAAC"}

package/dist/categories/entry/ballistic-coefficient.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Compute the **ballistic coefficient** of an entry vehicle: how much mass it has per unit of drag.
+ *
+ * $$
+ * \beta = \frac{m}{C_D A}
+ * $$
+ *
+ * Where:
+ * - $ m $ is the vehicle's mass (kg)
+ * - $ C_D $ is its drag coefficient (dimensionless)
+ * - $ A $ is its reference area, usually the frontal area (m²)
+ *
+ * **Units**
+ * - Inputs: `m` in **kg**, `Cd` dimensionless, `A` in **m²**.
+ * - Output: $ \beta $ in **kg/m²**.
+ *
+ * ::: info Notes
+ *
+ * - A low $ \beta $ slows down high in the thin upper atmosphere; a high $ \beta $ plunges deeper before it slows.
+ * - The drag deceleration is $ a = \rho V^2 / (2\beta) $.
+ * - Some texts define it the other way up, as $ C_D A / m $. This library uses $ m / (C_D A) $ throughout.
+ *
+ * :::
+ *
+ * @param m - Mass $ m $ in **kg** (finite, > 0).
+ * @param Cd - Drag coefficient $ C_D $ (finite, > 0).
+ * @param A - Reference area $ A $ in **m²** (finite, > 0).
+ * @returns Ballistic coefficient $ \beta $ in **kg/m²**.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If any input is `<= 0`.
+ * @group Entry
+ *
+ * @example
+ * ```ts
+ * // A 5000 kg capsule, 3.9 m across, with Cd = 1.3
+ * const beta = ballisticCoefficient(5000, 1.3, Math.PI * 1.95 ** 2);
+ * // beta ≈ 322 kg/m²
+ * ```
+ *
+ * @see {@link ballisticEntrySpeed}
+ * @see https://en.wikipedia.org/wiki/Ballistic_coefficient Ballistic coefficient
+ */
+export declare const ballisticCoefficient: (m: number, Cd: number, A: number) => number;
+//# sourceMappingURL=ballistic-coefficient.d.ts.map

package/dist/categories/entry/ballistic-coefficient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ballistic-coefficient.d.ts","sourceRoot":"","sources":["../../../src/categories/entry/ballistic-coefficient.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,oBAAoB,GAC/B,GAAG,MAAM,EACT,IAAI,MAAM,EACV,GAAG,MAAM,KACR,MAWF,CAAC"}

package/dist/categories/entry/ballistic-coefficient.js

@@ -0,0 +1,54 @@
+import { assertFinite, assertPositive } from './validate.js';
+/**
+ * Compute the **ballistic coefficient** of an entry vehicle: how much mass it has per unit of drag.
+ *
+ * $$
+ * \beta = \frac{m}{C_D A}
+ * $$
+ *
+ * Where:
+ * - $ m $ is the vehicle's mass (kg)
+ * - $ C_D $ is its drag coefficient (dimensionless)
+ * - $ A $ is its reference area, usually the frontal area (m²)
+ *
+ * **Units**
+ * - Inputs: `m` in **kg**, `Cd` dimensionless, `A` in **m²**.
+ * - Output: $ \beta $ in **kg/m²**.
+ *
+ * ::: info Notes
+ *
+ * - A low $ \beta $ slows down high in the thin upper atmosphere; a high $ \beta $ plunges deeper before it slows.
+ * - The drag deceleration is $ a = \rho V^2 / (2\beta) $.
+ * - Some texts define it the other way up, as $ C_D A / m $. This library uses $ m / (C_D A) $ throughout.
+ *
+ * :::
+ *
+ * @param m - Mass $ m $ in **kg** (finite, > 0).
+ * @param Cd - Drag coefficient $ C_D $ (finite, > 0).
+ * @param A - Reference area $ A $ in **m²** (finite, > 0).
+ * @returns Ballistic coefficient $ \beta $ in **kg/m²**.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If any input is `<= 0`.
+ * @group Entry
+ *
+ * @example
+ * ```ts
+ * // A 5000 kg capsule, 3.9 m across, with Cd = 1.3
+ * const beta = ballisticCoefficient(5000, 1.3, Math.PI * 1.95 ** 2);
+ * // beta ≈ 322 kg/m²
+ * ```
+ *
+ * @see {@link ballisticEntrySpeed}
+ * @see https://en.wikipedia.org/wiki/Ballistic_coefficient Ballistic coefficient
+ */
+export const ballisticCoefficient = (m, Cd, A) => {
+    const inputs = [
+        ['m', m],
+        ['Cd', Cd],
+        ['A', A]
+    ];
+    assertFinite(inputs);
+    assertPositive(inputs);
+    return m / (Cd * A);
+};
+//# sourceMappingURL=ballistic-coefficient.js.map

package/dist/categories/entry/ballistic-coefficient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ballistic-coefficient.js","sourceRoot":"","sources":["../../../src/categories/entry/ballistic-coefficient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,CAAS,EACT,EAAU,EACV,CAAS,EACD,EAAE;IACV,MAAM,MAAM,GAAG;QACb,CAAC,GAAG,EAAE,CAAC,CAAC;QACR,CAAC,IAAI,EAAE,EAAE,CAAC;QACV,CAAC,GAAG,EAAE,CAAC,CAAC;KACA,CAAC;IAEX,YAAY,CAAC,MAAM,CAAC,CAAC;IACrB,cAAc,CAAC,MAAM,CAAC,CAAC;IAEvB,OAAO,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;AACtB,CAAC,CAAC"}

package/dist/categories/entry/ballistic-entry-speed.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Compute the **speed of a ballistic entry** at an altitude, with the Allen–Eggers solution.
+ *
+ * $$
+ * V(h) = V_E \exp\left(-\frac{\rho_0 H}{2\beta\sin\lvert\gamma\rvert}\, e^{-h/H}\right)
+ * $$
+ *
+ * Where:
+ * - $ V_E $ is the speed at entry (m/s)
+ * - $ \gamma $ is the flight-path angle, constant along the straight path (rad)
+ * - $ \beta $ is the ballistic coefficient (kg/m²)
+ * - $ \rho_0 $ and $ H $ describe an exponential atmosphere, $ \rho = \rho_0 e^{-h/H} $
+ *
+ * **Units**
+ * - Inputs: `h` and `H` in **m**, `VE` in **m/s**, `gamma` in **radians**, `beta` in **kg/m²**, `rho0` in **kg/m³**.
+ * - Output: $ V $ in **m/s**.
+ *
+ * ::: info Notes
+ *
+ * - Assumes drag dominates: no lift, no gravity, and a straight path at a constant angle. That holds well for steep, fast entries of non-lifting bodies.
+ * - The deceleration at any altitude is $ \rho V^2 / (2\beta) $; its peak is {@link ballisticPeakDeceleration}, at {@link ballisticPeakDecelerationAltitude}.
+ * - `gamma` can be given as negative (descending, the usual convention) or positive: only its size is used.
+ * - Earth's lower atmosphere is roughly $ \rho_0 = 1.225 $ kg/m³ with $ H \approx 7.2 $ km. A single exponential is a rough fit; see the density models in [#226](https://github.com/phun-ky/interstellar-tools/issues/226).
+ *
+ * :::
+ *
+ * @param h - Altitude $ h $ in **m** (finite).
+ * @param VE - Entry speed $ V_E $ in **m/s** (finite, > 0).
+ * @param gamma - Flight-path angle $ \gamma $ in **radians** (finite, non-zero, within [-π/2, π/2]).
+ * @param beta - Ballistic coefficient $ \beta $ in **kg/m²** (finite, > 0).
+ * @param rho0 - Reference density $ \rho_0 $ in **kg/m³** (finite, > 0).
+ * @param H - Scale height $ H $ in **m** (finite, > 0).
+ * @returns Speed $ V $ in **m/s**.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `VE`, `beta`, `rho0` or `H` is `<= 0`, or `gamma` is zero or past vertical.
+ * @group Entry
+ *
+ * @example
+ * ```ts
+ * import type { Radians } from '@interstellar-tools/types';
+ *
+ * // A 322 kg/m² capsule entering at 11 km/s, 6.5° below horizontal
+ * const v = ballisticEntrySpeed(40_000, 11_000, (-6.5 * Math.PI / 180) as Radians, 322, 1.225, 7200);
+ * // v ≈ 6.9 km/s at 40 km
+ * ```
+ *
+ * @see {@link ballisticCoefficient}
+ * @see {@link ballisticPeakDeceleration}
+ * @see https://en.wikipedia.org/wiki/Atmospheric_entry Atmospheric entry
+ */
+export declare const ballisticEntrySpeed: (h: number, VE: number, gamma: number, beta: number, rho0: number, H: number) => number;
+//# sourceMappingURL=ballistic-entry-speed.d.ts.map

package/dist/categories/entry/ballistic-entry-speed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ballistic-entry-speed.d.ts","sourceRoot":"","sources":["../../../src/categories/entry/ballistic-entry-speed.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,eAAO,MAAM,mBAAmB,GAC9B,GAAG,MAAM,EACT,IAAI,MAAM,EACV,OAAO,MAAM,EACb,MAAM,MAAM,EACZ,MAAM,MAAM,EACZ,GAAG,MAAM,KACR,MAoBF,CAAC"}

package/dist/categories/entry/ballistic-entry-speed.js

@@ -0,0 +1,71 @@
+import { assertFinite, assertFlightPathAngle, assertPositive } from './validate.js';
+/**
+ * Compute the **speed of a ballistic entry** at an altitude, with the Allen–Eggers solution.
+ *
+ * $$
+ * V(h) = V_E \exp\left(-\frac{\rho_0 H}{2\beta\sin\lvert\gamma\rvert}\, e^{-h/H}\right)
+ * $$
+ *
+ * Where:
+ * - $ V_E $ is the speed at entry (m/s)
+ * - $ \gamma $ is the flight-path angle, constant along the straight path (rad)
+ * - $ \beta $ is the ballistic coefficient (kg/m²)
+ * - $ \rho_0 $ and $ H $ describe an exponential atmosphere, $ \rho = \rho_0 e^{-h/H} $
+ *
+ * **Units**
+ * - Inputs: `h` and `H` in **m**, `VE` in **m/s**, `gamma` in **radians**, `beta` in **kg/m²**, `rho0` in **kg/m³**.
+ * - Output: $ V $ in **m/s**.
+ *
+ * ::: info Notes
+ *
+ * - Assumes drag dominates: no lift, no gravity, and a straight path at a constant angle. That holds well for steep, fast entries of non-lifting bodies.
+ * - The deceleration at any altitude is $ \rho V^2 / (2\beta) $; its peak is {@link ballisticPeakDeceleration}, at {@link ballisticPeakDecelerationAltitude}.
+ * - `gamma` can be given as negative (descending, the usual convention) or positive: only its size is used.
+ * - Earth's lower atmosphere is roughly $ \rho_0 = 1.225 $ kg/m³ with $ H \approx 7.2 $ km. A single exponential is a rough fit; see the density models in [#226](https://github.com/phun-ky/interstellar-tools/issues/226).
+ *
+ * :::
+ *
+ * @param h - Altitude $ h $ in **m** (finite).
+ * @param VE - Entry speed $ V_E $ in **m/s** (finite, > 0).
+ * @param gamma - Flight-path angle $ \gamma $ in **radians** (finite, non-zero, within [-π/2, π/2]).
+ * @param beta - Ballistic coefficient $ \beta $ in **kg/m²** (finite, > 0).
+ * @param rho0 - Reference density $ \rho_0 $ in **kg/m³** (finite, > 0).
+ * @param H - Scale height $ H $ in **m** (finite, > 0).
+ * @returns Speed $ V $ in **m/s**.
+ * @throws {TypeError} If any input is not a finite number.
+ * @throws {RangeError} If `VE`, `beta`, `rho0` or `H` is `<= 0`, or `gamma` is zero or past vertical.
+ * @group Entry
+ *
+ * @example
+ * ```ts
+ * import type { Radians } from '@interstellar-tools/types';
+ *
+ * // A 322 kg/m² capsule entering at 11 km/s, 6.5° below horizontal
+ * const v = ballisticEntrySpeed(40_000, 11_000, (-6.5 * Math.PI / 180) as Radians, 322, 1.225, 7200);
+ * // v ≈ 6.9 km/s at 40 km
+ * ```
+ *
+ * @see {@link ballisticCoefficient}
+ * @see {@link ballisticPeakDeceleration}
+ * @see https://en.wikipedia.org/wiki/Atmospheric_entry Atmospheric entry
+ */
+export const ballisticEntrySpeed = (h, VE, gamma, beta, rho0, H) => {
+    assertFinite([
+        ['h', h],
+        ['VE', VE],
+        ['gamma', gamma],
+        ['beta', beta],
+        ['rho0', rho0],
+        ['H', H]
+    ]);
+    assertPositive([
+        ['VE', VE],
+        ['beta', beta],
+        ['rho0', rho0],
+        ['H', H]
+    ]);
+    assertFlightPathAngle(gamma);
+    const k = (rho0 * H) / (2 * beta * Math.sin(Math.abs(gamma)));
+    return VE * Math.exp(-k * Math.exp(-h / H));
+};
+//# sourceMappingURL=ballistic-entry-speed.js.map

package/dist/categories/entry/ballistic-entry-speed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ballistic-entry-speed.js","sourceRoot":"","sources":["../../../src/categories/entry/ballistic-entry-speed.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,cAAc,EACf,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,CAAS,EACT,EAAU,EACV,KAAa,EACb,IAAY,EACZ,IAAY,EACZ,CAAS,EACD,EAAE;IACV,YAAY,CAAC;QACX,CAAC,GAAG,EAAE,CAAC,CAAC;QACR,CAAC,IAAI,EAAE,EAAE,CAAC;QACV,CAAC,OAAO,EAAE,KAAK,CAAC;QAChB,CAAC,MAAM,EAAE,IAAI,CAAC;QACd,CAAC,MAAM,EAAE,IAAI,CAAC;QACd,CAAC,GAAG,EAAE,CAAC,CAAC;KACT,CAAC,CAAC;IACH,cAAc,CAAC;QACb,CAAC,IAAI,EAAE,EAAE,CAAC;QACV,CAAC,MAAM,EAAE,IAAI,CAAC;QACd,CAAC,MAAM,EAAE,IAAI,CAAC;QACd,CAAC,GAAG,EAAE,CAAC,CAAC;KACT,CAAC,CAAC;IACH,qBAAqB,CAAC,KAAK,CAAC,CAAC;IAE7B,MAAM,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAE9D,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC,CAAC"}