@camstack/system 1.2.390 → 1.2.391

package/dist/builtins/autotrack/autotrack-config.d.ts

@@ -1,89 +1,89 @@
 /**
- * Tuning constants for the emulated PTZ autotrack.
- *
- * Everything here is a number the OPERATOR does not set: the dead zone, the
- * settle zone, the command ceiling, the pulse dead time, the refresh cadences.
- * D520 kept them out of the settings surface on purpose — they are the
- * behaviour of the control loop, not a preference, and a camera whose dead zone
- * somebody widened by hand is a camera nobody can reason about.
- *
- * What IS per camera lives with the record (`autotrack-cameras.ts`): the switch,
- * the target class and the disappear delay, all read through the cap's own
- * settings so there is one place an operator changes them.
- */
+* Tuning constants for the emulated PTZ autotrack.
+*
+* Everything here is a number the OPERATOR does not set: the dead zone, the
+* settle zone, the command ceiling, the pulse dead time, the refresh cadences.
+* D520 kept them out of the settings surface on purpose — they are the
+* behaviour of the control loop, not a preference, and a camera whose dead zone
+* somebody widened by hand is a camera nobody can reason about.
+*
+* What IS per camera lives with the record (`autotrack-cameras.ts`): the switch,
+* the target class and the disappear delay, all read through the cap's own
+* settings so there is one place an operator changes them.
+*/
 /**
- * ## The constants that used to live here
- *
- * `AUTOTRACK_ARMED` and `AUTOTRACK_TARGET_DEVICE_ID` were the whole protection
- * of the measurement slice: arming was a deploy-shaped act because there was no
- * switch to do it with. There is one now — the emulation registers
- * `ptz-autotrack` as a wrapper the operator BINDS per camera and switches on
- * through the cap's own `setEnabled` (D62: one function, one switch). The
- * protection is no longer a constant; it is that a camera must be both bound
- * and switched on, and that the loop still refuses to move without
- * `moveImpulseMs` or while the camera's native autotrack is armed (D520).
- *
- * `AUTOTRACK_TARGET_CLASS` went the same way: the class is per camera now,
- * from the cap's `targetType` setting (`autotrack-cameras.ts`).
- */
+* ## The constants that used to live here
+*
+* `AUTOTRACK_ARMED` and `AUTOTRACK_TARGET_DEVICE_ID` were the whole protection
+* of the measurement slice: arming was a deploy-shaped act because there was no
+* switch to do it with. There is one now — the emulation registers
+* `ptz-autotrack` as a wrapper the operator BINDS per camera and switches on
+* through the cap's own `setEnabled` (D62: one function, one switch). The
+* protection is no longer a constant; it is that a camera must be both bound
+* and switched on, and that the loop still refuses to move without
+* `moveImpulseMs` or while the camera's native autotrack is armed (D520).
+*
+* `AUTOTRACK_TARGET_CLASS` went the same way: the class is per camera now,
+* from the cap's `targetType` setting (`autotrack-cameras.ts`).
+*/
 /** Signed single-axis step handed to `ptz.move` — a DIRECTION, not a delta.
- *  Every provider reads the sign and ignores the magnitude (reolink:
- *  `pan > 0 ? 'Right' : 'Left'`), so only -1 / 0 / +1 are meaningful. */
+*  Every provider reads the sign and ignores the magnitude (reolink:
+*  `pan > 0 ? 'Right' : 'Left'`), so only -1 / 0 / +1 are meaningful. */
 export type PtzAxisStep = -1 | 0 | 1;
 /** Tuning of the control loop. Every field is a time or a fraction; nothing
- *  here is derived from `detectionFps` — see {@link maxCommandsPerSecond}. */
+*  here is derived from `detectionFps` — see {@link maxCommandsPerSecond}. */
 export interface AutotrackLoopConfig {
-    /**
-     * Width/height of the central "do nothing" box, as a fraction of the frame.
-     * `0.5` = the central 50%: a correction starts only once the subject's
-     * centre leaves it (|error| > 0.25 on that axis).
-     */
-    readonly deadZoneFraction: number;
-    /**
-     * Width/height of the TIGHTER box that ENDS a correction, as a fraction of
-     * the frame. Must be smaller than {@link deadZoneFraction}.
-     *
-     * This is the anti-overshoot rule: the loop stops correcting BEFORE the
-     * subject reaches the centre. Aiming at the centre with an estimated gain
-     * overshoots, and an overshoot on the next frame reverses the sign — that is
-     * the oscillation this box exists to prevent.
-     */
-    readonly settleZoneFraction: number;
-    /**
-     * Hard ceiling on commands issued to the camera, in commands per second,
-     * owned by the LOOP.
-     *
-     * Explicitly NOT derived from the analysis rate. `frame-tracked` arrives at
-     * 1–10 Hz; at 10 Hz a per-frame command would be ~10 commands/s, an order of
-     * magnitude above what the hardware takes. The ceiling is measured, in-repo:
-     * a Reolink E1 Outdoor PoE rejects a command issued while the previous one
-     * is still travelling with `response_code 400` — presses 1.2 s apart were
-     * REJECTED, 3 s apart were ACCEPTED (`reolink-camera.ts`, `runZoom`). `1/3`
-     * is that 3 s, and it is the gate that binds in practice.
-     */
-    readonly maxCommandsPerSecond: number;
-    /**
-     * Extra silence after a pulse is expected to have FINISHED, ms.
-     *
-     * The dead time after a command is `moveImpulseMs + pulseSettleMs`: the head
-     * is still travelling for the first part and the detector has not yet seen
-     * the new framing for the second. Commanding inside it measures an error
-     * that the in-flight pulse has already corrected.
-     */
-    readonly pulseSettleMs: number;
-    /**
-     * How long the chosen target may be absent before it is released and the
-     * head is sent home, ms. Also the silence watchdog's budget: if
-     * `frame-tracked` stops arriving entirely, the same delay elapses and the
-     * same release happens — off the event path, by timer.
-     */
-    readonly disappearDelayMs: number;
-    /** Normalized speed (0..1) handed to `ptz.move`. */
-    readonly speed: number;
-    /** How often the off-event-path mirror re-reads `ptz.getOptions` and the
-     *  native-autotrack state, ms. Never on the event path (D49). */
-    readonly mirrorRefreshMs: number;
-    /** How often the measurement aggregates are summarized to the log, ms. */
-    readonly measurementSummaryMs: number;
+	/**
+	* Width/height of the central "do nothing" box, as a fraction of the frame.
+	* `0.5` = the central 50%: a correction starts only once the subject's
+	* centre leaves it (|error| > 0.25 on that axis).
+	*/
+	readonly deadZoneFraction: number;
+	/**
+	* Width/height of the TIGHTER box that ENDS a correction, as a fraction of
+	* the frame. Must be smaller than {@link deadZoneFraction}.
+	*
+	* This is the anti-overshoot rule: the loop stops correcting BEFORE the
+	* subject reaches the centre. Aiming at the centre with an estimated gain
+	* overshoots, and an overshoot on the next frame reverses the sign — that is
+	* the oscillation this box exists to prevent.
+	*/
+	readonly settleZoneFraction: number;
+	/**
+	* Hard ceiling on commands issued to the camera, in commands per second,
+	* owned by the LOOP.
+	*
+	* Explicitly NOT derived from the analysis rate. `frame-tracked` arrives at
+	* 1–10 Hz; at 10 Hz a per-frame command would be ~10 commands/s, an order of
+	* magnitude above what the hardware takes. The ceiling is measured, in-repo:
+	* a Reolink E1 Outdoor PoE rejects a command issued while the previous one
+	* is still travelling with `response_code 400` — presses 1.2 s apart were
+	* REJECTED, 3 s apart were ACCEPTED (`reolink-camera.ts`, `runZoom`). `1/3`
+	* is that 3 s, and it is the gate that binds in practice.
+	*/
+	readonly maxCommandsPerSecond: number;
+	/**
+	* Extra silence after a pulse is expected to have FINISHED, ms.
+	*
+	* The dead time after a command is `moveImpulseMs + pulseSettleMs`: the head
+	* is still travelling for the first part and the detector has not yet seen
+	* the new framing for the second. Commanding inside it measures an error
+	* that the in-flight pulse has already corrected.
+	*/
+	readonly pulseSettleMs: number;
+	/**
+	* How long the chosen target may be absent before it is released and the
+	* head is sent home, ms. Also the silence watchdog's budget: if
+	* `frame-tracked` stops arriving entirely, the same delay elapses and the
+	* same release happens — off the event path, by timer.
+	*/
+	readonly disappearDelayMs: number;
+	/** Normalized speed (0..1) handed to `ptz.move`. */
+	readonly speed: number;
+	/** How often the off-event-path mirror re-reads `ptz.getOptions` and the
+	*  native-autotrack state, ms. Never on the event path (D49). */
+	readonly mirrorRefreshMs: number;
+	/** How often the measurement aggregates are summarized to the log, ms. */
+	readonly measurementSummaryMs: number;
 }
 export declare const DEFAULT_AUTOTRACK_LOOP_CONFIG: AutotrackLoopConfig;

package/dist/builtins/autotrack/autotrack-decision.d.ts

@@ -1,99 +1,86 @@
-import { AutotrackLoopConfig, PtzAxisStep } from './autotrack-config.js';
-import { NormalizedError } from './frame-error.js';
 /**
- * What the loop knows about the camera's NATIVE autotrack, from the
- * off-event-path mirror.
- *
- * Native and emulated are two implementations of ONE function and must never
- * be two switches an operator can set to disagree (D62). Until that single
- * switch exists, this slice refuses to move a head whose firmware may also be
- * moving it — and `unknown` refuses too, because not-yet-read must not look
- * like not-enabled (D315, D393).
- */
-export type NativeAutotrackState = 
-/** The camera has no `ptz-autotrack` binding at all. No conflict possible. */
-'absent'
-/** Bound and reported OFF. */
- | 'disabled'
-/** Bound and reported ON — the firmware is driving this head. */
- | 'enabled'
-/** Never successfully read, or the last read failed. */
- | 'unknown';
+* `decideAutotrack` — the whole control loop, as one pure function.
+*
+* Error in, action out, clock injected (`nowMs` is a parameter and is never
+* read inside), state immutable (a new state object comes back; the input is
+* never mutated). Same shape as `FrameGovernor` / `MotionSettleGovernor`.
+*
+* ## The one property that makes this safe over droppable telemetry
+*
+* The only command this loop ever issues to move the head is `ptz.move`, which
+* is a SELF-TERMINATING pulse on every driver (reolink 200 ms, amcrest 350,
+* hikvision 500, onvif 1000 — readable as `ptz.getOptions().moveImpulseMs`).
+* `continuousMove` would need a matching `stop`, and its `stop` would travel
+* over an event-driven loop whose input is telemetry and MAY BE DROPPED (D8,
+* D11). A dropped frame would then leave the head panning until someone
+* noticed. With a pulse, a dead event stream means the head stops by itself.
+*
+* That is also why {@link AutotrackDecisionInput.moveImpulseMs} being `null`
+* REFUSES rather than substituting a default: a driver that cannot say how
+* long its pulse lasts has not told us the head stops, and this loop is only
+* safe because it does (D393 — a measurement that failed is `null`).
+*/
+import type { AutotrackLoopConfig, PtzAxisStep } from "./autotrack-config.js";
+import type { NormalizedError } from "./frame-error.js";
+/**
+* What the loop knows about the camera's NATIVE autotrack, from the
+* off-event-path mirror.
+*
+* Native and emulated are two implementations of ONE function and must never
+* be two switches an operator can set to disagree (D62). Until that single
+* switch exists, this slice refuses to move a head whose firmware may also be
+* moving it — and `unknown` refuses too, because not-yet-read must not look
+* like not-enabled (D315, D393).
+*/
+export type NativeAutotrackState = "absent" | "disabled" | "enabled" | "unknown";
 /** Why the loop did NOT move. Every one of these is logged, per frame, with
- *  the measured error: a loop that decides not to move must not be
- *  indistinguishable from a dead one (D391). */
-export type AutotrackHoldReason = 
-/** `AUTOTRACK_ARMED` is false, or no target camera is configured. */
-'disarmed'
-/** No target has ever been held. */
- | 'no-target'
-/** The held target was absent from this frame, inside its disappear delay. */
- | 'target-absent'
-/** The target is gone and the head has already been sent home. */
- | 'home-already-issued'
-/** The frame did not say how big it is — the error is unknowable (D393). */
- | 'frame-geometry-unknown'
-/** The subject's centre is inside the central dead zone. THE NORMAL CASE. */
- | 'inside-dead-zone'
-/** A correction was running and the subject reached the tighter inner box.
- *  The correction ENDS here, deliberately short of the centre. */
- | 'settled'
-/** The driver does not report `moveImpulseMs`, so nothing proves the pulse
- *  self-terminates. */
- | 'impulse-duration-unknown'
-/** The camera's own autotrack is armed — two sources, one mechanism. */
- | 'native-autotrack-enabled'
-/** The camera's own autotrack state has never been read. */
- | 'native-autotrack-unknown'
-/** The previous pulse is still travelling, or the detector has not yet seen
- *  the framing it produced. */
- | 'pulse-dead-time'
-/** The loop's own commands-per-second ceiling. */
- | 'rate-limited';
+*  the measured error: a loop that decides not to move must not be
+*  indistinguishable from a dead one (D391). */
+export type AutotrackHoldReason = "disarmed" | "no-target" | "target-absent" | "home-already-issued" | "frame-geometry-unknown" | "inside-dead-zone" | "settled" | "impulse-duration-unknown" | "native-autotrack-enabled" | "native-autotrack-unknown" | "pulse-dead-time" | "rate-limited";
 export type AutotrackDecision = {
-    readonly action: 'hold';
-    readonly reason: AutotrackHoldReason;
+	readonly action: "hold";
+	readonly reason: AutotrackHoldReason;
 } | {
-    readonly action: 'pulse';
-    readonly pan: PtzAxisStep;
-    readonly tilt: PtzAxisStep;
-    readonly speed: number;
+	readonly action: "pulse";
+	readonly pan: PtzAxisStep;
+	readonly tilt: PtzAxisStep;
+	readonly speed: number;
 } | {
-    readonly action: 'home';
-    readonly reason: 'target-gone';
+	readonly action: "home";
+	readonly reason: "target-gone";
 };
 export interface AutotrackLoopState {
-    /** A correction is in progress on this axis: it ends at the tighter inner
-     *  box, not at the dead zone it started outside of. */
-    readonly correctingX: boolean;
-    readonly correctingY: boolean;
-    /** When the last command (pulse or home) was issued. `null` = never. */
-    readonly lastCommandAtMs: number | null;
-    /** Whether the head has already been sent home for the current absence. */
-    readonly homeIssued: boolean;
+	/** A correction is in progress on this axis: it ends at the tighter inner
+	*  box, not at the dead zone it started outside of. */
+	readonly correctingX: boolean;
+	readonly correctingY: boolean;
+	/** When the last command (pulse or home) was issued. `null` = never. */
+	readonly lastCommandAtMs: number | null;
+	/** Whether the head has already been sent home for the current absence. */
+	readonly homeIssued: boolean;
 }
 export declare const INITIAL_AUTOTRACK_LOOP_STATE: AutotrackLoopState;
 /** The held target as this frame saw it. `error` is `null` when the frame's
- *  geometry was unreadable — present-but-unmeasurable, which is NOT absent. */
+*  geometry was unreadable — present-but-unmeasurable, which is NOT absent. */
 export interface AutotrackTargetFrame {
-    readonly trackId: string;
-    readonly error: NormalizedError | null;
+	readonly trackId: string;
+	readonly error: NormalizedError | null;
 }
 export interface AutotrackDecisionInput {
-    readonly nowMs: number;
-    /** Armed AND pointed at a camera. False ⇒ the loop only measures. */
-    readonly armed: boolean;
-    /** The held target if it was OBSERVED on this frame, else `null`. */
-    readonly target: AutotrackTargetFrame | null;
-    /** When the held target was last observed. `null` = nothing held. */
-    readonly targetLastSeenAtMs: number | null;
-    /** `ptz.getOptions().moveImpulseMs`, from the mirror. `null` = unknown. */
-    readonly moveImpulseMs: number | null;
-    readonly nativeAutotrack: NativeAutotrackState;
-    readonly config: AutotrackLoopConfig;
+	readonly nowMs: number;
+	/** Armed AND pointed at a camera. False ⇒ the loop only measures. */
+	readonly armed: boolean;
+	/** The held target if it was OBSERVED on this frame, else `null`. */
+	readonly target: AutotrackTargetFrame | null;
+	/** When the held target was last observed. `null` = nothing held. */
+	readonly targetLastSeenAtMs: number | null;
+	/** `ptz.getOptions().moveImpulseMs`, from the mirror. `null` = unknown. */
+	readonly moveImpulseMs: number | null;
+	readonly nativeAutotrack: NativeAutotrackState;
+	readonly config: AutotrackLoopConfig;
 }
 export interface AutotrackDecisionResult {
-    readonly state: AutotrackLoopState;
-    readonly decision: AutotrackDecision;
+	readonly state: AutotrackLoopState;
+	readonly decision: AutotrackDecision;
 }
 export declare function decideAutotrack(state: AutotrackLoopState, input: AutotrackDecisionInput): AutotrackDecisionResult;

package/dist/builtins/autotrack/autotrack-loop.d.ts

@@ -1,75 +1,95 @@
-import { IScopedLogger, ObjectDetection } from '@camstack/types';
-import { AutotrackLoopConfig, PtzAxisStep } from './autotrack-config.js';
-import { MirrorRefreshOutcome, PtzMirror } from './ptz-mirror.js';
-import { TargetCandidate } from './target-selection.js';
+/**
+* `AutotrackLoop` — the thin wiring between a `frame-tracked` payload and the
+* pure decision function, plus the two measurements.
+*
+* Everything with a decision in it lives in `autotrack-decision.ts` /
+* `target-selection.ts` and is pure; this class owns the state those functions
+* are threaded through, the clock (injected), and the logging. It performs no
+* I/O itself — commands go out through {@link AutotrackCommands}, which the
+* addon fills with `ctx.api.ptz.*`.
+*
+* ## The silence watchdog is not optional
+*
+* The input is TELEMETRY and may be dropped (D8, D11). A subject does not
+* disappear because the bus did, so a target released only by "a frame said it
+* was gone" would be held forever the moment the stream stopped. {@link tick}
+* runs off the event path, applies the SAME disappear delay to the silence,
+* and releases + homes. It is also what makes the D49 shape work: the gate
+* ("am I tracking") is in-memory state refreshed off the event path, and a
+* failed mirror read never spells the subject's disappearance.
+*/
+import type { IScopedLogger, ObjectDetection } from "@camstack/types";
+import type { AutotrackLoopConfig, PtzAxisStep } from "./autotrack-config.js";
+import { type MirrorRefreshOutcome, type PtzMirror } from "./ptz-mirror.js";
+import { type TargetCandidate } from "./target-selection.js";
 export interface PulseCommand {
-    readonly deviceId: number;
-    readonly pan: PtzAxisStep;
-    readonly tilt: PtzAxisStep;
-    readonly speed: number;
+	readonly deviceId: number;
+	readonly pan: PtzAxisStep;
+	readonly tilt: PtzAxisStep;
+	readonly speed: number;
 }
 /** The only way this loop touches the camera. One self-terminating pulse, or
- *  home. There is deliberately no `continuousMove` and no `stop`. */
+*  home. There is deliberately no `continuousMove` and no `stop`. */
 export interface AutotrackCommands {
-    pulse(command: PulseCommand): Promise<void>;
-    goHome(deviceId: number): Promise<void>;
+	pulse(command: PulseCommand): Promise<void>;
+	goHome(deviceId: number): Promise<void>;
 }
 export interface AutotrackLoopDeps {
-    readonly deviceId: number;
-    readonly targetClass: string;
-    readonly armed: boolean;
-    readonly config: AutotrackLoopConfig;
-    readonly logger: IScopedLogger;
-    readonly commands: AutotrackCommands;
-    readonly now: () => number;
+	readonly deviceId: number;
+	readonly targetClass: string;
+	readonly armed: boolean;
+	readonly config: AutotrackLoopConfig;
+	readonly logger: IScopedLogger;
+	readonly commands: AutotrackCommands;
+	readonly now: () => number;
 }
 /** The subset of the `frame-tracked` payload this loop reads. Named so the
- *  tests can build one without the event envelope. */
+*  tests can build one without the event envelope. */
 export interface TrackedFrame {
-    readonly deviceId: number;
-    readonly timestamp: number;
-    readonly frameWidth: number;
-    readonly frameHeight: number;
-    readonly detections: readonly ObjectDetection[];
+	readonly deviceId: number;
+	readonly timestamp: number;
+	readonly frameWidth: number;
+	readonly frameHeight: number;
+	readonly detections: readonly ObjectDetection[];
 }
 /**
- * Candidates of the configured class on this frame.
- *
- * A detection counts only when it carries a `track` — `buildOverlayDetections`
- * attaches one exactly to the boxes a tracked entry was ASSOCIATED with on this
- * frame, so this set is the observed-and-tracked set and nothing else.
- */
+* Candidates of the configured class on this frame.
+*
+* A detection counts only when it carries a `track` — `buildOverlayDetections`
+* attaches one exactly to the boxes a tracked entry was ASSOCIATED with on this
+* frame, so this set is the observed-and-tracked set and nothing else.
+*/
 export declare function candidatesFromFrame(detections: readonly ObjectDetection[], targetClass: string): readonly TargetCandidate[];
 export declare class AutotrackLoop {
-    private readonly deps;
-    private selection;
-    private loopState;
-    private mirror;
-    private latency;
-    private presence;
-    private lastFrameAtMs;
-    private lastSummaryAtMs;
-    constructor(deps: AutotrackLoopDeps);
-    /** Read-only view of the mirror, for the addon's startup log. */
-    get ptzMirror(): PtzMirror;
-    /** Fold one refresh outcome into the mirror. Called by the TIMER, never from
-     *  {@link onFrame}. */
-    applyMirror(outcome: MirrorRefreshOutcome): void;
-    /** One analysed frame. Measures first, then decides. */
-    onFrame(frame: TrackedFrame): Promise<void>;
-    /**
-     * Off-event-path tick: the silence watchdog.
-     *
-     * Evaluates the SAME disappear delay against the time since the last frame.
-     * A stream that died is a target that is gone, and the head goes home —
-     * which is also the only thing that would otherwise never happen, because
-     * every other release is driven by a frame arriving.
-     */
-    tick(): Promise<void>;
-    /** Emit the aggregates now, whatever the schedule says. Used at shutdown so
-     *  a short run still reports what it measured. */
-    logSummary(): void;
-    private maybeSummarize;
-    private dispatch;
-    private logDecision;
+	private readonly deps;
+	private selection;
+	private loopState;
+	private mirror;
+	private latency;
+	private presence;
+	private lastFrameAtMs;
+	private lastSummaryAtMs;
+	constructor(deps: AutotrackLoopDeps);
+	/** Read-only view of the mirror, for the addon's startup log. */
+	get ptzMirror(): PtzMirror;
+	/** Fold one refresh outcome into the mirror. Called by the TIMER, never from
+	*  {@link onFrame}. */
+	applyMirror(outcome: MirrorRefreshOutcome): void;
+	/** One analysed frame. Measures first, then decides. */
+	onFrame(frame: TrackedFrame): Promise<void>;
+	/**
+	* Off-event-path tick: the silence watchdog.
+	*
+	* Evaluates the SAME disappear delay against the time since the last frame.
+	* A stream that died is a target that is gone, and the head goes home —
+	* which is also the only thing that would otherwise never happen, because
+	* every other release is driven by a frame arriving.
+	*/
+	tick(): Promise<void>;
+	/** Emit the aggregates now, whatever the schedule says. Used at shutdown so
+	*  a short run still reports what it measured. */
+	logSummary(): void;
+	private maybeSummarize;
+	private dispatch;
+	private logDecision;
 }