@johnmorrisdotca/uchusen-rockets 0.19.0 → 0.20.0

package/dist/physics/transfers.js

@@ -0,0 +1,155 @@
+// Planning a transfer: the speed a burn needs to reach a new orbit size, a change of plane, the bi-elliptic transfer, where two orbits
+// in one plane cross, and where a craft's orbit crosses another plane (its nodes), with when it gets there. Pure.
+// Ported from Orbiter (https://github.com/orbitersim/orbiter): the speed change that keeps a chosen semi-major axis and the crossing of
+// two orbits from Src/Orbiter/MfdTransfer.cpp (Instrument_Transfer::CalcElements and UpdateDraw), and the relative inclination, the
+// nodes, the time to each and the speed there from Src/Orbiter/MfdAlign.cpp (Instrument_OPlaneAlign::UpdateDraw). Copyright (c)
+// 2000-2026 Martin Schweiger, MIT licence (LICENSES/Orbiter-MIT.txt). Changed in the port: functions of elements in place of the
+// displays; a right-handed frame, so Orbiter's node line crossp(nm1, nm2) is nm2 x nm1 here; both crossings of two orbits are given
+// (Orbiter's display picks one); angles by atan2. Written here: the bi-elliptic transfer and the plane change by the law of cosines
+// (Orbiter's display estimates a plane change as the speed times the angle, for a push kept normal to the plane).
+import { stateAtTrueAnomaly, timeToTrueAnomaly } from "./elements.js";
+import { cross, dot, length, scale } from "./vector.js";
+const TAU = 2 * Math.PI;
+const posAngle = (angle) => ((angle % TAU) + TAU) % TAU;
+/**
+ * The speed change at distance `r` that turns an orbit of semi-major axis `aNow` into one of `aNew`, burning along the speed (the vis-viva equation, as Orbiter's transfer display rescales a burn to keep a chosen orbit).
+ * @param gm The body's gravitational parameter, m^3/s^2.
+ * @param r The distance of the burn from the body's centre, metres.
+ * @param aNow The semi-major axis before, metres (negative for an open path).
+ * @param aNew The semi-major axis wanted, metres.
+ * @returns The change of speed, metres a second: positive to speed up (prograde), negative to slow down.
+ * @example
+ * ```ts
+ * import { speedChangeFor } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(speedChangeFor(3.986004418e14, 6_778_000, 6_778_000, (6_778_000 + 42_164_000) / 2).toFixed(1), "m/s");
+ * ```
+ */
+export const speedChangeFor = (gm, r, aNow, aNew) => Math.sqrt(gm * (2 / r - 1 / aNew)) - Math.sqrt(gm * (2 / r - 1 / aNow));
+/**
+ * The change of speed that turns a speed through an angle, and to a new size if given: `sqrt(v1^2 + v2^2 - 2 v1 v2 cos angle)`, which is `2 v sin(angle / 2)` for a pure change of plane. Orbiter's plane-alignment display estimates `v angle` instead, the cost of keeping the push normal to the plane all through the burn.
+ * @param speed The speed before, metres a second.
+ * @param angle The angle to turn through, radians.
+ * @param newSpeed The speed after; the same as before when left out.
+ * @returns The change of speed, metres a second.
+ * @example
+ * ```ts
+ * import { planeChange } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * console.log(planeChange(7_669, (10 * Math.PI) / 180).toFixed(0), "m/s for 10 degrees in low orbit");
+ * ```
+ */
+export function planeChange(speed, angle, newSpeed = speed) {
+    return Math.sqrt(Math.max(0, speed * speed + newSpeed * newSpeed - 2 * speed * newSpeed * Math.cos(angle)));
+}
+/**
+ * The bi-elliptic transfer between two circular orbits about one body: out on one half-ellipse to a far point `rb`, a burn there, and back on a second half-ellipse to the final orbit. With `rb` equal to the final radius its speed changes are the Hohmann transfer's (and its time adds the half turn of the final circle that the second leg then is).
+ * @param gm The body's gravitational parameter, m^3/s^2.
+ * @param r1 The starting radius, metres.
+ * @param r2 The final radius, metres.
+ * @param rb The far point, metres (at least the larger of `r1` and `r2`).
+ * @returns The three speed changes (metres a second, each positive), their sum, and the flight time (seconds).
+ * @example
+ * ```ts
+ * import { biElliptic } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const far = biElliptic(3.986004418e14, 6_778_000, 384_400_000, 1_000_000_000);
+ * console.log(far.total.toFixed(0), "m/s,", (far.seconds / 86_400).toFixed(1), "days");
+ * ```
+ */
+export function biElliptic(gm, r1, r2, rb) {
+    const a1 = (r1 + rb) / 2;
+    const a2 = (r2 + rb) / 2;
+    const visViva = (r, a) => Math.sqrt(gm * (2 / r - 1 / a));
+    const dv1 = Math.abs(visViva(r1, a1) - Math.sqrt(gm / r1));
+    const dv2 = Math.abs(visViva(rb, a2) - visViva(rb, a1));
+    const dv3 = Math.abs(visViva(r2, a2) - Math.sqrt(gm / r2));
+    return { dv1, dv2, dv3, total: dv1 + dv2 + dv3, seconds: Math.PI * (Math.sqrt(a1 ** 3 / gm) + Math.sqrt(a2 ** 3 / gm)) };
+}
+/** The unit normal of an orbit's plane, along its angular momentum. */
+const normalOf = (el) => [Math.sin(el.i) * Math.sin(el.node), -Math.sin(el.i) * Math.cos(el.node), Math.cos(el.i)];
+/**
+ * The angle between two orbits' planes.
+ * @param a One orbit's elements.
+ * @param b The other's.
+ * @returns The angle, radians, 0 to pi.
+ * @example
+ * ```ts
+ * import { elementsOf, relativeInclination } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const gm = 3.986004418e14;
+ * const iss = elementsOf(gm, [6_778_000, 0, 0], [0, 4_766, 6_008]);
+ * const equator = elementsOf(gm, [6_778_000, 0, 0], [0, 7_669, 0]);
+ * console.log(((relativeInclination(iss, equator) * 180) / Math.PI).toFixed(1), "degrees");
+ * ```
+ */
+export function relativeInclination(a, b) {
+    const na = normalOf(a);
+    const nb = normalOf(b);
+    return Math.atan2(length(cross(na, nb)), dot(na, nb));
+}
+/**
+ * Where a craft's orbit crosses another orbit's plane, and when it gets there (Orbiter's plane-alignment display): the ascending node, where it passes to the north of the other plane, and the descending node.
+ * @param ship The craft's elements.
+ * @param target The elements of the orbit whose plane is wanted (another craft, a moon, or one made up for the plane).
+ * @returns The angle between the planes and the two nodes, or null when the planes are the same (no nodes).
+ * @example
+ * ```ts
+ * import { elementsOf, nodes } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const gm = 3.986004418e14;
+ * const tilted = elementsOf(gm, [6_778_000, 0, 0], [0, 4_766, 6_008]);
+ * const equator = elementsOf(gm, [6_778_000, 0, 0], [0, 7_669, 0]);
+ * const n = nodes(tilted, equator);
+ * console.log(n?.descending.seconds.toFixed(0), "s to the descending node,", n?.descending.dv.toFixed(0), "m/s there");
+ * ```
+ */
+export function nodes(ship, target) {
+    const n1 = normalOf(ship);
+    const n2 = normalOf(target);
+    const line = cross(n2, n1);
+    const l = length(line);
+    if (l < 1e-12)
+        return null;
+    const nd = scale(line, 1 / l);
+    const reli = Math.atan2(l, dot(n1, n2));
+    const here = stateAtTrueAnomaly(ship, ship.trueAnomaly).position;
+    const ahead = Math.atan2(dot(cross(here, nd), n1), dot(here, nd));
+    const at = (trueAnomaly) => {
+        const speed = length(stateAtTrueAnomaly(ship, trueAnomaly).velocity);
+        return { trueAnomaly, seconds: timeToTrueAnomaly(ship, trueAnomaly), speed, dv: planeChange(speed, reli) };
+    };
+    const ascending = posAngle(ship.trueAnomaly + posAngle(ahead));
+    return { relativeInclination: reli, ascending: at(ascending), descending: at(posAngle(ascending + Math.PI)) };
+}
+/**
+ * Where two orbits about one body, in one plane, cross: the points that are on both (Orbiter's transfer display, which finds where a transfer orbit meets its target's). Both orbits must share their plane; for orbits in different planes, use the {@link nodes} first.
+ * @param path The orbit flown (a transfer orbit).
+ * @param target The orbit to reach.
+ * @returns The true anomalies on `path` of the crossings, radians, 0 to 2 pi in increasing order: none, one (touching) or two (on an open path, only points it reaches).
+ * @example
+ * ```ts
+ * import { crossings, elementsOf } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const gm = 3.986004418e14;
+ * const transfer = elementsOf(gm, [6_778_000, 0, 0], [0, 9_000, 0]);
+ * const higher = elementsOf(gm, [10_000_000, 0, 0], [0, Math.sqrt(gm / 10_000_000), 0]);
+ * console.log(crossings(transfer, higher).map((nu) => ((nu * 180) / Math.PI).toFixed(1)));
+ * ```
+ */
+export function crossings(path, target) {
+    const domega = target.longitudePeriapsis - path.longitudePeriapsis;
+    const p1 = path.semiLatus;
+    const p2 = target.semiLatus;
+    const a = path.e / p1 - (target.e / p2) * Math.cos(domega);
+    const b = (-target.e / p2) * Math.sin(domega);
+    const c = 1 / p1 - 1 / p2;
+    const r = Math.hypot(a, b);
+    if (r === 0 || Math.abs(c) > r)
+        return [];
+    const centre = Math.atan2(b, a);
+    const half = Math.acos(Math.max(-1, Math.min(1, -c / r)));
+    const found = half === 0 ? [centre] : [centre - half, centre + half];
+    const reached = (nu) => 1 + path.e * Math.cos(nu) > 0 && 1 + target.e * Math.cos(nu - domega) > 0;
+    return found.map(posAngle).filter(reached).sort((x, y) => x - y);
+}

package/dist/physics/vector.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A vector in three dimensions: `[x, y, z]`, right-handed. The flight physics works in metres, metres a second and metres a second squared, in whatever frame the caller's bodies are given in (for example the ecliptic of J2000 from the solar system's barycentre, or the Earth's equator from its centre).
+ *
+ * @example
+ * ```ts
+ * import type { Vec3 } from "@johnmorrisdotca/uchusen-rockets/physics";
+ *
+ * const issHeight: Vec3 = [6_778_000, 0, 0];
+ * console.log(issHeight[0]);
+ * ```
+ */
+export type Vec3 = readonly [number, number, number];
+export declare const add: (a: Vec3, b: Vec3) => Vec3;
+export declare const sub: (a: Vec3, b: Vec3) => Vec3;
+export declare const scale: (a: Vec3, k: number) => Vec3;
+/** `a + b k`, the step every integrator takes. */
+export declare const addScaled: (a: Vec3, b: Vec3, k: number) => Vec3;
+export declare const dot: (a: Vec3, b: Vec3) => number;
+export declare const cross: (a: Vec3, b: Vec3) => Vec3;
+export declare const length: (a: Vec3) => number;

package/dist/physics/vector.js

@@ -0,0 +1,9 @@
+// Three numbers for a place, a speed or an acceleration, and the few sums the flight physics needs. Pure.
+export const add = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+export const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+export const scale = (a, k) => [a[0] * k, a[1] * k, a[2] * k];
+/** `a + b k`, the step every integrator takes. */
+export const addScaled = (a, b, k) => [a[0] + b[0] * k, a[1] + b[1] * k, a[2] + b[2] * k];
+export const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+export const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+export const length = (a) => Math.hypot(a[0], a[1], a[2]);

package/dist/react.d.ts

@@ -90,6 +90,7 @@ export declare function UchusenRocket({ build, ...rest }: UchusenRocketProps): i
     accessKey?: string | undefined | undefined;
     "aria-selected"?: (boolean | "true" | "false") | undefined;
     hidden?: boolean | undefined | undefined;
+    lang?: string | undefined | undefined;
     defaultChecked?: boolean | undefined | undefined;
     defaultValue?: string | number | readonly string[] | undefined;
     suppressContentEditableWarning?: boolean | undefined | undefined;
@@ -101,7 +102,6 @@ export declare function UchusenRocket({ build, ...rest }: UchusenRocketProps): i
     contextMenu?: string | undefined | undefined;
     draggable?: (boolean | "true" | "false") | undefined;
     enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined | undefined;
-    lang?: string | undefined | undefined;
     nonce?: string | undefined | undefined;
     spellCheck?: (boolean | "true" | "false") | undefined;
     tabIndex?: number | undefined | undefined;

package/dist/rockets.d.ts

@@ -1,4 +1,5 @@
 import { type MakerId } from "./data/makers.ts";
+import { type CountryCode } from "./data/countries.ts";
 import type { Figure, Variant } from "./data/types.ts";
 import type { SourceId } from "./data/sources.ts";
 /**
@@ -34,6 +35,8 @@ export interface RocketEntry {
     maker: MakerId;
     /** Whose it is and who built it, as its source says, or a blank. */
     madeBy: Figure<string>;
+    /** Its country as an ISO 3166-1 alpha-2 code, as its source says, or a blank: none for a craft of several countries or an international body, or a ship of the SPX fleet. */
+    country: Figure<CountryCode>;
 }
 /**
  * A rocket on the list with no mesh yet: its name and the sourced facts to build it from.
@@ -54,6 +57,8 @@ export interface PlannedRocket {
     diameter: Figure;
     firstFlight: Figure<string>;
     source: SourceId;
+    /** Its country as an ISO 3166-1 alpha-2 code, as its source says, or a blank. */
+    country: Figure<CountryCode>;
 }
 /**
  * Whether a craft flies in space: the same ones that may be seen from straight above or below, including the fleet. A rocket or a place on the ground does not. On the compare page one of these stands on a marked plinth, so it is not read as a rocket on a pad.

package/dist/rockets.js

@@ -21,6 +21,7 @@ import { JUPITER_C_VARIANTS } from "./data/jupiterc.js";
 import { ISS_VARIANTS } from "./data/iss.js";
 import { HUBBLE_VARIANTS } from "./data/hubble.js";
 import { TIANGONG_VARIANTS } from "./data/tiangong.js";
+import { ROADSTER_VARIANTS } from "./data/roadster.js";
 import { STARSHIP_VARIANTS } from "./data/starship.js";
 import { FLEET_KIT_ROCKETS, FLEET_SLOT_NAMES } from "./data/fleet.js";
 import { CONCEPT_SLOT_NAMES, KAMINARI_VARIANTS } from "./data/kaminari-concepts.js";
@@ -29,8 +30,9 @@ import { KYOTORI_SLOT_NAMES, KYOTORI_VARIANTS } from "./data/ship-kyotori.js";
 import { DRONE_VARIANTS } from "./data/drone.js";
 import { ARIAKE_VARIANTS, SHIP_03_INSET_ROCKET, SHIP_03_SLOT_NAMES, SHIP_03_VARIANTS } from "./data/ship-03.js";
 import { MADE_BY } from "./data/makers.js";
+import { countryOf } from "./data/countries.js";
 /** Craft that fly in space: seen from any side, from straight above or below. Everything else stands on the ground or the sea, and keeps the ground in view. */
-const IN_SPACE = new Set(["dragon", "lunar-module", "apollo-soyuz", "gemini", "mercury", "iss", "hubble", "tiangong"]);
+const IN_SPACE = new Set(["dragon", "lunar-module", "apollo-soyuz", "gemini", "mercury", "iss", "hubble", "tiangong", "roadster"]);
 /**
  * Whether a craft flies in space: the same ones that may be seen from straight above or below, including the fleet. A rocket or a place on the ground does not. On the compare page one of these stands on a marked plinth, so it is not read as a rocket on a pad.
  *
@@ -40,11 +42,11 @@ const IN_SPACE = new Set(["dragon", "lunar-module", "apollo-soyuz", "gemini", "m
 export function fliesInSpace(id) {
     return IN_SPACE.has(id) || id in FLEET_KIT_ROCKETS || id.startsWith("fleet-");
 }
-/** Gives each variant its `view.tiltMax`: 90 degrees for a craft in space and the fleet, 45 for the rest. */
+/** Gives each variant its `view.tiltMax`: 90 degrees for a craft in space and the fleet, 45 for the rest. And each rocket its country. */
 function withTilt(rockets) {
     return Object.fromEntries(Object.entries(rockets).map(([id, rocket]) => {
         const tiltMax = fliesInSpace(id) ? 90 : 45;
-        return [id, { ...rocket, variants: rocket.variants.map((variant) => ({ ...variant, view: { tiltMax } })) }];
+        return [id, { ...rocket, country: countryOf(id), variants: rocket.variants.map((variant) => ({ ...variant, view: { tiltMax } })) }];
     }));
 }
 /**
@@ -78,6 +80,7 @@ export const ROCKETS = withTilt({
     "iss": { id: "iss", name: "International Space Station", status: "built", ...MADE_BY["iss"], variants: ISS_VARIANTS, defaultVariant: "iss" },
     "hubble": { id: "hubble", name: "Hubble Space Telescope", status: "built", ...MADE_BY["hubble"], variants: HUBBLE_VARIANTS, defaultVariant: "hubble" },
     tiangong: { id: "tiangong", name: "Tiangong 天宮", status: "built", ...MADE_BY["tiangong"], variants: TIANGONG_VARIANTS, defaultVariant: "tiangong" },
+    roadster: { id: "roadster", name: "Roadster", status: "built", ...MADE_BY["roadster"], variants: ROADSTER_VARIANTS, defaultVariant: "first-generation" },
     droneship: { id: "droneship", name: "Drone ships", status: "built", ...MADE_BY["droneship"], variants: DRONESHIP_VARIANTS, defaultVariant: "ocisly" },
     "landing-zone": { id: "landing-zone", name: "Landing zones", status: "built", ...MADE_BY["landing-zone"], variants: LANDING_ZONE_VARIANTS, defaultVariant: "lz-1" },
     "launch-tower": { id: "launch-tower", name: "Launch tower", status: "built", ...MADE_BY["launch-tower"], variants: TOWER_VARIANTS, defaultVariant: "stack" },
@@ -110,7 +113,7 @@ const fig = (value, source) => ({ value, source });
 export const PLANNED_ROCKETS = [
     { id: "vulcan-centaur", name: "Vulcan Centaur", status: "planned", height: fig(61.6, "wikipedia-vulcan"), diameter: fig(5.4, "wikipedia-vulcan"), firstFlight: { value: "2024-01-08", source: "wikipedia-vulcan" }, source: "wikipedia-vulcan" },
     { id: "ariane-6", name: "Ariane 6", status: "planned", height: fig(63, "wikipedia-ariane-6"), diameter: fig(5.4, "wikipedia-ariane-6"), firstFlight: { value: "2024-07-09", source: "wikipedia-ariane-6" }, source: "wikipedia-ariane-6" },
-];
+].map((rocket) => ({ ...rocket, country: countryOf(rocket.id) }));
 /**
  * Finds a rocket's variant, with its sourced sizes.
  *
@@ -235,6 +238,8 @@ export const SLOT_NAMES = {
     "arrays-p6": "Solar arrays on P6",
     "radiators-starboard": "Radiators, starboard",
     "radiators-port": "Radiators, port",
+    car: "The Roadster",
+    starman: "Starman",
     ground: "The ground and the road",
     pads: "The pads",
     "tank-farm": "The tank farm",

package/dist/sun.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Reads the `sun` attribute: the direction towards the Sun in the craft's own frame (Y up, +Z its nose or windward side), as three numbers. Anything else is no Sun, and the view keeps its showroom light.
+ *
+ * @param text The attribute's text, such as `"1, 0.2, -0.5"`.
+ * @returns The direction, one metre long, or null for a missing, malformed or zero value.
+ * @example
+ * ```ts
+ * import { parseSun } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(parseSun("2, 0, 0"), parseSun("east"), parseSun("0,0,0"));
+ * ```
+ */
+export declare function parseSun(text: string | null | undefined): readonly [number, number, number] | null;

package/dist/sun.js

@@ -0,0 +1,25 @@
+// Where the Sun is, for a craft drawn in space: one direction, read from text. Pure: no three.js and no DOM.
+/**
+ * Reads the `sun` attribute: the direction towards the Sun in the craft's own frame (Y up, +Z its nose or windward side), as three numbers. Anything else is no Sun, and the view keeps its showroom light.
+ *
+ * @param text The attribute's text, such as `"1, 0.2, -0.5"`.
+ * @returns The direction, one metre long, or null for a missing, malformed or zero value.
+ * @example
+ * ```ts
+ * import { parseSun } from "@johnmorrisdotca/uchusen-rockets";
+ *
+ * console.log(parseSun("2, 0, 0"), parseSun("east"), parseSun("0,0,0"));
+ * ```
+ */
+export function parseSun(text) {
+    if (typeof text !== "string" || text.length > 80)
+        return null;
+    const parts = text.split(",").map((one) => one.trim());
+    if (parts.length !== 3 || parts.some((one) => !/^-?(\d+\.?\d*|\.\d+)(e-?\d+)?$/i.test(one)))
+        return null;
+    const [x, y, z] = parts.map(Number);
+    const length = Math.hypot(x, y, z);
+    if (!Number.isFinite(length) || length < 1e-9)
+        return null;
+    return [x / length, y / length, z / length];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnmorrisdotca/uchusen-rockets",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Uchusen Rockets 宇宙船: line drawings and 3D views of rockets, as a web component. Every variant with its own sourced sizes, a typed way to assemble a rocket from parts, stack and separate. No logos. three.js is a peer dependency.",
   "keywords": [
     "rocket",
@@ -74,6 +74,11 @@
       "import": "./dist/journey/index.js",
       "default": "./dist/journey/index.js"
     },
+    "./physics": {
+      "types": "./dist/physics/index.d.ts",
+      "import": "./dist/physics/index.js",
+      "default": "./dist/physics/index.js"
+    },
     "./element": {
       "types": "./dist/element.d.ts",
       "import": "./dist/element.js",
@@ -135,10 +140,14 @@
     "size": "node scripts/docs-site.mjs size"
   },
   "peerDependencies": {
+    "@johnmorrisdotca/hata": ">=1.8.0 <2",
     "react": ">=18",
     "three": ">=0.170.0"
   },
   "peerDependenciesMeta": {
+    "@johnmorrisdotca/hata": {
+      "optional": true
+    },
     "react": {
       "optional": true
     },
@@ -156,6 +165,7 @@
     "@gltf-transform/extensions": "4.5.1",
     "@gltf-transform/functions": "4.5.1",
     "@johnmorrisdotca/chikyu-earth": "0.10.0",
+    "@johnmorrisdotca/hata": "1.8.0",
     "@johnmorrisdotca/kazoku-ui": "^0.32.0",
     "@johnmorrisdotca/wakusei-planets": "0.17.1",
     "@playwright/test": "1.64.0",