Files
gods-eye-view/src/render/contract/query.d.ts
T
Sameh Khamis b7c26351f7 Settle the draw decisions in the renderer contract
- lodGroup links items across sets as one thing at different detail;
  picks name the member shown and report the group. displayRange is
  half-open.
- An orbits capability: the renderer propagates two-line elements with
  SGP4 on the set's motion clock. The stub propagates with satellite.js.
- Height queries see draw sets only with includeInHeightQueries (was
  excludeFromHeightQueries); HeightSample.source gains 'set'.
- courseGlide is a capability; courseBlendMs eases the course on every
  renderer.
- Arc segments climb at climbMps; a negative minDtS stays for the
  aircraft warm-up.
- The star catalogue is optional, a hidden column row keeps its motion,
  and draw.clampState() reports the drape fallback.

Checks cover the climb and warm-up, lodGroup ranges, orbits against SGP4
(with and without motionSegments), hidden rows resuming, and sets not
answering height queries by default.
2026-11-05 12:50:58 -08:00

114 lines
4.0 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* Questions about what is on screen.
*
* Picks, projection and rays are synchronous and answer against the last
* presented frame. Heights have a synchronous cache-only form that may
* return null, and asynchronous forms that load what they need.
*/
import type { Ecef, LonLat, Meta, Ray, ScreenXY } from './common';
/** One thing under the pointer. */
export interface Hit {
/** The draw set's id. */
set: string;
/** The item's id. */
id: string;
/** The item's `meta`, as it was given; absent when the item had none. */
meta?: Meta;
/** The item's `lodGroup`, when it has one: the thing it is a detail level of. */
lodGroup?: string;
/** The map itself (tiles or globe), rather than a drawn item. */
surface: boolean;
/** Where the hit is, when the renderer knows it. */
position?: Ecef;
}
export interface PickWindow {
/** Pick window, CSS pixels; default 3 × 3. */
width?: number;
height?: number;
/**
* What the pick is for. A hover pick may skip costly exact tests (a
* point-in-polygon on a large fill) that a select pick must make.
*/
purpose?: 'hover' | 'select';
}
export interface HeightOptions {
/**
* `surface`: tiles where they are drawn, otherwise terrain. Sets drawn
* with `includeInHeightQueries` count under `surface` and `tiles`, never
* under `terrain`.
*/
against?: 'surface' | 'terrain' | 'tiles';
/** Set ids to see through, of those drawn with `includeInHeightQueries`. */
exclude?: string[];
}
export interface HeightSample {
/** Metres above the ellipsoid. */
height: number;
/** 1 for the most detailed data, lower for a coarser level. */
confidence: number;
/** `set`: a draw set drawn with `includeInHeightQueries`. */
source: 'tiles' | 'terrain' | 'ellipsoid' | 'set';
/** The detail answered from: what is drawn now, or (`finestHeights`) the finest available. */
lod: 'visible' | 'finest';
/** Edge length of the tile answered from, metres, when known. */
tileSizeM?: number;
}
export interface QueryPort {
pick(x: number, y: number, window?: PickWindow): Hit | null;
drillPick(
x: number,
y: number,
options?: PickWindow & { limit?: number },
): Hit[];
/** `pickPosition`: depth under the pointer, against tiles and terrain. */
pickPosition(x: number, y: number): Ecef | null;
pickEllipsoid(x: number, y: number): Ecef | null;
/** Where a ray meets the globe surface (not tiles). */
pickGlobe(ray: Ray): Ecef | null;
pickRay(x: number, y: number): Ray;
/** Screen position, or null behind the eye (off-screen points still answer). */
project(position: Ecef): ScreenXY | null;
/**
* Packed `x, y, z` in → packed `x, y` out, CSS pixels; NaN for points
* behind the eye. For the label overlay's per-frame pass.
*/
projectMany(source: Float64Array, out: Float32Array): void;
/** Hidden by the ellipsoid's horizon from the current eye. */
isOccluded(position: Ecef): boolean;
/** `sampleHeight`: cached height now, or null when not loaded. */
sampleHeightNow(point: LonLat, options?: HeightOptions): number | null;
/**
* `sampleHeight`: cached heights for many points at once: packed `lon, lat`
* degrees in, one height per point out (NaN when not loaded). The app makes
* its per-frame height reads through this, once a frame.
*/
sampleHeightNowMany(
points: Float64Array,
out: Float64Array,
options?: HeightOptions,
): void;
/**
* `sampleHeight`: heights, loading as needed; null per miss.
* `mostDetailed` (`finestHeights`) waits for the finest data.
*/
sampleHeight(
points: LonLat[],
options?: HeightOptions & { mostDetailed?: boolean },
): Promise<Array<HeightSample | null>>;
/** `sampleHeight`: positions moved onto the surface; null per miss. */
clampToSurface(
positions: Ecef[],
options?: HeightOptions,
): Promise<Array<Ecef | null>>;
/** `rayCast`: first surface hit along a ray. */
rayCast(
ray: Ray,
options?: HeightOptions & { maxDistance?: number },
): Promise<Ecef | null>;
}