@camstack/types 1.2.404 → 1.2.405

package/dist/pipeline/second-pass/small-subject-recovery.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Small-subject recovery — a second detector pass at NATIVE resolution on
+ * the moving regions the full-frame pass did not account for.
+ *
+ * ## Why
+ *
+ * The first-level detector sees the frame at its input size (320 px on every
+ * hardware-aware default). A 4K frame is reduced 12×: a dog measured at
+ * 89–277 px in the source is 7–38 px for the model and is not emitted. Camera 615, six
+ * instants with a dog in the scene, five with no `animal` detection at all —
+ * nothing downstream (tracker, gate, notifications) ever saw a subject. The
+ * confirmation gate, which re-runs the same detector on a 320 px native crop
+ * of the PERSON, found the dog at 0.74–0.91 as `bestIncompatibleClass`. The
+ * measurement that decided the constants below is
+ * `docs/benchmarks/pipeline-frame-model-eval.md`, case `miss-dog-615`: a
+ * 640–800 px native square around the moving region brings the dog to
+ * 0.82–0.91 with the SAME 320 model; a 1280 px square loses it again.
+ *
+ * ## What this is NOT (D52)
+ *
+ * Not a detail/CLIP crop. `deriveDetailCropRect` derives the rectangle a
+ * detail or embedding step is fed from a KNOWN subject box, and one vector
+ * index tolerates exactly one such derivation. This module derives a square
+ * from a MOTION region, before any subject exists, for the FIRST-LEVEL
+ * detector; its output is a detection, never a vector. Nothing here may be
+ * reused for a detail crop, and nothing here calls the detail derivation.
+ *
+ * ## When it runs — NOT only when the frame is empty
+ *
+ * The trigger is an UNCOVERED MOTION REGION, deliberately broader than "the
+ * full-frame pass found nothing". Camera 615, 2026-09-06 19:54:33 local: the
+ * gate DID confirm an `animal` birth (bestScore 0.8983) — and the track held
+ * 9 positions over 1 666 ms, then coasted out its `maxMissedMs` (4 000 ms) and
+ * died at 19:54:39, before the dog reached the Aiuola zone. Both of its object
+ * events carry `zones: []`, while in the same seconds the animal was in fact
+ * at x≈3200, inside the zone. So the defect is not only "the subject is never
+ * born" — it is "the subject is born and then the full-frame pass stops seeing
+ * it", and a pass gated on "no detections at all" would not have run on a
+ * single one of those frames, because the PERSON was still detected.
+ *
+ * Gating on the motion region instead makes the pass fire in both cases with
+ * one rule: a moving thing the full-frame boxes do not account for. A live
+ * track feeding on recovered boxes needs one hit per `maxMissedMs` to survive
+ * and `minHits` (3) to be born; at {@link RECOVERY_MIN_INTERVAL_MS} the pass
+ * supplies 2/s, which is 8× the coasting budget and births a subject in 1.5 s.
+ *
+ * ## Where
+ *
+ * In the runner, in-process, on the frame the full pass just ran on. The
+ * pixels come from the same process-local `frameRef` lease the full pass
+ * used; the crop is resolved as one compressed ≤640 px view. Frames never
+ * cross a process boundary at frame rate (D9/D18) — a second crop of the
+ * same frame on the same channel does not change that.
+ *
+ * Pure: no runner state, no IPC, no pixels. The runner wires the lease, the
+ * executor call and the rate limit around it.
+ *
+ * Lives in `@camstack/types` so the live runner (`addon-pipeline`) and the
+ * offline accuracy evaluation (`addon-benchmark`) plan the SAME crops: one
+ * module, two callers, no copy to drift.
+ */
+import type { ObjectDetection } from '../../types/detection.js';
+import type { PipelineStepInputOutput } from '../../capabilities/pipeline-executor.cap.js';
+/** The object-detection step id — the first-level detector both recipes run. */
+export declare const OBJECT_DETECTION_STEP_ID = "object-detection";
+/** Fraction of a frame, `[0, 1]` on both axes. */
+export interface NormalizedRect {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export interface FrameDims {
+    readonly width: number;
+    readonly height: number;
+}
+/** A square of the NATIVE frame, in native pixels. */
+export interface RecoveryCrop {
+    readonly left: number;
+    readonly top: number;
+    readonly side: number;
+}
+/**
+ * Smallest crop side, native pixels. Below this the model no longer
+ * magnifies enough to matter on a 4K frame, and on a 1080p frame 640 is
+ * already a third of the picture. Measured: 480–800 px all recover the dog.
+ */
+export declare const RECOVERY_CROP_MIN_SIDE_PX = 640;
+/**
+ * Largest crop side. A 320 model on a 1024 px square is a 3.2× reduction and
+ * scored the dog at 0.52–0.76; at 1280 px it was absent again. A region wider
+ * than this is tiled, never zoomed out.
+ */
+export declare const RECOVERY_CROP_MAX_SIDE_PX = 800;
+/** Context around the region before squaring, as a fraction of its larger side. */
+export declare const RECOVERY_CROP_PADDING_RATIO = 0.25;
+/**
+ * The view the crop is resolved at, compressed. Never larger than the crop
+ * (the floor is {@link RECOVERY_CROP_MIN_SIDE_PX}), so it never upscales, and
+ * the model letterboxes it to its own input from here as it does the frame.
+ */
+export declare const RECOVERY_VIEW_PX = 640;
+/**
+ * Crops per frame. Each is one more inference on the same pool (15–25 ms on
+ * CoreML for a 640 view); two cover a person-and-dog blob and a second mover.
+ */
+export declare const RECOVERY_MAX_CROPS_PER_FRAME = 2;
+/**
+ * The pass runs at most this often per camera — at 10 fps that is one frame
+ * in five. A subject the full pass misses is missed for seconds, not for one
+ * frame, so the recovery does not need every frame to find it.
+ *
+ * The floor under this number is the tracker: a track coasts for
+ * `maxMissedMs` (4 000 ms by default) before it is dropped, so 2 recoveries a
+ * second keep a subject the full-frame pass has lost ALIVE with 8× margin,
+ * and reach `minHits` (3) in 1.5 s. Raising it past ~1 300 ms would start to
+ * lose tracks between passes.
+ */
+export declare const RECOVERY_MIN_INTERVAL_MS = 500;
+/**
+ * A region larger than this share of the frame is not a small subject: a
+ * lighting change, a car filling the picture, a person at the lens. The
+ * full-frame pass already sees those at scale.
+ */
+export declare const RECOVERY_MAX_REGION_FRAME_FRACTION = 0.25;
+/**
+ * How much of a region must lie OUTSIDE every full-frame detection for the
+ * pass to run on it. A person's own blob (dilated, with shadow) is covered
+ * 70–90% by the person box; a person-and-dog blob is covered ~55% by it.
+ */
+export declare const RECOVERY_MIN_UNCOVERED_FRACTION = 0.35;
+/** Motion regions older than this describe a different frame. */
+export declare const RECOVERY_MOTION_MAX_AGE_MS = 2000;
+/** A recovered box overlapping a same-class full-frame box this much is the same subject. */
+export declare const RECOVERY_FUSE_IOU = 0.5;
+/**
+ * A recovered box CONTAINED this much in a same-class full-frame box is a part
+ * of it — a torso the crop cut out of a person the full pass already has.
+ */
+export declare const RECOVERY_FUSE_CONTAINMENT = 0.7;
+/** A box within this many crop-view pixels of the crop edge was clipped by it. */
+export declare const RECOVERY_EDGE_MARGIN_PX = 2;
+/** Area of a normalised rectangle, never negative. Shared with the D396 recipe. */
+export declare function normalizedArea(r: NormalizedRect): number;
+/**
+ * THE square-placement rule of this pass — one owner, shared by both recipes.
+ *
+ * A crop is a square of `side` native pixels centred where it can be and slid
+ * inside the frame where it cannot. Both region rules place their squares
+ * through this function so a crop means the same rectangle whichever rule
+ * chose the region.
+ */
+export declare function squareAround(centreX: number, centreY: number, side: number, native: FrameDims): RecoveryCrop;
+export interface RecoveryPlanInput {
+    /** Motion regions of this frame, normalised. */
+    readonly regions: readonly NormalizedRect[];
+    /** The full-frame pass's boxes, normalised. */
+    readonly detections: readonly NormalizedRect[];
+    /** The NATIVE frame the crops are cut from. */
+    readonly native: FrameDims;
+}
+/**
+ * The crops the second pass runs on this frame — possibly none.
+ *
+ * A region qualifies when it is small (`RECOVERY_MAX_REGION_FRAME_FRACTION`)
+ * and mostly uncovered by the full-frame boxes
+ * (`RECOVERY_MIN_UNCOVERED_FRACTION`). Qualifying regions are served largest
+ * uncovered area first under `RECOVERY_MAX_CROPS_PER_FRAME`; a crop whose
+ * centre already lies inside a planned crop is folded into it. A frame that
+ * cannot hold the smallest crop yields nothing: it is already seen at scale.
+ */
+/** Why a motion region is, or is not, worth a native crop. */
+export type RecoveryRegionVerdict = 'eligible' | 'too-large' | 'covered';
+/** How the regions of one frame fell against the two gates. */
+export interface RecoverySkipCounts {
+    readonly tooLarge: number;
+    readonly covered: number;
+    readonly eligible: number;
+}
+/**
+ * WHY A FRAME PLANNED NO CROP, AS A NUMBER (D378).
+ *
+ * The pass report counts the passes that RAN, so "the second pass stops running
+ * when a person is beside the dog" — a plausible reading of
+ * {@link RECOVERY_MAX_REGION_FRAME_FRACTION} and
+ * {@link RECOVERY_MIN_UNCOVERED_FRACTION}, and a live hypothesis on camera 615
+ * — could not be confirmed or killed from the logs at all. This classifies the
+ * regions a frame offered, against the same predicate the planner filters on.
+ */
+export declare function countRecoverySkips(input: RecoveryPlanInput): RecoverySkipCounts;
+export declare function planRecoveryCrops(input: RecoveryPlanInput): readonly RecoveryCrop[];
+/**
+ * Boxes the executor produced on the crop VIEW → the result's own space.
+ *
+ * Three spaces meet here: the view the model saw (`view`, ≤640 px), the native
+ * square it was cut from (`crop`, native px) and the space the full-frame
+ * result reports in (`result`, native px on the `frameRef` path, the inline
+ * ≤640 view otherwise). A box touching the view edge was clipped by the crop
+ * and is dropped: half a person is not a person, and the tracker would take
+ * the half as the whole.
+ */
+export declare function remapCropDetections(detections: readonly ObjectDetection[], crop: RecoveryCrop, view: FrameDims, result: FrameDims, native: FrameDims): readonly ObjectDetection[];
+/**
+ * Class-aware NMS of the recovered boxes against the full-frame ones. Every
+ * full-frame box is kept as it is — the second pass only ADDS. A recovered box
+ * is added when no full-frame box of the same macro class is the same subject
+ * (`RECOVERY_FUSE_IOU`) or contains it (`RECOVERY_FUSE_CONTAINMENT`). Ids are
+ * re-minted so a crop's `d0` cannot collide with the frame's.
+ */
+export declare function fuseRecoveredDetections(full: readonly ObjectDetection[], recovered: readonly ObjectDetection[]): readonly ObjectDetection[];
+/**
+ * The step the second pass runs: the enabled first-level object detector of
+ * the camera's own tree, with its own model and no children. Same model as
+ * the full pass so a recovered box is comparable to a full-frame one.
+ */
+export declare function selectRecoveryStep(steps: readonly PipelineStepInputOutput[]): PipelineStepInputOutput | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.2.404",
+  "version": "1.2.405",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",