refactor(space): separate satellite and mission layer components

This commit is contained in:
Sameh Khamis committed 2026-09-13 13:12:34 -07:00
1 parent 61db945b21
commit ce0568983a
44 files changed
+8767 -6095

No files matched your search

+375
View File
@@ -0,0 +1,375 @@
import * as Cesium from 'cesium';
import {
REPLAY_ASCENT_CAMERA_OFFSET_RAD,
REPLAY_ORBIT_CAMERA_OFFSET_RAD,
MISSION_CLOSE_VIEW_RANGE_M,
MISSION_GLOBE_VIEW_RANGE_M,
REPLAY_INITIAL_RANGE_M,
REPLAY_LOCAL_MAX_RANGE_M,
REPLAY_CONTEXT_ALTITUDE_END_M,
REPLAY_CONTEXT_MAX_RANGE_M,
REPLAY_ORBIT_PULLBACK_FRACTION,
REPLAY_ORBIT_GLOBE_RANGE_M,
REPLAY_ORBIT_FRAME_CENTER_BLEND,
} from './policy.js';
export function createCamera({ state: layerState, services, parts, source }) {
function cameraHeadingForPath(path, progress, fallback = Math.PI) {
if (!path?.length) return fallback;
const current = parts.paths.samplePath(path, progress);
const currentCartographic =
Cesium.Ellipsoid.WGS84.cartesianToCartographic(current);
if (!currentCartographic) return fallback;
for (const step of [0.01, 0.025, 0.05, 0.1, 0.2]) {
const next = parts.paths.samplePath(path, Math.min(1, progress + step));
const nextCartographic =
Cesium.Ellipsoid.WGS84.cartesianToCartographic(next);
if (!nextCartographic) continue;
const geodesic = new Cesium.EllipsoidGeodesic(
currentCartographic,
nextCartographic,
);
if (
geodesic.surfaceDistance > 10 &&
Number.isFinite(geodesic.startHeading)
) {
// HeadingPitchRange positions the camera opposite its heading vector.
// Passing the forward path heading therefore keeps the camera behind
// the vehicle, with the remaining ascent receding into the scene.
return Cesium.Math.zeroToTwoPi(geodesic.startHeading);
}
}
return fallback;
}
/**
* Resolve the initial replay heading as a profile view of the path.
* @param {Cesium.Cartesian3[]} path Replay path.
* @returns {number} Heading perpendicular to the initial path direction.
*/
function replayInitialCameraHeading(path) {
return Cesium.Math.zeroToTwoPi(
cameraHeadingForPath(path, 0, Math.PI) + Cesium.Math.PI_OVER_TWO,
);
}
/**
* Keep ascent framing behind and slightly to one side of the vehicle, then
* widen that rear-quarter angle as the orbit becomes visible.
* @param {number} pathHeading Forward path bearing in radians.
* @param {number} orbitBlend Normalized orbit-camera transition.
* @returns {number} Cesium HeadingPitchRange heading.
*/
function replayChaseCameraHeading(pathHeading, orbitBlend = 0) {
const blend = Cesium.Math.clamp(Number(orbitBlend) || 0, 0, 1);
return Cesium.Math.zeroToTwoPi(
pathHeading +
Cesium.Math.lerp(
REPLAY_ASCENT_CAMERA_OFFSET_RAD,
REPLAY_ORBIT_CAMERA_OFFSET_RAD,
blend,
),
);
}
/**
* Limit replay-camera yaw changes so a path heading wrap or insertion turn
* cannot swing the chase view through the front of the vehicle.
* @param {number} previous Previous Cesium heading in radians.
* @param {number} desired Desired Cesium heading in radians.
* @param {number} [maxStepRad] Maximum angular change for one rendered frame.
* @returns {number}
*/
function smoothReplayCameraHeading(
previous,
desired,
maxStepRad = Cesium.Math.toRadians(2),
) {
if (!Number.isFinite(previous)) return Cesium.Math.zeroToTwoPi(desired);
if (!Number.isFinite(desired)) return Cesium.Math.zeroToTwoPi(previous);
const delta = Cesium.Math.negativePiToPi(desired - previous);
const step = Cesium.Math.clamp(
delta,
-Math.abs(maxStepRad),
Math.abs(maxStepRad),
);
return Cesium.Math.zeroToTwoPi(previous + step);
}
/**
* Blend from a global nadir view into an oblique local 3D view as the user
* approaches a selected launch site.
* @param {number} rangeM Camera distance from the launch-site anchor.
* @returns {number} Cesium camera pitch in radians.
*/
function missionZoomPitch(rangeM) {
const range = Math.max(0, Number(rangeM) || 0);
const blend = Cesium.Math.clamp(
(Math.log(Math.max(range, MISSION_CLOSE_VIEW_RANGE_M)) -
Math.log(MISSION_CLOSE_VIEW_RANGE_M)) /
(Math.log(MISSION_GLOBE_VIEW_RANGE_M) -
Math.log(MISSION_CLOSE_VIEW_RANGE_M)),
0,
1,
);
return Cesium.Math.lerp(
Cesium.Math.toRadians(-42),
-Cesium.Math.PI_OVER_TWO,
blend,
);
}
/**
* Resolve the replay camera offset for either close ascent tracking or the
* orbital globe pullback.
* @param {{ascending: boolean, phaseProgress: number}} state Replay phase.
* @param {number} altitudeM Animated vehicle altitude above the ellipsoid.
* @returns {{range: number, pitch: number}}
*/
function replayCameraView(state, altitudeM) {
const altitude = Math.max(0, Number(altitudeM) || 0);
const localRange = Cesium.Math.clamp(
REPLAY_INITIAL_RANGE_M + altitude * 0.7,
REPLAY_INITIAL_RANGE_M,
REPLAY_LOCAL_MAX_RANGE_M,
);
const rawContextBlend = Cesium.Math.clamp(
(altitude - 20000) / (REPLAY_CONTEXT_ALTITUDE_END_M - 20000),
0,
1,
);
const contextBlend =
rawContextBlend * rawContextBlend * (3 - 2 * rawContextBlend);
const contextRange = Cesium.Math.clamp(
180000 + altitude * 3.8,
MISSION_CLOSE_VIEW_RANGE_M,
REPLAY_CONTEXT_MAX_RANGE_M,
);
const ascentRange = Cesium.Math.lerp(
localRange,
contextRange,
contextBlend,
);
const ascentPitch = Cesium.Math.lerp(
Cesium.Math.toRadians(-20),
Cesium.Math.toRadians(-34),
contextBlend,
);
if (state?.ascending) {
return { range: ascentRange, pitch: ascentPitch };
}
const rawBlend = Cesium.Math.clamp(
(Number(state?.phaseProgress) || 0) / REPLAY_ORBIT_PULLBACK_FRACTION,
0,
1,
);
const blend = rawBlend * rawBlend * (3 - 2 * rawBlend);
return {
range: Cesium.Math.lerp(ascentRange, REPLAY_ORBIT_GLOBE_RANGE_M, blend),
// Keep an oblique tactical view of the complete orbit rather than ending
// in a nadir view. This also prevents the camera from appearing to
// return toward the launch site after insertion.
pitch: Cesium.Math.lerp(ascentPitch, Cesium.Math.toRadians(-45), blend),
};
}
/**
* Move the orbit-follow target from the vehicle toward its sub-satellite
* globe anchor, keeping Earth centered while the vehicle remains in frame.
* @param {Cesium.Cartesian3} position Animated orbital position.
* @param {number} orbitBlend Normalized orbit-camera transition.
* @returns {Cesium.Cartesian3} Camera look-at target.
*/
function replayOrbitGlobeAnchor(position, orbitBlend = 0) {
if (!position) return position;
const blend = Cesium.Math.clamp(Number(orbitBlend) || 0, 0, 1);
if (blend <= 0) return Cesium.Cartesian3.clone(position);
const cartographic =
Cesium.Ellipsoid.WGS84.cartesianToCartographic(position);
if (!cartographic) return Cesium.Cartesian3.clone(position);
const altitude = Math.max(0, cartographic.height || 0);
return Cesium.Cartesian3.fromRadians(
cartographic.longitude,
cartographic.latitude,
Cesium.Math.lerp(altitude, altitude * 0.1, blend),
);
}
/**
* Keep the orbital camera's look-at frame biased toward the moving vehicle.
* Blending completely to a whole-orbit bounding-sphere center can place the
* target at (or numerically close to) Earth's center. That frame is singular
* for a heading/pitch camera and lets compact-orbit vehicles leave the view as
* the camera rotates. Retaining a radial vehicle bias keeps the local frame
* stable while the wider camera range still contains Earth and the full orbit.
* @param {Cesium.Cartesian3} vehicleAnchor Globe-side anchor below the vehicle.
* @param {Cesium.Cartesian3|null} frameCenter Combined Earth/orbit frame center.
* @param {number} orbitBlend Normalized orbit-camera transition.
* @returns {Cesium.Cartesian3} Stable camera look-at target.
*/
function replayOrbitCameraTarget(vehicleAnchor, frameCenter, orbitBlend = 0) {
if (!vehicleAnchor) return vehicleAnchor;
if (!frameCenter) return Cesium.Cartesian3.clone(vehicleAnchor);
const blend =
Cesium.Math.clamp(Number(orbitBlend) || 0, 0, 1) *
REPLAY_ORBIT_FRAME_CENTER_BLEND;
return Cesium.Cartesian3.lerp(
vehicleAnchor,
frameCenter,
blend,
new Cesium.Cartesian3(),
);
}
/**
* Build a stable orbit-relative camera pose. The camera remains on one side
* of the orbital plane and uses the vehicle radial as its visual up axis.
* Consequently the forward orbit tangent always projects toward screen-left
* instead of changing direction when local compass headings wrap near a pole.
* @param {Cesium.Cartesian3} position Current vehicle position.
* @param {Cesium.Cartesian3} tangentPosition Nearby forward path position.
* @param {Cesium.Cartesian3} target Camera look-at target.
* @param {number} range Camera distance from the target.
* @param {number} pitch Camera elevation below the local horizon.
* @returns {{destination: Cesium.Cartesian3, direction: Cesium.Cartesian3, up: Cesium.Cartesian3}|null}
*/
function replayOrbitCameraPose(
position,
tangentPosition,
target,
range,
pitch,
) {
if (!position || !tangentPosition || !target) return null;
const radial = Cesium.Cartesian3.normalize(
Cesium.Cartesian3.clone(position),
new Cesium.Cartesian3(),
);
const tangent = Cesium.Cartesian3.subtract(
tangentPosition,
position,
new Cesium.Cartesian3(),
);
if (Cesium.Cartesian3.magnitudeSquared(tangent) < 1) return null;
Cesium.Cartesian3.normalize(tangent, tangent);
const orbitNormal = Cesium.Cartesian3.cross(
radial,
tangent,
new Cesium.Cartesian3(),
);
if (Cesium.Cartesian3.magnitudeSquared(orbitNormal) < 1e-12) return null;
Cesium.Cartesian3.normalize(orbitNormal, orbitNormal);
const distance = Math.max(1, Number(range) || 1);
const elevation = Cesium.Math.clamp(
Math.abs(Number(pitch) || 0),
Cesium.Math.toRadians(5),
Cesium.Math.toRadians(80),
);
const planeOffset = Cesium.Cartesian3.multiplyByScalar(
orbitNormal,
Math.cos(elevation) * distance,
new Cesium.Cartesian3(),
);
const radialOffset = Cesium.Cartesian3.multiplyByScalar(
radial,
Math.sin(elevation) * distance,
new Cesium.Cartesian3(),
);
const destination = Cesium.Cartesian3.add(
target,
planeOffset,
new Cesium.Cartesian3(),
);
Cesium.Cartesian3.add(destination, radialOffset, destination);
const direction = Cesium.Cartesian3.normalize(
Cesium.Cartesian3.subtract(target, destination, new Cesium.Cartesian3()),
new Cesium.Cartesian3(),
);
const radialAlongView = Cesium.Cartesian3.multiplyByScalar(
direction,
Cesium.Cartesian3.dot(radial, direction),
new Cesium.Cartesian3(),
);
const up = Cesium.Cartesian3.normalize(
Cesium.Cartesian3.subtract(
radial,
radialAlongView,
new Cesium.Cartesian3(),
),
new Cesium.Cartesian3(),
);
return { destination, direction, up };
}
/**
* Build one conservative frame that contains both Earth and the complete
* selected orbit. High-apogee missions cannot be composed from the vehicle's
* instantaneous altitude alone because the opposite side of the orbit may
* extend much farther from the globe.
* @param {Cesium.Cartesian3[]} orbitPath Selected orbit samples.
* @returns {Cesium.BoundingSphere} Combined Earth/orbit frame.
*/
function replayOrbitFrameSphere(orbitPath = []) {
const earth = new Cesium.BoundingSphere(
Cesium.Cartesian3.ZERO,
Cesium.Ellipsoid.WGS84.maximumRadius,
);
if (!Array.isArray(orbitPath) || orbitPath.length < 2) return earth;
const orbit = Cesium.BoundingSphere.fromPoints(orbitPath);
return Cesium.BoundingSphere.union(
earth,
orbit,
new Cesium.BoundingSphere(),
);
}
/**
* Ensure high-altitude missions frame both the globe and selected vehicle.
* @param {number} baseRange Range from the normal replay camera transition.
* @param {number} altitudeM Vehicle altitude above the ellipsoid.
* @param {number} orbitBlend Normalized orbit-camera transition.
* @param {number} frameRadiusM Radius of the combined Earth/orbit frame.
* @returns {number} Camera range in metres.
*/
function replayOrbitGlobeRange(
baseRange,
altitudeM,
orbitBlend = 0,
frameRadiusM = 0,
) {
const range = Math.max(0, Number(baseRange) || 0);
const altitude = Math.max(0, Number(altitudeM) || 0);
const frameRadius = Math.max(0, Number(frameRadiusM) || 0);
const blend = Cesium.Math.clamp(Number(orbitBlend) || 0, 0, 1);
const globeAndVehicleRange = Math.max(
range,
altitude + Cesium.Ellipsoid.WGS84.maximumRadius * 2.4,
frameRadius * 3,
);
return Cesium.Math.lerp(range, globeAndVehicleRange, blend);
}
return {
cameraHeadingForPath,
replayInitialCameraHeading,
replayChaseCameraHeading,
smoothReplayCameraHeading,
missionZoomPitch,
replayCameraView,
replayOrbitGlobeAnchor,
replayOrbitCameraTarget,
replayOrbitCameraPose,
replayOrbitFrameSphere,
replayOrbitGlobeRange,
};
}