feat(cctv): seven camera packs, semantic labels, terrain-clear monitor planes (#433)

Seven contributed CCTV camera packs (Ontario 511, Fintraffic Finland, DriveBC, TxDOT Texas, Estonia Tallinn + Tarktee, Warendorf, Live Traffic NSW) on a fair per-pack catalog cap; semantic camera labels; monitor planes lifted clear of the terrain from a precomputed, bundled ground-height dataset. Default catalog 800 → 3,446 cameras. Full context in PR #433.

Co-authored-by: sendmebits <[email protected]>
Co-authored-by: avocadoAgent <[email protected]>
Co-authored-by: Alex Harvey <[email protected]>
Co-authored-by: Jason Meredith <[email protected]>
Co-authored-by: Daniel Smith <[email protected]>
Co-authored-by: Vladimir Sobolev <[email protected]>
Co-authored-by: Matthias Schneider <[email protected]>
Co-authored-by: Cyber Knight <[email protected]>
Co-authored-by: NovaSoft Australia <[email protected]>

src/data/cctvGroundHeights.test.mjs

@@ -0,0 +1,81 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  joinGroundHeights,
+  loadGroundHeights,
+} from '../../server/providers/cctv/groundHeights.js';
+import { poseHash } from './cctvFootprint.js';
+
+const source = (over = {}) => ({
+  id: 'cam-1',
+  lat: 30.2672,
+  lon: -97.7431,
+  headingDeg: 90,
+  pitchDeg: -24,
+  fovDeg: 56,
+  rangeM: 210,
+  mountHeightM: 12,
+  ...over,
+});
+
+test('a shipped entry attaches only while the nominal pose still matches', () => {
+  const s = source();
+  const entry = {
+    status: 'ok',
+    poseHash: poseHash(s),
+    mountGroundM: 151.2,
+    supports: { bl: 150.1, bm: 149.9, br: 155.5, tl: null, tm: 'x' },
+  };
+  const [joined] = joinGroundHeights([s], { 'cam-1': entry });
+  assert.deepEqual(joined.groundHeights, {
+    poseHash: entry.poseHash,
+    mountGroundM: 151.2,
+    supports: { bl: 150.1, bm: 149.9, br: 155.5 },
+  });
+
+  const moved = source({ lat: 30.2673 });
+  const [notJoined] = joinGroundHeights([moved], { 'cam-1': entry });
+  assert.equal(
+    notJoined.groundHeights,
+    undefined,
+    'a moved camera loses the shipped value',
+  );
+
+  const [missed] = joinGroundHeights([source()], {
+    'cam-1': { ...entry, status: 'miss', mountGroundM: null },
+  });
+  assert.equal(missed.groundHeights, undefined, 'a miss ships nothing');
+  assert.deepEqual(
+    joinGroundHeights([source()], null)[0].groundHeights,
+    undefined,
+  );
+});
+
+test('the sidecar loads from the source root and tolerates a missing or malformed file', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gev-heights-'));
+  fs.mkdirSync(
+    path.join(dir, 'src', 'data', 'local_data', 'cctv_ground_heights'),
+    {
+      recursive: true,
+    },
+  );
+  assert.deepEqual(loadGroundHeights(dir), {}, 'missing file');
+  const file = path.join(
+    dir,
+    'src',
+    'data',
+    'local_data',
+    'cctv_ground_heights',
+    'cctv_ground_heights.json',
+  );
+  fs.writeFileSync(file, '{not json');
+  assert.deepEqual(loadGroundHeights(dir), {}, 'malformed file');
+  fs.writeFileSync(
+    file,
+    JSON.stringify({ schemaVersion: 1, cameras: { a: { status: 'ok' } } }),
+  );
+  assert.deepEqual(loadGroundHeights(dir), { a: { status: 'ok' } });
+});