mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +00:00
The camera port gains an optional followFrame() (capability followFrame): the frame the eye is placed in now, as a column-major 4x4 matrix to ECEF. Once a follow has framed the camera it is the follow's own frame (east-north-up, or the orbit frame an autodetect follow chose), under lookAt the target's east-north-up frame, otherwise the identity. setView places a world pose and keeps that frame. The Cesium port reads it from camera.transform, only when the capability is on; the stub from its own eye frame. A conformance check covers the world, lookAt and enu-follow frames, the offset in it, and setView keeping it. src/ui/shareFollow.js now reads the pose, the frame and the follow offset through the camera and frame ports: a shared offset is re-expressed in the follow's own frame as before, satellites included, and the eye is placed with setView at exact heading, pitch and roll, so a near-vertical view keeps its roll. placeFollowEye returns false on a camera that cannot say its frame. offsetFromHeadingPitchRange moves to src/geo/frames.js, shared with the stub.
273 lines
10 KiB
TypeScript
273 lines
10 KiB
TypeScript
/**
|
||
* The camera. It belongs to the renderer: the application asks for poses,
|
||
* flights and follows, and the renderer reproduces the behaviour below
|
||
* exactly.
|
||
*
|
||
* Behaviour the renderer keeps (the application depends on each one):
|
||
* - Camera input is suspended during a flight, by a hold: a flight ending
|
||
* gives back only its own hold, never another owner's.
|
||
* - `lookAt` orbits the target (the user can still rotate and zoom about it);
|
||
* `release` returns to the world frame.
|
||
* - `changed` fires when the view has moved by more than the listener's own
|
||
* `threshold` (default 0.5) since it last fired, measured per listener:
|
||
* heading and roll each by their change over π since they last fired; the
|
||
* view by the larger of the direction's turn over half the vertical field
|
||
* of view and the eye's travel over its height, since the view last
|
||
* fired. A frame can fire it twice, once for each measure.
|
||
* - `moveEnd` fires 500 ms after the last change, and never while following.
|
||
* - A flight's `onCancel` and `onComplete` run synchronously, inside the call
|
||
* or frame that ends it.
|
||
* - Axes follow the usual convention: heading clockwise from north, pitch
|
||
* negative looking down, roll about the view direction; local frames are
|
||
* east-north-up.
|
||
*/
|
||
import type {
|
||
Ecef,
|
||
GeoRect,
|
||
HeadingPitchRange,
|
||
HeadingPitchRoll,
|
||
Off,
|
||
Position,
|
||
Release,
|
||
Sphere,
|
||
Vec3,
|
||
} from './common';
|
||
|
||
export interface CameraPose {
|
||
lon: number;
|
||
lat: number;
|
||
/** Metres above the ellipsoid. */
|
||
height: number;
|
||
heading: number;
|
||
pitch: number;
|
||
roll: number;
|
||
position: Ecef;
|
||
direction: Vec3;
|
||
up: Vec3;
|
||
right: Vec3;
|
||
/** Vertical field of view, radians. */
|
||
fovy: number;
|
||
aspectRatio: number;
|
||
near: number;
|
||
far: number;
|
||
/** False while `lookAt` has the camera in a target's frame. */
|
||
frameIsIdentity: boolean;
|
||
}
|
||
|
||
export type Orientation =
|
||
Partial<HeadingPitchRoll> | { direction: Vec3; up: Vec3 };
|
||
|
||
/**
|
||
* A position, or a rectangle. For a rectangle the eye stands on the surface
|
||
* normal at the geodesic midpoint of its central meridian (latitude 0 when it
|
||
* spans nearly pole to pole), at the least distance that keeps on screen its
|
||
* corners, its edge centres and, when it crosses the equator, its equator
|
||
* points. The orientation is then resolved as for any position.
|
||
*/
|
||
export type Destination = Position | { rect: GeoRect };
|
||
|
||
/**
|
||
* Omitted orientation angles are heading 0, pitch −π/2 (straight down) and
|
||
* roll 0, not the current ones; an omitted destination keeps the position.
|
||
*/
|
||
export interface ViewSpec {
|
||
destination?: Destination;
|
||
orientation?: Orientation;
|
||
}
|
||
|
||
export type Easing =
|
||
| 'linear'
|
||
| 'quadraticInOut'
|
||
| 'cubicInOut'
|
||
| 'cubicOut'
|
||
| 'quinticInOut'
|
||
| 'sineInOut';
|
||
|
||
/**
|
||
* A flight's omitted orientation is the same as `setView`'s. Its omitted
|
||
* duration is `min(3, ceil(distance / 1000 km) + 2)` seconds, the distance
|
||
* measured from the eye's position in its current frame (the `lookAt` frame
|
||
* when one is active). A flight with a duration of 0 or less, or one whose
|
||
* eye (its position in its current frame, as above) already stands at the
|
||
* destination with the destination's angles (to 1e-10, relative),
|
||
* completes inside the call: it places the eye, runs `onComplete`, raises
|
||
* `flightEnd` and resolves `done`, and no frame is needed. Starting a
|
||
* flight cancels the one in progress.
|
||
*
|
||
* The path, at eased time `s` (0..1): longitude and latitude linear in `s`
|
||
* the short way round; heading, pitch and roll linear in `s` the short way
|
||
* round; height on an arc to `maxHeight` when both ends are below it,
|
||
* otherwise linear. The reference traces (`conformance/goldens/camera.json`)
|
||
* pin the arc and the omitted `maxHeight`.
|
||
*/
|
||
export interface FlightOptions {
|
||
orientation?: Orientation;
|
||
durationS?: number;
|
||
/**
|
||
* Omitted: `cubicOut` when descending from above 11.5 km, otherwise
|
||
* `quinticInOut`.
|
||
*/
|
||
easing?: Easing;
|
||
/** Top of the height arc, metres. Omitted: a fifth of what fits both ends on screen. */
|
||
maxHeight?: number;
|
||
/** When the arc tops this height, pitch turns straight down mid-flight. */
|
||
pitchAdjustHeight?: number;
|
||
/** End in the world frame even when a target frame is active. */
|
||
endFrame?: 'world';
|
||
onComplete?: () => void;
|
||
onCancel?: () => void;
|
||
}
|
||
|
||
export interface Flight {
|
||
done: Promise<'complete' | 'cancelled'>;
|
||
cancel(): void;
|
||
}
|
||
|
||
/** Something the camera follows; the application owns it and the renderer reads it each frame. */
|
||
export interface FollowTarget {
|
||
/** Stable key, e.g. `'flights:a1b2c3'`. */
|
||
key: string;
|
||
/** Where the target is at scene time `t` (epoch ms), or null when unknown. */
|
||
position(t: number): Ecef | null;
|
||
/** Where it is drawn, when that differs from `position` (a lifted icon). */
|
||
visualPosition?(t: number): Ecef | null;
|
||
/**
|
||
* The drawn item this target is, when it is one. Where the renderer moves
|
||
* items itself (`motionSegments`) follows where it draws the item, so the
|
||
* eye and the icon never part; `position` stays the answer elsewhere.
|
||
*/
|
||
item?: { set: string; id: string };
|
||
/**
|
||
* `enu`: offset in the target's east-north-up frame;
|
||
* `autodetect`: an orbit frame from its motion, north-up when still
|
||
* (`followAutodetect`).
|
||
*/
|
||
frame: 'enu' | 'autodetect';
|
||
/** Offset of the eye from the target, metres in `frame`. */
|
||
viewFrom: Vec3 | ((t: number) => Vec3);
|
||
minRange?: number;
|
||
boundingRadius?: number;
|
||
}
|
||
|
||
/**
|
||
* A camera command, as an ownership hook sees it before it runs. An owner
|
||
* that issues commands itself (a ground guard) recognises its own by
|
||
* issuing them inside its own call; any other command is someone else's.
|
||
*/
|
||
export interface CameraCommand {
|
||
kind:
|
||
| 'setView'
|
||
| 'flyTo'
|
||
| 'flyToBounds'
|
||
| 'lookAt'
|
||
| 'release'
|
||
| 'follow'
|
||
| 'cancelFlight';
|
||
}
|
||
|
||
export interface CameraControls {
|
||
/** False while any hold is out. */
|
||
readonly enabled: boolean;
|
||
/** Suspend user camera input until released. Holds are counted. */
|
||
suspend(reason: string): Release;
|
||
enableTilt: boolean;
|
||
enableRotate: boolean;
|
||
enableZoom: boolean;
|
||
minDistance: number;
|
||
maxDistance: number;
|
||
/**
|
||
* How long a motion the user lets go of coasts: seconds for its speed to
|
||
* fall to 1/e. `drag` is moving the globe under the pointer and tilting
|
||
* (one motion in the default renderer), `zoom` is zooming; 0 stops at
|
||
* once. Set the whole object to change it.
|
||
*/
|
||
coast: { drag: number; zoom: number };
|
||
/** What the eye cannot pass below. */
|
||
collision: 'none' | 'terrain' | 'tiles' | 'both';
|
||
zoomFactor: number;
|
||
/** Pitch the user may tilt between, radians (−π/2 straight down). */
|
||
pitchRange: [min: number, max: number];
|
||
/** Input bindings that zoom. */
|
||
zoomInputs: Array<'wheel' | 'pinch' | 'rightDrag' | 'ctrlWheel'>;
|
||
}
|
||
|
||
export type CameraEvent =
|
||
'changed' | 'moveStart' | 'moveEnd' | 'followChanged' | 'flightEnd';
|
||
|
||
export interface CameraPort {
|
||
pose(): CameraPose;
|
||
setView(view: ViewSpec): void;
|
||
setFov(fov: { vertical: number }): void;
|
||
/**
|
||
* The geodetic rectangle in view: the bounds of the canvas corners on the
|
||
* ellipsoid, a corner that misses it taken where the horizon is, and the
|
||
* full longitude span to the pole when the view goes over one. The whole
|
||
* globe when fewer than two corners land; null only when the globe is
|
||
* wholly outside the view.
|
||
*/
|
||
viewRectangle(): GeoRect | null;
|
||
flyTo(destination: Destination, options?: FlightOptions): Flight;
|
||
/**
|
||
* Fly to look at a sphere from `offset` in its east-north-up frame
|
||
* (default heading 0, pitch −π/4; a range of 0 fits the sphere in view).
|
||
*/
|
||
flyToBounds(
|
||
sphere: Sphere,
|
||
options?: { offset?: HeadingPitchRange } & Pick<
|
||
FlightOptions,
|
||
'durationS' | 'easing' | 'onComplete' | 'onCancel'
|
||
>,
|
||
): Flight;
|
||
cancelFlight(): void;
|
||
readonly flying: boolean;
|
||
/** Orbit `target` at `offset`; user input orbits it too. */
|
||
lookAt(target: Ecef, offset: HeadingPitchRange): void;
|
||
/** Leave `lookAt` for the world frame. */
|
||
release(): void;
|
||
move(
|
||
direction: 'forward' | 'back' | 'left' | 'right' | 'up' | 'down',
|
||
metres: number,
|
||
): void;
|
||
look(direction: 'left' | 'right' | 'up' | 'down', radians: number): void;
|
||
rotateAround(axis: Vec3, radians: number): void;
|
||
zoom(metres: number): void;
|
||
/**
|
||
* Follow `target`, or stop following with null; `followChanged` fires
|
||
* whenever `followed` changes, and only then.
|
||
*/
|
||
follow(target: FollowTarget | null): void;
|
||
readonly followed: FollowTarget | null;
|
||
/** Whether the follow has placed its first frame. */
|
||
readonly followFramed: boolean;
|
||
/** The eye's offset from the followed target, in its frame. */
|
||
readonly followOffset: {
|
||
get(): Vec3 | null;
|
||
set(offset: Vec3): void;
|
||
};
|
||
/**
|
||
* `followFrame`: the frame the eye is placed in now, as a column-major
|
||
* 4×4 matrix from that frame to ECEF (a rigid frame: unit axes, then the
|
||
* origin). Once a follow has framed the camera (`followFramed`) it is the
|
||
* follow's frame, whose origin is the target and in which `followOffset`
|
||
* is the eye: east-north-up for an `enu` follow, the renderer's own orbit
|
||
* frame for `autodetect`; until then it is whatever frame the eye was in
|
||
* before. Under `lookAt` it is the target's east-north-up frame; in the
|
||
* world frame, the identity. A follow's frame moves with its target, so a
|
||
* reading is valid only for the tick it is read in. `setView` places a
|
||
* world pose and keeps this frame, so code can re-express an offset in
|
||
* the follow's own frame, whichever frame that is, and place the eye there.
|
||
*/
|
||
followFrame?(): Float64Array;
|
||
readonly controls: CameraControls;
|
||
on(event: CameraEvent, cb: () => void, options?: { threshold?: number }): Off;
|
||
/** Runs before each camera command, so an owner can yield to another. */
|
||
onCommand(cb: (command: CameraCommand) => void): Off;
|
||
/**
|
||
* Column-major, right-handed: `view` takes ECEF to eye space (absolute,
|
||
* not eye-relative); `projection` takes eye space to clip space with depth
|
||
* in [-1, 1]. A renderer with an infinite far plane returns the
|
||
* infinite-far form, and `pose().far` is `Infinity`.
|
||
*/
|
||
matrices(): { view: Float64Array; projection: Float64Array };
|
||
}
|