@camstack/lib-pipeline-analysis 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/lib-pipeline-analysis",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Object tracking, state analysis, zone evaluation, and event emission for CamStack",
   "keywords": [
     "camstack",
@@ -43,7 +43,8 @@
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "publish": "npm publish --access public"
   },
   "peerDependencies": {
     "@camstack/types": "^0.1.0"

package/dist/index.d.mts

@@ -1,333 +0,0 @@
-import { SpatialDetection, TrackedDetection, TrackedObjectState, ZoneDefinition, ZoneEvent, DetectionEventType, Classification, DetectionEvent, TrackDetail, PipelineStatus, CameraLiveState, HeatmapData, ICameraAnalyticsProvider, TimeRangeOptions, ZoneHistoryPoint, HeatmapOptions, TrackFilter, TrackedObjectSummary, ZoneLiveState, IAddonFileStorage, FrameInput, EventSnapshot, ICamstackAddon, PipelineResult, PipelineConfig, KnownFace, KnownPlate, AddonManifest, AddonContext } from '@camstack/types';
-
-interface Point {
-    readonly x: number;
-    readonly y: number;
-}
-interface LineSegment {
-    readonly p1: Point;
-    readonly p2: Point;
-}
-/**
- * Point-in-polygon test using the ray casting algorithm.
- * Returns true if the point is inside the polygon.
- */
-declare function pointInPolygon(point: Point, polygon: readonly Point[]): boolean;
-/**
- * Line segment intersection — returns the intersection point or null if they don't intersect.
- * Uses parametric form of line equations.
- */
-declare function lineIntersection(a: LineSegment, b: LineSegment): Point | null;
-/**
- * Check if a movement from prev to curr crosses the given tripwire.
- * Returns crossed=true and direction if crossed, null otherwise.
- * Direction is determined by the cross product sign:
- *   - 'right' if moving from the left side of the tripwire to the right
- *   - 'left' if moving from the right side to the left
- */
-declare function tripwireCrossing(prev: Point, curr: Point, tripwire: LineSegment): {
-    crossed: boolean;
-    direction: 'left' | 'right';
-} | null;
-/**
- * Calculate the centroid (center point) of a bounding box.
- */
-declare function bboxCentroid(bbox: {
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-}): Point;
-/**
- * Convert normalized coordinates (0–1 range) to pixel coordinates.
- */
-declare function normalizeToPixel(point: Point, imageWidth: number, imageHeight: number): Point;
-
-interface ITracker {
-    update(detections: readonly SpatialDetection[], frameTimestamp: number): TrackedDetection[];
-    getActiveTracks(): TrackedDetection[];
-    getLostTracks(): TrackedDetection[];
-    reset(): void;
-}
-interface TrackerConfig {
-    /** Frames without match before track is considered lost (default: 30) */
-    readonly maxAge: number;
-    /** Minimum detections before track is confirmed and returned (default: 3) */
-    readonly minHits: number;
-    /** Minimum IoU for a detection to match an existing track (default: 0.3) */
-    readonly iouThreshold: number;
-}
-
-declare const DEFAULT_TRACKER_CONFIG: TrackerConfig;
-declare class SortTracker implements ITracker {
-    private tracks;
-    private lostTracks;
-    private nextTrackId;
-    private readonly config;
-    constructor(config?: Partial<TrackerConfig>);
-    update(detections: readonly SpatialDetection[], frameTimestamp: number): TrackedDetection[];
-    getActiveTracks(): TrackedDetection[];
-    getLostTracks(): TrackedDetection[];
-    reset(): void;
-    private createTrack;
-    private getConfirmedTracks;
-    private ageTracksAndPruneLost;
-}
-
-/**
- * Greedy assignment algorithm for matching detections to tracks based on IoU.
- *
- * Sorts all (track, detection) pairs by IoU descending, then greedily assigns
- * pairs as long as neither the track nor detection has been assigned yet and
- * the IoU meets the threshold.
- *
- * @param costMatrix  [tracks × detections] — values are IoU (higher = better)
- * @param threshold   Minimum IoU to accept a match
- * @returns matches, unmatchedTracks, unmatchedDetections indices
- */
-declare function greedyAssignment(costMatrix: readonly (readonly number[])[], threshold: number): {
-    matches: [number, number][];
-    unmatchedTracks: number[];
-    unmatchedDetections: number[];
-};
-
-interface StateAnalyzerConfig {
-    /** Seconds without movement to transition to 'stationary' (default: 10) */
-    readonly stationaryThresholdSec: number;
-    /** Seconds stationary to transition to 'loitering' (default: 60) */
-    readonly loiteringThresholdSec: number;
-    /** Pixels/frame below which a track is considered not moving (default: 2) */
-    readonly velocityThreshold: number;
-    /** Track age (frames) below which it's considered 'entering' (default: 5) */
-    readonly enteringFrames: number;
-}
-declare const DEFAULT_STATE_ANALYZER_CONFIG: StateAnalyzerConfig;
-declare class StateAnalyzer {
-    private readonly states;
-    private readonly config;
-    constructor(config?: Partial<StateAnalyzerConfig>);
-    analyze(tracks: readonly TrackedDetection[], timestamp: number): TrackedObjectState[];
-    private computeObjectState;
-}
-
-declare class ZoneEvaluator {
-    /** Track which zones each track was in last frame */
-    private readonly trackZoneState;
-    evaluate(tracks: readonly TrackedDetection[], zones: readonly ZoneDefinition[], imageWidth: number, imageHeight: number, timestamp: number): ZoneEvent[];
-    /** Returns a snapshot of the current track → zones mapping */
-    getTrackZones(): Map<string, Set<string>>;
-}
-
-interface EventFilterConfig {
-    /** Don't emit for tracks younger than N frames */
-    readonly minTrackAge: number;
-    /** Seconds between same event type for same track */
-    readonly cooldownSec: number;
-    /** Event types that are enabled */
-    readonly enabledTypes: readonly DetectionEventType[];
-}
-declare const DEFAULT_EVENT_FILTER_CONFIG: EventFilterConfig;
-declare class EventFilter {
-    private readonly config;
-    /** key: `${trackId}:${eventType}` → last emitted timestamp */
-    private readonly lastEmitted;
-    constructor(config: EventFilterConfig);
-    shouldEmit(trackId: string, eventType: DetectionEventType, trackAge: number, timestamp: number): boolean;
-    /** Record an emission without a gate check — for events that bypass normal cooldown logic */
-    recordEmission(trackId: string, eventType: DetectionEventType, timestamp: number): void;
-    /** Remove cooldown entries for tracks that are no longer active */
-    cleanup(activeTrackIds: ReadonlySet<string>): void;
-    /** Reset all cooldown state */
-    reset(): void;
-}
-
-declare class DetectionEventEmitter {
-    private readonly filter;
-    /** trackId → last known ObjectState */
-    private readonly previousStates;
-    constructor(filterConfig?: Partial<EventFilterConfig>);
-    emit(tracks: readonly TrackedDetection[], states: readonly TrackedObjectState[], zoneEvents: readonly ZoneEvent[], classifications: readonly {
-        trackId: string;
-        classifications: Classification[];
-    }[], deviceId: string): DetectionEvent[];
-    private tryEmit;
-    reset(): void;
-}
-
-declare class TrackStore {
-    private readonly activeTracks;
-    update(tracks: readonly TrackedDetection[], states: readonly TrackedObjectState[], zoneEvents: readonly ZoneEvent[], classifications: readonly {
-        trackId: string;
-        classifications: Classification[];
-    }[]): void;
-    /** Attach a DetectionEvent to its associated track accumulator */
-    addEvent(trackId: string, event: DetectionEvent): void;
-    /** Get accumulated detail for an active track */
-    getTrackDetail(trackId: string): TrackDetail | null;
-    /** Called when a track ends — returns complete TrackDetail and removes from active set */
-    finishTrack(trackId: string): TrackDetail | null;
-    /** Get all active track IDs */
-    getActiveTrackIds(): string[];
-    /** Clear all accumulated state */
-    reset(): void;
-    private buildTrackDetail;
-}
-
-declare class LiveStateManager {
-    private zones;
-    private readonly fpsCounter;
-    private readonly pipelineMsHistory;
-    private readonly maxPipelineHistory;
-    setZones(zones: ZoneDefinition[]): void;
-    buildState(deviceId: string, tracks: readonly TrackedDetection[], states: readonly TrackedObjectState[], trackZones: Map<string, Set<string>>, pipelineStatus: readonly PipelineStatus[], pipelineMs: number, lastEvent: DetectionEvent | undefined, timestamp: number): CameraLiveState;
-    reset(): void;
-}
-
-/**
- * Grid-based accumulator for track centroid positions.
- *
- * Positions are normalized (0–1) and mapped into a grid of `gridSize × gridSize` cells.
- * Each update increments the count of the corresponding cell.
- */
-declare class HeatmapAggregator {
-    private readonly width;
-    private readonly height;
-    private readonly gridSize;
-    private readonly grid;
-    private maxCount;
-    constructor(width: number, height: number, gridSize: number);
-    /**
-     * Add a normalized point (0–1 range) to the heatmap.
-     * Points outside [0, 1] are clamped to the grid boundary.
-     */
-    addPoint(x: number, y: number): void;
-    /** Add a pixel-coordinate point. Normalizes against the configured width/height. */
-    addPixelPoint(px: number, py: number): void;
-    getHeatmap(): HeatmapData;
-    reset(): void;
-    /** Total number of points accumulated */
-    get totalPoints(): number;
-}
-
-declare class AnalyticsProvider implements ICameraAnalyticsProvider {
-    private readonly liveStateManager;
-    private readonly trackStore;
-    private readonly getZoneHistoryCb?;
-    private readonly getHeatmapCb?;
-    /** Cached live state reference — kept up to date by the pipeline orchestrator */
-    private lastLiveState;
-    constructor(liveStateManager: LiveStateManager, trackStore: TrackStore, getZoneHistoryCb?: ((deviceId: string, zoneId: string, options: TimeRangeOptions) => Promise<ZoneHistoryPoint[]>) | undefined, getHeatmapCb?: ((deviceId: string, options: HeatmapOptions) => Promise<HeatmapData>) | undefined, 
-    /** Cached live state reference — kept up to date by the pipeline orchestrator */
-    lastLiveState?: CameraLiveState | null);
-    /** Called by the orchestrator each frame to update the cached live state */
-    updateLiveState(state: CameraLiveState): void;
-    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[];
-}
-
-interface SnapshotConfig {
-    readonly enabled: boolean;
-    readonly saveThumbnail: boolean;
-    readonly saveAnnotatedFrame: boolean;
-    readonly saveDebugThumbnails: boolean;
-    /** File storage abstraction for snapshot persistence */
-    readonly mediaStorage?: IAddonFileStorage;
-    /** Legacy: output directory for direct file system writes */
-    readonly outputDir?: string;
-}
-declare const DEFAULT_SNAPSHOT_CONFIG: Omit<SnapshotConfig, 'mediaStorage' | 'outputDir'>;
-/**
- * Manages snapshot capture for detection events.
- *
- * Core operation: crop the detection bbox from the full frame and persist as JPEG.
- * Annotated frame (bbox overlay) is optional and requires saveAnnotatedFrame = true.
- *
- * All persistence goes through mediaStorage (IAddonFileStorage).
- *
- * sharp is imported dynamically so the module can load even when sharp is unavailable
- * (e.g., in test environments that mock this class).
- */
-declare class SnapshotManager {
-    private readonly config;
-    constructor(config: SnapshotConfig);
-    capture(frame: FrameInput, detection: TrackedDetection, allDetections: readonly TrackedDetection[], eventId: string): Promise<EventSnapshot | undefined>;
-    private saveThumbnail;
-    private saveAnnotatedFrame;
-    /**
-     * Write output using mediaStorage if available, otherwise fall back to fs.writeFile.
-     */
-    private writeOutput;
-    /**
-     * Resolve actual frame dimensions. JPEG frames from decoders may report
-     * width=0, height=0 — in that case read the real size from sharp metadata.
-     */
-    private resolveFrameDimensions;
-    private sharpInputOptions;
-    private ensureOutputDir;
-}
-
-interface AnalysisPipelineConfig {
-    readonly tracker?: Partial<TrackerConfig>;
-    readonly stateAnalyzer?: Partial<StateAnalyzerConfig>;
-    readonly eventFilter?: Partial<EventFilterConfig>;
-    readonly snapshot?: Partial<SnapshotConfig>;
-    /** Heatmap grid resolution (default: 32) */
-    readonly heatmapGridSize?: number;
-    /** Default frame dimensions when not available from FrameInput (default: 1920×1080) */
-    readonly defaultFrameWidth?: number;
-    readonly defaultFrameHeight?: number;
-}
-/**
- * IAnalysisAddon-compatible interface.
- *
- * NOTE: The types package defines `processFrame(deviceId, frame)` on IAnalysisAddon.
- * In practice the server orchestrator already calls the vision pipeline and passes
- * the PipelineResult. We add an overloaded variant that accepts the PipelineResult
- * as a third argument while remaining compatible with the base interface.
- */
-interface IAnalysisAddon extends ICamstackAddon, ICameraAnalyticsProvider {
-    processFrame(deviceId: string, frame: FrameInput, pipelineResult?: PipelineResult): Promise<DetectionEvent[]>;
-    setCameraPipeline(deviceId: string, config: PipelineConfig): void;
-    setCameraZones(deviceId: string, zones: ZoneDefinition[]): void;
-    setKnownFaces(faces: KnownFace[]): void;
-    setKnownPlates(plates: KnownPlate[]): void;
-    onLiveStateChange(deviceId: string, callback: (state: CameraLiveState) => void): () => void;
-    onTrackFinished?: (deviceId: string, detail: TrackDetail) => void;
-}
-declare class AnalysisPipeline implements IAnalysisAddon {
-    readonly id = "pipeline-analysis";
-    readonly manifest: AddonManifest;
-    private readonly config;
-    private readonly cameras;
-    private knownFaces;
-    private knownPlates;
-    private readonly listeners;
-    /** Optional callback: server orchestrator can hook in to persist finished tracks */
-    onTrackFinished?: (deviceId: string, detail: TrackDetail) => void;
-    constructor(config?: AnalysisPipelineConfig);
-    initialize(_ctx: AddonContext): Promise<void>;
-    shutdown(): Promise<void>;
-    processFrame(deviceId: string, frame: FrameInput, pipelineResult?: PipelineResult): Promise<DetectionEvent[]>;
-    setCameraPipeline(deviceId: string, _config: PipelineConfig): void;
-    setCameraZones(deviceId: string, zones: ZoneDefinition[]): void;
-    setKnownFaces(faces: KnownFace[]): void;
-    setKnownPlates(plates: KnownPlate[]): void;
-    onLiveStateChange(deviceId: string, callback: (state: CameraLiveState) => void): () => void;
-    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 getOrCreateCamera;
-    private extractDetections;
-    private matchClassifications;
-}
-
-export { AnalysisPipeline, type AnalysisPipelineConfig, AnalyticsProvider, DEFAULT_EVENT_FILTER_CONFIG, DEFAULT_SNAPSHOT_CONFIG, DEFAULT_STATE_ANALYZER_CONFIG, DEFAULT_TRACKER_CONFIG, DetectionEventEmitter, EventFilter, type EventFilterConfig, HeatmapAggregator, type IAnalysisAddon, type ITracker, type LineSegment, LiveStateManager, type Point, type SnapshotConfig, SnapshotManager, SortTracker, StateAnalyzer, type StateAnalyzerConfig, TrackStore, type TrackerConfig, ZoneEvaluator, bboxCentroid, greedyAssignment, lineIntersection, normalizeToPixel, pointInPolygon, tripwireCrossing };

package/dist/index.d.ts

@@ -1,333 +0,0 @@
-import { SpatialDetection, TrackedDetection, TrackedObjectState, ZoneDefinition, ZoneEvent, DetectionEventType, Classification, DetectionEvent, TrackDetail, PipelineStatus, CameraLiveState, HeatmapData, ICameraAnalyticsProvider, TimeRangeOptions, ZoneHistoryPoint, HeatmapOptions, TrackFilter, TrackedObjectSummary, ZoneLiveState, IAddonFileStorage, FrameInput, EventSnapshot, ICamstackAddon, PipelineResult, PipelineConfig, KnownFace, KnownPlate, AddonManifest, AddonContext } from '@camstack/types';
-
-interface Point {
-    readonly x: number;
-    readonly y: number;
-}
-interface LineSegment {
-    readonly p1: Point;
-    readonly p2: Point;
-}
-/**
- * Point-in-polygon test using the ray casting algorithm.
- * Returns true if the point is inside the polygon.
- */
-declare function pointInPolygon(point: Point, polygon: readonly Point[]): boolean;
-/**
- * Line segment intersection — returns the intersection point or null if they don't intersect.
- * Uses parametric form of line equations.
- */
-declare function lineIntersection(a: LineSegment, b: LineSegment): Point | null;
-/**
- * Check if a movement from prev to curr crosses the given tripwire.
- * Returns crossed=true and direction if crossed, null otherwise.
- * Direction is determined by the cross product sign:
- *   - 'right' if moving from the left side of the tripwire to the right
- *   - 'left' if moving from the right side to the left
- */
-declare function tripwireCrossing(prev: Point, curr: Point, tripwire: LineSegment): {
-    crossed: boolean;
-    direction: 'left' | 'right';
-} | null;
-/**
- * Calculate the centroid (center point) of a bounding box.
- */
-declare function bboxCentroid(bbox: {
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-}): Point;
-/**
- * Convert normalized coordinates (0–1 range) to pixel coordinates.
- */
-declare function normalizeToPixel(point: Point, imageWidth: number, imageHeight: number): Point;
-
-interface ITracker {
-    update(detections: readonly SpatialDetection[], frameTimestamp: number): TrackedDetection[];
-    getActiveTracks(): TrackedDetection[];
-    getLostTracks(): TrackedDetection[];
-    reset(): void;
-}
-interface TrackerConfig {
-    /** Frames without match before track is considered lost (default: 30) */
-    readonly maxAge: number;
-    /** Minimum detections before track is confirmed and returned (default: 3) */
-    readonly minHits: number;
-    /** Minimum IoU for a detection to match an existing track (default: 0.3) */
-    readonly iouThreshold: number;
-}
-
-declare const DEFAULT_TRACKER_CONFIG: TrackerConfig;
-declare class SortTracker implements ITracker {
-    private tracks;
-    private lostTracks;
-    private nextTrackId;
-    private readonly config;
-    constructor(config?: Partial<TrackerConfig>);
-    update(detections: readonly SpatialDetection[], frameTimestamp: number): TrackedDetection[];
-    getActiveTracks(): TrackedDetection[];
-    getLostTracks(): TrackedDetection[];
-    reset(): void;
-    private createTrack;
-    private getConfirmedTracks;
-    private ageTracksAndPruneLost;
-}
-
-/**
- * Greedy assignment algorithm for matching detections to tracks based on IoU.
- *
- * Sorts all (track, detection) pairs by IoU descending, then greedily assigns
- * pairs as long as neither the track nor detection has been assigned yet and
- * the IoU meets the threshold.
- *
- * @param costMatrix  [tracks × detections] — values are IoU (higher = better)
- * @param threshold   Minimum IoU to accept a match
- * @returns matches, unmatchedTracks, unmatchedDetections indices
- */
-declare function greedyAssignment(costMatrix: readonly (readonly number[])[], threshold: number): {
-    matches: [number, number][];
-    unmatchedTracks: number[];
-    unmatchedDetections: number[];
-};
-
-interface StateAnalyzerConfig {
-    /** Seconds without movement to transition to 'stationary' (default: 10) */
-    readonly stationaryThresholdSec: number;
-    /** Seconds stationary to transition to 'loitering' (default: 60) */
-    readonly loiteringThresholdSec: number;
-    /** Pixels/frame below which a track is considered not moving (default: 2) */
-    readonly velocityThreshold: number;
-    /** Track age (frames) below which it's considered 'entering' (default: 5) */
-    readonly enteringFrames: number;
-}
-declare const DEFAULT_STATE_ANALYZER_CONFIG: StateAnalyzerConfig;
-declare class StateAnalyzer {
-    private readonly states;
-    private readonly config;
-    constructor(config?: Partial<StateAnalyzerConfig>);
-    analyze(tracks: readonly TrackedDetection[], timestamp: number): TrackedObjectState[];
-    private computeObjectState;
-}
-
-declare class ZoneEvaluator {
-    /** Track which zones each track was in last frame */
-    private readonly trackZoneState;
-    evaluate(tracks: readonly TrackedDetection[], zones: readonly ZoneDefinition[], imageWidth: number, imageHeight: number, timestamp: number): ZoneEvent[];
-    /** Returns a snapshot of the current track → zones mapping */
-    getTrackZones(): Map<string, Set<string>>;
-}
-
-interface EventFilterConfig {
-    /** Don't emit for tracks younger than N frames */
-    readonly minTrackAge: number;
-    /** Seconds between same event type for same track */
-    readonly cooldownSec: number;
-    /** Event types that are enabled */
-    readonly enabledTypes: readonly DetectionEventType[];
-}
-declare const DEFAULT_EVENT_FILTER_CONFIG: EventFilterConfig;
-declare class EventFilter {
-    private readonly config;
-    /** key: `${trackId}:${eventType}` → last emitted timestamp */
-    private readonly lastEmitted;
-    constructor(config: EventFilterConfig);
-    shouldEmit(trackId: string, eventType: DetectionEventType, trackAge: number, timestamp: number): boolean;
-    /** Record an emission without a gate check — for events that bypass normal cooldown logic */
-    recordEmission(trackId: string, eventType: DetectionEventType, timestamp: number): void;
-    /** Remove cooldown entries for tracks that are no longer active */
-    cleanup(activeTrackIds: ReadonlySet<string>): void;
-    /** Reset all cooldown state */
-    reset(): void;
-}
-
-declare class DetectionEventEmitter {
-    private readonly filter;
-    /** trackId → last known ObjectState */
-    private readonly previousStates;
-    constructor(filterConfig?: Partial<EventFilterConfig>);
-    emit(tracks: readonly TrackedDetection[], states: readonly TrackedObjectState[], zoneEvents: readonly ZoneEvent[], classifications: readonly {
-        trackId: string;
-        classifications: Classification[];
-    }[], deviceId: string): DetectionEvent[];
-    private tryEmit;
-    reset(): void;
-}
-
-declare class TrackStore {
-    private readonly activeTracks;
-    update(tracks: readonly TrackedDetection[], states: readonly TrackedObjectState[], zoneEvents: readonly ZoneEvent[], classifications: readonly {
-        trackId: string;
-        classifications: Classification[];
-    }[]): void;
-    /** Attach a DetectionEvent to its associated track accumulator */
-    addEvent(trackId: string, event: DetectionEvent): void;
-    /** Get accumulated detail for an active track */
-    getTrackDetail(trackId: string): TrackDetail | null;
-    /** Called when a track ends — returns complete TrackDetail and removes from active set */
-    finishTrack(trackId: string): TrackDetail | null;
-    /** Get all active track IDs */
-    getActiveTrackIds(): string[];
-    /** Clear all accumulated state */
-    reset(): void;
-    private buildTrackDetail;
-}
-
-declare class LiveStateManager {
-    private zones;
-    private readonly fpsCounter;
-    private readonly pipelineMsHistory;
-    private readonly maxPipelineHistory;
-    setZones(zones: ZoneDefinition[]): void;
-    buildState(deviceId: string, tracks: readonly TrackedDetection[], states: readonly TrackedObjectState[], trackZones: Map<string, Set<string>>, pipelineStatus: readonly PipelineStatus[], pipelineMs: number, lastEvent: DetectionEvent | undefined, timestamp: number): CameraLiveState;
-    reset(): void;
-}
-
-/**
- * Grid-based accumulator for track centroid positions.
- *
- * Positions are normalized (0–1) and mapped into a grid of `gridSize × gridSize` cells.
- * Each update increments the count of the corresponding cell.
- */
-declare class HeatmapAggregator {
-    private readonly width;
-    private readonly height;
-    private readonly gridSize;
-    private readonly grid;
-    private maxCount;
-    constructor(width: number, height: number, gridSize: number);
-    /**
-     * Add a normalized point (0–1 range) to the heatmap.
-     * Points outside [0, 1] are clamped to the grid boundary.
-     */
-    addPoint(x: number, y: number): void;
-    /** Add a pixel-coordinate point. Normalizes against the configured width/height. */
-    addPixelPoint(px: number, py: number): void;
-    getHeatmap(): HeatmapData;
-    reset(): void;
-    /** Total number of points accumulated */
-    get totalPoints(): number;
-}
-
-declare class AnalyticsProvider implements ICameraAnalyticsProvider {
-    private readonly liveStateManager;
-    private readonly trackStore;
-    private readonly getZoneHistoryCb?;
-    private readonly getHeatmapCb?;
-    /** Cached live state reference — kept up to date by the pipeline orchestrator */
-    private lastLiveState;
-    constructor(liveStateManager: LiveStateManager, trackStore: TrackStore, getZoneHistoryCb?: ((deviceId: string, zoneId: string, options: TimeRangeOptions) => Promise<ZoneHistoryPoint[]>) | undefined, getHeatmapCb?: ((deviceId: string, options: HeatmapOptions) => Promise<HeatmapData>) | undefined, 
-    /** Cached live state reference — kept up to date by the pipeline orchestrator */
-    lastLiveState?: CameraLiveState | null);
-    /** Called by the orchestrator each frame to update the cached live state */
-    updateLiveState(state: CameraLiveState): void;
-    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[];
-}
-
-interface SnapshotConfig {
-    readonly enabled: boolean;
-    readonly saveThumbnail: boolean;
-    readonly saveAnnotatedFrame: boolean;
-    readonly saveDebugThumbnails: boolean;
-    /** File storage abstraction for snapshot persistence */
-    readonly mediaStorage?: IAddonFileStorage;
-    /** Legacy: output directory for direct file system writes */
-    readonly outputDir?: string;
-}
-declare const DEFAULT_SNAPSHOT_CONFIG: Omit<SnapshotConfig, 'mediaStorage' | 'outputDir'>;
-/**
- * Manages snapshot capture for detection events.
- *
- * Core operation: crop the detection bbox from the full frame and persist as JPEG.
- * Annotated frame (bbox overlay) is optional and requires saveAnnotatedFrame = true.
- *
- * All persistence goes through mediaStorage (IAddonFileStorage).
- *
- * sharp is imported dynamically so the module can load even when sharp is unavailable
- * (e.g., in test environments that mock this class).
- */
-declare class SnapshotManager {
-    private readonly config;
-    constructor(config: SnapshotConfig);
-    capture(frame: FrameInput, detection: TrackedDetection, allDetections: readonly TrackedDetection[], eventId: string): Promise<EventSnapshot | undefined>;
-    private saveThumbnail;
-    private saveAnnotatedFrame;
-    /**
-     * Write output using mediaStorage if available, otherwise fall back to fs.writeFile.
-     */
-    private writeOutput;
-    /**
-     * Resolve actual frame dimensions. JPEG frames from decoders may report
-     * width=0, height=0 — in that case read the real size from sharp metadata.
-     */
-    private resolveFrameDimensions;
-    private sharpInputOptions;
-    private ensureOutputDir;
-}
-
-interface AnalysisPipelineConfig {
-    readonly tracker?: Partial<TrackerConfig>;
-    readonly stateAnalyzer?: Partial<StateAnalyzerConfig>;
-    readonly eventFilter?: Partial<EventFilterConfig>;
-    readonly snapshot?: Partial<SnapshotConfig>;
-    /** Heatmap grid resolution (default: 32) */
-    readonly heatmapGridSize?: number;
-    /** Default frame dimensions when not available from FrameInput (default: 1920×1080) */
-    readonly defaultFrameWidth?: number;
-    readonly defaultFrameHeight?: number;
-}
-/**
- * IAnalysisAddon-compatible interface.
- *
- * NOTE: The types package defines `processFrame(deviceId, frame)` on IAnalysisAddon.
- * In practice the server orchestrator already calls the vision pipeline and passes
- * the PipelineResult. We add an overloaded variant that accepts the PipelineResult
- * as a third argument while remaining compatible with the base interface.
- */
-interface IAnalysisAddon extends ICamstackAddon, ICameraAnalyticsProvider {
-    processFrame(deviceId: string, frame: FrameInput, pipelineResult?: PipelineResult): Promise<DetectionEvent[]>;
-    setCameraPipeline(deviceId: string, config: PipelineConfig): void;
-    setCameraZones(deviceId: string, zones: ZoneDefinition[]): void;
-    setKnownFaces(faces: KnownFace[]): void;
-    setKnownPlates(plates: KnownPlate[]): void;
-    onLiveStateChange(deviceId: string, callback: (state: CameraLiveState) => void): () => void;
-    onTrackFinished?: (deviceId: string, detail: TrackDetail) => void;
-}
-declare class AnalysisPipeline implements IAnalysisAddon {
-    readonly id = "pipeline-analysis";
-    readonly manifest: AddonManifest;
-    private readonly config;
-    private readonly cameras;
-    private knownFaces;
-    private knownPlates;
-    private readonly listeners;
-    /** Optional callback: server orchestrator can hook in to persist finished tracks */
-    onTrackFinished?: (deviceId: string, detail: TrackDetail) => void;
-    constructor(config?: AnalysisPipelineConfig);
-    initialize(_ctx: AddonContext): Promise<void>;
-    shutdown(): Promise<void>;
-    processFrame(deviceId: string, frame: FrameInput, pipelineResult?: PipelineResult): Promise<DetectionEvent[]>;
-    setCameraPipeline(deviceId: string, _config: PipelineConfig): void;
-    setCameraZones(deviceId: string, zones: ZoneDefinition[]): void;
-    setKnownFaces(faces: KnownFace[]): void;
-    setKnownPlates(plates: KnownPlate[]): void;
-    onLiveStateChange(deviceId: string, callback: (state: CameraLiveState) => void): () => void;
-    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 getOrCreateCamera;
-    private extractDetections;
-    private matchClassifications;
-}
-
-export { AnalysisPipeline, type AnalysisPipelineConfig, AnalyticsProvider, DEFAULT_EVENT_FILTER_CONFIG, DEFAULT_SNAPSHOT_CONFIG, DEFAULT_STATE_ANALYZER_CONFIG, DEFAULT_TRACKER_CONFIG, DetectionEventEmitter, EventFilter, type EventFilterConfig, HeatmapAggregator, type IAnalysisAddon, type ITracker, type LineSegment, LiveStateManager, type Point, type SnapshotConfig, SnapshotManager, SortTracker, StateAnalyzer, type StateAnalyzerConfig, TrackStore, type TrackerConfig, ZoneEvaluator, bboxCentroid, greedyAssignment, lineIntersection, normalizeToPixel, pointInPolygon, tripwireCrossing };