@blueharford/scrypted-spatial-awareness 0.1.0

package/src/models/alert.ts

@@ -0,0 +1,229 @@
+/**
+ * Alert Models
+ * Defines alerts and notification rules for tracking events
+ */
+
+import { GlobalTrackingId, ObjectClass } from './tracked-object';
+
+/** Alert severity levels */
+export type AlertSeverity = 'info' | 'warning' | 'critical';
+
+/** Types of alerts the system can generate */
+export type AlertType =
+  | 'property_entry'
+  | 'property_exit'
+  | 'unusual_path'
+  | 'dwell_time'
+  | 'restricted_zone'
+  | 'lost_tracking'
+  | 'reappearance'
+  | 'zone_entry'
+  | 'zone_exit';
+
+/** Alert condition operators */
+export type AlertOperator = 'equals' | 'not_equals' | 'contains' | 'greater_than' | 'less_than';
+
+/** An alert generated by the system */
+export interface Alert {
+  /** Unique alert ID */
+  id: string;
+  /** Type of alert */
+  type: AlertType;
+  /** Severity level */
+  severity: AlertSeverity;
+  /** Timestamp when alert was generated */
+  timestamp: number;
+  /** ID of the tracked object that triggered this alert */
+  trackedObjectId: GlobalTrackingId;
+  /** Human-readable message */
+  message: string;
+  /** Additional details */
+  details: AlertDetails;
+  /** Whether the alert has been acknowledged */
+  acknowledged: boolean;
+  /** Rule ID that generated this alert (if any) */
+  ruleId?: string;
+}
+
+/** Additional details for an alert */
+export interface AlertDetails {
+  /** Camera device ID */
+  cameraId?: string;
+  /** Camera display name */
+  cameraName?: string;
+  /** Zone name (for zone-related alerts) */
+  zoneName?: string;
+  /** Dwell time in milliseconds (for dwell alerts) */
+  dwellTime?: number;
+  /** Expected path (for unusual path alerts) */
+  expectedPath?: string;
+  /** Actual path taken */
+  actualPath?: string;
+  /** Detection ID for thumbnail */
+  detectionId?: string;
+  /** Object class */
+  objectClass?: ObjectClass;
+  /** Object label (if recognized) */
+  objectLabel?: string;
+  /** Thumbnail image URL or data */
+  thumbnailUrl?: string;
+}
+
+/** A condition for alert rules */
+export interface AlertCondition {
+  /** Field path to evaluate (e.g., "className", "label", "totalDwellTime") */
+  field: string;
+  /** Comparison operator */
+  operator: AlertOperator;
+  /** Value to compare against */
+  value: string | number | boolean;
+}
+
+/** Alert rule configuration */
+export interface AlertRule {
+  /** Unique rule ID */
+  id: string;
+  /** Rule display name */
+  name: string;
+  /** Whether the rule is enabled */
+  enabled: boolean;
+  /** Alert type this rule generates */
+  type: AlertType;
+  /** Conditions that must be met */
+  conditions: AlertCondition[];
+  /** Severity of alerts generated */
+  severity: AlertSeverity;
+  /** Scrypted Notifier device IDs to send alerts to */
+  notifiers: string[];
+  /** Minimum time between repeat alerts (cooldown) in milliseconds */
+  cooldown: number;
+  /** Object classes this rule applies to (empty = all) */
+  objectClasses?: ObjectClass[];
+  /** Specific cameras this rule applies to (empty = all) */
+  cameraIds?: string[];
+  /** Specific zones this rule applies to (empty = all) */
+  zoneIds?: string[];
+}
+
+/** Creates default alert rules */
+export function createDefaultRules(): AlertRule[] {
+  return [
+    {
+      id: 'property-entry',
+      name: 'Property Entry',
+      enabled: true,
+      type: 'property_entry',
+      conditions: [],
+      severity: 'info',
+      notifiers: [],
+      cooldown: 300000, // 5 minutes
+    },
+    {
+      id: 'property-exit',
+      name: 'Property Exit',
+      enabled: true,
+      type: 'property_exit',
+      conditions: [],
+      severity: 'info',
+      notifiers: [],
+      cooldown: 300000,
+    },
+    {
+      id: 'unusual-path',
+      name: 'Unusual Path Detected',
+      enabled: true,
+      type: 'unusual_path',
+      conditions: [],
+      severity: 'warning',
+      notifiers: [],
+      cooldown: 600000, // 10 minutes
+    },
+    {
+      id: 'dwell-time',
+      name: 'Extended Dwell Time',
+      enabled: true,
+      type: 'dwell_time',
+      conditions: [
+        { field: 'totalDwellTime', operator: 'greater_than', value: 300000 } // 5 minutes
+      ],
+      severity: 'warning',
+      notifiers: [],
+      cooldown: 600000,
+    },
+    {
+      id: 'restricted-zone',
+      name: 'Restricted Zone Entry',
+      enabled: true,
+      type: 'restricted_zone',
+      conditions: [],
+      severity: 'critical',
+      notifiers: [],
+      cooldown: 0, // Always alert immediately
+    },
+    {
+      id: 'lost-tracking',
+      name: 'Lost Object Tracking',
+      enabled: false, // Disabled by default (can be noisy)
+      type: 'lost_tracking',
+      conditions: [],
+      severity: 'info',
+      notifiers: [],
+      cooldown: 300000,
+    },
+  ];
+}
+
+/** Generates a human-readable message for an alert */
+export function generateAlertMessage(
+  type: AlertType,
+  details: AlertDetails
+): string {
+  const objectDesc = details.objectLabel
+    ? `${details.objectClass} (${details.objectLabel})`
+    : details.objectClass || 'Object';
+
+  switch (type) {
+    case 'property_entry':
+      return `${objectDesc} entered property via ${details.cameraName || 'unknown camera'}`;
+    case 'property_exit':
+      return `${objectDesc} exited property via ${details.cameraName || 'unknown camera'}`;
+    case 'unusual_path':
+      return `${objectDesc} took unusual path: ${details.actualPath || 'unknown'}`;
+    case 'dwell_time':
+      const dwellMinutes = Math.round((details.dwellTime || 0) / 60000);
+      return `${objectDesc} has been present for ${dwellMinutes} minutes in ${details.zoneName || details.cameraName || 'area'}`;
+    case 'restricted_zone':
+      return `${objectDesc} entered restricted zone: ${details.zoneName}`;
+    case 'lost_tracking':
+      return `Lost tracking of ${objectDesc} near ${details.cameraName || 'unknown location'}`;
+    case 'reappearance':
+      return `${objectDesc} reappeared on ${details.cameraName}`;
+    case 'zone_entry':
+      return `${objectDesc} entered ${details.zoneName}`;
+    case 'zone_exit':
+      return `${objectDesc} exited ${details.zoneName}`;
+    default:
+      return `Tracking event: ${type}`;
+  }
+}
+
+/** Creates an alert instance */
+export function createAlert(
+  type: AlertType,
+  trackedObjectId: GlobalTrackingId,
+  details: AlertDetails,
+  severity: AlertSeverity = 'info',
+  ruleId?: string
+): Alert {
+  return {
+    id: `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+    type,
+    severity,
+    timestamp: Date.now(),
+    trackedObjectId,
+    message: generateAlertMessage(type, details),
+    details,
+    acknowledged: false,
+    ruleId,
+  };
+}

package/src/models/topology.ts

@@ -0,0 +1,168 @@
+/**
+ * Camera Topology Models
+ * Defines the spatial relationships between cameras in the NVR system
+ */
+
+/** A point in 2D space (normalized 0-100 or pixel coordinates) */
+export type Point = [number, number];
+
+/** A polygon path defined by an array of points */
+export type ClipPath = Point[];
+
+/** Position on a floor plan */
+export interface FloorPlanPosition {
+  x: number;
+  y: number;
+}
+
+/** Camera field of view configuration */
+export interface CameraFOV {
+  /** FOV angle in degrees */
+  angle: number;
+  /** Direction the camera faces in degrees from north (0 = north, 90 = east) */
+  direction: number;
+}
+
+/** Transit time configuration between cameras */
+export interface TransitTime {
+  /** Minimum expected transit time in milliseconds */
+  min: number;
+  /** Typical/average transit time in milliseconds */
+  typical: number;
+  /** Maximum expected transit time in milliseconds */
+  max: number;
+}
+
+/** Represents a camera in the topology */
+export interface CameraNode {
+  /** Scrypted device ID */
+  deviceId: string;
+  /** Native ID for plugin reference */
+  nativeId: string;
+  /** Display name */
+  name: string;
+  /** Position on floor plan (optional) */
+  floorPlanPosition?: FloorPlanPosition;
+  /** Camera field of view configuration (optional) */
+  fov?: CameraFOV;
+  /** Is this an entry point to the property */
+  isEntryPoint: boolean;
+  /** Is this an exit point from the property */
+  isExitPoint: boolean;
+  /** Detection classes to track on this camera */
+  trackClasses: string[];
+}
+
+/** Represents a connection between two cameras */
+export interface CameraConnection {
+  /** Unique identifier for this connection */
+  id: string;
+  /** Source camera device ID */
+  fromCameraId: string;
+  /** Target camera device ID */
+  toCameraId: string;
+  /** Exit zone in source camera (normalized coordinates 0-100) */
+  exitZone: ClipPath;
+  /** Entry zone in target camera (normalized coordinates 0-100) */
+  entryZone: ClipPath;
+  /** Expected transit time configuration */
+  transitTime: TransitTime;
+  /** Whether this connection works both ways */
+  bidirectional: boolean;
+  /** Human-readable path name (e.g., "Driveway to Front Door") */
+  name: string;
+}
+
+/** Zone type for alerting purposes */
+export type GlobalZoneType = 'entry' | 'exit' | 'dwell' | 'restricted';
+
+/** A zone that spans multiple cameras */
+export interface GlobalZone {
+  /** Unique identifier */
+  id: string;
+  /** Display name */
+  name: string;
+  /** Zone type for alerting */
+  type: GlobalZoneType;
+  /** Camera zones that comprise this global zone */
+  cameraZones: CameraZoneMapping[];
+}
+
+/** Maps a zone to a specific camera */
+export interface CameraZoneMapping {
+  /** Camera device ID */
+  cameraId: string;
+  /** Zone polygon on this camera */
+  zone: ClipPath;
+}
+
+/** Floor plan image configuration */
+export interface FloorPlanConfig {
+  /** Base64 encoded image data or URL */
+  imageData?: string;
+  /** Image width in pixels */
+  width: number;
+  /** Image height in pixels */
+  height: number;
+  /** Scale factor (pixels per real-world unit) */
+  scale?: number;
+}
+
+/** Complete camera topology configuration */
+export interface CameraTopology {
+  /** Version for migration support */
+  version: string;
+  /** All cameras in the system */
+  cameras: CameraNode[];
+  /** Connections between cameras */
+  connections: CameraConnection[];
+  /** Named zones spanning multiple cameras */
+  globalZones: GlobalZone[];
+  /** Floor plan configuration (optional) */
+  floorPlan?: FloorPlanConfig;
+}
+
+/** Creates an empty topology */
+export function createEmptyTopology(): CameraTopology {
+  return {
+    version: '1.0',
+    cameras: [],
+    connections: [],
+    globalZones: [],
+  };
+}
+
+/** Finds a camera by device ID */
+export function findCamera(topology: CameraTopology, deviceId: string): CameraNode | undefined {
+  return topology.cameras.find(c => c.deviceId === deviceId);
+}
+
+/** Finds connections from a camera */
+export function findConnectionsFrom(topology: CameraTopology, cameraId: string): CameraConnection[] {
+  return topology.connections.filter(c =>
+    c.fromCameraId === cameraId ||
+    (c.bidirectional && c.toCameraId === cameraId)
+  );
+}
+
+/** Finds a connection between two cameras */
+export function findConnection(
+  topology: CameraTopology,
+  fromCameraId: string,
+  toCameraId: string
+): CameraConnection | undefined {
+  return topology.connections.find(c =>
+    (c.fromCameraId === fromCameraId && c.toCameraId === toCameraId) ||
+    (c.bidirectional && c.fromCameraId === toCameraId && c.toCameraId === fromCameraId)
+  );
+}
+
+/** Gets all entry point cameras */
+export function getEntryPoints(topology: CameraTopology): CameraNode[] {
+  return topology.cameras.filter(c => c.isEntryPoint);
+}
+
+/** Gets all exit point cameras */
+export function getExitPoints(topology: CameraTopology): CameraNode[] {
+  return topology.cameras.filter(c => c.isExitPoint);
+}

package/src/models/tracked-object.ts

@@ -0,0 +1,226 @@
+/**
+ * Tracked Object Models
+ * Defines objects being tracked across multiple cameras
+ */
+
+import { ObjectDetectionResult } from '@scrypted/sdk';
+
+/** Unique identifier for a globally tracked object */
+export type GlobalTrackingId = string;
+
+/** Object detection class types */
+export type ObjectClass = 'person' | 'car' | 'animal' | 'package' | 'vehicle' | string;
+
+/** Tracking state of an object */
+export type TrackingState = 'active' | 'pending' | 'exited' | 'lost';
+
+/** A sighting of an object on a specific camera */
+export interface ObjectSighting {
+  /** Detection from the camera */
+  detection: ObjectDetectionResult;
+  /** Camera device ID */
+  cameraId: string;
+  /** Camera name for display */
+  cameraName?: string;
+  /** Timestamp of detection */
+  timestamp: number;
+  /** Detection confidence */
+  confidence: number;
+  /** Visual embedding if available */
+  embedding?: string;
+  /** Detection image reference ID */
+  detectionId?: string;
+  /** Position in the camera frame (normalized 0-1) */
+  position?: {
+    x: number;
+    y: number;
+  };
+}
+
+/** Complete journey segment between cameras */
+export interface JourneySegment {
+  /** Starting camera device ID */
+  fromCameraId: string;
+  /** Starting camera name */
+  fromCameraName?: string;
+  /** Ending camera device ID */
+  toCameraId: string;
+  /** Ending camera name */
+  toCameraName?: string;
+  /** Exit timestamp from source camera */
+  exitTime: number;
+  /** Entry timestamp on target camera */
+  entryTime: number;
+  /** Transit duration in milliseconds */
+  transitDuration: number;
+  /** Correlation confidence score (0-1) */
+  correlationConfidence: number;
+}
+
+/** A globally tracked object across cameras */
+export interface TrackedObject {
+  /** Unique global tracking ID */
+  globalId: GlobalTrackingId;
+  /** Object class (person, car, etc.) */
+  className: ObjectClass;
+  /** Optional recognized label (face name, license plate) */
+  label?: string;
+  /** All sightings across cameras (chronological order) */
+  sightings: ObjectSighting[];
+  /** Journey segments between cameras */
+  journey: JourneySegment[];
+  /** First seen timestamp */
+  firstSeen: number;
+  /** Last seen timestamp */
+  lastSeen: number;
+  /** Currently active on camera(s) */
+  activeOnCameras: string[];
+  /** Entry point camera (if known) */
+  entryCamera?: string;
+  /** Entry point camera name */
+  entryCameraName?: string;
+  /** Has exited the property */
+  hasExited: boolean;
+  /** Exit camera (if known) */
+  exitCamera?: string;
+  /** Exit camera name */
+  exitCameraName?: string;
+  /** Total dwell time in milliseconds */
+  totalDwellTime: number;
+  /** Tracking state */
+  state: TrackingState;
+  /** Visual descriptor for re-identification (aggregated embedding) */
+  visualDescriptor?: string;
+  /** Best thumbnail detection ID */
+  bestThumbnailId?: string;
+}
+
+/** Pending correlation candidate */
+export interface CorrelationCandidate {
+  /** Existing tracked object */
+  trackedObject: TrackedObject;
+  /** New sighting to potentially correlate */
+  newSighting: ObjectSighting;
+  /** Correlation confidence score 0-1 */
+  confidence: number;
+  /** Factors contributing to confidence */
+  factors: CorrelationFactors;
+}
+
+/** Factors used in correlation scoring */
+export interface CorrelationFactors {
+  /** Timing factor: how well transit time matches expected range */
+  timing: number;
+  /** Visual factor: embedding similarity score */
+  visual: number;
+  /** Spatial factor: exit zone → entry zone coherence */
+  spatial: number;
+  /** Class factor: object class match */
+  class: number;
+}
+
+/** Creates a new tracked object from an initial sighting */
+export function createTrackedObject(
+  globalId: GlobalTrackingId,
+  sighting: ObjectSighting,
+  isEntryPoint: boolean
+): TrackedObject {
+  return {
+    globalId,
+    className: sighting.detection.className as ObjectClass,
+    label: sighting.detection.label,
+    sightings: [sighting],
+    journey: [],
+    firstSeen: sighting.timestamp,
+    lastSeen: sighting.timestamp,
+    activeOnCameras: [sighting.cameraId],
+    entryCamera: isEntryPoint ? sighting.cameraId : undefined,
+    entryCameraName: isEntryPoint ? sighting.cameraName : undefined,
+    hasExited: false,
+    totalDwellTime: 0,
+    state: 'active',
+    visualDescriptor: sighting.embedding,
+    bestThumbnailId: sighting.detectionId,
+  };
+}
+
+/** Adds a sighting to an existing tracked object */
+export function addSighting(tracked: TrackedObject, sighting: ObjectSighting): void {
+  tracked.sightings.push(sighting);
+  tracked.lastSeen = sighting.timestamp;
+
+  // Update active cameras
+  if (!tracked.activeOnCameras.includes(sighting.cameraId)) {
+    tracked.activeOnCameras.push(sighting.cameraId);
+  }
+
+  // Update visual descriptor if we have a new embedding
+  if (sighting.embedding && !tracked.visualDescriptor) {
+    tracked.visualDescriptor = sighting.embedding;
+  }
+
+  // Update best thumbnail if this has higher confidence
+  if (sighting.detectionId && sighting.confidence > 0.8) {
+    tracked.bestThumbnailId = sighting.detectionId;
+  }
+
+  // Update label if recognized
+  if (sighting.detection.label && !tracked.label) {
+    tracked.label = sighting.detection.label;
+  }
+}
+
+/** Adds a journey segment when object moves between cameras */
+export function addJourneySegment(
+  tracked: TrackedObject,
+  segment: JourneySegment
+): void {
+  tracked.journey.push(segment);
+
+  // Remove from old camera, add to new
+  tracked.activeOnCameras = tracked.activeOnCameras.filter(
+    id => id !== segment.fromCameraId
+  );
+  if (!tracked.activeOnCameras.includes(segment.toCameraId)) {
+    tracked.activeOnCameras.push(segment.toCameraId);
+  }
+}
+
+/** Calculates total time an object has been tracked */
+export function calculateDwellTime(tracked: TrackedObject): number {
+  if (tracked.sightings.length === 0) return 0;
+  return tracked.lastSeen - tracked.firstSeen;
+}
+
+/** Gets the last known camera for an object */
+export function getLastCamera(tracked: TrackedObject): string | undefined {
+  if (tracked.sightings.length === 0) return undefined;
+  return tracked.sightings[tracked.sightings.length - 1].cameraId;
+}
+
+/** Gets the last sighting for an object */
+export function getLastSighting(tracked: TrackedObject): ObjectSighting | undefined {
+  if (tracked.sightings.length === 0) return undefined;
+  return tracked.sightings[tracked.sightings.length - 1];
+}
+
+/** Generates a summary of the object's journey */
+export function getJourneySummary(tracked: TrackedObject): string {
+  const cameras: string[] = [];
+
+  if (tracked.entryCamera) {
+    cameras.push(tracked.entryCameraName || tracked.entryCamera);
+  }
+
+  for (const segment of tracked.journey) {
+    if (!cameras.includes(segment.toCameraName || segment.toCameraId)) {
+      cameras.push(segment.toCameraName || segment.toCameraId);
+    }
+  }
+
+  if (tracked.exitCamera && !cameras.includes(tracked.exitCameraName || tracked.exitCamera)) {
+    cameras.push(tracked.exitCameraName || tracked.exitCamera);
+  }
+
+  return cameras.join(' → ');
+}