@trillboards/edge-sdk 0.2.4 → 0.2.6

package/dist/SceneChangeDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SceneChangeDetector.d.ts","sourceRoot":"","sources":["../src/SceneChangeDetector.ts"],"names":[],"mappings":"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"}

package/dist/SceneChangeDetector.js

@@ -0,0 +1,682 @@
+"use strict";
+/**
+ * SceneChangeDetector + MotionGate — the connector's ONE motion implementation.
+ *
+ * This is the cheap stage of the cascade that stands in front of the expensive
+ * one: in a real store most frames are an empty aisle, and today every one of
+ * them is decoded, prompted and generated over by Gemma at 6–32 s a frame. The
+ * cheap stage answers "did anything change?" in single-digit milliseconds on a
+ * ~178x100 greyscale frame — about 116x fewer pixels than the 640x480 JPEG the
+ * VLM would otherwise chew through.
+ *
+ * PORTED FROM FRIGATE (MIT), `frigate/motion/improved_motion.py` +
+ * `frigate/config/camera/motion.py`, keeping its defaults and — more
+ * importantly — its two non-obvious behaviors:
+ *
+ *   1. THE BACKGROUND ONLY MOVES AFTER MOTION PERSISTS. `accumulateWeighted`
+ *      runs every frame while the scene is still, but while motion is present
+ *      it runs only once the motion has lasted `BACKGROUND_UPDATE_AFTER_FRAMES`
+ *      (10) frames. Without that rule a slowly-moving object is absorbed into
+ *      the background and becomes invisible mid-walk.
+ *   2. A CALIBRATION STATE MACHINE. A camera flipping its IR-cut filter at dusk
+ *      changes every pixel at once; so does a cloud crossing the sun. Frigate
+ *      treats "more than `lightningThreshold` of the frame moved" as a signal
+ *      to re-enter calibration rather than as motion, and stays calibrating
+ *      until the scene settles (<5% moved AND <=4 regions). We suppress
+ *      VLM-triggering while calibrating for exactly that reason — otherwise
+ *      dusk costs a 16-camera store one full inference storm per day.
+ *
+ * RELATIONSHIP TO THE ANDROID `SceneChangeDetector`. agent-core carries a class
+ * of the same name (`ctv/core/audience/SceneChangeDetector.kt`) built on
+ * luminance-HISTOGRAM chi-squared distance over Android `Bitmap`s. That is the
+ * right shape for a tablet whose camera frames a single face at arm's length,
+ * and the wrong shape here: a person crossing a wide CCTV frame moves a few
+ * percent of the pixels and barely perturbs a global histogram, which is why
+ * this port is region-based (threshold → dilate → connected components) instead.
+ * Two runtimes (Kotlin/Bitmap vs Node/Buffer) with two different jobs; there is
+ * exactly ONE motion implementation on each side, and this is the connector's.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MotionGate = exports.SceneChangeDetector = void 0;
+exports.resetGreyDecoderCache = resetGreyDecoderCache;
+exports.decodeGreyFrame = decodeGreyFrame;
+exports.downscaleRgbaToGrey = downscaleRgbaToGrey;
+exports.motionSignature = motionSignature;
+const DEFAULT_FRAME_HEIGHT = 100;
+const DEFAULT_THRESHOLD = 30;
+const DEFAULT_CONTOUR_AREA = 10;
+const DEFAULT_FRAME_ALPHA = 0.01;
+const DEFAULT_CALIBRATING_ALPHA = 0.2;
+const DEFAULT_LIGHTNING_THRESHOLD = 0.8;
+/** Frames motion must persist before the background is allowed to absorb it. */
+const BACKGROUND_UPDATE_AFTER_FRAMES = 10;
+/**
+ * Frigate keeps the last 50 contrast readings and stretches to their mean.
+ *
+ * Frigate SEEDS that ring with (0, 255) and lets real readings displace the
+ * seed one frame at a time. At its 5 fps that seed is gone in ten seconds. We
+ * look every `scanIntervalMs` — 30 s by default — so the same ring takes
+ * 50 x 30 s = 25 MINUTES to fill, and for all of it the stretch mapping is
+ * still crawling from the synthetic seed toward the scene's real percentiles.
+ *
+ * A moving mapping means the CONTRAST-STRETCHED frame changes every look even
+ * when the camera is bolted to a wall pointing at an empty aisle. Measured on a
+ * byte-identical still frame at the 30 s cadence: no motion through look 32,
+ * then phantom motion from look 33 to look 93 (wall clock 16.5 min -> 46.5 min
+ * after start) — 53 inferences, ~387 s of the single admission slot, per camera,
+ * against a scene where literally nothing happened. `reset()` re-arms it, so a
+ * feed that flaps re-enters the window every reconnect.
+ *
+ * Seeding from the FIRST real reading instead makes the mapping stationary from
+ * frame 1. Once the ring holds 50 real readings the behaviour is identical to
+ * Frigate's; only the startup transient differs, and only because our cadence
+ * is 150x slower than the one Frigate chose the seed for.
+ */
+const CONTRAST_HISTORY = 50;
+/** Cells per axis in the motion signature grid (stationary suppression). */
+const SIGNATURE_GRID = 16;
+/** scipy `gaussian_filter(sigma=1, radius=1)`, normalized. Separable 1-D. */
+const GAUSS_1D = [0.2740686, 0.4518628, 0.2740686];
+/**
+ * The Frigate motion core, one instance per camera feed. Stateful: it owns the
+ * running background model, the contrast history and the calibration state, so
+ * frames must be fed to the SAME instance in capture order.
+ */
+class SceneChangeDetector {
+    constructor(options = {}) {
+        this.avgFrame = null;
+        this.avgWidth = 0;
+        this.avgHeight = 0;
+        this.motionFrameCount = 0;
+        this.calibrating = true;
+        this.contrastMin = new Int32Array(CONTRAST_HISTORY);
+        this.contrastMax = new Int32Array(CONTRAST_HISTORY).fill(255);
+        this.contrastIndex = 0;
+        /** False until the ring has been seeded from a real frame (see CONTRAST_HISTORY). */
+        this.contrastSeeded = false;
+        this.framesSeen = 0;
+        this.frameHeight = Math.max(16, Math.trunc(options.frameHeight ?? DEFAULT_FRAME_HEIGHT));
+        this.threshold = Math.min(255, Math.max(1, Math.trunc(options.threshold ?? DEFAULT_THRESHOLD)));
+        this.contourArea = Math.max(1, Math.trunc(options.contourArea ?? DEFAULT_CONTOUR_AREA));
+        this.frameAlpha = clamp01(options.frameAlpha ?? DEFAULT_FRAME_ALPHA);
+        this.calibratingAlpha = clamp01(options.calibratingAlpha ?? DEFAULT_CALIBRATING_ALPHA);
+        this.lightningThreshold = clamp01(options.lightningThreshold ?? DEFAULT_LIGHTNING_THRESHOLD);
+        this.improveContrast = options.improveContrast !== false;
+    }
+    /** Height (px) callers must downscale to before calling `detect`. */
+    getFrameHeight() {
+        return this.frameHeight;
+    }
+    isCalibrating() {
+        return this.calibrating;
+    }
+    /** Frames fed so far (a feed with 0 has never produced a motion verdict). */
+    getFramesSeen() {
+        return this.framesSeen;
+    }
+    /**
+     * Forget the background model. Call when the view itself changed (camera
+     * re-opened on a different channel, connector resumed after a long stop) so a
+     * stale baseline cannot report a whole-frame "change" that never happened.
+     */
+    reset() {
+        this.avgFrame = null;
+        this.avgWidth = 0;
+        this.avgHeight = 0;
+        this.motionFrameCount = 0;
+        this.calibrating = true;
+        this.contrastMin.fill(0);
+        this.contrastMax.fill(255);
+        this.contrastIndex = 0;
+        this.contrastSeeded = false;
+        this.framesSeen = 0;
+    }
+    /**
+     * One motion verdict. `frame` must already be greyscale at `frameHeight`
+     * (see `decodeGreyFrame`), which is what keeps this stage ~116x cheaper than
+     * handing the full JPEG to the model.
+     */
+    detect(frame) {
+        const { width, height } = frame;
+        this.framesSeen++;
+        let working = this.improveContrast ? this.stretchContrast(frame) : Uint8Array.from(frame.data);
+        working = blur3x3(working, width, height);
+        // A new (or resized) view has no baseline: seed the background from this
+        // frame and report NO motion rather than a whole-frame false positive.
+        if (!this.avgFrame || this.avgWidth !== width || this.avgHeight !== height) {
+            this.avgFrame = Float32Array.from(working);
+            this.avgWidth = width;
+            this.avgHeight = height;
+            this.motionFrameCount = 0;
+            this.calibrating = true;
+            return { motion: false, boxes: [], pctMotion: 0, calibrating: true, signature: '' };
+        }
+        // |frame - background| > threshold, then dilate to close holes.
+        const avg = this.avgFrame;
+        const mask = new Uint8Array(width * height);
+        for (let i = 0; i < mask.length; i++) {
+            // cv2.convertScaleAbs rounds the float background before differencing.
+            if (Math.abs(working[i] - Math.round(avg[i])) > this.threshold)
+                mask[i] = 1;
+        }
+        const dilated = dilate3x3(mask, width, height);
+        const components = connectedComponents(dilated, width, height);
+        const boxes = [];
+        let totalArea = 0;
+        for (const c of components) {
+            totalArea += c.area;
+            if (c.area > this.contourArea)
+                boxes.push(c);
+        }
+        const pctMotion = totalArea / (width * height);
+        // Calibration state machine (Frigate's order: settle first, then re-arm).
+        if (pctMotion < 0.05 && boxes.length <= 4)
+            this.calibrating = false;
+        if (this.calibrating || pctMotion > this.lightningThreshold)
+            this.calibrating = true;
+        // Background update: every still frame, but only once motion has PERSISTED
+        // — otherwise a slow walker is absorbed and disappears mid-frame.
+        const alpha = this.calibrating ? this.calibratingAlpha : this.frameAlpha;
+        if (boxes.length > 0) {
+            this.motionFrameCount++;
+            if (this.motionFrameCount >= BACKGROUND_UPDATE_AFTER_FRAMES) {
+                accumulateWeighted(working, avg, alpha);
+            }
+        }
+        else {
+            accumulateWeighted(working, avg, alpha);
+            this.motionFrameCount = 0;
+        }
+        return {
+            motion: boxes.length > 0,
+            boxes,
+            pctMotion,
+            calibrating: this.calibrating,
+            signature: motionSignature(boxes, width, height),
+        };
+    }
+    /**
+     * Frigate's `improve_contrast`: stretch the 4th–96th percentile band to
+     * 0..255 using the MEAN of the last 50 readings, so one odd frame cannot
+     * yank the mapping and manufacture motion everywhere.
+     */
+    stretchContrast(frame) {
+        const src = frame.data;
+        const out = new Uint8Array(src.length);
+        const hist = new Int32Array(256);
+        for (let i = 0; i < src.length; i++)
+            hist[src[i]]++;
+        const minValue = percentileFromHistogram(hist, src.length, 0.04);
+        const maxValue = percentileFromHistogram(hist, src.length, 0.96);
+        if (minValue < maxValue) {
+            if (!this.contrastSeeded) {
+                // First real reading fills the whole ring, so the stretch mapping is
+                // stationary from frame 1 instead of crawling off the (0,255) seed for
+                // the next 25 minutes of 30 s looks. See CONTRAST_HISTORY.
+                this.contrastMin.fill(minValue);
+                this.contrastMax.fill(maxValue);
+                this.contrastSeeded = true;
+                this.contrastIndex = 0;
+            }
+            else {
+                this.contrastMin[this.contrastIndex] = minValue;
+                this.contrastMax[this.contrastIndex] = maxValue;
+            }
+            this.contrastIndex = (this.contrastIndex + 1) % CONTRAST_HISTORY;
+        }
+        let sumMin = 0;
+        let sumMax = 0;
+        for (let i = 0; i < CONTRAST_HISTORY; i++) {
+            sumMin += this.contrastMin[i];
+            sumMax += this.contrastMax[i];
+        }
+        const avgMin = sumMin / CONTRAST_HISTORY;
+        const avgMax = sumMax / CONTRAST_HISTORY;
+        if (!(avgMax > avgMin))
+            return Uint8Array.from(src);
+        const scale = 255 / (avgMax - avgMin);
+        for (let i = 0; i < src.length; i++) {
+            const clipped = src[i] < avgMin ? avgMin : src[i] > avgMax ? avgMax : src[i];
+            out[i] = (clipped - avgMin) * scale;
+        }
+        return out;
+    }
+}
+exports.SceneChangeDetector = SceneChangeDetector;
+const DEFAULT_STATIONARY_REANALYZE_EVERY = 10;
+/**
+ * Per-feed cascade decision: decode cheap → motion → should this frame cost a
+ * VLM call? Owns the feed's `SceneChangeDetector`, its heartbeat clock and its
+ * stationary-suppression counter.
+ *
+ * FAILS OPEN. Any decode failure analyzes the frame. A motion gate that cannot
+ * see must not be allowed to silence a camera — the whole product is the alert
+ * that fires.
+ */
+class MotionGate {
+    constructor(options) {
+        this.lastAnalyzedAtMs = null;
+        this.lastAnalyzedSignature = null;
+        this.stationarySuppressions = 0;
+        this.evaluated = 0;
+        this.analyzed = 0;
+        this.byReason = {
+            heartbeat: 0,
+            motion: 0,
+            no_motion: 0,
+            calibrating: 0,
+            stationary: 0,
+            rate_limited: 0,
+            undecodable: 0,
+        };
+        this.detector = new SceneChangeDetector(options);
+        this.heartbeatIntervalMs = Math.max(0, Math.trunc(options.heartbeatIntervalMs));
+        this.minAnalyzeIntervalMs = Math.max(0, Math.trunc(options.minAnalyzeIntervalMs ?? 0));
+        this.stationaryReanalyzeEvery = Math.max(0, Math.trunc(options.stationaryReanalyzeEvery ?? DEFAULT_STATIONARY_REANALYZE_EVERY));
+        this.decodeFrame = options.decode ?? decodeGreyFrame;
+        this.now = options.now ?? Date.now;
+    }
+    /**
+     * Decide whether this JPEG earns an inference. Decision order matters:
+     * heartbeat first (proof-of-life outranks everything), then the motion
+     * verdict, then the suppressions that make a busy-but-boring scene cheap.
+     */
+    async evaluate(jpeg, nowMs) {
+        const now = nowMs ?? this.now();
+        this.evaluated++;
+        const heartbeatDue = this.lastAnalyzedAtMs === null || now - this.lastAnalyzedAtMs >= this.heartbeatIntervalMs;
+        let grey = null;
+        try {
+            grey = await this.decodeFrame(jpeg, this.detector.getFrameHeight());
+        }
+        catch {
+            grey = null;
+        }
+        if (!grey) {
+            // No eyes → no opinion → do not suppress. A gate that cannot see must
+            // never be the reason a camera goes quiet.
+            return this.decide(true, 'undecodable', false, 0, [], null);
+        }
+        const result = this.detector.detect(grey);
+        const live = result.motion && !result.calibrating;
+        if (heartbeatDue) {
+            return this.decide(true, 'heartbeat', live, result.pctMotion, result.boxes, result.signature);
+        }
+        if (!result.motion) {
+            return this.decide(false, 'no_motion', false, result.pctMotion, result.boxes, result.signature);
+        }
+        if (result.calibrating) {
+            // Dusk IR-cut flip / cloud shadow: everything "moved" and none of it is real.
+            return this.decide(false, 'calibrating', false, result.pctMotion, result.boxes, result.signature);
+        }
+        if (this.stationaryReanalyzeEvery > 0 &&
+            this.lastAnalyzedSignature !== null &&
+            result.signature === this.lastAnalyzedSignature) {
+            this.stationarySuppressions++;
+            if (this.stationarySuppressions < this.stationaryReanalyzeEvery) {
+                return this.decide(false, 'stationary', live, result.pctMotion, result.boxes, result.signature);
+            }
+        }
+        if (this.minAnalyzeIntervalMs > 0 &&
+            this.lastAnalyzedAtMs !== null &&
+            now - this.lastAnalyzedAtMs < this.minAnalyzeIntervalMs) {
+            return this.decide(false, 'rate_limited', live, result.pctMotion, result.boxes, result.signature);
+        }
+        return this.decide(true, 'motion', live, result.pctMotion, result.boxes, result.signature);
+    }
+    /**
+     * Confirm the frame really reached the model. Called by the manager only
+     * after `analyze()` resolves, so a frame the admission gate or the network
+     * dropped does not reset the heartbeat and silence the feed.
+     */
+    markAnalyzed(nowMs) {
+        this.lastAnalyzedAtMs = nowMs ?? this.now();
+    }
+    /** The still-scene reporting floor currently in force (ms). */
+    getHeartbeatIntervalMs() {
+        return this.heartbeatIntervalMs;
+    }
+    /**
+     * Retune the still-scene reporting floor WITHOUT forgetting anything.
+     *
+     * Changing a cadence is a statement about how often a still scene must report.
+     * It is NOT a statement that the scene changed, that the camera moved, or that
+     * the last analysis never happened — but rebuilding the gate says all three:
+     * a new `SceneChangeDetector` has no background model, is back in
+     * `calibrating`, has an un-seeded contrast ring (the exact state the
+     * CONTRAST_HISTORY seeding fix exists to avoid), and a null
+     * `lastAnalyzedAtMs`, which makes the very next look heartbeat-DUE and buys a
+     * forced inference per feed for a scene the gate had already proven still.
+     *
+     * The heartbeat is a scalar the next `evaluate()` reads. Moving it is the
+     * whole change.
+     *
+     * @returns true when the interval actually changed.
+     */
+    setHeartbeatIntervalMs(intervalMs) {
+        const raw = Number(intervalMs);
+        if (!Number.isFinite(raw))
+            return false;
+        const next = Math.max(0, Math.trunc(raw));
+        if (next === this.heartbeatIntervalMs)
+            return false;
+        this.heartbeatIntervalMs = next;
+        return true;
+    }
+    /** Forget the background model (camera re-opened on a different view). */
+    reset() {
+        this.detector.reset();
+        this.lastAnalyzedSignature = null;
+        this.stationarySuppressions = 0;
+    }
+    getStats() {
+        return {
+            evaluated: this.evaluated,
+            analyzed: this.analyzed,
+            skipped: this.evaluated - this.analyzed,
+            byReason: { ...this.byReason },
+            calibrating: this.detector.isCalibrating(),
+            framesSeen: this.detector.getFramesSeen(),
+        };
+    }
+    decide(analyze, reason, motion, pctMotion, boxes, signature) {
+        this.byReason[reason]++;
+        if (analyze) {
+            this.analyzed++;
+            // The signature/counter track what the MODEL last saw, so a suppressed
+            // frame never moves the stationary baseline.
+            //
+            // The heartbeat CLOCK is deliberately not touched here: only
+            // markAnalyzed() moves it, and only after the call landed. A feed whose
+            // inference failed therefore stays heartbeat-due and retries on its next
+            // look, instead of going quiet for a whole heartbeat window because of
+            // one bad request.
+            this.lastAnalyzedSignature = signature;
+            this.stationarySuppressions = 0;
+        }
+        return { analyze, reason, motion, pctMotion, boxes };
+    }
+}
+exports.MotionGate = MotionGate;
+let sharpModule;
+let jpegModule;
+function loadSharp() {
+    if (sharpModule === undefined) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            sharpModule = require('sharp');
+        }
+        catch {
+            sharpModule = null;
+        }
+    }
+    return sharpModule;
+}
+function loadJpeg() {
+    if (jpegModule === undefined) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            jpegModule = require('jpeg-js');
+        }
+        catch {
+            jpegModule = null;
+        }
+    }
+    return jpegModule;
+}
+/** Test seam: forget which decoder was resolved. */
+function resetGreyDecoderCache() {
+    sharpModule = undefined;
+    jpegModule = undefined;
+}
+/**
+ * JPEG → greyscale at `targetHeight`, the ~116x pixel reduction the whole
+ * cascade rests on. `sharp` (a hard dependency of @trillboards/edge-sensing, so
+ * present wherever sensing runs) does it natively; `jpeg-js` is the pure-JS
+ * fallback. Returns null when neither is available, which makes the gate fail
+ * open rather than blind a camera.
+ *
+ * WHY NOT FRIGATE'S LITERAL `INTER_NEAREST`. Frigate picks nearest because
+ * `cv2.resize` nearest is the cheapest thing that exists and it blurs the
+ * result immediately afterwards anyway. sharp's "nearest" is not a true
+ * point-sample — it pre-shrinks on load — so asking for it buys none of
+ * Frigate's determinism and costs the two decoders their agreement (measured
+ * MAD 21.8 grey levels against a real point-sample, versus 4.2 for cubic
+ * against the fallback's box average). Both decoders low-pass before
+ * decimating, which is what the subsequent absdiff+threshold wants, and they
+ * land within ~4 grey levels of each other — far inside the threshold of 30, so
+ * a host with sharp and a host without cannot disagree about whether a scene
+ * moved.
+ */
+async function decodeGreyFrame(jpeg, targetHeight) {
+    const sharp = loadSharp();
+    if (sharp) {
+        const { data, info } = await sharp(jpeg)
+            .resize({ height: targetHeight, fit: 'inside', kernel: 'cubic', withoutEnlargement: false })
+            .greyscale()
+            .raw()
+            .toBuffer({ resolveWithObject: true });
+        return { width: info.width, height: info.height, data: new Uint8Array(data.buffer, data.byteOffset, data.length) };
+    }
+    const jpegJs = loadJpeg();
+    if (!jpegJs)
+        return null;
+    const decoded = jpegJs.decode(jpeg, { useTArray: true });
+    return downscaleRgbaToGrey(decoded.data, decoded.width, decoded.height, targetHeight);
+}
+/**
+ * RGBA → greyscale + box-average downscale: each output pixel is the mean of
+ * the source rectangle it covers. Averaging (rather than point-sampling) is
+ * what keeps this in step with the sharp path and what stops a single noisy
+ * pixel from surviving a 4.8x decimation into the difference image.
+ */
+function downscaleRgbaToGrey(rgba, width, height, targetHeight) {
+    const outH = Math.max(1, Math.min(height, Math.round(targetHeight)));
+    const outW = Math.max(1, Math.round((width * outH) / height));
+    const out = new Uint8Array(outW * outH);
+    for (let y = 0; y < outH; y++) {
+        const sy0 = Math.floor((y * height) / outH);
+        const sy1 = Math.max(sy0 + 1, Math.floor(((y + 1) * height) / outH));
+        for (let x = 0; x < outW; x++) {
+            const sx0 = Math.floor((x * width) / outW);
+            const sx1 = Math.max(sx0 + 1, Math.floor(((x + 1) * width) / outW));
+            let sum = 0;
+            let n = 0;
+            for (let sy = sy0; sy < sy1 && sy < height; sy++) {
+                for (let sx = sx0; sx < sx1 && sx < width; sx++) {
+                    const p = (sy * width + sx) * 4;
+                    // ITU-R BT.601 luma, the same weights sharp's greyscale uses.
+                    sum += 0.299 * rgba[p] + 0.587 * rgba[p + 1] + 0.114 * rgba[p + 2];
+                    n++;
+                }
+            }
+            out[y * outW + x] = n > 0 ? Math.round(sum / n) : 0;
+        }
+    }
+    return { width: outW, height: outH, data: out };
+}
+// ─── Pixel kernels ───────────────────────────────────────────────────────────
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/** Value at quantile `q` from a 256-bin histogram (np.percentile, floored). */
+function percentileFromHistogram(hist, total, q) {
+    if (total <= 0)
+        return 0;
+    const target = Math.round(q * (total - 1));
+    let seen = 0;
+    for (let v = 0; v < 256; v++) {
+        seen += hist[v];
+        if (seen > target)
+            return v;
+    }
+    return 255;
+}
+/** Separable 3x3 gaussian (sigma=1, radius=1) with edge clamping. */
+function blur3x3(src, width, height) {
+    const tmp = new Float32Array(src.length);
+    const out = new Uint8Array(src.length);
+    const [k0, k1, k2] = GAUSS_1D;
+    for (let y = 0; y < height; y++) {
+        const row = y * width;
+        for (let x = 0; x < width; x++) {
+            const l = src[row + (x > 0 ? x - 1 : 0)];
+            const c = src[row + x];
+            const r = src[row + (x < width - 1 ? x + 1 : width - 1)];
+            tmp[row + x] = k0 * l + k1 * c + k2 * r;
+        }
+    }
+    for (let y = 0; y < height; y++) {
+        const up = (y > 0 ? y - 1 : 0) * width;
+        const row = y * width;
+        const down = (y < height - 1 ? y + 1 : height - 1) * width;
+        for (let x = 0; x < width; x++) {
+            const v = k0 * tmp[up + x] + k1 * tmp[row + x] + k2 * tmp[down + x];
+            out[row + x] = v < 0 ? 0 : v > 255 ? 255 : Math.round(v);
+        }
+    }
+    return out;
+}
+/**
+ * cv2.dilate with the default 3x3 rectangular element, 1 iteration. A rect
+ * element is separable, so this is two 1-D passes instead of a 9-tap window.
+ */
+function dilate3x3(src, width, height) {
+    const tmp = new Uint8Array(src.length);
+    const out = new Uint8Array(src.length);
+    for (let y = 0; y < height; y++) {
+        const row = y * width;
+        for (let x = 0; x < width; x++) {
+            const l = x > 0 ? src[row + x - 1] : 0;
+            const r = x < width - 1 ? src[row + x + 1] : 0;
+            tmp[row + x] = src[row + x] | l | r;
+        }
+    }
+    for (let y = 0; y < height; y++) {
+        const row = y * width;
+        const up = y > 0 ? row - width : row;
+        const down = y < height - 1 ? row + width : row;
+        for (let x = 0; x < width; x++) {
+            out[row + x] = tmp[row + x] | tmp[up + x] | tmp[down + x];
+        }
+    }
+    return out;
+}
+/**
+ * 8-connected components — the counterpart of `cv2.findContours(RETR_EXTERNAL)`
+ * + `contourArea` + `boundingRect`. Area is the foreground PIXEL count, which
+ * is marginally more permissive than OpenCV's polygon area for the same blob;
+ * on a 100 px-tall frame with a floor of 10 px that difference is well inside
+ * the noise the dilate step already introduces.
+ */
+function connectedComponents(src, width, height) {
+    const labels = new Int32Array(src.length);
+    // Union-find over provisional labels (index 0 unused).
+    const parent = [0];
+    const find = (a) => {
+        let root = a;
+        while (parent[root] !== root)
+            root = parent[root];
+        let cur = a;
+        while (parent[cur] !== root) {
+            const next = parent[cur];
+            parent[cur] = root;
+            cur = next;
+        }
+        return root;
+    };
+    const union = (a, b) => {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra !== rb)
+            parent[Math.max(ra, rb)] = Math.min(ra, rb);
+    };
+    let next = 1;
+    // Already-scanned 8-neighbours of (x, y): NW, N, NE, W. Reused, never
+    // reallocated — this runs once per foreground pixel on every frame.
+    const neighbours = new Int32Array(4);
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const i = y * width + x;
+            if (!src[i])
+                continue;
+            neighbours[0] = y > 0 && x > 0 ? labels[i - width - 1] : 0;
+            neighbours[1] = y > 0 ? labels[i - width] : 0;
+            neighbours[2] = y > 0 && x < width - 1 ? labels[i - width + 1] : 0;
+            neighbours[3] = x > 0 ? labels[i - 1] : 0;
+            let best = 0;
+            let bestRoot = 0;
+            for (let n = 0; n < 4; n++) {
+                const label = neighbours[n];
+                if (!label)
+                    continue;
+                const root = find(label);
+                if (best === 0 || root < bestRoot) {
+                    best = label;
+                    bestRoot = root;
+                }
+            }
+            if (best === 0) {
+                labels[i] = next;
+                parent[next] = next;
+                next++;
+            }
+            else {
+                labels[i] = best;
+                for (let n = 0; n < 4; n++)
+                    if (neighbours[n])
+                        union(best, neighbours[n]);
+            }
+        }
+    }
+    const boxes = new Map();
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const i = y * width + x;
+            if (!labels[i])
+                continue;
+            const root = find(labels[i]);
+            const box = boxes.get(root);
+            if (!box) {
+                boxes.set(root, { x, y, w: 1, h: 1, area: 1 });
+            }
+            else {
+                const x1 = Math.max(box.x + box.w - 1, x);
+                const y1 = Math.max(box.y + box.h - 1, y);
+                const x0 = Math.min(box.x, x);
+                const y0 = Math.min(box.y, y);
+                box.x = x0;
+                box.y = y0;
+                box.w = x1 - x0 + 1;
+                box.h = y1 - y0 + 1;
+                box.area++;
+            }
+        }
+    }
+    return [...boxes.values()];
+}
+/** `avg = (1 - alpha) * avg + alpha * src` — cv2.accumulateWeighted. */
+function accumulateWeighted(src, avg, alpha) {
+    const keep = 1 - alpha;
+    for (let i = 0; i < avg.length; i++)
+        avg[i] = keep * avg[i] + alpha * src[i];
+}
+/**
+ * Quantize motion regions onto a coarse grid so "the same thing is still there"
+ * produces a stable string. Deliberately lossy: a person walking one cell over
+ * changes it, a swinging sign does not.
+ */
+function motionSignature(boxes, width, height) {
+    if (boxes.length === 0)
+        return '';
+    const cells = new Set();
+    for (const b of boxes) {
+        const cx0 = Math.floor((b.x * SIGNATURE_GRID) / width);
+        const cy0 = Math.floor((b.y * SIGNATURE_GRID) / height);
+        const cx1 = Math.floor(((b.x + b.w - 1) * SIGNATURE_GRID) / width);
+        const cy1 = Math.floor(((b.y + b.h - 1) * SIGNATURE_GRID) / height);
+        cells.add(`${cx0},${cy0},${cx1},${cy1}`);
+    }
+    return [...cells].sort().join('|');
+}
+//# sourceMappingURL=SceneChangeDetector.js.map