@blueharford/scrypted-spatial-awareness 0.6.32 → 0.6.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueharford/scrypted-spatial-awareness",
-  "version": "0.6.32",
+  "version": "0.6.33",
   "description": "Cross-camera object tracking for Scrypted NVR with spatial awareness",
   "author": "Joshua Seidel <blueharford>",
   "license": "Apache-2.0",
@@ -24,7 +24,8 @@
     "scrypted-debug": "node node_modules/@scrypted/sdk/bin/scrypted-debug.js",
     "scrypted-deploy": "node node_modules/@scrypted/sdk/bin/scrypted-deploy.js",
     "scrypted-readme": "node node_modules/@scrypted/sdk/bin/scrypted-readme.js",
-    "scrypted-package-json": "node node_modules/@scrypted/sdk/bin/scrypted-package-json.js"
+    "scrypted-package-json": "node node_modules/@scrypted/sdk/bin/scrypted-package-json.js",
+    "test": "node -r ts-node/register/transpile-only ./tests/run-tests.ts"
   },
   "keywords": [
     "scrypted",
@@ -54,6 +55,7 @@
   "devDependencies": {
     "@scrypted/common": "^1.0.0",
     "@types/node": "^20.11.0",
+    "ts-node": "^10.9.2",
     "typescript": "^5.3.0"
   }
 }

package/src/alerts/alert-manager.ts

@@ -3,7 +3,7 @@
  * Generates and dispatches alerts based on tracking events
  */
 
-import sdk, { Notifier, Camera, ScryptedInterface, MediaObject } from '@scrypted/sdk';
+import type { Notifier, Camera, MediaObject } from '@scrypted/sdk';
 import {
   Alert,
   AlertRule,
@@ -12,15 +12,31 @@ import {
   AlertCondition,
   createAlert,
   createDefaultRules,
+  generateAlertMessage,
 } from '../models/alert';
 import { TrackedObject, GlobalTrackingId } from '../models/tracked-object';
-
-const { systemManager, mediaManager } = sdk;
+import {
+  getActiveAlertKey,
+  hasMeaningfulAlertChange,
+  shouldSendUpdateNotification,
+} from './alert-utils';
+
+let sdkModule: typeof import('@scrypted/sdk') | null = null;
+const getSdk = async () => {
+  if (!sdkModule) {
+    sdkModule = await import('@scrypted/sdk');
+  }
+  return sdkModule;
+};
 
 export class AlertManager {
   private rules: AlertRule[] = [];
   private recentAlerts: Alert[] = [];
   private cooldowns: Map<string, number> = new Map();
+  private activeAlerts: Map<string, { alert: Alert; lastUpdate: number; lastNotified: number }> = new Map();
+  private readonly activeAlertTtlMs: number = 10 * 60 * 1000;
+  private notifyOnUpdates: boolean = false;
+  private updateNotificationCooldownMs: number = 60000;
   private console: Console;
   private storage: Storage;
   private maxAlerts: number = 100;
@@ -37,7 +53,8 @@ export class AlertManager {
   async checkAndAlert(
     type: AlertType,
     tracked: TrackedObject,
-    details: Partial<AlertDetails>
+    details: Partial<AlertDetails>,
+    mediaObjectOverride?: MediaObject
   ): Promise<Alert | null> {
     // Find matching rule
     const rule = this.rules.find(r => r.type === type && r.enabled);
@@ -57,15 +74,21 @@ export class AlertManager {
       }
     }
 
-    // Check cooldown
-    const cooldownKey = `${rule.id}:${tracked.globalId}`;
-    const lastAlert = this.cooldowns.get(cooldownKey) || 0;
-    if (rule.cooldown > 0 && Date.now() - lastAlert < rule.cooldown) {
+    // Check conditions
+    if (!this.evaluateConditions(rule.conditions, tracked)) {
       return null;
     }
 
-    // Check conditions
-    if (!this.evaluateConditions(rule.conditions, tracked)) {
+    // Update existing movement alert if active (prevents alert spam)
+    if (type === 'movement') {
+      const updated = await this.updateActiveAlert(type, rule.id, tracked, details);
+      if (updated) return updated;
+    }
+
+    // Check cooldown (only for new alerts)
+    const cooldownKey = `${rule.id}:${tracked.globalId}`;
+    const lastAlert = this.cooldowns.get(cooldownKey) || 0;
+    if (rule.cooldown > 0 && Date.now() - lastAlert < rule.cooldown) {
       return null;
     }
 
@@ -91,21 +114,59 @@ export class AlertManager {
       this.recentAlerts.pop();
     }
 
+    if (type === 'movement') {
+      const key = getActiveAlertKey(type, rule.id, tracked.globalId);
+      this.activeAlerts.set(key, { alert, lastUpdate: Date.now(), lastNotified: alert.timestamp });
+    }
+
     // Update cooldown
     this.cooldowns.set(cooldownKey, Date.now());
 
     // Send notifications
-    await this.sendNotifications(alert, rule);
+    await this.sendNotifications(alert, rule, mediaObjectOverride);
 
     this.console.log(`Alert generated: [${alert.severity}] ${alert.message}`);
 
     return alert;
   }
 
+  async updateMovementAlert(
+    tracked: TrackedObject,
+    details: Partial<AlertDetails>
+  ): Promise<Alert | null> {
+    const rule = this.rules.find(r => r.type === 'movement' && r.enabled);
+    if (!rule) return null;
+
+    if (rule.objectClasses && rule.objectClasses.length > 0) {
+      if (!rule.objectClasses.includes(tracked.className)) {
+        return null;
+      }
+    }
+
+    if (rule.cameraIds && rule.cameraIds.length > 0 && details.cameraId) {
+      if (!rule.cameraIds.includes(details.cameraId)) {
+        return null;
+      }
+    }
+
+    if (!this.evaluateConditions(rule.conditions, tracked)) {
+      return null;
+    }
+
+    return this.updateActiveAlert('movement', rule.id, tracked, details);
+  }
+
   /**
    * Send notifications for an alert
    */
-  private async sendNotifications(alert: Alert, rule: AlertRule): Promise<void> {
+  private async sendNotifications(
+    alert: Alert,
+    rule: AlertRule,
+    mediaObjectOverride?: MediaObject
+  ): Promise<void> {
+    const sdkModule = await getSdk();
+    const { ScryptedInterface } = sdkModule;
+    const { systemManager } = sdkModule.default;
     const notifierIds = rule.notifiers.length > 0
       ? rule.notifiers
       : this.getDefaultNotifiers();
@@ -119,16 +180,18 @@ export class AlertManager {
     }
 
     // Try to get a thumbnail from the camera
-    let mediaObject: MediaObject | undefined;
-    const cameraId = alert.details.toCameraId || alert.details.cameraId;
-    if (cameraId) {
-      try {
-        const camera = systemManager.getDeviceById<Camera>(cameraId);
-        if (camera && camera.interfaces?.includes(ScryptedInterface.Camera)) {
-          mediaObject = await camera.takePicture();
+    let mediaObject: MediaObject | undefined = mediaObjectOverride;
+    if (!mediaObject) {
+      const cameraId = alert.details.toCameraId || alert.details.cameraId;
+      if (cameraId) {
+        try {
+          const camera = systemManager.getDeviceById<Camera>(cameraId);
+          if (camera && camera.interfaces?.includes(ScryptedInterface.Camera)) {
+            mediaObject = await camera.takePicture();
+          }
+        } catch (e) {
+          this.console.warn(`Failed to get thumbnail from camera ${cameraId}:`, e);
         }
-      } catch (e) {
-        this.console.warn(`Failed to get thumbnail from camera ${cameraId}:`, e);
       }
     }
 
@@ -161,6 +224,71 @@ export class AlertManager {
     }
   }
 
+  clearActiveAlertsForObject(globalId: GlobalTrackingId): void {
+    for (const [key, entry] of this.activeAlerts.entries()) {
+      if (entry.alert.trackedObjectId === globalId) {
+        this.activeAlerts.delete(key);
+      }
+    }
+  }
+
+  setUpdateNotificationOptions(enabled: boolean, cooldownMs: number): void {
+    this.notifyOnUpdates = enabled;
+    this.updateNotificationCooldownMs = Math.max(0, cooldownMs);
+  }
+
+  private async updateActiveAlert(
+    type: AlertType,
+    ruleId: string,
+    tracked: TrackedObject,
+    details: Partial<AlertDetails>
+  ): Promise<Alert | null> {
+    const key = getActiveAlertKey(type, ruleId, tracked.globalId);
+    const existing = this.activeAlerts.get(key);
+    if (!existing) return null;
+
+    const now = Date.now();
+    if (now - existing.lastUpdate > this.activeAlertTtlMs) {
+      this.activeAlerts.delete(key);
+      return null;
+    }
+
+    const updatedDetails: AlertDetails = {
+      ...existing.alert.details,
+      ...details,
+      objectClass: tracked.className,
+      objectLabel: details.objectLabel || tracked.label,
+    };
+
+    const shouldUpdate = hasMeaningfulAlertChange(existing.alert.details, updatedDetails);
+    if (!shouldUpdate) return existing.alert;
+
+    existing.alert.details = updatedDetails;
+    existing.alert.message = generateAlertMessage(type, updatedDetails);
+    existing.alert.timestamp = now;
+    existing.lastUpdate = now;
+
+    const idx = this.recentAlerts.findIndex(a => a.id === existing.alert.id);
+    if (idx >= 0) {
+      this.recentAlerts.splice(idx, 1);
+    }
+    this.recentAlerts.unshift(existing.alert);
+    if (this.recentAlerts.length > this.maxAlerts) {
+      this.recentAlerts.pop();
+    }
+
+    if (this.notifyOnUpdates) {
+      const rule = this.rules.find(r => r.id === ruleId);
+      if (rule && shouldSendUpdateNotification(this.notifyOnUpdates, existing.lastNotified, now, this.updateNotificationCooldownMs)) {
+        existing.lastNotified = now;
+        await this.sendNotifications(existing.alert, rule);
+      }
+    }
+
+    return existing.alert;
+  }
+
+
   /**
    * Get notification title based on alert type
    * For movement alerts with LLM descriptions, use the smart description as title

package/src/alerts/alert-utils.ts

@@ -0,0 +1,32 @@
+import { AlertDetails, AlertType } from '../models/alert';
+import { GlobalTrackingId } from '../models/tracked-object';
+
+export function hasMeaningfulAlertChange(prev: AlertDetails, next: AlertDetails): boolean {
+  return (
+    prev.fromCameraId !== next.fromCameraId ||
+    prev.toCameraId !== next.toCameraId ||
+    prev.cameraId !== next.cameraId ||
+    prev.objectLabel !== next.objectLabel ||
+    prev.pathDescription !== next.pathDescription ||
+    JSON.stringify(prev.involvedLandmarks || []) !== JSON.stringify(next.involvedLandmarks || [])
+  );
+}
+
+export function getActiveAlertKey(
+  type: AlertType,
+  ruleId: string,
+  trackedId: GlobalTrackingId
+): string {
+  return `${type}:${ruleId}:${trackedId}`;
+}
+
+export function shouldSendUpdateNotification(
+  enabled: boolean,
+  lastNotified: number,
+  now: number,
+  cooldownMs: number
+): boolean {
+  if (!enabled) return false;
+  if (cooldownMs <= 0) return true;
+  return now - lastNotified >= cooldownMs;
+}

package/src/core/tracking-engine.ts

@@ -61,6 +61,8 @@ export interface TrackingEngineConfig {
   loiteringThreshold: number;
   /** Per-object alert cooldown (ms) */
   objectAlertCooldown: number;
+  /** Minimum detection score to consider */
+  minDetectionScore: number;
   /** Use LLM for enhanced descriptions */
   useLlmDescriptions: boolean;
   /** Specific LLM device IDs to use (if not set, auto-discovers all for load balancing) */
@@ -112,7 +114,9 @@ export class TrackingEngine {
   private spatialReasoning: SpatialReasoningEngine;
   private listeners: Map<string, EventListenerRegister> = new Map();
   private pendingTimers: Map<GlobalTrackingId, NodeJS.Timeout> = new Map();
+  private loiteringTimers: Map<GlobalTrackingId, NodeJS.Timeout> = new Map();
   private lostCheckInterval: NodeJS.Timeout | null = null;
+  private cleanupInterval: NodeJS.Timeout | null = null;
   /** Track last alert time per object to enforce cooldown */
   private objectLastAlertTime: Map<GlobalTrackingId, number> = new Map();
   /** Callback for topology changes (e.g., landmark suggestions) */
@@ -215,6 +219,10 @@ export class TrackingEngine {
       this.checkForLostObjects();
     }, 30000); // Check every 30 seconds
 
+    this.cleanupInterval = setInterval(() => {
+      this.state.cleanup();
+    }, 300000); // Cleanup every 5 minutes
+
     this.console.log(`Tracking engine started with ${this.listeners.size} cameras`);
   }
 
@@ -236,12 +244,22 @@ export class TrackingEngine {
     }
     this.pendingTimers.clear();
 
+    for (const timer of this.loiteringTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.loiteringTimers.clear();
+
     // Stop lost check interval
     if (this.lostCheckInterval) {
       clearInterval(this.lostCheckInterval);
       this.lostCheckInterval = null;
     }
 
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+
     this.console.log('Tracking engine stopped');
   }
 
@@ -264,7 +282,7 @@ export class TrackingEngine {
 
     for (const detection of detected.detections) {
       // Skip low-confidence detections
-      if (detection.score < 0.5) continue;
+      if (detection.score < this.config.minDetectionScore) continue;
 
       // If in training mode, record trainer detections
       if (this.isTrainingActive() && detection.className === 'person') {
@@ -358,6 +376,15 @@ export class TrackingEngine {
     const fallbackTimeout = this.config.llmFallbackTimeout ?? 3000;
 
     try {
+      if (!this.config.useLlmDescriptions) {
+        return this.spatialReasoning.generateMovementDescription(
+          tracked,
+          fromCameraId,
+          toCameraId,
+          transitTime
+        );
+      }
+
       // Check rate limiting - if not allowed, return null to use basic description
       if (!this.tryLlmCall()) {
         this.console.log('[Movement] LLM rate-limited, using basic notification');
@@ -366,11 +393,9 @@ export class TrackingEngine {
 
       // Get snapshot from camera for LLM analysis (if LLM is enabled)
       let mediaObject: MediaObject | undefined;
-      if (this.config.useLlmDescriptions) {
-        const camera = systemManager.getDeviceById<Camera>(currentCameraId);
-        if (camera?.interfaces?.includes(ScryptedInterface.Camera)) {
-          mediaObject = await camera.takePicture();
-        }
+      const camera = systemManager.getDeviceById<Camera>(currentCameraId);
+      if (camera?.interfaces?.includes(ScryptedInterface.Camera)) {
+        mediaObject = await camera.takePicture();
       }
 
       // Use spatial reasoning engine for rich context-aware description
@@ -460,6 +485,8 @@ export class TrackingEngine {
       // Check if this is a cross-camera transition
       const lastSighting = getLastSighting(tracked);
       if (lastSighting && lastSighting.cameraId !== sighting.cameraId) {
+        // Cancel any pending loitering alert if object already transitioned
+        this.clearLoiteringTimer(tracked.globalId);
         const transitDuration = sighting.timestamp - lastSighting.timestamp;
 
         // Update cached snapshot from new camera (object is now visible here)
@@ -491,33 +518,57 @@ export class TrackingEngine {
         );
 
         // Check loitering threshold and per-object cooldown before alerting
-        if (this.passesLoiteringThreshold(tracked) && !this.isInAlertCooldown(tracked.globalId)) {
-          // Get spatial reasoning result with RAG context
-          const spatialResult = await this.getSpatialDescription(
-            tracked,
-            lastSighting.cameraId,
-            sighting.cameraId,
-            transitDuration,
-            sighting.cameraId
-          );
-
-          // Generate movement alert for cross-camera transition
-          await this.alertManager.checkAndAlert('movement', tracked, {
-            fromCameraId: lastSighting.cameraId,
-            fromCameraName: lastSighting.cameraName,
-            toCameraId: sighting.cameraId,
-            toCameraName: sighting.cameraName,
-            transitTime: transitDuration,
-            objectClass: sighting.detection.className,
-            objectLabel: spatialResult?.description || sighting.detection.label,
-            detectionId: sighting.detectionId,
-            // Include spatial context for enriched alerts
-            pathDescription: spatialResult?.pathDescription,
-            involvedLandmarks: spatialResult?.involvedLandmarks?.map(l => l.name),
-            usedLlm: spatialResult?.usedLlm,
-          });
-
-          this.recordAlertTime(tracked.globalId);
+        if (this.passesLoiteringThreshold(tracked)) {
+          if (this.isInAlertCooldown(tracked.globalId)) {
+            const spatialResult = await this.spatialReasoning.generateMovementDescription(
+              tracked,
+              lastSighting.cameraId,
+              sighting.cameraId,
+              transitDuration
+            );
+
+            await this.alertManager.updateMovementAlert(tracked, {
+              fromCameraId: lastSighting.cameraId,
+              fromCameraName: lastSighting.cameraName,
+              toCameraId: sighting.cameraId,
+              toCameraName: sighting.cameraName,
+              transitTime: transitDuration,
+              objectClass: sighting.detection.className,
+              objectLabel: spatialResult.description || sighting.detection.label,
+              detectionId: sighting.detectionId,
+              pathDescription: spatialResult.pathDescription,
+              involvedLandmarks: spatialResult.involvedLandmarks?.map(l => l.name),
+              usedLlm: spatialResult.usedLlm,
+            });
+          } else {
+            // Get spatial reasoning result with RAG context
+            const spatialResult = await this.getSpatialDescription(
+              tracked,
+              lastSighting.cameraId,
+              sighting.cameraId,
+              transitDuration,
+              sighting.cameraId
+            );
+
+            // Generate movement alert for cross-camera transition
+            const mediaObject = this.snapshotCache.get(tracked.globalId);
+            await this.alertManager.checkAndAlert('movement', tracked, {
+              fromCameraId: lastSighting.cameraId,
+              fromCameraName: lastSighting.cameraName,
+              toCameraId: sighting.cameraId,
+              toCameraName: sighting.cameraName,
+              transitTime: transitDuration,
+              objectClass: sighting.detection.className,
+              objectLabel: spatialResult?.description || sighting.detection.label,
+              detectionId: sighting.detectionId,
+              // Include spatial context for enriched alerts
+              pathDescription: spatialResult?.pathDescription,
+              involvedLandmarks: spatialResult?.involvedLandmarks?.map(l => l.name),
+              usedLlm: spatialResult?.usedLlm,
+            }, mediaObject);
+
+            this.recordAlertTime(tracked.globalId);
+          }
         }
       }
 
@@ -569,18 +620,49 @@ export class TrackingEngine {
     }
 
     // Check after loitering threshold if object is still being tracked
-    setTimeout(async () => {
-      const tracked = this.state.getObject(globalId);
-      if (!tracked || tracked.state !== 'active') return;
+    const existing = this.loiteringTimers.get(globalId);
+    if (existing) {
+      clearTimeout(existing);
+      this.loiteringTimers.delete(globalId);
+    }
+
+    const timer = setTimeout(async () => {
+      try {
+        const tracked = this.state.getObject(globalId);
+        if (!tracked || tracked.state !== 'active') return;
 
-      // Check if we've already alerted for this object
-      if (this.isInAlertCooldown(globalId)) return;
+        const lastSighting = getLastSighting(tracked);
+        if (!lastSighting || lastSighting.cameraId !== sighting.cameraId) {
+          return;
+        }
+
+        const maxStaleMs = Math.max(10000, this.config.loiteringThreshold * 2);
+        if (Date.now() - lastSighting.timestamp > maxStaleMs) {
+          return;
+        }
+
+        // Check if we've already alerted for this object
+        if (this.isInAlertCooldown(globalId)) {
+          const spatialResult = await this.spatialReasoning.generateEntryDescription(tracked, sighting.cameraId);
+          await this.alertManager.updateMovementAlert(tracked, {
+            cameraId: sighting.cameraId,
+            cameraName: sighting.cameraName,
+            toCameraId: sighting.cameraId,
+            toCameraName: sighting.cameraName,
+            objectClass: sighting.detection.className,
+            objectLabel: spatialResult.description,
+            detectionId: sighting.detectionId,
+            involvedLandmarks: spatialResult.involvedLandmarks?.map(l => l.name),
+            usedLlm: spatialResult.usedLlm,
+          });
+          return;
+        }
 
       // Use prefetched LLM result if available (started when snapshot was captured)
       let spatialResult: SpatialReasoningResult;
       const pendingDescription = this.pendingDescriptions.get(globalId);
 
-      if (pendingDescription) {
+        if (pendingDescription) {
         this.console.log(`[Entry Alert] Using prefetched LLM result for ${globalId.slice(0, 8)}`);
         try {
           spatialResult = await pendingDescription;
@@ -591,7 +673,7 @@ export class TrackingEngine {
           spatialResult = await this.spatialReasoning.generateEntryDescription(tracked, sighting.cameraId);
         }
         this.pendingDescriptions.delete(globalId);
-      } else {
+        } else {
         // No prefetch available - only call LLM if rate limit allows
         if (this.tryLlmCall()) {
           this.console.log(`[Entry Alert] No prefetch, generating with LLM`);
@@ -607,7 +689,8 @@ export class TrackingEngine {
 
       // Always use movement alert type for smart notifications with LLM descriptions
       // The property_entry/property_exit types are legacy and disabled by default
-      await this.alertManager.checkAndAlert('movement', tracked, {
+        const mediaObject = this.snapshotCache.get(globalId);
+        await this.alertManager.checkAndAlert('movement', tracked, {
         cameraId: sighting.cameraId,
         cameraName: sighting.cameraName,
         toCameraId: sighting.cameraId,
@@ -617,10 +700,15 @@ export class TrackingEngine {
         detectionId: sighting.detectionId,
         involvedLandmarks: spatialResult.involvedLandmarks?.map(l => l.name),
         usedLlm: spatialResult.usedLlm,
-      });
+        }, mediaObject);
 
-      this.recordAlertTime(globalId);
+        this.recordAlertTime(globalId);
+      } finally {
+        this.loiteringTimers.delete(globalId);
+      }
     }, this.config.loiteringThreshold);
+
+    this.loiteringTimers.set(globalId, timer);
   }
 
   /** Capture and cache a snapshot for a tracked object, and start LLM analysis immediately */
@@ -712,6 +800,9 @@ export class TrackingEngine {
     // Mark as pending and set timer
     this.state.markPending(tracked.globalId);
 
+    // Cancel any pending loitering alert
+    this.clearLoiteringTimer(tracked.globalId);
+
     // Capture a fresh snapshot now while object is still visible (before they leave)
     // Also starts LLM analysis immediately in parallel
     if (this.config.useLlmDescriptions) {
@@ -756,6 +847,7 @@ export class TrackingEngine {
         }
 
         // Use movement alert for exit too - smart notifications with LLM descriptions
+        const mediaObject = this.snapshotCache.get(tracked.globalId);
         await this.alertManager.checkAndAlert('movement', current, {
           cameraId: sighting.cameraId,
           cameraName: sighting.cameraName,
@@ -765,7 +857,9 @@ export class TrackingEngine {
           objectLabel: spatialResult.description,
           involvedLandmarks: spatialResult.involvedLandmarks?.map(l => l.name),
           usedLlm: spatialResult.usedLlm,
-        });
+        }, mediaObject);
+
+        this.alertManager.clearActiveAlertsForObject(tracked.globalId);
 
         // Clean up cached snapshot and pending descriptions after exit alert
         this.snapshotCache.delete(tracked.globalId);
@@ -787,6 +881,7 @@ export class TrackingEngine {
 
       if (timeSinceSeen > this.config.lostTimeout) {
         this.state.markLost(tracked.globalId);
+        this.clearLoiteringTimer(tracked.globalId);
         this.console.log(
           `Object ${tracked.globalId.slice(0, 8)} marked as lost ` +
           `(not seen for ${Math.round(timeSinceSeen / 1000)}s)`
@@ -800,10 +895,21 @@ export class TrackingEngine {
           objectClass: tracked.className,
           objectLabel: tracked.label,
         });
+
+        this.alertManager.clearActiveAlertsForObject(tracked.globalId);
       }
     }
   }
 
+  /** Clear a pending loitering timer if present */
+  private clearLoiteringTimer(globalId: GlobalTrackingId): void {
+    const timer = this.loiteringTimers.get(globalId);
+    if (timer) {
+      clearTimeout(timer);
+      this.loiteringTimers.delete(globalId);
+    }
+  }
+
   /** Update topology configuration */
   updateTopology(topology: CameraTopology): void {
     this.topology = topology;