feat(selection): selecting a contact keeps its size and the camera's view: aircraft, vessels, trains and transit vehicles keep their form and size when selected (colour only); a click follows from the camera's own distance and angle, the contact gliding to the centre over one second (FollowTarget transitionS, shared rule render/camera/followTransition, conformance camera.follow.transition)

This commit is contained in:
Sameh Khamis committed 2026-11-13 15:02:28 -08:00
1 parent e3865f462f
commit 7a61bf04a0
52 files changed
+1648 -891

No files matched your search

+103
View File
@@ -0,0 +1,103 @@
/**
* @module render/camera/followTransition
* @description A follow's `transitionS` (`camera.d.ts`), shared by every
* renderer and by camera controllers (the package's
* `./render/camera/followTransition` export): the eye's way from where it
* stood when the follow began to the follow's first framing.
*
* Everything is in the target's frame, which moves with the target, so the
* eye rides along with it from the first frame. Over the transition the eye's
* offset turns from the offset it had towards `viewFrom` (its length going
* from the one to the other), and its view turns from the way it looked to
* the framing's, which looks at the target with no roll. An offset that
* equals the eye's own direction and range from the target (the camera's
* current view, kept) leaves the view direction and the range unchanged
* throughout: only the eye's place moves, and the target slides to the
* centre.
*/
import {
cross,
dot,
magnitude,
normalize,
scale,
vec,
} from '../../geo/index.js';
const EPSILON10 = 1e-10;
/**
* The eased fraction of a transition `elapsedMs` into `durationMs`:
* smoothstep, 0 before it starts and 1 from its end on.
* @param {number} elapsedMs
* @param {number} durationMs
* @returns {number}
*/
export function followTransitionFraction(elapsedMs, durationMs) {
if (!(durationMs > 0)) return 1;
const t = Math.min(1, Math.max(0, elapsedMs / durationMs));
return t * t * (3 - 2 * t);
}
/** `(1 - s) a + s b`, normalized; `fallback` when that has no length. */
function blendUnit(a, b, s, fallback) {
const v = vec(
(1 - s) * a.x + s * b.x,
(1 - s) * a.y + s * b.y,
(1 - s) * a.z + s * b.z,
);
return dot(v, v) > EPSILON10 ? normalize(v) : fallback;
}
/**
* The eye a follow's first framing places at `offset` in the target's frame:
* there, looking at the target, its right level with the frame's x-y plane
* (east-north for an `enu` follow).
* @param {{x: number, y: number, z: number}} offset
*/
export function followFramingEye(offset) {
const direction = normalize(scale(offset, -1));
let right = cross(direction, vec(0, 0, 1));
right = dot(right, right) < EPSILON10 ? vec(1, 0, 0) : normalize(right);
return {
position: { x: offset.x, y: offset.y, z: offset.z },
direction,
up: normalize(cross(right, direction)),
right,
};
}
/**
* The eye at eased fraction `s` of a follow's transition, in the target's
* frame.
* @param {{position: object, direction: object, up: object}} start The eye
* where the transition began, in the target's frame.
* @param {{x: number, y: number, z: number}} offset The framing's offset
* (`viewFrom`, put out to the least range).
* @param {number} s Eased fraction, 0 to 1 (`followTransitionFraction`).
* @returns {{position: object, direction: object, up: object, right: object}}
*/
export function followTransitionEye(start, offset, s) {
const end = followFramingEye(offset);
if (s >= 1) return end;
const startRange = magnitude(start.position);
const endRange = magnitude(offset);
const along = blendUnit(
startRange > 0 ? scale(start.position, 1 / startRange) : end.direction,
scale(end.direction, -1),
s,
scale(end.direction, -1),
);
const position = scale(along, (1 - s) * startRange + s * endRange);
const direction = blendUnit(start.direction, end.direction, s, end.direction);
// The up blended, then made square to the view.
const blendedUp = blendUnit(start.up, end.up, s, end.up);
let up = vec(
blendedUp.x - direction.x * dot(direction, blendedUp),
blendedUp.y - direction.y * dot(direction, blendedUp),
blendedUp.z - direction.z * dot(direction, blendedUp),
);
up = dot(up, up) > EPSILON10 ? normalize(up) : end.up;
const right = normalize(cross(direction, up));
return { position, direction, up, right };
}
+1
View File
@@ -151,6 +151,7 @@ export function createCesiumCamera({
camera,
onChanged: () => cameraEvents.emit('followChanged'),
itemPosition,
now,
})
: null;
+45 -6
View File
@@ -18,6 +18,10 @@
import * as Cesium from 'cesium';
import { toCartesian } from './common.js';
import { trackedEntityViewEntity } from './internals.js';
import {
followTransitionEye,
followTransitionFraction,
} from '../camera/followTransition.js';
/** Frames to wait for a target's first position before giving up framing. */
const MAX_FRAME_ATTEMPTS = 120;
@@ -155,6 +159,9 @@ export function clampFollowEye(camera, previousPosition, minimumRangeM) {
return false;
}
/** A Cartesian3 as a plain vector. */
const plain = (c) => ({ x: c.x, y: c.y, z: c.z });
const gregorianScratch = new Cesium.GregorianDate();
/**
* Scene time in epoch ms, sub-millisecond included: `JulianDate.toDate`
@@ -196,6 +203,8 @@ function startOffset(target, viewFrom, result) {
* `onChanged` runs on every change of what it tracks; `itemPosition`,
* where the draw port draws an item at a scene time (null when it does
* not), which a target naming a drawn `item` is followed at.
* @param {() => number} [options.now] Wall clock, ms, for a target's
* `transitionS`.
*/
export function createCesiumFollow({
widget,
@@ -203,6 +212,7 @@ export function createCesiumFollow({
camera,
onChanged,
itemPosition,
now = () => performance.now(),
}) {
/** Where a target is at a scene time: its drawn item, else `position`. */
const positionOf = (target, time) =>
@@ -323,16 +333,45 @@ export function createCesiumFollow({
giveUp(entry);
return;
}
camera.lookAtTransform(
Cesium.Transforms.eastNorthUpToFixedFrame(
toCartesian(at),
Cesium.Ellipsoid.WGS84,
),
offset,
const enu = Cesium.Transforms.eastNorthUpToFixedFrame(
toCartesian(at),
Cesium.Ellipsoid.WGS84,
);
if (target.transitionS > 0 && transitionStep(entry, enu, offset)) return;
camera.lookAtTransform(enu, offset);
entry.framed = true;
}
/**
* One frame of a target's `transitionS`: the eye on its way from where it
* stood to the framing at `offset`, in the target's frame `enu`.
* @returns {boolean} Whether the transition is still under way.
*/
function transitionStep(entry, enu, offset) {
// Into the target's frame, keeping the world pose.
camera.lookAtTransform(enu);
entry.transition ??= {
startMs: now(),
eye: {
position: plain(camera.position),
direction: plain(camera.direction),
up: plain(camera.up),
},
};
const s = followTransitionFraction(
now() - entry.transition.startMs,
entry.target.transitionS * 1000,
);
if (s >= 1) return false;
const eye = followTransitionEye(entry.transition.eye, plain(offset), s);
Cesium.Cartesian3.clone(toCartesian(eye.position), camera.position);
Cesium.Cartesian3.clone(toCartesian(eye.direction), camera.direction);
Cesium.Cartesian3.clone(toCartesian(eye.up), camera.up);
Cesium.Cartesian3.clone(toCartesian(eye.right), camera.right);
scene.requestRender();
return true;
}
/**
* With no position to frame for MAX_FRAME_ATTEMPTS frames, the follow
* leaves the camera to Cesium: no framing, no zoom hold, no clamp.
+74
View File
@@ -11,6 +11,14 @@ import {
import { contractDriver, runCameraScript } from '../cameraRunner.js';
import { deepEqual, equal, near, nearAngle, nearVec, ok } from '../expect.js';
import { eyeMoved } from '../../../geo/eyeMoves.js';
import {
cross,
eastNorthUp,
framePoint,
frameVector,
normalize,
scale,
} from '../../../geo/index.js';
const lonLatToEcef = (h) => h.toEcef;
@@ -472,6 +480,72 @@ export function cameraChecks() {
r.destroy();
},
},
{
id: 'camera.follow.transition',
port: 'camera',
title:
'a follow with transitionS moves the eye from where it stood to viewFrom; a viewFrom along its own view keeps view and range',
async run(h) {
const r = await fresh(h);
const target = h.toEcef({ lon: -97.74, lat: 30.27, height: 1000 });
const enu = eastNorthUp(target);
// The eye 1.8 km off the target, looking a little beside it.
const local = { x: 400, y: -1500, z: 900 };
const range = Math.hypot(local.x, local.y, local.z);
const look = normalize({
x: -local.x + 150,
y: -local.y,
z: -local.z - 120,
});
const right = normalize(cross(look, { x: 0, y: 0, z: 1 }));
const lookUp = normalize(cross(right, look));
const eye = framePoint(enu, local);
const direction = normalize(frameVector(enu, look));
r.camera.setView({
destination: eye,
orientation: { direction, up: normalize(frameVector(enu, lookUp)) },
});
await h.frame(r);
const viewFrom = scale(look, -range);
r.camera.follow({
key: 'test:transition',
position: () => target,
frame: 'enu',
viewFrom,
transitionS: 1,
});
const startedAt = h.now(r);
await h.frame(r);
ok(!r.camera.followFramed, 'not framed on the first frame');
nearVec(
r.camera.pose().position,
eye,
1e-3,
'the eye starts where it stood',
);
let midway = false;
for (let i = 0; i < 600 && !r.camera.followFramed; i++) {
const pose = r.camera.pose();
near(dist(pose.position, target), range, 1e-6 * range, `range ${i}`);
nearVec(pose.direction, direction, 1e-6, `view ${i}`);
if (dist(pose.position, eye) > 1) midway = true;
await h.frame(r);
}
ok(midway, 'the eye moved before it arrived');
ok(r.camera.followFramed, 'framed on arrival');
ok(h.now(r) - startedAt >= 1000 - 1e-6, 'arrived after transitionS');
const pose = r.camera.pose();
nearVec(
pose.position,
framePoint(enu, viewFrom),
1e-3,
'the eye at viewFrom',
);
nearVec(pose.direction, direction, 1e-6, 'the same view');
r.camera.follow(null);
r.destroy();
},
},
{
id: 'camera.follow.autodetect',
port: 'camera',
+11
View File
@@ -155,6 +155,17 @@ export interface FollowTarget {
viewFrom: Vec3 | ((t: number) => Vec3);
minRange?: number;
boundingRadius?: number;
/**
* Seconds of wall time the first framing takes; without it the eye is
* placed at `viewFrom` on the first frame. With it the eye stays in the
* target's frame from the first frame (riding along with the target) and
* moves from where it stood to the framing, both its offset and its view
* turning, eased (`render/camera/followTransition.js`, the one rule every
* renderer follows); `followFramed` turns true on arrival. A `viewFrom`
* along the eye's own view at its own range keeps the view and the range
* throughout, so the target slides to the centre.
*/
transitionS?: number;
}
/**
+29
View File
@@ -44,6 +44,10 @@ import {
zeroToTwoPi,
} from './math.js';
import { createCameraEvents } from '../camera/events.js';
import {
followTransitionEye,
followTransitionFraction,
} from '../camera/followTransition.js';
import { geodesicAt } from '../../geo/geodesic.js';
const DEFAULT_FOV = Math.PI / 3;
@@ -116,6 +120,8 @@ export function createStubCamera({
let flight = null;
let followed = null;
let followFramed = false;
/** A follow's transition under way: where the eye began, and when. */
let transition = null;
let coast = Object.freeze({ drag: 0.4, zoom: 0.2 });
const controls = {
@@ -666,6 +672,7 @@ export function createStubCamera({
const changed = followed !== target;
followed = target;
followFramed = false;
transition = null;
if (!target) setFrame(IDENTITY);
if (changed) emit('followChanged');
requestRender('follow');
@@ -689,6 +696,28 @@ export function createStubCamera({
);
if (range < minRange && range > 0)
offset = scale(offset, minRange / range);
if (followed.transitionS > 0 && range > 0) {
// The eye moves from where it is to the framing (`transitionS`).
setFrame(targetFrame);
transition ??= {
startMs: now(),
eye: { position, direction, up },
};
const s = followTransitionFraction(
now() - transition.startMs,
followed.transitionS * 1000,
);
if (s < 1) {
const eye = followTransitionEye(transition.eye, offset, s);
position = eye.position;
direction = eye.direction;
up = eye.up;
right = eye.right;
requestRender('follow');
return;
}
transition = null;
}
lookAtFrame(targetFrame, offset);
followFramed = true;
return;