refactor(cctv): isolate native rendering resources

Keep shared CCTV logic independent of Cesium, release the original renderer's resources, and guard retired initialization/media work. Preserve native marker, plane, volume, calibration and input behavior.

Record keyless dev/preview validation and retain unresolved shell idle/terrain and photoreal acceptance gaps. Routine QA builds use empty Google and Cesium credentials and block paid maps before navigation.
This commit is contained in:
German Khokhlov committed 2026-10-29 00:06:22 +04:00
1 parent f72bf6a774
commit 93c71ffc86
32 files changed
+1536 -740

No files matched your search

+364
View File
@@ -0,0 +1,364 @@
import * as Cesium from 'cesium';
import * as geo from '../../../geo/index.js';
import { horizonOccluder } from '../../../data/iconOrientation.js';
import { createFrustumVolumePrimitive } from './cesiumViewshed.js';
import {
bindTrackingClickGesture,
isTrackingClickGesture,
} from '../../../data/trackingClickGesture.js';
import { createCesiumCctvGizmoRenderer } from './cesiumGizmo.js';
import {
CAMERA_ICON,
IDLE_CAMERA_COLOR,
IDLE_COVERAGE_COLOR,
PLANE_OUTLINE_COLOR,
} from '../policy.js';
/** Native CCTV resources and scene operations owned by one viewer. */
export function createCctvCesiumRenderer({ services, state }) {
let viewer = null;
let billboards = null;
let activeTileset = null;
const entities = new Set();
const volumes = new Set();
const listeners = new Set();
const gizmos = new Set();
const color = (value) => (value ? Cesium.Color.clone(value) : undefined);
function ownListener(remove) {
const release = () => {
if (!listeners.delete(release)) return;
remove();
};
listeners.add(release);
return release;
}
function addEntity(options) {
const entity = viewer.entities.add(options);
entities.add(entity);
return entity;
}
function removeEntity(entity) {
if (!entities.delete(entity)) return;
if (viewer.entities.getById(entity.id) === entity)
viewer.entities.remove(entity);
}
function tilesReady() {
if (!activeTileset || activeTileset.isDestroyed?.()) {
activeTileset = null;
const primitives = viewer?.scene?.primitives;
if (primitives && typeof primitives.get === 'function') {
for (let i = 0; i < primitives.length; i++) {
const p = primitives.get(i);
if (p instanceof Cesium.Cesium3DTileset && !p.isDestroyed?.()) {
activeTileset = p;
break;
}
}
}
}
if (!activeTileset) return true;
return activeTileset.show !== false && activeTileset.tilesLoaded === true;
}
function extractPickedCameraId(picked) {
if (!picked) return null;
const entity = picked.id?.properties
? picked.id
: picked.primitive?.id?.properties
? picked.primitive.id
: null;
const maybeProp = entity?.properties?.cctvCameraId;
if (maybeProp) {
const value =
typeof maybeProp.getValue === 'function'
? maybeProp.getValue(Cesium.JulianDate.now())
: maybeProp;
const record =
typeof value === 'string' ? state._recordById.get(value) : null;
const ownsCoverageEntity = Boolean(
record?.coverageEntities?.includes(entity),
);
const ownsProjectionEntity =
record?.projection?.planeEntity === entity ||
state._projectionEntities.some(
(runtime) =>
runtime?.cameraId === value && runtime.planeEntity === entity,
);
if (record && (ownsCoverageEntity || ownsProjectionEntity)) return value;
}
// Camera billboard IDs are intentionally the upstream camera ID, so a
// sibling may legitimately use the same string. A bare ID match is not
// ownership proof: require this layer's billboard collection or the exact
// billboard stored on the record.
const directId =
typeof picked.id === 'string'
? picked.id
: typeof picked.primitive?.id === 'string'
? picked.primitive.id
: null;
const record = directId === null ? null : state._recordById.get(directId);
if (!record) return null;
return picked.primitive === billboards ||
picked.primitive === record.billboard
? directId
: null;
}
return {
extractPickedCameraId,
attach(owner) {
if (viewer && viewer !== owner)
throw new Error('CCTV renderer already has an owner');
viewer = owner;
activeTileset = null;
},
get ready() {
return Boolean(viewer && !viewer.isDestroyed?.());
},
cameraCartographic: () => viewer?.camera?.positionCartographic,
following: () => Boolean(viewer?.trackedEntity),
globeVisible: () => viewer?.scene?.globe?.show,
tilesReady,
project: (position, result) =>
viewer.scene.cartesianToCanvasCoordinates(position, result),
distance: (position) =>
geo.cartesian3.distance(viewer.camera.positionWC, position),
horizonTest() {
const occluder = horizonOccluder(viewer.camera);
return (position) => occluder.isPointVisible(position);
},
viewport() {
const canvas = viewer.scene.canvas;
return {
width: canvas.clientWidth || canvas.width || 0,
height: canvas.clientHeight || canvas.height || 0,
};
},
request: () => viewer?.scene?.requestRender?.(),
pick: (screen) => viewer.scene.pick(screen),
onMoveEnd: (fn) => ownListener(viewer.camera.moveEnd.addEventListener(fn)),
onMoveStart: (fn) =>
ownListener(viewer.camera.moveStart.addEventListener(fn)),
bindClick(onClick, options = {}) {
const handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas);
bindTrackingClickGesture(
handler,
(event, gesture) => {
if (isTrackingClickGesture(gesture)) onClick(event);
},
options,
);
return ownListener(() => handler.destroy());
},
createGizmoRenderer() {
const gizmo = createCesiumCctvGizmoRenderer(viewer);
gizmos.add(gizmo);
return gizmo;
},
createMarkers() {
if (billboards) throw new Error('CCTV markers already exist');
billboards = new Cesium.BillboardCollection();
viewer.scene.primitives.add(billboards);
services.sprites.registerSpriteCollection('cctv', billboards);
return billboards;
},
createMarker(camera, position) {
return billboards.add({
id: camera.id,
image: CAMERA_ICON,
position,
color: color(IDLE_CAMERA_COLOR),
width: 24,
height: 24,
disableDepthTestDistance: Number.POSITIVE_INFINITY,
scaleByDistance: new Cesium.NearFarScalar(350, 1.25, 4_000_000, 0.42),
});
},
setMarkersVisible(value) {
if (billboards) billboards.show = value;
},
restoreOrder: () => services.sprites.restoreSpriteOrder(viewer),
showCredit: () => services.credits?.showOsmCredit?.(viewer, 'cctv'),
hideCredit: () => services.credits?.hideOsmCredit?.(viewer, 'cctv'),
sampleMeshFloorCells: (points, options) =>
services.mesh.sampleMeshFloorCells(viewer?.scene, points, options),
obstructionRay(origin, direction, exclude, far) {
if (!viewer?.scene?.pickFromRay) return undefined;
const hit = viewer.scene.pickFromRay(
new Cesium.Ray(origin, direction),
[billboards, ...exclude].filter(Boolean),
);
return hit?.position &&
geo.cartesian3.distance(origin, hit.position) <= far
? hit
: undefined;
},
createPlaneMaterial(image) {
return new Cesium.ImageMaterialProperty({
image,
transparent: true,
color: Cesium.Color.WHITE.withAlpha(0.95),
});
},
createTestPlaneMaterial: () =>
new Cesium.ColorMaterialProperty(Cesium.Color.WHITE),
setPlaneImage(runtime, image) {
runtime.planeMaterial.image = image;
},
createPlane(record, runtime, geometry, positions, orientation) {
return addEntity({
id: `cctv-${record.camera.id}-plane`,
properties: { cctvCameraId: record.camera.id },
show: false,
position: positions.capCenter,
orientation: Cesium.Quaternion.clone(orientation),
plane: {
plane: new Cesium.Plane(Cesium.Cartesian3.UNIT_Z, 0.0),
dimensions: new Cesium.Cartesian2(
geometry.halfW * 2,
geometry.halfH * 2,
),
material: runtime.planeMaterial,
outline: true,
outlineColor: color(PLANE_OUTLINE_COLOR),
},
});
},
updatePlane(runtime, geometry, positions, orientation) {
const entity = runtime.planeEntity;
entity.position = positions.capCenter;
entity.orientation = Cesium.Quaternion.clone(orientation);
if (entity.plane)
entity.plane.dimensions = new Cesium.Cartesian2(
geometry.halfW * 2,
geometry.halfH * 2,
);
},
setPlaneVisible(runtime, visible) {
if (runtime.planeEntity) runtime.planeEntity.show = visible;
},
removePlane: (runtime) => removeEntity(runtime.planeEntity),
createCoverage(cameraId, positions) {
const created = [];
try {
for (const [role, points] of [
['ray-tl', [positions.mount, positions.tl]],
['ray-tr', [positions.mount, positions.tr]],
['ray-br', [positions.mount, positions.br]],
['ray-bl', [positions.mount, positions.bl]],
[
'cap',
[
positions.tl,
positions.tr,
positions.br,
positions.bl,
positions.tl,
],
],
]) {
const entity = addEntity({
id: `cctv-${cameraId}-${role}`,
properties: { cctvCameraId: cameraId },
polyline: {
positions: points,
width: 1.2,
material: color(IDLE_COVERAGE_COLOR),
},
});
entity._coverageRole = role === 'cap' ? 'cap' : 'edge';
created.push(entity);
}
return created;
} catch (error) {
for (const entity of created) removeEntity(entity);
throw error;
}
},
updateCoverage(record, positions) {
const lines = record.coverageEntities;
if (!lines || lines.length < 5) return;
for (const [i, role] of ['tl', 'tr', 'br', 'bl'].entries())
lines[i].polyline.positions = [positions.mount, positions[role]];
lines[4].polyline.positions = [
positions.tl,
positions.tr,
positions.br,
positions.bl,
positions.tl,
];
},
removeCoverageEntity: removeEntity,
styleLine(entity, { visible, width, tint, dashed, depthFail }) {
entity.show = visible;
if (!entity.polyline) return;
entity.polyline.width = width;
entity.polyline.material = dashed
? new Cesium.PolylineDashMaterialProperty({ color: color(tint) })
: color(tint);
entity.polyline.depthFailMaterial = color(depthFail);
},
hideCoverage(record) {
for (const entity of record.coverageEntities || []) entity.show = false;
},
removeCoverage(record) {
for (const entity of record.coverageEntities || []) removeEntity(entity);
},
createVolume(record, tint) {
const primitive = createFrustumVolumePrimitive(
record.frustumPositions,
color(tint),
);
primitive._gevViewshed = record.camera.id;
viewer.scene.primitives.add(primitive);
volumes.add(primitive);
return primitive;
},
removeVolume(primitive) {
if (volumes.delete(primitive)) viewer.scene.primitives.remove(primitive);
},
focus(record, duration) {
viewer.camera.flyToBoundingSphere(
new Cesium.BoundingSphere(
record.position,
Math.max(40, record.camera.rangeM * 0.36),
),
{
offset: new Cesium.HeadingPitchRange(
geo.math.toRadians(record.camera.headingDeg),
geo.math.toRadians(-22),
Math.max(280, record.camera.rangeM * 1.18),
),
duration: Math.max(0.2, duration || 0),
easingFunction: Cesium.EasingFunction.CUBIC_IN_OUT,
},
);
},
destroy() {
if (!viewer) return;
services.credits?.hideOsmCredit?.(viewer, 'cctv');
for (const remove of listeners) remove();
for (const gizmo of gizmos) gizmo.destroy();
gizmos.clear();
for (const entity of entities) removeEntity(entity);
for (const volume of volumes) viewer.scene.primitives.remove(volume);
volumes.clear();
if (billboards) {
services.sprites.unregisterSpriteCollection?.('cctv', billboards);
viewer.scene.primitives.remove(billboards);
}
viewer = billboards = activeTileset = null;
},
};
}
export function bindCctvWorldClickGesture(handler, onClick, options = {}) {
bindTrackingClickGesture(
handler,
(click, gesture) => {
if (!isTrackingClickGesture(gesture)) return;
onClick(click);
},
options,
);
}
+158
View File
@@ -0,0 +1,158 @@
import assert from 'node:assert/strict';
import { test } from 'node:test';
import * as Cesium from 'cesium';
import { createCctvCesiumRenderer } from './cesium.js';
import { viewshedColors } from '../../../data/cctvViewshed.js';
function viewer() {
return {
entities: new Cesium.EntityCollection(),
scene: { primitives: new Cesium.PrimitiveCollection() },
camera: { moveStart: new Cesium.Event(), moveEnd: new Cesium.Event() },
isDestroyed: () => false,
};
}
function setup(t) {
const owner = viewer();
const sprites = [];
const state = { _recordById: new Map(), _projectionEntities: [] };
const renderer = createCctvCesiumRenderer({
state,
services: {
sprites: {
registerSpriteCollection: (...args) => sprites.push(['add', ...args]),
unregisterSpriteCollection: (...args) =>
sprites.push(['remove', ...args]),
},
},
});
renderer.attach(owner);
t.after(() => renderer.destroy());
const p = (x, y, z) => new Cesium.Cartesian3(x, y, z);
const positions = {
mount: p(6378137, 0, 10),
tl: p(6378137, 100, 40),
tr: p(6378137, 140, 40),
br: p(6378137, 140, 0),
bl: p(6378137, 100, 0),
capCenter: p(6378137, 120, 20),
};
return { owner, renderer, sprites, positions, state };
}
test('native CCTV releases only its original viewer resources and listeners', (t) => {
const h = setup(t);
const foreignViewer = viewer();
const foreign = foreignViewer.entities.add({ id: 'cctv-a-cap' });
const neighbor = h.owner.entities.add({ id: 'neighbor' });
const markers = h.renderer.createMarkers();
h.renderer.createMarker({ id: 'a' }, h.positions.mount);
h.renderer.createCoverage('a', h.positions);
const record = { camera: { id: 'a' }, frustumPositions: h.positions };
const volume = h.renderer.createVolume(record, viewshedColors(30).fill);
assert.equal(volume.allowPicking, false);
assert.equal(volume.asynchronous, false);
let moves = 0;
h.renderer.onMoveEnd(() => moves++);
h.owner.camera.moveEnd.raiseEvent();
assert.equal(moves, 1);
assert.throws(() => h.renderer.attach(foreignViewer), /already has an owner/);
h.renderer.destroy(foreignViewer);
h.renderer.destroy();
h.owner.camera.moveEnd.raiseEvent();
assert.equal(moves, 1);
assert.deepEqual(h.owner.entities.values, [neighbor]);
assert.equal(h.owner.scene.primitives.length, 0);
assert.equal(foreignViewer.entities.getById(foreign.id), foreign);
assert.deepEqual(h.sprites, [
['add', 'cctv', markers],
['remove', 'cctv', markers],
]);
});
test('coverage construction rolls back partial entities and can retry', (t) => {
const h = setup(t);
const collision = h.owner.entities.add({ id: 'cctv-a-ray-br' });
assert.throws(() => h.renderer.createCoverage('a', h.positions));
assert.deepEqual(h.owner.entities.values, [collision]);
h.owner.entities.remove(collision);
const lines = h.renderer.createCoverage('a', h.positions);
assert.equal(lines.length, 5);
assert.deepEqual(
lines.map((line) => line._coverageRole),
['edge', 'edge', 'edge', 'edge', 'cap'],
);
});
test('replaced native entity identities survive CCTV teardown', (t) => {
const h = setup(t);
const [line] = h.renderer.createCoverage('a', h.positions);
h.owner.entities.remove(line);
const replacement = h.owner.entities.add({ id: line.id });
h.renderer.destroy();
assert.deepEqual(h.owner.entities.values, [replacement]);
});
test('native materials convert portable colours and keep depth-fail and dash policy', (t) => {
const h = setup(t);
const [line] = h.renderer.createCoverage('a', h.positions);
const tint = viewshedColors(210).line;
h.renderer.styleLine(line, {
visible: true,
width: 1.8,
tint,
dashed: true,
depthFail: tint.withAlpha(0.18),
});
const now = Cesium.JulianDate.now();
assert.equal(line.polyline.material.getType(now), 'PolylineDash');
assert.ok(
Cesium.Color.equals(line.polyline.material.getValue(now).color, tint),
);
assert.equal(line.polyline.depthFailMaterial.getValue(now).color.alpha, 0.18);
h.renderer.styleLine(line, {
visible: false,
width: 0.9,
tint,
dashed: false,
});
assert.equal(line.show, false);
assert.equal(line.polyline.material.getType(now), 'Color');
assert.equal(line.polyline.depthFailMaterial, undefined);
});
test('obstruction queries include the owned marker set and enforce finite range', (t) => {
const h = setup(t);
const markers = h.renderer.createMarkers();
const exclude = [{}];
let query;
h.owner.scene.pickFromRay = (ray, exclusions) => {
query = { ray, exclusions };
return {
position: Cesium.Cartesian3.add(
ray.origin,
new Cesium.Cartesian3(0, 20, 0),
new Cesium.Cartesian3(),
),
};
};
assert.equal(
h.renderer.obstructionRay(
h.positions.mount,
Cesium.Cartesian3.UNIT_Y,
exclude,
10,
),
undefined,
);
assert.ok(
h.renderer.obstructionRay(
h.positions.mount,
Cesium.Cartesian3.UNIT_Y,
exclude,
30,
),
);
assert.deepEqual(query.exclusions, [markers, ...exclude]);
assert.ok(query.ray instanceof Cesium.Ray);
});
+45
View File
@@ -0,0 +1,45 @@
import * as Cesium from 'cesium';
import { frustumVolumeGeometryData } from '../../../data/cctvViewshed.js';
/**
* Builds the translucent frustum-volume primitive for one camera.
* Synchronous (6 triangles — cheaper than the async geometry pipeline's
* bookkeeping), unlit flat color, both faces visible (the viewer is routinely
* inside or behind a cone), never pickable (clicks fall through to the
* billboard/wireframe/plane, whose pick semantics are established).
* @param {Object} positions - frustumCartesians shape (see frustumVolumeGeometryData).
* @param {Cesium.Color} color - Per-camera fill color (already alpha'd).
* @returns {Cesium.Primitive}
*/
export function createFrustumVolumePrimitive(positions, color) {
const { positions: flat, indices } = frustumVolumeGeometryData(positions);
const geometry = new Cesium.Geometry({
attributes: {
position: new Cesium.GeometryAttribute({
componentDatatype: Cesium.ComponentDatatype.DOUBLE,
componentsPerAttribute: 3,
values: flat,
}),
},
indices,
primitiveType: Cesium.PrimitiveType.TRIANGLES,
boundingSphere: Cesium.BoundingSphere.fromVertices(Array.from(flat)),
});
return new Cesium.Primitive({
geometryInstances: new Cesium.GeometryInstance({
geometry,
attributes: {
color: Cesium.ColorGeometryInstanceAttribute.fromColor(color),
},
}),
appearance: new Cesium.PerInstanceColorAppearance({
flat: true,
translucent: true,
renderState: {
cull: { enabled: false },
},
}),
asynchronous: false,
allowPicking: false,
});
}