Files
gods-eye-view/src/app/tools.js
T
German Khokhlov 18f69c2699 Follow, credits, embed views and FPS through the engine on Navara
Five places still read the Cesium viewer and so did nothing, or the wrong
thing, on Navara. Each now goes through the globe contract, and Cesium
behaves as before.

- The Navara ground floor stands aside while the camera inputs are
  suspended, not only while they are switched off. The cockpit suspends
  them, so its eye 12 m up no longer jumps to the floor's 30 m between
  updates. A follow's own suspension keeps the floor on, as before.
- Follow state comes from engine.camera.following() and followChanged
  instead of viewer.trackedEntity. Enabling CCTV during a follow no longer
  flies away and ends it, a new follow stamps navigation, Director cards
  wait while a subject is followed, and an explicit navigation stops the
  follow on both engines.
- Navara registers every data credit, as Cesium does. The allowlist left
  out the layers that moved to Navara later (CCTV agencies, street-level
  imagery, GIBS, routing, bike feeds and others).
- Annotation links and embed mode attach on every engine; their camera
  flights use engine.camera.flyTo. Only Cesium adds the timer that keeps
  an inline panel drawing.
- The FPS readout counts engine.frames.postRender, so it shows on Navara.

Each fix has a test that fails without it.
2026-11-08 17:05:27 +04:00

533 lines
17 KiB
JavaScript

import { retainsLayerSession } from './layerSession.js';
import { SceneDirector } from '../scenes/director.js';
import { initImageryBoxTool } from '../ui/imageryBoxTool.js';
import { createRecentImageryPanel } from '../ui/recentImagery.js';
import { attachSessionVoice } from './sessionVoice.js';
import {
sessionAnnotations,
sessionDrawTool,
sessionGeoImport,
} from './sessionTools.js';
import {
attachScenePart,
currentSceneOf,
detachPartsOnTeardown,
} from './sceneParts.js';
import { installViews, isEmbeddedInline, keepPanelRendering } from './embed.js';
import {
installScopeMask,
destroyScopeMask,
isScopeMaskEnabled,
} from '../scopeMask.js';
import { KEYHOLE_OUTER_RADIUS } from '../celestialRing.js';
import { installGlobeInViewRecovery } from '../globe/cesium/viewer.js';
import { installLayerReleaseTrim } from '../sceneCommandRelease.js';
import { renderGovernorFor } from '../renderGovernor.js';
/**
* Attach scene tools, rendering listeners and the application debug handle.
* The Director, the annotation board, Draw, Import, voice and the debug
* handle belong to the application; the tools bound to one globe (render
* governor, release trim, scope mask, imagery box, tracking and visibility
* listeners, embedded views, the debug handle's globe fields) attach to each
* engine the page shows (src/app/sceneParts.js), one tree for every engine
* (attachEngineTools): each engine kind's tool backend says where the shared
* tools draw on it, and the tools that still drive the Cesium viewer attach
* only where there is one. The Director follows the attached engine.
*/
export async function createApplicationTools({
scene,
controls,
data,
loadingScreen,
placeSearch,
voice = {},
startChrome,
onSceneDirector,
sceneDataPacks,
layerSession,
signal,
defer,
}) {
const { operations } = scene;
const first = currentSceneOf(scene);
const { styleManager } = controls;
const { dataManager } = data;
// The shell leaves its globe before the data layers detach (registered
// after them, so it detaches first): its share restoration and Context
// transactions end while the layers and the viewer still exist.
await attachScenePart(
scene,
{
name: 'shell-release',
detachScene: (options, transaction) =>
styleManager.detachScene?.(options, transaction),
},
{ defer },
);
const isStackAvailable = (mapStackController) => (id) =>
mapStackController?.isStackAvailable(id) === true;
const sceneDirector =
layerSession?.director ??
new SceneDirector(first, styleManager, dataManager, {
dataPacks: sceneDataPacks,
isMapStackAvailable: isStackAvailable(first.mapStackController),
});
// The Director built on this globe is attached to it already.
let directorScene = layerSession?.director ? null : first;
if (layerSession) layerSession.director = sceneDirector;
dataManager.layers
.get('bhote-koshi-2026')
?.module.attachSceneController(sceneDirector);
defer(() => {
if (retainsLayerSession(layerSession)) {
sceneDirector.suspendScene();
} else {
if (layerSession) layerSession.director = null;
return sceneDirector.destroy();
}
});
onSceneDirector?.(sceneDirector);
await attachScenePart(
scene,
{
name: 'globe-in-view',
// Cesium only for now: it reads Cesium's camera (positionWC, its
// running flight).
attachScene(next, { defer: deferScene }) {
const viewer = cesiumViewerOf(next.engine);
if (!viewer) return;
deferScene(
installGlobeInViewRecovery(viewer, {
// The scope mask hides everything outside its keyhole.
keyholeRadius: () =>
isScopeMaskEnabled() ? KEYHOLE_OUTER_RADIUS : 0,
// An authored scene frames its own shots, holds included.
paused: () => sceneDirector.running,
}),
);
},
},
{ defer },
);
await attachScenePart(
scene,
{
name: 'director',
attachScene(next) {
if (next === directorScene) return;
directorScene = null;
sceneDirector.attachScene(
next,
styleManager,
isStackAvailable(next.mapStackController),
);
},
// The session keeps the Director; the page teardown destroys it.
detachScene: () => sceneDirector.suspendScene(),
},
{ defer },
);
// The application's debug handle, the same object on every globe; its
// globe fields follow the engine.
const debug = {
viewer: null,
engine: null,
styleManager,
tileset: null,
dataManager,
sceneDirector,
mapStackController: null,
annotations: null,
weatherEffects: controls.weatherEffects ?? null,
cockpitCloudEffects: null,
voiceCommands: null,
getRenderGovernorDiagnostics: () =>
renderGovernorFor(debug.engine)?.getRenderGovernorDiagnostics(),
surfaceServices: operations.surface,
requestRender: (reason) =>
renderGovernorFor(debug.engine)?.governorRequestRender(reason),
};
defer(() => {
if (window.__godsEyeView === debug) delete window.__godsEyeView;
});
// The attached engine's tools; `annotations` and the voice handle answer
// for the engine attached now.
const attached = { annotations: null, voiceCommands: null };
let startupChromeOptions;
const context = {
controls,
data,
operations,
placeSearch,
voice,
sceneDirector,
layerSession,
styleManager,
dataManager,
};
await attachScenePart(
scene,
{
name: 'tools',
async attachScene(next, attachment) {
const tools = await attachEngineTools(next, context, attachment);
startupChromeOptions ??= tools.startupChrome;
attached.annotations = tools.annotations;
attached.voiceCommands = tools.voiceCommands;
attachment.defer(() => {
attached.annotations = null;
});
},
},
{ defer },
);
// The debug handle names the attached globe once every part is on it.
await attachScenePart(
scene,
{
name: 'debug-handle',
attachScene(next) {
Object.assign(debug, {
viewer: next.viewer ?? null,
engine: next.engine,
tileset: next.tileset ?? null,
mapStackController: next.mapStackController ?? null,
annotations: attached.annotations,
cockpitCloudEffects: controls.cockpitCloudEffects ?? null,
voiceCommands: attached.voiceCommands,
});
// Present only while a globe is attached, as when every engine
// built its own application: scripts read `engine.kind` from it.
window.__godsEyeView = debug;
},
detachScene() {
if (window.__godsEyeView === debug) delete window.__godsEyeView;
Object.assign(debug, {
viewer: null,
engine: null,
tileset: null,
mapStackController: null,
annotations: null,
cockpitCloudEffects: null,
});
},
},
{ defer },
);
detachPartsOnTeardown(scene, defer, () => ({
handoff: retainsLayerSession(layerSession),
}));
// Startup chrome belongs to the page and keeps the first backend
// policy across later engine attachments.
if (startChrome)
defer(
startChrome({
loadingScreen,
styleManager,
dataManager,
signal,
...startupChromeOptions,
}),
);
return {
sceneDirector,
get annotations() {
return attached.annotations;
},
get voiceCommands() {
return attached.voiceCommands;
},
};
}
/**
* The Cesium viewer under an engine, or null on an engine without one: the
* one place the tools read it.
*/
const cesiumViewerOf = (engine) => engine?.extensions?.cesium?.viewer ?? null;
/**
* The tool backend of each engine kind (see attachEngineTools). Cesium's
* holds the tools that still drive its viewer, so they stay absent on
* other engines; Navara's loads with its mode (src/app/navaraMode.js), so
* the Cesium-mode bundle carries none of it.
*/
const TOOL_BACKENDS = Object.freeze({
cesium: async () => cesiumToolBackend,
navara: async () => (await import('./navaraMode.js')).navaraToolBackend,
});
/** The Cesium tool backend: the shared tools and its own on the viewer. */
function cesiumToolBackend({ engine, tileset }) {
const viewer = cesiumViewerOf(engine);
const {
governorRequestRender,
holdContinuousRender,
releaseContinuousRender,
} = renderGovernorFor(engine);
return {
viewer,
startupChrome: {},
board: () => ({ viewer, engine, tileset }),
draw: () => ({ engine }),
// The tileset lets the layer drape while the globe is hidden.
recentImagery(layer) {
layer.attachTileset(tileset);
return { viewer };
},
attach({ dataManager }, { defer }) {
// Cesium keeps a turned-off layer's draw commands (and so all its
// entities) alive in reused per-pass arrays; trim them after each
// disable.
defer(
installLayerReleaseTrim({
scene: viewer.scene,
dataManager,
requestRender: governorRequestRender,
}),
);
// The follow camera recomputes the tracked target's dead-reckon
// position every frame — tracking anything is a per-frame animation.
// (perf wave 2)
const removeTrackingListener =
viewer.trackedEntityChanged.addEventListener(() => {
if (viewer.trackedEntity) holdContinuousRender('tracked-entity');
else releaseContinuousRender('tracked-entity');
});
defer(() => {
removeTrackingListener();
releaseContinuousRender('tracked-entity');
});
},
// Hidden-state suspension (perf wave 2): when the window/tab is hidden,
// stop the default render loop outright — a hidden canvas repaints for
// nobody, and browser rAF throttling still lets throttled frames burn
// GPU.
suspend(hidden, { cockpitCloudEffects }) {
viewer.useDefaultRenderLoop = !hidden;
cockpitCloudEffects?.setSuspended?.(hidden);
},
// An inline panel the host reports hidden stops Cesium's render loop.
keepRendering: (options) => keepPanelRendering(viewer, options),
};
}
/**
* The tools of one globe, on any engine: the annotation board, Draw,
* Import, the Recent Imagery box and panel, the render governor, the scope
* mask, hidden-tab handling and voice, and the engine's own tools. The
* engine kind's backend (TOOL_BACKENDS) says where the shared tools draw:
* `board()` and `draw()` give their attachScene arguments (null: not on
* this engine), `recentImagery(layer)` the panel's globe,
* `attach(context, attachment)` adds
* the engine's own tools, `suspend(hidden, controls)` its hidden-tab
* handling and `keepRendering` what keeps an inline panel drawing. The
* shared tools keep their session state across engines. Returns the
* annotation board (null without one) and voice commands.
*/
async function attachEngineTools(
scene,
{
controls,
data,
operations,
placeSearch,
voice,
sceneDirector,
layerSession,
styleManager,
dataManager,
},
{ signal, defer },
) {
const { engine, mapStackController } = scene;
const governor = scene.services?.render ?? renderGovernorFor(engine);
const backend = (await TOOL_BACKENDS[engine.kind]())(scene);
// The page session's board, Draw and Import (src/app/sessionTools.js):
// an engine switch only takes their drawing off this globe.
const annotations = attachBoard(
backend.board(),
{ layerSession, placeSearch, operations },
defer,
);
attachDraw(backend.draw, { layerSession, annotations, styleManager }, defer);
// Import draws through the globe contract, the same on every engine.
attachGeoImport(
{ engine },
{ layerSession, styleManager, operations, mapStackController },
defer,
);
// DATA ▸ Recent Imagery: the box tool claims the pointer like Draw and the
// panel lives on the right rail, so both belong to this globe.
const recentImagery = dataManager.layers.get('recent-imagery')?.module;
if (recentImagery) {
const panelGlobe = backend.recentImagery(recentImagery);
const imageryBoxTool = initImageryBoxTool({
engine,
onBox: (box) => recentImagery.setBox(box),
onPreview: (box) => recentImagery.setBoxPreview(box),
onCancel: (reason, message, box) => {
if (message) recentImagery.reportBoxRefusal(message, box);
},
onActive: (active) => recentImagery.setToolActive(active),
// The tool takes Escape in a capture listener, so the panel's order
// (clear a preview before cancelling the tool) is applied here.
onEscape: () => recentImagery.clearPreview(),
});
// The readout mounts in its rail body through the layer panel, like the
// weather readout.
data.presentation.attachRecentImagery((container) =>
createRecentImageryPanel({
container,
...panelGlobe,
layer: recentImagery,
tool: imageryBoxTool,
}),
);
// The live gate's handle (scripts/qa-recent-imagery.mjs).
const recentImageryHandle = { layer: recentImagery, tool: imageryBoxTool };
window.__gevRecentImagery = recentImageryHandle;
defer(() => {
if (window.__gevRecentImagery === recentImageryHandle)
delete window.__gevRecentImagery;
data.presentation.attachRecentImagery(null);
imageryBoxTool?.destroy();
});
}
// Installed AFTER every module above has had its chance to register
// pre-install holds.
governor.install();
backend.attach?.({ data, styleManager, dataManager }, { signal, defer });
// Install the explicit scope mask used by the DISPLAY controls: a canvas
// in the engine's container, its terminus following the camera's height.
installScopeMask(engine);
defer(() => destroyScopeMask());
// A hidden tab: the engine's own suspension, if any; holder/data state is
// untouched, so return is seamless: restore the loop, refresh the one DOM
// surface we gated, render a frame.
const syncVisibilitySuspension = () => {
// A panel's host may report it hidden while it is on screen; the panel
// keeps drawing itself (see keepPanelRendering in embed.js).
const hidden = document.hidden && !isEmbeddedInline();
backend.suspend?.(hidden, controls);
if (!hidden) {
data.presentation.flushVisible();
governor.governorRequestRender('visibility-restore');
}
};
document.addEventListener('visibilitychange', syncVisibilitySuspension);
defer(() =>
document.removeEventListener('visibilitychange', syncVisibilitySuspension),
);
// Apply the CURRENT state to a suspending engine too — bootstrap can
// complete while the tab is already hidden, and waiting for the next
// transition would leave the loop burning behind a hidden tab. (perf wave
// 2 fix)
if (backend.suspend) syncVisibilitySuspension();
// Voice uses the engine and shared session services; each action checks
// the capabilities it needs on the attached scene.
const voiceCommands = attachSessionVoice({
layerSession,
voice,
operations,
placeSearch,
dataManager,
scene: {
viewer: backend.viewer ?? null,
engine,
styleManager,
sceneDirector,
annotations,
},
signal,
defer,
});
// Annotation links and embed mode, on every engine.
defer(
installViews({
shell: styleManager,
engine,
keepRendering: backend.keepRendering ?? null,
dataManager,
run: (name, args) => voiceCommands.runner(name, args, { signal }),
signal,
}),
);
return { annotations, voiceCommands, startupChrome: backend.startupChrome };
}
/** The annotation board drawn on this globe (`boardScene`), or null. */
function attachBoard(
boardScene,
{ layerSession, placeSearch, operations },
defer,
) {
if (!boardScene) return null;
// The board belongs to the page session when there is one: an engine
// switch only takes its drawing off this globe.
const annotations = sessionAnnotations({
layerSession,
placeSearch,
resolver: operations.annotationResolver,
defer,
});
annotations.attachScene(boardScene);
defer(() => annotations.detachScene());
return annotations;
}
/**
* UTILITIES ▸ Draw on this globe (`drawScene()`: its input and preview):
* the tool claims the globe's pointer while a sketch is open, so a switch
* ends an open sketch and keeps the chosen shape and colour. Returns the
* tool (null on a page without it or without the board).
*/
function attachDraw(
drawScene,
{ layerSession, annotations, styleManager },
defer,
) {
if (!annotations) return null;
const drawTool = sessionDrawTool({
layerSession,
annotations,
styleManager,
defer,
});
drawTool?.attachScene({ ...drawScene(), navigation: styleManager });
defer(() => drawTool?.detachScene());
return drawTool;
}
/**
* UTILITIES ▸ Import on this globe (`importScene`: its engine): the next
* globe reads the session's files again. The drop listeners belong to
* this globe. Returns the control (null on a page without it).
*/
function attachGeoImport(
importScene,
{ layerSession, styleManager, operations, mapStackController },
defer,
) {
if (!importScene) return null;
const geoFileImport = sessionGeoImport({
layerSession,
styleManager,
operations,
defer,
});
geoFileImport?.attachScene({
...importScene,
navigation: styleManager,
subscribeMapSource: (listener) => mapStackController?.subscribe?.(listener),
});
defer(() => geoFileImport?.detachScene());
return geoFileImport;
}