@camstack/addon-pipeline-analysis 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,208 @@
+import { ICamstackAddon, AddonManifest, AddonContext, CapabilityProviderMap, PipelineConfig, CameraZone, MotionSource, KnownFace, KnownPlate, CameraLiveState, FrameInput, PipelineRunResult, DetectionEvent, TrackFilter, TrackedObjectSummary, ZoneLiveState, TimeRangeOptions, ZoneHistoryPoint, HeatmapOptions, HeatmapData, TrackDetail, PipelineStatus, DetectionZoneMembership, SpatialDetection, TrackedDetection, BoundingBox, TrackedObjectState, ZoneEvent, Classification } from '@camstack/types';
+
+declare class AnalysisPipelineAddon implements ICamstackAddon {
+    readonly manifest: AddonManifest;
+    private pipeline;
+    initialize(context: AddonContext): Promise<void>;
+    shutdown(): Promise<void>;
+    getCapabilityProvider<K extends keyof CapabilityProviderMap>(name: K): CapabilityProviderMap[K] | null;
+}
+
+/**
+ * AnalysisPipeline — the main per-camera orchestrator.
+ *
+ * Implements IAnalysisAddon (extends ICamstackAddon + ICameraAnalyticsProvider).
+ * Per-camera state is keyed by deviceId.
+ *
+ * processFrame pipeline:
+ *   PipelineRunResult → convert bboxes → zone filter → track → analyze state
+ *                    → emit events → update analytics → notify callbacks
+ */
+declare class AnalysisPipeline implements ICamstackAddon {
+    readonly manifest: AddonManifest;
+    private readonly cameraStates;
+    private readonly analytics;
+    private readonly liveStateCallbacks;
+    initialize(_context: AddonContext): Promise<void>;
+    shutdown(): Promise<void>;
+    getCapabilityProvider<K extends keyof CapabilityProviderMap>(name: K): CapabilityProviderMap[K] | null;
+    setCameraPipeline(deviceId: string, _config: PipelineConfig): void;
+    setCameraZones(deviceId: string, zones: readonly CameraZone[]): void;
+    setCameraMotionConfig(_deviceId: string, _source: MotionSource): void;
+    setKnownFaces(_faces: KnownFace[]): void;
+    setKnownPlates(_plates: KnownPlate[]): void;
+    onLiveStateChange(deviceId: string, callback: (state: CameraLiveState) => void): () => void;
+    processFrame(deviceId: string, frame: FrameInput, pipelineResult?: PipelineRunResult): Promise<DetectionEvent[]>;
+    getLiveState(deviceId: string): CameraLiveState | null;
+    getTracks(deviceId: string, filter?: TrackFilter): TrackedObjectSummary[];
+    getZoneState(deviceId: string, zoneId: string): ZoneLiveState | null;
+    getZoneHistory(deviceId: string, zoneId: string, options: TimeRangeOptions): Promise<ZoneHistoryPoint[]>;
+    getHeatmap(deviceId: string, options: HeatmapOptions): Promise<HeatmapData>;
+    getTrackDetail(deviceId: string, trackId: string): TrackDetail | null;
+    getCameraStatus(deviceId: string): PipelineStatus[];
+    private ensureCameraState;
+    /**
+     * Convert PipelineDetection bbox [x1, y1, x2, y2] to BoundingBox {x, y, w, h}.
+     * Pipeline bboxes are in pixel coordinates.
+     */
+    private convertBbox;
+}
+
+interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+interface LineSegment {
+    readonly p1: Point;
+    readonly p2: Point;
+}
+interface BboxRect {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+interface TripwireResult {
+    readonly crossed: boolean;
+    readonly direction: 'left' | 'right';
+}
+/** Ray-casting point-in-polygon test */
+declare function pointInPolygon(point: Point, polygon: readonly Point[]): boolean;
+/** Parametric line-segment intersection. Returns intersection point or null. */
+declare function lineIntersection(a: LineSegment, b: LineSegment): Point | null;
+/** Detect tripwire crossing and direction via cross product. */
+declare function tripwireCrossing(prev: Point, curr: Point, wire: LineSegment): TripwireResult | null;
+/** Centroid of a bounding box { x, y, w, h } */
+declare function bboxCentroid(bbox: BboxRect): Point;
+/** Convert normalized (0–1) coordinates to pixel coordinates */
+declare function normalizeToPixel(p: Point, width: number, height: number): Point;
+
+interface FilterResult<T> {
+    readonly passed: readonly T[];
+    readonly excluded: readonly T[];
+    readonly annotations: ReadonlyMap<T, readonly DetectionZoneMembership[]>;
+}
+type Stage = 'motion' | 'detection';
+declare class ZoneEngine {
+    /**
+     * Annotate a single detection with its zone memberships.
+     * Returns zones where the detection overlaps above threshold.
+     */
+    annotateDetection(bbox: BboxRect, zones: readonly CameraZone[], frameWidth: number, frameHeight: number, mask?: Uint8Array, maskWidth?: number, maskHeight?: number, className?: string): DetectionZoneMembership[];
+    /**
+     * Filter detections based on zone include/exclude/monitor logic for a given stage.
+     */
+    filterDetections<T extends BboxRect>(detections: readonly T[], zones: readonly CameraZone[], frameWidth: number, frameHeight: number, stage: Stage, getClassName?: (d: T) => string | undefined, getMask?: (d: T) => {
+        mask: Uint8Array;
+        width: number;
+        height: number;
+    } | undefined): FilterResult<T>;
+    /**
+     * Generate an auto-border exclusion zone as a polygon with a hole.
+     */
+    generateAutoBorderZone(percent: number): CameraZone;
+}
+
+interface TrackerConfig {
+    readonly iouThreshold: number;
+    readonly maxMissedFrames: number;
+    readonly minHits: number;
+}
+declare const DEFAULT_TRACKER_CONFIG: TrackerConfig;
+interface InternalTrack {
+    id: string;
+    bbox: BoundingBox;
+    class: string;
+    originalClass: string;
+    score: number;
+    age: number;
+    hits: number;
+    path: BoundingBox[];
+    firstSeen: number;
+    lastSeen: number;
+    velocity: {
+        dx: number;
+        dy: number;
+    };
+    lost: boolean;
+}
+declare class SortTracker {
+    private readonly config;
+    private tracks;
+    private lostTracks;
+    constructor(config?: Partial<TrackerConfig>);
+    update(detections: readonly SpatialDetection[], timestamp: number): TrackedDetection[];
+    getActiveTracks(): readonly InternalTrack[];
+    getLostTracks(): readonly InternalTrack[];
+    reset(): void;
+}
+
+interface StateAnalyzerConfig {
+    readonly stationaryThresholdSec: number;
+    readonly loiteringThresholdSec: number;
+    readonly velocityThreshold: number;
+    readonly enteringFrames: number;
+}
+declare const DEFAULT_STATE_ANALYZER_CONFIG: StateAnalyzerConfig;
+declare class StateAnalyzer {
+    private readonly config;
+    private readonly states;
+    constructor(config?: Partial<StateAnalyzerConfig>);
+    analyze(tracks: readonly TrackedDetection[], timestamp: number): TrackedObjectState[];
+    reset(): void;
+}
+
+interface EventEmitterConfig {
+    readonly minTrackAge: number;
+    readonly cooldownSec: number;
+    readonly enabledTypes: readonly string[];
+}
+
+declare class DetectionEventEmitter {
+    private readonly config;
+    private readonly previousStates;
+    private readonly lastEmitted;
+    constructor(config?: Partial<EventEmitterConfig>);
+    emit(tracks: readonly TrackedDetection[], states: readonly TrackedObjectState[], zoneEvents: readonly ZoneEvent[], classifications: readonly Classification[], deviceId: string): DetectionEvent[];
+    reset(): void;
+}
+
+declare class HeatmapAggregator {
+    private readonly gridSize;
+    private readonly cells;
+    private maxCount;
+    private _totalPoints;
+    constructor(gridSize?: number);
+    get totalPoints(): number;
+    addPoint(x: number, y: number): void;
+    getHeatmap(): HeatmapData;
+    reset(): void;
+}
+
+declare class TrackStore {
+    private readonly tracks;
+    update(tracked: readonly TrackedDetection[], zoneEvents: readonly ZoneEvent[], classifications: readonly Classification[], timestamp: number): void;
+    addEvent(trackId: string, event: DetectionEvent): void;
+    getTrackDetail(trackId: string): TrackDetail | null;
+    finishTrack(trackId: string): TrackDetail | null;
+    getActiveTrackIds(): string[];
+    reset(): void;
+    private toDetail;
+}
+
+/**
+ * Calculate overlap of a bounding box with a polygon.
+ * Uses sampling: divides bbox into grid, counts points inside polygon.
+ * Returns fraction 0–1 (intersection area / bbox area).
+ */
+declare function bboxPolygonOverlap(bbox: BboxRect, polygon: readonly Point[]): number;
+/**
+ * Calculate overlap of a segmentation mask with a polygon.
+ * Mask is a binary array (0/1) at maskWidth×maskHeight resolution,
+ * positioned at bbox within a frame of frameWidth×frameHeight.
+ * Polygon points are in pixel coordinates.
+ * Returns fraction 0–1 (mask pixels inside polygon / total mask pixels).
+ */
+declare function maskPolygonOverlap(mask: Uint8Array, maskWidth: number, maskHeight: number, bbox: BboxRect, polygon: readonly Point[], _frameWidth: number, _frameHeight: number): number;
+
+export { AnalysisPipeline, AnalysisPipelineAddon, type BboxRect, DEFAULT_STATE_ANALYZER_CONFIG, DEFAULT_TRACKER_CONFIG, DetectionEventEmitter, HeatmapAggregator, type LineSegment, type Point, SortTracker, StateAnalyzer, TrackStore, type TripwireResult, ZoneEngine, bboxCentroid, bboxPolygonOverlap, lineIntersection, maskPolygonOverlap, normalizeToPixel, pointInPolygon, tripwireCrossing };

package/dist/index.d.ts

@@ -0,0 +1,208 @@
+import { ICamstackAddon, AddonManifest, AddonContext, CapabilityProviderMap, PipelineConfig, CameraZone, MotionSource, KnownFace, KnownPlate, CameraLiveState, FrameInput, PipelineRunResult, DetectionEvent, TrackFilter, TrackedObjectSummary, ZoneLiveState, TimeRangeOptions, ZoneHistoryPoint, HeatmapOptions, HeatmapData, TrackDetail, PipelineStatus, DetectionZoneMembership, SpatialDetection, TrackedDetection, BoundingBox, TrackedObjectState, ZoneEvent, Classification } from '@camstack/types';
+
+declare class AnalysisPipelineAddon implements ICamstackAddon {
+    readonly manifest: AddonManifest;
+    private pipeline;
+    initialize(context: AddonContext): Promise<void>;
+    shutdown(): Promise<void>;
+    getCapabilityProvider<K extends keyof CapabilityProviderMap>(name: K): CapabilityProviderMap[K] | null;
+}
+
+/**
+ * AnalysisPipeline — the main per-camera orchestrator.
+ *
+ * Implements IAnalysisAddon (extends ICamstackAddon + ICameraAnalyticsProvider).
+ * Per-camera state is keyed by deviceId.
+ *
+ * processFrame pipeline:
+ *   PipelineRunResult → convert bboxes → zone filter → track → analyze state
+ *                    → emit events → update analytics → notify callbacks
+ */
+declare class AnalysisPipeline implements ICamstackAddon {
+    readonly manifest: AddonManifest;
+    private readonly cameraStates;
+    private readonly analytics;
+    private readonly liveStateCallbacks;
+    initialize(_context: AddonContext): Promise<void>;
+    shutdown(): Promise<void>;
+    getCapabilityProvider<K extends keyof CapabilityProviderMap>(name: K): CapabilityProviderMap[K] | null;
+    setCameraPipeline(deviceId: string, _config: PipelineConfig): void;
+    setCameraZones(deviceId: string, zones: readonly CameraZone[]): void;
+    setCameraMotionConfig(_deviceId: string, _source: MotionSource): void;
+    setKnownFaces(_faces: KnownFace[]): void;
+    setKnownPlates(_plates: KnownPlate[]): void;
+    onLiveStateChange(deviceId: string, callback: (state: CameraLiveState) => void): () => void;
+    processFrame(deviceId: string, frame: FrameInput, pipelineResult?: PipelineRunResult): Promise<DetectionEvent[]>;
+    getLiveState(deviceId: string): CameraLiveState | null;
+    getTracks(deviceId: string, filter?: TrackFilter): TrackedObjectSummary[];
+    getZoneState(deviceId: string, zoneId: string): ZoneLiveState | null;
+    getZoneHistory(deviceId: string, zoneId: string, options: TimeRangeOptions): Promise<ZoneHistoryPoint[]>;
+    getHeatmap(deviceId: string, options: HeatmapOptions): Promise<HeatmapData>;
+    getTrackDetail(deviceId: string, trackId: string): TrackDetail | null;
+    getCameraStatus(deviceId: string): PipelineStatus[];
+    private ensureCameraState;
+    /**
+     * Convert PipelineDetection bbox [x1, y1, x2, y2] to BoundingBox {x, y, w, h}.
+     * Pipeline bboxes are in pixel coordinates.
+     */
+    private convertBbox;
+}
+
+interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+interface LineSegment {
+    readonly p1: Point;
+    readonly p2: Point;
+}
+interface BboxRect {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+interface TripwireResult {
+    readonly crossed: boolean;
+    readonly direction: 'left' | 'right';
+}
+/** Ray-casting point-in-polygon test */
+declare function pointInPolygon(point: Point, polygon: readonly Point[]): boolean;
+/** Parametric line-segment intersection. Returns intersection point or null. */
+declare function lineIntersection(a: LineSegment, b: LineSegment): Point | null;
+/** Detect tripwire crossing and direction via cross product. */
+declare function tripwireCrossing(prev: Point, curr: Point, wire: LineSegment): TripwireResult | null;
+/** Centroid of a bounding box { x, y, w, h } */
+declare function bboxCentroid(bbox: BboxRect): Point;
+/** Convert normalized (0–1) coordinates to pixel coordinates */
+declare function normalizeToPixel(p: Point, width: number, height: number): Point;
+
+interface FilterResult<T> {
+    readonly passed: readonly T[];
+    readonly excluded: readonly T[];
+    readonly annotations: ReadonlyMap<T, readonly DetectionZoneMembership[]>;
+}
+type Stage = 'motion' | 'detection';
+declare class ZoneEngine {
+    /**
+     * Annotate a single detection with its zone memberships.
+     * Returns zones where the detection overlaps above threshold.
+     */
+    annotateDetection(bbox: BboxRect, zones: readonly CameraZone[], frameWidth: number, frameHeight: number, mask?: Uint8Array, maskWidth?: number, maskHeight?: number, className?: string): DetectionZoneMembership[];
+    /**
+     * Filter detections based on zone include/exclude/monitor logic for a given stage.
+     */
+    filterDetections<T extends BboxRect>(detections: readonly T[], zones: readonly CameraZone[], frameWidth: number, frameHeight: number, stage: Stage, getClassName?: (d: T) => string | undefined, getMask?: (d: T) => {
+        mask: Uint8Array;
+        width: number;
+        height: number;
+    } | undefined): FilterResult<T>;
+    /**
+     * Generate an auto-border exclusion zone as a polygon with a hole.
+     */
+    generateAutoBorderZone(percent: number): CameraZone;
+}
+
+interface TrackerConfig {
+    readonly iouThreshold: number;
+    readonly maxMissedFrames: number;
+    readonly minHits: number;
+}
+declare const DEFAULT_TRACKER_CONFIG: TrackerConfig;
+interface InternalTrack {
+    id: string;
+    bbox: BoundingBox;
+    class: string;
+    originalClass: string;
+    score: number;
+    age: number;
+    hits: number;
+    path: BoundingBox[];
+    firstSeen: number;
+    lastSeen: number;
+    velocity: {
+        dx: number;
+        dy: number;
+    };
+    lost: boolean;
+}
+declare class SortTracker {
+    private readonly config;
+    private tracks;
+    private lostTracks;
+    constructor(config?: Partial<TrackerConfig>);
+    update(detections: readonly SpatialDetection[], timestamp: number): TrackedDetection[];
+    getActiveTracks(): readonly InternalTrack[];
+    getLostTracks(): readonly InternalTrack[];
+    reset(): void;
+}
+
+interface StateAnalyzerConfig {
+    readonly stationaryThresholdSec: number;
+    readonly loiteringThresholdSec: number;
+    readonly velocityThreshold: number;
+    readonly enteringFrames: number;
+}
+declare const DEFAULT_STATE_ANALYZER_CONFIG: StateAnalyzerConfig;
+declare class StateAnalyzer {
+    private readonly config;
+    private readonly states;
+    constructor(config?: Partial<StateAnalyzerConfig>);
+    analyze(tracks: readonly TrackedDetection[], timestamp: number): TrackedObjectState[];
+    reset(): void;
+}
+
+interface EventEmitterConfig {
+    readonly minTrackAge: number;
+    readonly cooldownSec: number;
+    readonly enabledTypes: readonly string[];
+}
+
+declare class DetectionEventEmitter {
+    private readonly config;
+    private readonly previousStates;
+    private readonly lastEmitted;
+    constructor(config?: Partial<EventEmitterConfig>);
+    emit(tracks: readonly TrackedDetection[], states: readonly TrackedObjectState[], zoneEvents: readonly ZoneEvent[], classifications: readonly Classification[], deviceId: string): DetectionEvent[];
+    reset(): void;
+}
+
+declare class HeatmapAggregator {
+    private readonly gridSize;
+    private readonly cells;
+    private maxCount;
+    private _totalPoints;
+    constructor(gridSize?: number);
+    get totalPoints(): number;
+    addPoint(x: number, y: number): void;
+    getHeatmap(): HeatmapData;
+    reset(): void;
+}
+
+declare class TrackStore {
+    private readonly tracks;
+    update(tracked: readonly TrackedDetection[], zoneEvents: readonly ZoneEvent[], classifications: readonly Classification[], timestamp: number): void;
+    addEvent(trackId: string, event: DetectionEvent): void;
+    getTrackDetail(trackId: string): TrackDetail | null;
+    finishTrack(trackId: string): TrackDetail | null;
+    getActiveTrackIds(): string[];
+    reset(): void;
+    private toDetail;
+}
+
+/**
+ * Calculate overlap of a bounding box with a polygon.
+ * Uses sampling: divides bbox into grid, counts points inside polygon.
+ * Returns fraction 0–1 (intersection area / bbox area).
+ */
+declare function bboxPolygonOverlap(bbox: BboxRect, polygon: readonly Point[]): number;
+/**
+ * Calculate overlap of a segmentation mask with a polygon.
+ * Mask is a binary array (0/1) at maskWidth×maskHeight resolution,
+ * positioned at bbox within a frame of frameWidth×frameHeight.
+ * Polygon points are in pixel coordinates.
+ * Returns fraction 0–1 (mask pixels inside polygon / total mask pixels).
+ */
+declare function maskPolygonOverlap(mask: Uint8Array, maskWidth: number, maskHeight: number, bbox: BboxRect, polygon: readonly Point[], _frameWidth: number, _frameHeight: number): number;
+
+export { AnalysisPipeline, AnalysisPipelineAddon, type BboxRect, DEFAULT_STATE_ANALYZER_CONFIG, DEFAULT_TRACKER_CONFIG, DetectionEventEmitter, HeatmapAggregator, type LineSegment, type Point, SortTracker, StateAnalyzer, TrackStore, type TripwireResult, ZoneEngine, bboxCentroid, bboxPolygonOverlap, lineIntersection, maskPolygonOverlap, normalizeToPixel, pointInPolygon, tripwireCrossing };