@mavware/bug-surveillance 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+# @mavware/bug-surveillance
+
+Point a phone or laptop camera at a room, leave it running all night, and get
+back every time something walked through the frame: when, where it came in,
+where it left, and a snapshot of each sighting.
+
+Detection, tracking and reporting all run in the browser. There is no server,
+no upload and no machine learning model to download. A night can be kept in the
+browser's own IndexedDB store, so the library works with no backend at all.
+
+Live demo: <https://mavware.github.io/bugtracker/>
+
+## Install
+
+```bash
+npm install @mavware/bug-surveillance
+```
+
+TypeScript declarations are included. This is a browser library, so a consumer's
+`tsconfig.json` needs `"lib": ["ES2022", "DOM"]`.
+
+## How it fits together
+
+Four pieces, which you wire into your own page:
+
+- **`Camera`** owns the video stream and two canvases, one at full resolution
+  for reference photos and snapshots, one downscaled for per-frame work.
+- **`Detector`** keeps a running-average background and reports the dark,
+  bug-sized blobs that differ from it. A frame holding something far larger than
+  a bug, such as a person or a pet, is dropped whole rather than reported as a
+  swarm.
+- **`Tracker`** joins those blobs into paths across frames and hands you each
+  path once it ends.
+- **A sink** receives those closed paths. `LocalNightSink` writes them to
+  IndexedDB. Implement the same handful of methods to upload them instead.
+
+The library never touches your markup, your router or your framework. It decides;
+your page plumbs.
+
+## Watching a room
+
+```js
+import {
+    calibrate,
+    calibrationOutcome,
+    Camera,
+    DEFAULT_PARAMS,
+    Detector,
+    LEAVE_ROOM_SECONDS,
+    LocalNightSink,
+    openNightStore,
+    PREFLIGHT_MESSAGE,
+    Tracker,
+    WakeLock,
+} from '@mavware/bug-surveillance';
+
+const camera = new Camera(document.querySelector('video'), DEFAULT_PARAMS.procWidth);
+const wakeLock = new WakeLock(() => console.warn('This screen will not stay on by itself.'));
+
+// The order matters. Ask before the camera opens, and let the room empty before
+// anything is measured: whoever pressed start would otherwise be baked into the
+// background model and recorded walking out.
+if (!window.confirm(PREFLIGHT_MESSAGE)) {
+    return;
+}
+
+await camera.start();
+await new Promise((resolve) => setTimeout(resolve, LEAVE_ROOM_SECONDS * 1000));
+
+const calibration = await calibrate(camera);
+
+if (calibrationOutcome(calibration).blocked) {
+    throw new Error('Too dark to see anything.');
+}
+
+const settings = { ...DEFAULT_PARAMS, diffThreshold: calibration.diffThreshold };
+const sink = new LocalNightSink({
+    store: await openNightStore(),
+    reportUrlTemplate: 'report.html?night=<LOCAL_ID_PLACEHOLDER>',
+});
+
+await sink.storeReference({
+    blob: await camera.captureReferenceJpeg(),
+    frameWidth: camera.frameWidth,
+    frameHeight: camera.frameHeight,
+    settings,
+});
+
+const startedAt = Date.now();
+const detector = new Detector(settings);
+const tracker = new Tracker({
+    scale: camera.scale,
+    sessionStartTime: startedAt,
+    captureCrop: (x, y) => camera.captureCropBase64(x, y),
+    onTrackClosed: (track) => sink.enqueue(track),
+});
+
+sink.start();
+await wakeLock.acquire();
+
+const loop = setInterval(() => {
+    tracker.update(detector.detect(camera.grabProcessedFrame()));
+}, 1000 / settings.processFps);
+```
+
+Ending the night flushes what is queued and hands back where its report lives:
+
+```js
+clearInterval(loop);
+tracker.flush();
+sink.stop();
+await sink.flush();
+camera.stop();
+await wakeLock.release();
+
+const { reportUrl } = await sink.end({
+    endedAtOffsetMs: Date.now() - startedAt,
+    aborted: false,
+});
+
+window.location.assign(reportUrl);
+```
+
+## Reading a night back
+
+`Replay` draws the trails and the animated playback over the reference photo,
+and `mountReportControls` wires the play, speed, scrub and trail controls to it.
+
+```js
+import {
+    buildLocalReportPayload,
+    mountReportControls,
+    openNightStore,
+    sightingRows,
+    statTiles,
+} from '@mavware/bug-surveillance';
+
+const store = await openNightStore();
+const night = await store.getNight(nightId);
+const tracks = await store.listTracks(nightId);
+
+const { rebuild } = mountReportControls(document.getElementById('report'), {
+    loadData: async () => ({ data: buildLocalReportPayload(night, tracks), referenceImage }),
+});
+```
+
+`mountReportControls` is the one part with a markup contract. Inside the element
+you hand it, it looks for `data-report="canvas"`, `"play"`, `"speed"`, `"scrub"`,
+`"clock"` and `"trails"`, and treats a click on any element carrying
+`data-track-id` as a request to highlight that trail. Use `Replay` directly if
+you would rather own the controls.
+
+`sightingRows` and `statTiles` give you the table rows and headline figures
+ready to render, and `computeNightAnalytics` produces the summary behind them:
+how many sightings, and which edges of the frame they clustered against.
+
+## Sending nights somewhere else
+
+Anything with these methods can stand in for `LocalNightSink`, so the capture
+code above is unchanged whether nights stay on the device or go to a server:
+
+```js
+class UploadingSink {
+    async storeReference({ blob, frameWidth, frameHeight, settings }) {}
+    start() {}
+    stop() {}
+    enqueue(closedTrack) {}
+    async flush({ keepalive } = {}) {}
+    async end({ endedAtOffsetMs, aborted }) {
+        return { ok: true, status: 200, reportUrl: '/report' };
+    }
+}
+```
+
+A closed track arrives with a client-generated id, its start and end offsets in
+milliseconds, its points as `[offsetMs, x, y]` in full-frame pixels, and two
+optional snapshots as raw base64 JPEG.
+
+## Wording
+
+Copy ships as exported constants, and the helpers that produce copy take an
+optional overrides object, so you can reword or translate without forking:
+
+```js
+watchingState(true, { largeMotion: 'Quelqu\'un est dans la pièce.' });
+calibrationOutcome(calibration, { tooDark: 'Trop sombre.' });
+```
+
+## Browser support
+
+Needs `getUserMedia`, canvas and IndexedDB, so any current version of Chrome,
+Edge, Firefox or Safari. The camera requires a secure context, meaning HTTPS or
+localhost. The screen wake lock is used when available and degrades to a warning
+through the `WakeLock` callback when it is not. When IndexedDB is unavailable,
+such as in some private browsing modes, `openNightStore` falls back to an
+in-memory store and marks it `volatile` so you can tell the user their night
+will not survive the tab.
+
+## Tuning detection
+
+`DEFAULT_PARAMS` is sized for cockroaches on a kitchen floor at about a
+two-metre camera distance. The knobs worth reaching for first:
+
+- `minArea` and `maxArea` bound a single bug in processing pixels
+- `maxChangedArea` is the whole-frame budget above which a frame is treated as a
+  person or a pet and dropped
+- `diffThreshold` is normally supplied by `calibrate`, which measures this
+  camera's noise floor in this light
+- `darkerThanBackground` assumes dark bugs on a lighter floor; turn it off to
+  track anything that moves
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,46 @@
+{
+    "name": "@mavware/bug-surveillance",
+    "version": "0.1.0",
+    "description": "Overnight bug surveillance from a browser camera: detection, tracking, a local night store, analytics and replay, with no server required.",
+    "keywords": [
+        "camera",
+        "motion-detection",
+        "object-tracking",
+        "computer-vision",
+        "indexeddb",
+        "offline",
+        "pest-control",
+        "surveillance",
+        "browser"
+    ],
+    "license": "MIT",
+    "author": "Michael <mlgreer1430@gmail.com>",
+    "homepage": "https://mavware.github.io/bugtracker/",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/mavware/bugtracker.git",
+        "directory": "packages/surveillance"
+    },
+    "bugs": {
+        "url": "https://github.com/mavware/bugtracker/issues"
+    },
+    "type": "module",
+    "sideEffects": false,
+    "types": "./src/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./src/index.d.ts",
+            "default": "./src/index.js"
+        }
+    },
+    "files": [
+        "src"
+    ],
+    "scripts": {
+        "typecheck": "npx --yes -p typescript@5 tsc -p tsconfig.json"
+    },
+    "publishConfig": {
+        "access": "public",
+        "provenance": true
+    }
+}

package/src/brightness.js

@@ -0,0 +1,65 @@
+// Calibrates against the actual night-time scene: measures mean luminance to
+// warn when the room is too dark, and the sensor noise floor so the motion
+// threshold adapts to this camera in this light.
+export const BRIGHTNESS_WARN = 12;
+export const BRIGHTNESS_BLOCK = 5;
+
+export async function calibrate(camera, durationMs = 3000, sampleIntervalMs = 200) {
+    const luminances = [];
+    const diffs = [];
+    let previous = null;
+
+    const deadline = performance.now() + durationMs;
+
+    while (performance.now() < deadline) {
+        const frame = camera.grabProcessedFrame();
+        const gray = toGrayscale(frame);
+
+        luminances.push(mean(gray));
+
+        if (previous !== null) {
+            for (let i = 0; i < gray.length; i += 7) {
+                diffs.push(Math.abs(gray[i] - previous[i]));
+            }
+        }
+
+        previous = gray;
+        await new Promise((resolve) => setTimeout(resolve, sampleIntervalMs));
+    }
+
+    const meanLuminance = mean(luminances);
+    const diffMean = mean(diffs);
+    const diffStd = Math.sqrt(mean(diffs.map((d) => (d - diffMean) ** 2)));
+
+    return {
+        meanLuminance,
+        tooDark: meanLuminance < BRIGHTNESS_BLOCK,
+        dim: meanLuminance < BRIGHTNESS_WARN,
+        diffThreshold: Math.min(40, Math.max(14, Math.round(diffMean + 4 * diffStd))),
+    };
+}
+
+export function toGrayscale(imageData) {
+    const { data } = imageData;
+    const gray = new Float32Array(data.length / 4);
+
+    for (let i = 0; i < gray.length; i++) {
+        const o = i * 4;
+        gray[i] = 0.299 * data[o] + 0.587 * data[o + 1] + 0.114 * data[o + 2];
+    }
+
+    return gray;
+}
+
+function mean(values) {
+    if (values.length === 0) {
+        return 0;
+    }
+
+    let sum = 0;
+    for (const value of values) {
+        sum += value;
+    }
+
+    return sum / values.length;
+}

package/src/camera.js

@@ -0,0 +1,69 @@
+// Owns the camera stream and the two canvases: a full-resolution one for
+// reference frames and crops, and a downscaled one for per-frame processing.
+export class Camera {
+    constructor(videoElement, processingWidth = 320) {
+        this.video = videoElement;
+        this.processingWidth = processingWidth;
+        this.stream = null;
+        this.fullCanvas = document.createElement('canvas');
+        this.procCanvas = document.createElement('canvas');
+        this.fullCtx = this.fullCanvas.getContext('2d', { willReadFrequently: true });
+        this.procCtx = this.procCanvas.getContext('2d', { willReadFrequently: true });
+    }
+
+    async start() {
+        this.stream = await navigator.mediaDevices.getUserMedia({
+            video: {
+                width: { ideal: 1280 },
+                height: { ideal: 720 },
+                facingMode: 'environment',
+            },
+            audio: false,
+        });
+
+        this.video.srcObject = this.stream;
+        await this.video.play();
+
+        this.frameWidth = this.video.videoWidth;
+        this.frameHeight = this.video.videoHeight;
+        this.fullCanvas.width = this.frameWidth;
+        this.fullCanvas.height = this.frameHeight;
+        this.procCanvas.width = this.processingWidth;
+        this.procCanvas.height = Math.round(this.frameHeight * (this.processingWidth / this.frameWidth));
+        this.scale = this.frameWidth / this.procCanvas.width;
+    }
+
+    stop() {
+        this.stream?.getTracks().forEach((track) => track.stop());
+        this.stream = null;
+    }
+
+    grabProcessedFrame() {
+        this.procCtx.drawImage(this.video, 0, 0, this.procCanvas.width, this.procCanvas.height);
+
+        return this.procCtx.getImageData(0, 0, this.procCanvas.width, this.procCanvas.height);
+    }
+
+    async captureReferenceJpeg() {
+        this.fullCtx.drawImage(this.video, 0, 0, this.frameWidth, this.frameHeight);
+
+        return new Promise((resolve) => this.fullCanvas.toBlob(resolve, 'image/jpeg', 0.85));
+    }
+
+    // Capture a small crop around a full-frame position, returned as raw base64
+    // (no data: prefix) so it can ride inline in a JSON payload.
+    captureCropBase64(centerX, centerY, size = 48) {
+        this.fullCtx.drawImage(this.video, 0, 0, this.frameWidth, this.frameHeight);
+
+        const half = size / 2;
+        const x = Math.max(0, Math.min(this.frameWidth - size, Math.round(centerX - half)));
+        const y = Math.max(0, Math.min(this.frameHeight - size, Math.round(centerY - half)));
+
+        const crop = document.createElement('canvas');
+        crop.width = size;
+        crop.height = size;
+        crop.getContext('2d').drawImage(this.fullCanvas, x, y, size, size, 0, 0, size, size);
+
+        return crop.toDataURL('image/jpeg', 0.7).split(',')[1];
+    }
+}

package/src/captureLogic.js

@@ -0,0 +1,124 @@
+// The decisions a capture page makes that do not depend on where the night is
+// sent: what a calibration result means, how the leave-the-room countdown and
+// the status line read, where the debug boxes land, and how the clock is
+// formatted. The copy ships as exported defaults; functions that return copy
+// take an optional messages object so a consumer can word things their own way.
+
+export const TOO_DARK_MESSAGE =
+    'The scene is pitch black — the camera cannot see anything. Add a nightlight or dim lamp, then start again.';
+
+export const DIM_MESSAGE =
+    'The scene is very dim. Detection will run, but a small extra light source would improve it.';
+
+/**
+ * Detection is frame differencing: anything that moves or changes colour reads as
+ * a bug. A fan, a television, a charger LED or a swaying curtain will fill the
+ * night with false sightings, so the checklist goes in front of the user while
+ * they can still act on it rather than in a page they have already scrolled past.
+ */
+export const PREFLIGHT_MESSAGE = [
+    'Before you start, check the room:',
+    '',
+    '• Turn on a light — a dim lamp or nightlight is enough, but the camera cannot see in pitch darkness.',
+    '• Turn off fans, heaters, and anything else that moves.',
+    '• Turn off televisions and screens, and cover blinking LEDs — changing colour reads as movement.',
+    '• Draw the curtains if you can, so passing headlights do not sweep the room.',
+    '',
+    'Then leave the room. You have five seconds once you press OK.',
+].join('\n');
+
+/**
+ * How long the room is left alone before anything is measured. The person who
+ * pressed start must be out of shot first: in the reference frame they become
+ * part of the background model, and walking out is recorded as a sighting.
+ */
+export const LEAVE_ROOM_SECONDS = 5;
+
+export function countdownMessage(secondsLeft) {
+    return `Leave the room — starting in ${secondsLeft}…`;
+}
+
+/**
+ * A camera check opens the preview on its own, watching nothing and measuring
+ * nothing, purely so the framing can be settled before a night is committed to.
+ */
+export const CAMERA_CHECK_MESSAGE = 'Camera check — aim the device, then start watching.';
+
+/** A toggle's label says what the next press does, not what the camera is doing. */
+export function cameraCheckLabel(previewing, { stop = 'Stop camera', check = 'Check camera' } = {}) {
+    return previewing ? stop : check;
+}
+
+/**
+ * What to say when the screen wake lock could not be taken. Naming the actual
+ * setting matters here: this banner is read on the device itself, in a dark room,
+ * by someone who has to fix it now or lose the night. Menu paths are kept to one
+ * line because they drift between OS versions — the setting names survive longer
+ * than the paths and are what a settings search box will match.
+ */
+export function wakeLockMessage(userAgent = '') {
+    const prefix = 'This device would not keep its screen on by itself — ';
+
+    if (/iPhone|iPad|iPod/i.test(userAgent)) {
+        return `${prefix}set Auto-Lock to Never (Settings › Display & Brightness), and turn Low Power Mode off, which blocks the screen lock on its own.`;
+    }
+
+    if (/Android/i.test(userAgent)) {
+        return `${prefix}set Screen timeout to its longest option (Settings › Display), and keep the device charging.`;
+    }
+
+    return `${prefix}turn off screen sleep in your system power settings so the display stays on all night.`;
+}
+
+/**
+ * Whether a calibrated scene can be watched, and what to tell the user about it.
+ * A pitch-black room is refused outright: with nothing to see, every frame is
+ * sensor noise and the night would be wasted.
+ */
+export function calibrationOutcome(calibration, { tooDark = TOO_DARK_MESSAGE, dim = DIM_MESSAGE } = {}) {
+    if (calibration.tooDark) {
+        return { blocked: true, banner: tooDark };
+    }
+
+    return { blocked: false, banner: calibration.dim ? dim : null };
+}
+
+export const WATCHING_MESSAGE = 'Watching';
+
+export const LARGE_MOTION_MESSAGE = 'Watching — ignoring something too large to be a bug';
+
+/**
+ * The status line while a night runs. When the detector drops a frame for
+ * holding a person or a pet, the page says so: a room full of movement that
+ * reports nothing looks broken otherwise, and the absence of a flurry of
+ * sightings is the whole point.
+ */
+export function watchingState(largeMotion, { watching = WATCHING_MESSAGE, largeMotion: largeMotionMessage = LARGE_MOTION_MESSAGE } = {}) {
+    return largeMotion ? largeMotionMessage : watching;
+}
+
+/**
+ * Detection boxes scaled from the small processing canvas up to the on-screen
+ * overlay, padded slightly so the outline sits around the blob rather than on it.
+ */
+export function overlayBoxes(blobs, { canvasWidth, canvasHeight, procWidth, procHeight }) {
+    const scaleX = canvasWidth / procWidth;
+    const scaleY = canvasHeight / procHeight;
+
+    return blobs.map((blob) => ({
+        x: (blob.box.x - 2) * scaleX,
+        y: (blob.box.y - 2) * scaleY,
+        width: (blob.box.width + 4) * scaleX,
+        height: (blob.box.height + 4) * scaleY,
+    }));
+}
+
+/** Milliseconds as HH:MM:SS, for a clock that may run all night. */
+export function formatClock(ms) {
+    const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+    const hours = String(Math.floor(totalSeconds / 3600)).padStart(2, '0');
+    const minutes = String(Math.floor((totalSeconds % 3600) / 60)).padStart(2, '0');
+    const seconds = String(totalSeconds % 60).padStart(2, '0');
+
+    return `${hours}:${minutes}:${seconds}`;
+}

package/src/detector.js

@@ -0,0 +1,137 @@
+import { toGrayscale } from './brightness.js';
+
+export const DEFAULT_PARAMS = {
+    processFps: 6,
+    procWidth: 320,
+    bgAlpha: 0.03, // slow background adaptation so a pausing bug isn't absorbed instantly
+    diffThreshold: 22, // overridden by calibration
+    minArea: 4,
+    maxArea: 300,
+    // Moving pixels a whole frame may hold before it is dropped as a person, a pet
+    // or the light changing: five roaches at maxArea. A body does not arrive as one
+    // oversized blob but as dozens of roach-sized fragments (folds, edges, patterned
+    // clothing), so per-blob limits never see it — only the frame total does.
+    maxChangedArea: 1200,
+    maxAspectRatio: 5,
+    darkerThanBackground: true, // roaches are dark blobs against the scene
+    darkMargin: 5,
+};
+
+// Frame-differencing blob detector: maintains a running-average background,
+// thresholds the difference, and extracts roach-sized connected components.
+export class Detector {
+    constructor(params = {}) {
+        this.params = { ...DEFAULT_PARAMS, ...params };
+        this.background = null;
+        this.mask = null;
+        this.stack = null;
+        // True while the last frame was dropped for holding something far larger
+        // than a roach, so the page can say so instead of reporting silence.
+        this.largeMotion = false;
+    }
+
+    // Returns blobs as [{cx, cy, area}] in processing-canvas coordinates.
+    detect(imageData) {
+        const { width, height } = imageData;
+        const gray = toGrayscale(imageData);
+
+        if (this.background === null) {
+            this.background = Float32Array.from(gray);
+            this.mask = new Uint8Array(gray.length);
+            this.stack = new Int32Array(gray.length);
+
+            return [];
+        }
+
+        const { bgAlpha, diffThreshold, darkerThanBackground, darkMargin, maxChangedArea } = this.params;
+        const background = this.background;
+        const mask = this.mask;
+        let changedArea = 0;
+
+        for (let i = 0; i < gray.length; i++) {
+            const diff = gray[i] - background[i];
+            const moving = Math.abs(diff) > diffThreshold;
+            const changed = moving && (!darkerThanBackground || diff < -darkMargin);
+            mask[i] = changed ? 1 : 0;
+            changedArea += changed ? 1 : 0;
+            background[i] += bgAlpha * diff;
+        }
+
+        // Something that big is not roaches, however many fragments it breaks into.
+        // The background keeps adapting underneath it on purpose: a pet that curls
+        // up and sleeps, or a chair left in shot, is absorbed within seconds and
+        // detection resumes around it, rather than the night going blind until it
+        // moves again.
+        this.largeMotion = changedArea > maxChangedArea;
+
+        if (this.largeMotion) {
+            return [];
+        }
+
+        return this.extractBlobs(mask, width, height);
+    }
+
+    reset() {
+        this.background = null;
+        this.largeMotion = false;
+    }
+
+    // Iterative flood-fill connected components over the binary mask.
+    extractBlobs(mask, width, height) {
+        const { minArea, maxArea, maxAspectRatio } = this.params;
+        const blobs = [];
+        const stack = this.stack;
+
+        for (let start = 0; start < mask.length; start++) {
+            if (mask[start] !== 1) {
+                continue;
+            }
+
+            let stackSize = 0;
+            stack[stackSize++] = start;
+            mask[start] = 2;
+
+            let area = 0;
+            let sumX = 0;
+            let sumY = 0;
+            let minX = width;
+            let maxX = 0;
+            let minY = height;
+            let maxY = 0;
+
+            while (stackSize > 0) {
+                const index = stack[--stackSize];
+                const x = index % width;
+                const y = (index / width) | 0;
+
+                area++;
+                sumX += x;
+                sumY += y;
+                if (x < minX) minX = x;
+                if (x > maxX) maxX = x;
+                if (y < minY) minY = y;
+                if (y > maxY) maxY = y;
+
+                if (x > 0 && mask[index - 1] === 1) { mask[index - 1] = 2; stack[stackSize++] = index - 1; }
+                if (x < width - 1 && mask[index + 1] === 1) { mask[index + 1] = 2; stack[stackSize++] = index + 1; }
+                if (y > 0 && mask[index - width] === 1) { mask[index - width] = 2; stack[stackSize++] = index - width; }
+                if (y < height - 1 && mask[index + width] === 1) { mask[index + width] = 2; stack[stackSize++] = index + width; }
+            }
+
+            const boxWidth = maxX - minX + 1;
+            const boxHeight = maxY - minY + 1;
+            const aspect = Math.max(boxWidth, boxHeight) / Math.max(1, Math.min(boxWidth, boxHeight));
+
+            if (area >= minArea && area <= maxArea && aspect <= maxAspectRatio) {
+                blobs.push({
+                    cx: sumX / area,
+                    cy: sumY / area,
+                    area,
+                    box: { x: minX, y: minY, width: boxWidth, height: boxHeight },
+                });
+            }
+        }
+
+        return blobs;
+    }
+}