fix(globe): keep the Navara camera above the ground

Navara 0.2.1's camera controller has no terrain or tile collision; its
only zoom limit, minimumZoomDistance, is a distance from the Earth's
centre, so a wheel zoom near the ground went through it (to -5.9 km).

groundFloor.js runs on the engine's preRender after the camera model
reads Navara's camera. While the camera is free (no flight, no lookAt
target) and below 20 km it samples the ground under it (tiles, else
terrain, else the ellipsoid; at most every 250 ms or 20 m), feeds
Navara's clamp (minimumZoomDistance = geocentric radius of the ground
point + 30 m, sent on changes over 10 m, reset to Navara's default
during flights and above 20 km) so the wheel stops smoothly, and lifts a
camera still below ground + 30 m straight up without camera.commanded.
It only lifts, so it cannot oscillate with the shell's ground guard,
whose lift is a flight the floor stands aside for.
This commit is contained in:
German Khokhlov committed 2026-10-15 21:27:57 +04:00
1 parent 4ded3fbf15
commit 64d3297301
6 files changed
+347

No files matched your search

+121
View File
@@ -0,0 +1,121 @@
// Keeps the Navara camera above the ground. Navara 0.2.1's camera controller
// has no terrain or 3D-tile collision: its only zoom limit is
// minimumZoomDistance, a distance from the Earth's centre (default: the
// semi-minor axis), so a wheel zoom near the ground goes through it. Cesium's
// controller stops at the surface.
//
// Each frame (engine preRender, after the camera model reads Navara's
// camera), while the camera is free (no flight running, no lookAt target)
// and below MAX_HEIGHT:
// - the ground under the camera is sampled (surface.sampleHeight: tiles,
// else terrain; else the ellipsoid), at most every RESAMPLE_MS or after a
// RESAMPLE_METRES move;
// - Navara's own clamp follows it (minimumZoomDistance = geocentric radius of
// the ground point + MIN_ABOVE), so the wheel stops smoothly; it is sent
// only when it moves more than CLAMP_STEP, and reset to Navara's default
// while a flight runs or the camera is high, so a stale clamp from another
// latitude can never hold the camera up;
// - a camera still below ground + MIN_ABOVE is lifted straight up, keeping
// its orientation.
// The floor only ever lifts, so it cannot oscillate with the shell's ground
// guard (src/cameraGroundGuard.js), which also only lifts, by camera.flyTo;
// during that flight the floor stands aside.
import * as geo from '../../geo/index.js';
const { cartesian3, cartographic } = geo;
const WGS84 = geo.ellipsoid.WGS84;
export const GROUND_FLOOR = Object.freeze({
/** Metres the camera stays above the ground. */
MIN_ABOVE: 30,
/** Ellipsoid height (m) above which there is no floor. */
MAX_HEIGHT: 20000,
/** Change (m) of the clamp radius worth sending to Navara. */
CLAMP_STEP: 10,
/** Horizontal move (m) after which the ground is sampled again. */
RESAMPLE_METRES: 20,
/** Age (ms) after which the ground is sampled again. */
RESAMPLE_MS: 250,
});
/**
* @param {{
* surface: { sampleHeight: Function, terrainHeight?: Function },
* position: () => import('../../geo/index.js').Cartesian3,
* isFree: () => boolean,
* lift: (position: object) => void,
* setMinimumZoomDistance: (distance: number | undefined) => void,
* now?: () => number,
* }} options
* @returns {{ update: () => boolean, ground: () => number | undefined }}
* `update` returns whether it lifted the camera.
*/
export function createGroundFloor({
surface,
position,
isFree,
lift,
setMinimumZoomDistance,
now = () => performance.now(),
}) {
let sample = null; // { point, at, height }
let clamp; // the radius last sent, or undefined for Navara's default
const sendClamp = (radius) => {
if (radius === undefined) {
if (clamp === undefined) return;
} else if (
clamp !== undefined &&
Math.abs(radius - clamp) <= GROUND_FLOOR.CLAMP_STEP
)
return;
clamp = radius;
setMinimumZoomDistance(radius);
};
function groundAt(place, at) {
const point = cartesian3.fromRadians(
place.longitude,
place.latitude,
0,
WGS84,
);
if (
sample &&
at - sample.at < GROUND_FLOOR.RESAMPLE_MS &&
cartesian3.distance(point, sample.point) < GROUND_FLOOR.RESAMPLE_METRES
)
return sample.height;
const height =
surface.sampleHeight(place) ?? surface.terrainHeight?.(place) ?? 0;
sample = { point, at, height };
const ground = cartesian3.fromRadians(
place.longitude,
place.latitude,
height,
WGS84,
);
sendClamp(cartesian3.magnitude(ground) + GROUND_FLOOR.MIN_ABOVE);
return height;
}
function update() {
if (!isFree()) {
sendClamp(undefined);
return false;
}
const place = cartographic.fromCartesian(position(), WGS84);
if (!place || place.height > GROUND_FLOOR.MAX_HEIGHT) {
sendClamp(undefined);
sample = null;
return false;
}
const floor = groundAt(place, now()) + GROUND_FLOOR.MIN_ABOVE;
if (!(place.height < floor)) return false;
lift(cartesian3.fromRadians(place.longitude, place.latitude, floor, WGS84));
return true;
}
return { update, ground: () => sample?.height };
}