mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 16:22:20 +00:00
feat(globe): implement the engine on Navara
src/globe/navara builds the GlobeEngine on a Navara 0.2.1 ThreeView. The engine keeps the camera pose in src/geo values and pushes it to Navara's setCamera in degrees (Cesium's heading/pitch/roll convention, S4); whatever Navara moves itself (user input, its flyTo arc) is read back from the drawn camera each frame. Projection, picks against the ellipsoid and the view rectangle are geo math on that pose, with Navara's fov kept on Cesium's 60° across the wider side. - flights: Navara flyTo in ms with mapped easings, cancelFlight via an empty setCamera, user input cancels a flight as in Cesium - events: moveStart/moveEnd (500 ms still)/changed from the pose - render: forceUpdate and animation (render on demand, S5) - surface: S2 CPU ray over 3D-tile meshes, Navara terrain fallback - maps: OSM/Esri raster, Re:Earth or ion quantized-mesh terrain, Google 3D tiles with a browser key and Google's logo - input: DOM pointer events with ScreenSpaceEventHandler semantics - the three private Navara members used live in internals.js, pinned to 0.2.1 by a test index.js builds the product view (MSAA 4, native pixel ratio, preserved drawing buffer, effects=minimal) for a dynamic import. The contract QA script gains --engine=navara on a dev-only harness page: 46/46 contract and 4/4 Navara checks; Cesium stays 53/53.
This commit is contained in:
1 parent
b6ac0e9c99
commit
90c8e7763a
19 files changed
+3311
No files matched your search
@@ -0,0 +1,388 @@
|
||||
// The GlobeCamera of the Navara engine. The engine keeps the camera pose
|
||||
// itself, in src/geo values, and Navara's camera follows it:
|
||||
//
|
||||
// - programmatic moves (setView, lookAt, zoom, a landed flight) change the
|
||||
// pose at once, as Cesium does, and push it to Navara's setCamera in
|
||||
// degrees; Navara draws it from its next update. Navara clamps pitch to
|
||||
// ±89.99°, so its redraw of a pushed pose is not read back;
|
||||
// - whatever Navara moves by itself (user input, its own flyTo arc) is read
|
||||
// back from the drawn camera every frame (sync) and becomes the pose;
|
||||
// - camera events come from frame-to-frame changes of the pose: moveStart on
|
||||
// the first moving frame, moveEnd once it has been still for 500 ms of
|
||||
// wall time (Cesium's cameraEventWaitTime), changed past percentageChanged.
|
||||
//
|
||||
// The port is the engine's thin layer over the Navara view (apply, read, fly,
|
||||
// stop, size, requestFrame); see createNavaraEngine.js.
|
||||
|
||||
import * as geo from '../../geo/index.js';
|
||||
import { createEngineEvent } from '../contract.js';
|
||||
import {
|
||||
cesiumFovy,
|
||||
headingPitchRoll,
|
||||
horizonVisible,
|
||||
lookAtFrame,
|
||||
navaraPose,
|
||||
orientationVectors,
|
||||
pickEllipsoid,
|
||||
pickRay,
|
||||
projectToWindow,
|
||||
rectangleViewPosition,
|
||||
sphereRange,
|
||||
viewProjection,
|
||||
viewRectangle,
|
||||
} from './cameraMath.js';
|
||||
|
||||
const { cartesian3, cartographic, math, matrix4 } = geo;
|
||||
const WGS84 = geo.ellipsoid.WGS84;
|
||||
const CESIUM_DEFAULTS = Object.freeze({
|
||||
heading: 0,
|
||||
pitch: -math.PI_OVER_TWO,
|
||||
roll: 0,
|
||||
});
|
||||
const DEFAULT_ZOOM_AMOUNT = 100000; // Cesium's camera.defaultZoomAmount
|
||||
const MOVE_END_WAIT_MS = 500; // Cesium's scene.cameraEventWaitTime
|
||||
const DEFAULT_PERCENTAGE_CHANGED = 0.5; // Cesium's camera.percentageChanged
|
||||
// How far Navara's drawing of a pushed pose may be from it and still count as
|
||||
// that pose: its ±89.99° pitch clamp is 1.7e-4 rad; positions land exactly.
|
||||
const PUSHED_ANGLE_TOLERANCE = 1e-3;
|
||||
const PUSHED_POSITION_TOLERANCE = 0.05;
|
||||
// Navara 0.2.1 flyTo presets for the contract easings. Navara has no sine
|
||||
// preset; quadInOut is the closest curve.
|
||||
const NAVARA_EASINGS = Object.freeze({
|
||||
linear: 'linear',
|
||||
cubicInOut: 'cubicInOut',
|
||||
sinusoidalInOut: 'quadInOut',
|
||||
});
|
||||
|
||||
const copy3 = (value) => cartesian3.create(value.x, value.y, value.z);
|
||||
const copyPose = (pose) => ({
|
||||
position: copy3(pose.position),
|
||||
direction: copy3(pose.direction),
|
||||
up: copy3(pose.up),
|
||||
});
|
||||
const angleBetween = (a, b) =>
|
||||
Math.acos(math.clamp(cartesian3.dot(a, b), -1, 1));
|
||||
// Unit vectors are compared by chord length (≈ the angle when small), which,
|
||||
// unlike acos of the dot product, does not turn last-bit noise into 1e-7 rad.
|
||||
function posesNear(a, b, distance, angle) {
|
||||
return (
|
||||
cartesian3.distance(a.position, b.position) <= distance &&
|
||||
cartesian3.distance(a.direction, b.direction) <= angle &&
|
||||
cartesian3.distance(a.up, b.up) <= angle
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* @param {{
|
||||
* port: {
|
||||
* apply: (pose: object) => void,
|
||||
* read: () => ({ position: object, direction: object, up: object } | null | undefined),
|
||||
* fly: (pose: object, options: { duration?: number, easing?: string }) => Promise<boolean>,
|
||||
* stop: () => void,
|
||||
* size: () => { width: number, height: number },
|
||||
* requestFrame: () => void,
|
||||
* },
|
||||
* clock?: { now: () => number, setTimeout: Function, clearTimeout: Function },
|
||||
* }} options
|
||||
*/
|
||||
export function createCameraModel({
|
||||
port,
|
||||
clock = {
|
||||
now: () => performance.now(),
|
||||
setTimeout: (fn, ms) => setTimeout(fn, ms),
|
||||
clearTimeout: (timer) => clearTimeout(timer),
|
||||
},
|
||||
}) {
|
||||
const events = {
|
||||
changed: createEngineEvent(),
|
||||
moveStart: createEngineEvent(),
|
||||
moveEnd: createEngineEvent(),
|
||||
};
|
||||
const initial = port.read();
|
||||
let state = initial
|
||||
? copyPose(initial)
|
||||
: (() => {
|
||||
const position = cartesian3.fromDegrees(0, 0, 1e7);
|
||||
return {
|
||||
position,
|
||||
...orientationVectors(position, 0, -math.PI_OVER_TWO, 0),
|
||||
};
|
||||
})();
|
||||
let transform = [...matrix4.IDENTITY];
|
||||
let percentageChanged = DEFAULT_PERCENTAGE_CHANGED;
|
||||
let flight = null;
|
||||
let pushed = null;
|
||||
let lastSeen = initial ? copyPose(initial) : null;
|
||||
let lastFramePose = copyPose(state);
|
||||
let lastChangedPose = copyPose(state);
|
||||
let moving = false;
|
||||
let lastMoveAt = 0;
|
||||
let moveEndTimer = null;
|
||||
let destroyed = false;
|
||||
|
||||
const view = () => {
|
||||
const { width, height } = port.size();
|
||||
return { ...state, fovy: cesiumFovy(width, height), width, height };
|
||||
};
|
||||
|
||||
// A programmatic pose: exact here, pushed to Navara for drawing.
|
||||
function place(pose) {
|
||||
state = copyPose(pose);
|
||||
pushed = copyPose(pose);
|
||||
port.apply(navaraPose(state.position, state.direction, state.up));
|
||||
port.requestFrame();
|
||||
}
|
||||
|
||||
function viewFor(destination, orientation) {
|
||||
const { width, height } = port.size();
|
||||
const position =
|
||||
'west' in destination
|
||||
? rectangleViewPosition(
|
||||
destination,
|
||||
cesiumFovy(width, height),
|
||||
width / height,
|
||||
)
|
||||
: copy3(destination);
|
||||
if (orientation && 'direction' in orientation)
|
||||
return {
|
||||
position,
|
||||
direction: cartesian3.normalize(
|
||||
orientation.direction,
|
||||
cartesian3.create(),
|
||||
),
|
||||
up: cartesian3.normalize(orientation.up, cartesian3.create()),
|
||||
};
|
||||
return {
|
||||
position,
|
||||
...orientationVectors(
|
||||
position,
|
||||
orientation?.heading ?? CESIUM_DEFAULTS.heading,
|
||||
orientation?.pitch ?? CESIUM_DEFAULTS.pitch,
|
||||
orientation?.roll ?? CESIUM_DEFAULTS.roll,
|
||||
),
|
||||
};
|
||||
}
|
||||
|
||||
function endFlight(current, outcome) {
|
||||
if (flight !== current) return;
|
||||
flight = null;
|
||||
if (outcome === 'cancel') current.options.cancel?.();
|
||||
}
|
||||
|
||||
function cancelCurrentFlight() {
|
||||
const current = flight;
|
||||
if (!current) return;
|
||||
endFlight(current, 'cancel');
|
||||
port.stop();
|
||||
}
|
||||
|
||||
function land(options, target) {
|
||||
if (options.endTransform) transform = [...options.endTransform];
|
||||
place(target);
|
||||
}
|
||||
|
||||
function startFlight(options, target) {
|
||||
cancelCurrentFlight();
|
||||
if (options.duration !== undefined && options.duration <= 0) {
|
||||
land(options, target);
|
||||
options.complete?.();
|
||||
return;
|
||||
}
|
||||
const current = { options };
|
||||
flight = current;
|
||||
// Navara moves the camera from here on; read it back every frame.
|
||||
pushed = null;
|
||||
const flyOptions = {};
|
||||
if (options.duration !== undefined)
|
||||
flyOptions.duration = options.duration * 1000;
|
||||
if (options.easing !== undefined)
|
||||
flyOptions.easing = NAVARA_EASINGS[options.easing];
|
||||
port
|
||||
.fly(navaraPose(target.position, target.direction, target.up), flyOptions)
|
||||
.then(
|
||||
(arrived) => {
|
||||
if (flight !== current || destroyed) return;
|
||||
if (!arrived) return endFlight(current, 'cancel');
|
||||
flight = null;
|
||||
land(options, target);
|
||||
options.complete?.();
|
||||
},
|
||||
() => endFlight(current, 'cancel'),
|
||||
);
|
||||
}
|
||||
|
||||
/** Reads Navara's drawn camera; called once per frame before preRender. */
|
||||
function sync() {
|
||||
const seen = port.read();
|
||||
if (!seen) return;
|
||||
const moved = !lastSeen || !posesNear(seen, lastSeen, 1e-6, 1e-10);
|
||||
lastSeen = copyPose(seen);
|
||||
if (!moved) return;
|
||||
if (
|
||||
pushed &&
|
||||
posesNear(seen, pushed, PUSHED_POSITION_TOLERANCE, PUSHED_ANGLE_TOLERANCE)
|
||||
)
|
||||
return;
|
||||
pushed = null;
|
||||
state = copyPose(seen);
|
||||
}
|
||||
|
||||
function finishMove() {
|
||||
moveEndTimer = null;
|
||||
const still = clock.now() - lastMoveAt;
|
||||
if (still < MOVE_END_WAIT_MS) {
|
||||
moveEndTimer = clock.setTimeout(finishMove, MOVE_END_WAIT_MS - still);
|
||||
return;
|
||||
}
|
||||
moving = false;
|
||||
events.moveEnd.raiseEvent();
|
||||
}
|
||||
|
||||
/** Raises camera events for this frame's pose; called after rendering. */
|
||||
function afterFrame() {
|
||||
const pose = copyPose(state);
|
||||
if (!posesNear(pose, lastFramePose, 1e-6, 1e-10)) {
|
||||
lastMoveAt = clock.now();
|
||||
if (!moving) {
|
||||
moving = true;
|
||||
events.moveStart.raiseEvent();
|
||||
}
|
||||
if (moveEndTimer) clock.clearTimeout(moveEndTimer);
|
||||
moveEndTimer = clock.setTimeout(finishMove, MOVE_END_WAIT_MS);
|
||||
}
|
||||
lastFramePose = pose;
|
||||
const turn =
|
||||
angleBetween(pose.direction, lastChangedPose.direction) / Math.PI;
|
||||
const altitude = Math.max(
|
||||
1,
|
||||
cartographic.fromCartesian(pose.position, WGS84).height,
|
||||
);
|
||||
const shift =
|
||||
cartesian3.distance(pose.position, lastChangedPose.position) / altitude;
|
||||
const amount = Math.max(turn, shift);
|
||||
if (amount > percentageChanged) {
|
||||
lastChangedPose = pose;
|
||||
events.changed.raiseEvent(amount);
|
||||
}
|
||||
}
|
||||
|
||||
const camera = {
|
||||
pose() {
|
||||
const current = view();
|
||||
const angles = headingPitchRoll(
|
||||
current.position,
|
||||
current.direction,
|
||||
current.up,
|
||||
);
|
||||
return {
|
||||
position: copy3(current.position),
|
||||
cartographic: cartographic.fromCartesian(current.position, WGS84),
|
||||
heading: angles.heading,
|
||||
pitch: angles.pitch,
|
||||
roll: angles.roll,
|
||||
direction: copy3(current.direction),
|
||||
up: copy3(current.up),
|
||||
right: cartesian3.normalize(
|
||||
cartesian3.cross(current.direction, current.up, cartesian3.create()),
|
||||
cartesian3.create(),
|
||||
),
|
||||
fovy: current.fovy,
|
||||
};
|
||||
},
|
||||
setView(options) {
|
||||
if (!options?.destination)
|
||||
throw new TypeError('setView needs a destination');
|
||||
place(viewFor(options.destination, options.orientation));
|
||||
},
|
||||
flyTo(options) {
|
||||
if (!options?.destination)
|
||||
throw new TypeError('flyTo needs a destination');
|
||||
startFlight(options, viewFor(options.destination, options.orientation));
|
||||
},
|
||||
flyToSphere(sphere, options = {}) {
|
||||
transform = [...matrix4.IDENTITY];
|
||||
const { width, height } = port.size();
|
||||
const range =
|
||||
options.range ||
|
||||
sphereRange(sphere.radius, cesiumFovy(width, height), width / height);
|
||||
const frame = geo.transforms.eastNorthUpToFixedFrame(
|
||||
sphere.center,
|
||||
WGS84,
|
||||
);
|
||||
startFlight(
|
||||
options,
|
||||
lookAtFrame(frame, {
|
||||
heading: options.heading ?? 0,
|
||||
pitch: options.pitch ?? -Math.PI / 4,
|
||||
range,
|
||||
}),
|
||||
);
|
||||
},
|
||||
flightActive: () => flight != null,
|
||||
lookAt(target, offset) {
|
||||
camera.lookAtTransform(
|
||||
geo.transforms.eastNorthUpToFixedFrame(target, WGS84),
|
||||
offset,
|
||||
);
|
||||
},
|
||||
lookAtTransform(frame, offset) {
|
||||
transform = [...frame];
|
||||
if (offset) place(lookAtFrame(frame, offset));
|
||||
},
|
||||
transform: () => [...transform],
|
||||
release() {
|
||||
transform = [...matrix4.IDENTITY];
|
||||
},
|
||||
cancelFlight() {
|
||||
cancelCurrentFlight();
|
||||
},
|
||||
zoomIn(amount = DEFAULT_ZOOM_AMOUNT) {
|
||||
place({
|
||||
...state,
|
||||
position: cartesian3.add(
|
||||
state.position,
|
||||
cartesian3.multiplyByScalar(
|
||||
state.direction,
|
||||
amount,
|
||||
cartesian3.create(),
|
||||
),
|
||||
cartesian3.create(),
|
||||
),
|
||||
});
|
||||
},
|
||||
zoomOut(amount = DEFAULT_ZOOM_AMOUNT) {
|
||||
camera.zoomIn(-amount);
|
||||
},
|
||||
viewRectangle: () => viewRectangle(view()),
|
||||
pickEllipsoid: (screen) => pickEllipsoid(view(), screen),
|
||||
pickRay: (screen) => pickRay(view(), screen),
|
||||
changed: events.changed,
|
||||
moveStart: events.moveStart,
|
||||
moveEnd: events.moveEnd,
|
||||
get percentageChanged() {
|
||||
return percentageChanged;
|
||||
},
|
||||
set percentageChanged(value) {
|
||||
percentageChanged = value;
|
||||
},
|
||||
};
|
||||
|
||||
return {
|
||||
camera,
|
||||
sync,
|
||||
afterFrame,
|
||||
/** The current camera for projections: pose, vertical fov and CSS size. */
|
||||
view,
|
||||
worldToWindow: (position, result) =>
|
||||
projectToWindow(view(), position, result),
|
||||
viewProjection: (result) => viewProjection(view(), result),
|
||||
horizonVisible: (position) => horizonVisible(state.position, position),
|
||||
destroy() {
|
||||
if (destroyed) return;
|
||||
cancelCurrentFlight();
|
||||
destroyed = true;
|
||||
if (moveEndTimer) clock.clearTimeout(moveEndTimer);
|
||||
moveEndTimer = null;
|
||||
},
|
||||
};
|
||||
}
|
||||
Reference in new issue
Block a user