mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 08:12:24 +00:00
The satellites layer publishes its focus rectangle with publishFocusTargetAt, projecting its cached position through the query port and measuring from the camera port's pose, as flights and military already do. The scene-taking publishFocusTargetFromCachedPosition and the unused advanceProjectedSpriteFocus go, and focusDeemphasis.js leaves the Cesium allow-list. The rectangle is the same; the target's frameNumber, which nothing reads, is now -1 as the other layers publish it.
555 lines
18 KiB
JavaScript
555 lines
18 KiB
JavaScript
import { findCamera, findQuery } from '../render/rendererOf.js';
|
|
|
|
/**
|
|
* Focus-aware sprite treatment shared by the live contact layers.
|
|
*
|
|
* The selected target is protected by changing ambient sprite alpha, never by
|
|
* collection ordering: Cesium's translucent distance sort is not stable for
|
|
* collections with similar bounding volumes. This is a narrow amendment to
|
|
* the normal always-visible contact rule. Ambient contacts remain present and
|
|
* never fall below `dimFloor`; only sprites competing with the tracked target
|
|
* are smoothly de-emphasized.
|
|
*
|
|
* The production consumers sample this service every 80 ms. The default
|
|
* 300 ms attack and 600 ms release deliberately span several consumer
|
|
* quanta, so a contact receives at least four distinct rendered emphasis
|
|
* values during attack instead of crossing the range in one or two ticks.
|
|
*/
|
|
|
|
export const DEFAULT_FOCUS_DEEMPHASIS_PARAMS = Object.freeze({
|
|
paddingPx: 18,
|
|
dimFloor: 0.25,
|
|
nearerBehavior: 'allow',
|
|
hysteresisPx: 6,
|
|
distanceHysteresisRatio: 0.08,
|
|
attackMs: 300,
|
|
releaseMs: 600,
|
|
writeEpsilon: 0.005,
|
|
});
|
|
|
|
let _params = { ...DEFAULT_FOCUS_DEEMPHASIS_PARAMS };
|
|
let _focusTarget = null;
|
|
const _spriteStates = new WeakMap();
|
|
const _advanceResult = {
|
|
factor: 1,
|
|
changed: false,
|
|
transitioning: false,
|
|
active: false,
|
|
desired: 1,
|
|
};
|
|
|
|
function clamp(value, min, max) {
|
|
return Math.min(max, Math.max(min, value));
|
|
}
|
|
|
|
function resolvedParams(overrides) {
|
|
if (!overrides || overrides === _params) return _params;
|
|
return { ..._params, ...overrides };
|
|
}
|
|
|
|
function focusTargetEmphasisResolved(
|
|
spriteScreenPosition,
|
|
spriteCameraDistance,
|
|
target,
|
|
tuning,
|
|
previouslyCompeting,
|
|
spriteHalfWidthPx,
|
|
spriteHalfHeightPx,
|
|
previouslyFarther,
|
|
) {
|
|
if (!target?.screenRect || !spriteScreenPosition) return 1;
|
|
if (
|
|
!Number.isFinite(spriteScreenPosition.x) ||
|
|
!Number.isFinite(spriteScreenPosition.y)
|
|
)
|
|
return 1;
|
|
|
|
// Published rects already contain their publication-time padding. The
|
|
// delta keeps direct pure-function calls and runtime A/B overrides honest.
|
|
// The ambient extent makes overlap mean visual overlap, not center-point
|
|
// containment: a class-sized icon whose edge intrudes into the focus rect
|
|
// yields even when its center remains just outside it.
|
|
const paddingDelta =
|
|
tuning.paddingPx -
|
|
(Number.isFinite(target.paddingPx) ? target.paddingPx : 0);
|
|
const hysteresis = previouslyCompeting ? tuning.hysteresisPx : 0;
|
|
const expansionX =
|
|
paddingDelta +
|
|
hysteresis +
|
|
Math.max(0, Number.isFinite(spriteHalfWidthPx) ? spriteHalfWidthPx : 0);
|
|
const expansionY =
|
|
paddingDelta +
|
|
hysteresis +
|
|
Math.max(0, Number.isFinite(spriteHalfHeightPx) ? spriteHalfHeightPx : 0);
|
|
const rect = target.screenRect;
|
|
const inside =
|
|
spriteScreenPosition.x >= rect.left - expansionX &&
|
|
spriteScreenPosition.x <= rect.right + expansionX &&
|
|
spriteScreenPosition.y >= rect.top - expansionY &&
|
|
spriteScreenPosition.y <= rect.bottom + expansionY;
|
|
if (!inside) return 1;
|
|
|
|
const floor = clamp(tuning.dimFloor, 0.01, 1);
|
|
if (tuning.nearerBehavior === 'dim') return floor;
|
|
|
|
const distanceBand = Number.isFinite(target.cameraDistance)
|
|
? Math.max(0, target.cameraDistance * tuning.distanceHysteresisRatio)
|
|
: 0;
|
|
const fartherThreshold = Number.isFinite(target.cameraDistance)
|
|
? target.cameraDistance + (previouslyFarther ? -distanceBand : distanceBand)
|
|
: Number.NaN;
|
|
const farther =
|
|
!Number.isFinite(spriteCameraDistance) ||
|
|
!Number.isFinite(fartherThreshold) ||
|
|
spriteCameraDistance >= fartherThreshold;
|
|
if (farther) return floor;
|
|
if (tuning.nearerBehavior === 'partial') return floor + (1 - floor) * 0.5;
|
|
return 1;
|
|
}
|
|
|
|
function smoothFocusEmphasisResolved(current, target, elapsedMs, tuning) {
|
|
const from = clamp(
|
|
Number.isFinite(current) ? current : 1,
|
|
tuning.dimFloor,
|
|
1,
|
|
);
|
|
const to = clamp(Number.isFinite(target) ? target : 1, tuning.dimFloor, 1);
|
|
if (Math.abs(to - from) < Number.EPSILON) return to;
|
|
const duration = to < from ? tuning.attackMs : tuning.releaseMs;
|
|
if (duration <= 0) return to;
|
|
const t = clamp(
|
|
(Number.isFinite(elapsedMs) ? elapsedMs : 0) / duration,
|
|
0,
|
|
1,
|
|
);
|
|
// Cubic ease-out reaches the exact endpoint at the configured duration and
|
|
// stays continuous when a moving contact reverses direction mid-transition.
|
|
const eased = 1 - (1 - t) ** 3;
|
|
return clamp(from + (to - from) * eased, tuning.dimFloor, 1);
|
|
}
|
|
|
|
/**
|
|
* Replace the runtime tuning values used by every focus consumer.
|
|
* Unknown keys are ignored so evidence-harness overrides cannot accidentally
|
|
* grow an undocumented rendering contract.
|
|
* @param {Partial<typeof DEFAULT_FOCUS_DEEMPHASIS_PARAMS>} [patch]
|
|
* @returns {typeof DEFAULT_FOCUS_DEEMPHASIS_PARAMS} Current normalized values.
|
|
*/
|
|
export function setFocusDeemphasisParams(patch = {}) {
|
|
const next = { ..._params };
|
|
if (Number.isFinite(patch.paddingPx))
|
|
next.paddingPx = Math.max(0, patch.paddingPx);
|
|
if (Number.isFinite(patch.dimFloor))
|
|
next.dimFloor = clamp(patch.dimFloor, 0.01, 1);
|
|
if (['allow', 'dim', 'partial'].includes(patch.nearerBehavior)) {
|
|
next.nearerBehavior = patch.nearerBehavior;
|
|
}
|
|
if (Number.isFinite(patch.hysteresisPx))
|
|
next.hysteresisPx = Math.max(0, patch.hysteresisPx);
|
|
if (Number.isFinite(patch.distanceHysteresisRatio)) {
|
|
next.distanceHysteresisRatio = clamp(patch.distanceHysteresisRatio, 0, 0.5);
|
|
}
|
|
if (Number.isFinite(patch.attackMs))
|
|
next.attackMs = Math.max(0, patch.attackMs);
|
|
if (Number.isFinite(patch.releaseMs))
|
|
next.releaseMs = Math.max(0, patch.releaseMs);
|
|
if (Number.isFinite(patch.writeEpsilon))
|
|
next.writeEpsilon = Math.max(0, patch.writeEpsilon);
|
|
_params = next;
|
|
return { ..._params };
|
|
}
|
|
|
|
/** @returns {typeof DEFAULT_FOCUS_DEEMPHASIS_PARAMS} Current runtime tuning. */
|
|
export function getFocusDeemphasisParams() {
|
|
return _params;
|
|
}
|
|
|
|
/** Restore production defaults. Primarily useful for deterministic QA. */
|
|
export function resetFocusDeemphasisParams() {
|
|
_params = { ...DEFAULT_FOCUS_DEEMPHASIS_PARAMS };
|
|
}
|
|
|
|
/**
|
|
* Publish a focus target from the exact world position already cached by its
|
|
* tracking/render path, through the renderer bound to `viewer`: its query
|
|
* port projects the position and its camera's pose gives the distance.
|
|
* Callers must never re-derive a position here: a second
|
|
* propagation/dead-reckoning sample at a different frame phase recreates the
|
|
* tracked-target jitter class this service is designed to avoid.
|
|
*
|
|
* @param {object} input
|
|
* @param {string} input.ownerLayer
|
|
* @param {string|number} input.id
|
|
* @param {object} input.viewer The host the renderer is bound to.
|
|
* @param {{x: number, y: number, z: number}} input.displayPosition Cached display position.
|
|
* @param {number} [input.widthPx=24]
|
|
* @param {number} [input.heightPx=24]
|
|
* @param {Partial<typeof DEFAULT_FOCUS_DEEMPHASIS_PARAMS>} [input.params]
|
|
* @returns {object|null} Published target, or null when it cannot be projected.
|
|
*/
|
|
export function publishFocusTargetAt({
|
|
ownerLayer,
|
|
id,
|
|
viewer,
|
|
displayPosition,
|
|
widthPx = 24,
|
|
heightPx = 24,
|
|
params,
|
|
}) {
|
|
const query = viewer ? findQuery(viewer) : null;
|
|
let eye = null;
|
|
try {
|
|
eye = viewer ? (findCamera(viewer)?.pose().position ?? null) : null;
|
|
} catch {
|
|
eye = null;
|
|
}
|
|
if (
|
|
!ownerLayer ||
|
|
id === null ||
|
|
id === undefined ||
|
|
!query ||
|
|
!eye ||
|
|
!displayPosition
|
|
) {
|
|
clearFocusTarget(ownerLayer, id);
|
|
return null;
|
|
}
|
|
return publishFocusRect({
|
|
ownerLayer,
|
|
id,
|
|
screen: query.project(displayPosition),
|
|
cameraDistance: Math.hypot(
|
|
displayPosition.x - eye.x,
|
|
displayPosition.y - eye.y,
|
|
displayPosition.z - eye.z,
|
|
),
|
|
frameNumber: -1,
|
|
widthPx,
|
|
heightPx,
|
|
params,
|
|
});
|
|
}
|
|
|
|
/** Publish the focus rectangle around `screen`, or clear it when there is none. */
|
|
function publishFocusRect({
|
|
ownerLayer,
|
|
id,
|
|
screen,
|
|
cameraDistance,
|
|
frameNumber,
|
|
widthPx,
|
|
heightPx,
|
|
params,
|
|
}) {
|
|
if (!screen || !Number.isFinite(screen.x) || !Number.isFinite(screen.y)) {
|
|
clearFocusTarget(ownerLayer, id);
|
|
return null;
|
|
}
|
|
const tuning = resolvedParams(params);
|
|
const padding = tuning.paddingPx;
|
|
const halfWidth = Math.max(1, widthPx) / 2;
|
|
const halfHeight = Math.max(1, heightPx) / 2;
|
|
const appeared = !_focusTarget;
|
|
_focusTarget = {
|
|
ownerLayer,
|
|
id,
|
|
screenRect: {
|
|
left: screen.x - halfWidth - padding,
|
|
top: screen.y - halfHeight - padding,
|
|
right: screen.x + halfWidth + padding,
|
|
bottom: screen.y + halfHeight + padding,
|
|
},
|
|
paddingPx: padding,
|
|
cameraDistance,
|
|
frameNumber,
|
|
};
|
|
if (appeared) {
|
|
for (const listener of _focusAppearListeners) {
|
|
try {
|
|
listener();
|
|
} catch (e) {
|
|
console.warn('[focus] appear listener error:', e);
|
|
}
|
|
}
|
|
}
|
|
return _focusTarget;
|
|
}
|
|
|
|
const _focusAppearListeners = new Set();
|
|
|
|
/**
|
|
* Notify on the null→set edge of the shared focus target. Consumers that
|
|
* self-suspend their per-frame focus work (e.g. CCTV's projection loop) use
|
|
* this single edge to re-arm; the set→null edge needs no event because the
|
|
* consumer's own loop is still running through the relax tail and
|
|
* self-stops via focusPassIsNeeded. (perf wave 1)
|
|
* @param {() => void} listener Called when a focus target is published after none existed.
|
|
* @returns {() => void} Unsubscribe.
|
|
*/
|
|
export function onFocusTargetAppear(listener) {
|
|
_focusAppearListeners.add(listener);
|
|
return () => _focusAppearListeners.delete(listener);
|
|
}
|
|
|
|
/**
|
|
* Clear the focus only when the caller still owns it. This prevents idle
|
|
* tracked-layer ticks from erasing a target just published by another layer.
|
|
* @param {string} [ownerLayer]
|
|
* @param {string|number|null} [id]
|
|
*/
|
|
export function clearFocusTarget(ownerLayer, id = null) {
|
|
if (!_focusTarget) return;
|
|
if (ownerLayer && _focusTarget.ownerLayer !== ownerLayer) return;
|
|
if (id !== null && id !== undefined && _focusTarget.id !== id) return;
|
|
_focusTarget = null;
|
|
}
|
|
|
|
/** @returns {object|null} The current shared focus target. */
|
|
export function getFocusTarget() {
|
|
return _focusTarget;
|
|
}
|
|
|
|
/**
|
|
* Pure focus decision for one ambient sprite.
|
|
*
|
|
* `previouslyCompeting` is state, not tuning: it expands the exit edge by
|
|
* `hysteresisPx` without moving the entry edge. Farther sprites dim fully;
|
|
* nearer treatment deliberately remains a runtime tuning choice.
|
|
*
|
|
* @param {{x:number,y:number}|null} spriteScreenPosition
|
|
* @param {number} spriteCameraDistance
|
|
* @param {object|null} target
|
|
* @param {Partial<typeof DEFAULT_FOCUS_DEEMPHASIS_PARAMS>} [params]
|
|
* @param {boolean} [previouslyCompeting=false]
|
|
* @param {number} [spriteHalfWidthPx=0] Ambient visual half-width.
|
|
* @param {number} [spriteHalfHeightPx=spriteHalfWidthPx] Ambient visual half-height.
|
|
* @param {boolean} [previouslyFarther=previouslyCompeting] Prior distance-side state.
|
|
* @returns {number} Target emphasis in [dimFloor, 1].
|
|
*/
|
|
export function focusTargetEmphasis(
|
|
spriteScreenPosition,
|
|
spriteCameraDistance,
|
|
target,
|
|
params,
|
|
previouslyCompeting = false,
|
|
spriteHalfWidthPx = 0,
|
|
spriteHalfHeightPx = spriteHalfWidthPx,
|
|
previouslyFarther = previouslyCompeting,
|
|
) {
|
|
const tuning = resolvedParams(params);
|
|
return focusTargetEmphasisResolved(
|
|
spriteScreenPosition,
|
|
spriteCameraDistance,
|
|
target,
|
|
tuning,
|
|
previouslyCompeting,
|
|
spriteHalfWidthPx,
|
|
spriteHalfHeightPx,
|
|
previouslyFarther,
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Pure time-based easing step. Attack means motion toward de-emphasis;
|
|
* release means restoration toward full emphasis.
|
|
* @param {number} current
|
|
* @param {number} target
|
|
* @param {number} elapsedMs
|
|
* @param {Partial<typeof DEFAULT_FOCUS_DEEMPHASIS_PARAMS>} [params]
|
|
* @returns {number}
|
|
*/
|
|
export function smoothFocusEmphasis(current, target, elapsedMs, params) {
|
|
const tuning = resolvedParams(params);
|
|
return smoothFocusEmphasisResolved(current, target, elapsedMs, tuning);
|
|
}
|
|
|
|
/**
|
|
* Advance one sprite's persistent focus state. The caller owns the eventual
|
|
* color write so focus can compose with freshness/horizon alpha at one site.
|
|
* @param {object} sprite Stable billboard/point primitive identity.
|
|
* @param {object} input
|
|
* @param {{x:number,y:number}|null} input.screenPosition
|
|
* @param {number} input.cameraDistance
|
|
* @param {number} input.nowMs
|
|
* @param {object|null} [input.target]
|
|
* @param {Partial<typeof DEFAULT_FOCUS_DEEMPHASIS_PARAMS>} [input.params]
|
|
* @param {number} [input.spriteHalfWidthPx=0]
|
|
* @param {number} [input.spriteHalfHeightPx=input.spriteHalfWidthPx]
|
|
*
|
|
* IMPORTANT: the returned object is a module-owned mutable singleton. Consume
|
|
* every needed property before the next call; never retain it as a snapshot.
|
|
* @returns {{factor:number, changed:boolean, transitioning:boolean,active:boolean,desired:number}}
|
|
*/
|
|
export function advanceSpriteFocus(
|
|
sprite,
|
|
{
|
|
screenPosition,
|
|
cameraDistance,
|
|
nowMs,
|
|
target = _focusTarget,
|
|
params,
|
|
spriteHalfWidthPx = 0,
|
|
spriteHalfHeightPx = spriteHalfWidthPx,
|
|
},
|
|
) {
|
|
const tuning = resolvedParams(params);
|
|
let state = _spriteStates.get(sprite);
|
|
if (!state) {
|
|
if (!target) {
|
|
_advanceResult.factor = 1;
|
|
_advanceResult.changed = false;
|
|
_advanceResult.transitioning = false;
|
|
_advanceResult.active = false;
|
|
_advanceResult.desired = 1;
|
|
return _advanceResult;
|
|
}
|
|
state = {
|
|
factor: 1,
|
|
desired: 1,
|
|
transitionFrom: 1,
|
|
transitionStartMs: nowMs,
|
|
wasFarther: false,
|
|
};
|
|
_spriteStates.set(sprite, state);
|
|
}
|
|
|
|
// First sample the OLD transition at this timestamp. If the desired state
|
|
// changes, the new transition must begin at the value already on screen,
|
|
// not the prior tick's stale anchor. This preserves progress during a
|
|
// retarget and, paired with range hysteresis, prevents boundary chatter
|
|
// from continually restarting at 1.0.
|
|
const oldElapsedMs = Math.max(0, nowMs - state.transitionStartMs);
|
|
const current = smoothFocusEmphasisResolved(
|
|
state.transitionFrom,
|
|
state.desired,
|
|
oldElapsedMs,
|
|
tuning,
|
|
);
|
|
const desired = focusTargetEmphasisResolved(
|
|
screenPosition,
|
|
cameraDistance,
|
|
target,
|
|
tuning,
|
|
state.desired < 1,
|
|
spriteHalfWidthPx,
|
|
spriteHalfHeightPx,
|
|
state.wasFarther,
|
|
);
|
|
if (desired !== state.desired) {
|
|
state.transitionFrom = current;
|
|
state.transitionStartMs = nowMs;
|
|
state.desired = desired;
|
|
}
|
|
const elapsedMs = Math.max(0, nowMs - state.transitionStartMs);
|
|
const next = smoothFocusEmphasisResolved(
|
|
state.transitionFrom,
|
|
desired,
|
|
elapsedMs,
|
|
tuning,
|
|
);
|
|
const changed = Math.abs(next - state.factor) > tuning.writeEpsilon;
|
|
state.factor = next;
|
|
state.desired = desired;
|
|
state.wasFarther =
|
|
tuning.nearerBehavior !== 'dim' &&
|
|
Math.abs(desired - tuning.dimFloor) <= tuning.writeEpsilon;
|
|
const transitioning = Math.abs(next - desired) > tuning.writeEpsilon;
|
|
const active = Math.abs(next - 1) > tuning.writeEpsilon;
|
|
|
|
if (!target && !transitioning && next === 1) _spriteStates.delete(sprite);
|
|
_advanceResult.factor = next;
|
|
_advanceResult.changed = changed;
|
|
_advanceResult.transitioning = transitioning;
|
|
_advanceResult.active = active;
|
|
_advanceResult.desired = desired;
|
|
return _advanceResult;
|
|
}
|
|
|
|
/**
|
|
* A gated consumer must keep ticking until every previously dimmed sprite has
|
|
* returned to identity, even when no target remains.
|
|
* @param {object|null} target
|
|
* @param {number} activeCount Count of emphasis factors outside the 1.0 deadband.
|
|
* @returns {boolean}
|
|
*/
|
|
export function focusPassIsNeeded(target, activeCount) {
|
|
return (
|
|
(target !== null && target !== undefined) ||
|
|
(Number.isFinite(activeCount) && activeCount > 0)
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Match Cesium's shader-side NearFarScalar interpolation for rendered extents.
|
|
* Cesium interpolates against squared camera distance with a 0.2 exponent.
|
|
* @param {{near:number,nearValue:number,far:number,farValue:number}|null} scalar
|
|
* @param {number} cameraDistanceM
|
|
* @returns {number}
|
|
*/
|
|
export function nearFarScalarValueAtDistance(scalar, cameraDistanceM) {
|
|
if (!scalar || !Number.isFinite(cameraDistanceM)) return 1;
|
|
const nearSq = scalar.near * scalar.near;
|
|
const farSq = scalar.far * scalar.far;
|
|
if (!Number.isFinite(nearSq) || !Number.isFinite(farSq) || farSq <= nearSq)
|
|
return 1;
|
|
const rawT = (cameraDistanceM * cameraDistanceM - nearSq) / (farSq - nearSq);
|
|
const t = Math.pow(clamp(rawT, 0, 1), 0.2);
|
|
return scalar.nearValue + (scalar.farValue - scalar.nearValue) * t;
|
|
}
|
|
|
|
/** Shared virtual time used only by the DEV evidence seam. */
|
|
let _focusEvidenceNowMs = null;
|
|
|
|
/** Resolve production time unless deterministic evidence capture owns it. */
|
|
export function focusNowMs(productionNowMs) {
|
|
return _focusEvidenceNowMs ?? productionNowMs;
|
|
}
|
|
|
|
/** Set deterministic evidence time; called only through development seams. */
|
|
export function setFocusEvidenceNowMs(nowMs) {
|
|
_focusEvidenceNowMs = Number.isFinite(nowMs) ? nowMs : null;
|
|
return _focusEvidenceNowMs;
|
|
}
|
|
|
|
/** Advance deterministic evidence time without consulting a wall clock. */
|
|
export function advanceFocusEvidenceNowMs(deltaMs) {
|
|
if (_focusEvidenceNowMs === null) return null;
|
|
_focusEvidenceNowMs += Math.max(0, Number.isFinite(deltaMs) ? deltaMs : 0);
|
|
return _focusEvidenceNowMs;
|
|
}
|
|
|
|
/**
|
|
* True when a sprite holds no dimming state, or has settled at full emphasis
|
|
* with nothing pending. Advancing such a sprite without a screen position (a
|
|
* hidden sprite) changes neither its state nor its alpha, so a layer pass may
|
|
* skip it.
|
|
* @param {object} sprite
|
|
* @returns {boolean}
|
|
*/
|
|
export function spriteFocusAtRest(sprite) {
|
|
const state = _spriteStates.get(sprite);
|
|
return (
|
|
!state || (state.factor === 1 && state.desired === 1 && !state.wasFarther)
|
|
);
|
|
}
|
|
|
|
/** Forget state when a primitive is removed from its owning collection. */
|
|
export function forgetSpriteFocus(sprite) {
|
|
if (sprite) _spriteStates.delete(sprite);
|
|
}
|
|
|
|
/**
|
|
* Deadband predicate shared by consumers' final alpha write sites.
|
|
* @param {number} currentAlpha
|
|
* @param {number} nextAlpha
|
|
* @param {Partial<typeof DEFAULT_FOCUS_DEEMPHASIS_PARAMS>} [params]
|
|
* @returns {boolean}
|
|
*/
|
|
export function focusAlphaNeedsWrite(currentAlpha, nextAlpha, params) {
|
|
const tuning = resolvedParams(params);
|
|
return (
|
|
!Number.isFinite(currentAlpha) ||
|
|
Math.abs(currentAlpha - nextAlpha) > tuning.writeEpsilon
|
|
);
|
|
}
|