"""Bounded unknown-object inspection policy. No model, network or actuator imports. Scores and budgets are mandatory, calibrated inputs, not deployment defaults. All timestamps called observed_at are local decoded-image times, not exposure UTC. """ from __future__ import annotations from collections import OrderedDict from dataclasses import dataclass, field import math import threading TARGETS = frozenset({'multirotor_uav', 'fixed_wing_uav'}) NON_TARGETS = frozenset({'bird', 'manned_aircraft'}) def finite(*values): return all(isinstance(v, (float, int)) and not isinstance(v, bool) and math.isfinite(v) for v in values) def digest(value): return isinstance(value, str) and len(value) == 64 and set(value) <= set('0123456789abcdef') def valid_box(box, shape): return (len(box) == 4 and len(shape) == 2 and finite(*box, *shape) and 0 <= box[0] < box[2] <= shape[1] and 0 <= box[1] < box[3] <= shape[0]) def same_object(a, b, shape): """Tight spatial continuity, independent of semantic label.""" if not valid_box(a, shape) or not valid_box(b, shape): return False area_a = (a[2]-a[0]) * (a[3]-a[1]) area_b = (b[2]-b[0]) * (b[3]-b[1]) jump = max(abs(a[0]+a[2]-b[0]-b[2]) / (2*shape[1]), abs(a[1]+a[3]-b[1]-b[3]) / (2*shape[0])) return .3 <= area_a/area_b <= 3.33 and jump <= .035 @dataclass(frozen=True) class Settings: proposal_sha: str classifier_sha: str proposal_names: tuple proposal_min: float semantic_min: float semantic_margin: float min_side_px: int min_sharpness: float budget_sec: float admission_frames: int = 3 semantic_frames: int = 2 enabled: bool = False def __post_init__(self): if not (digest(self.proposal_sha) and digest(self.classifier_sha) and self.proposal_names == ('airborne_object',) and finite(self.proposal_min, self.semantic_min, self.semantic_margin, self.min_sharpness, self.budget_sec) and .25 <= self.proposal_min <= 1 and 0 < self.semantic_min <= 1 and 0 < self.semantic_margin <= 1 and type(self.min_side_px) is int and self.min_side_px >= 2 and self.min_sharpness > 0 and 0 < self.budget_sec <= 120 and type(self.admission_frames) is int and self.admission_frames >= 2 and type(self.semantic_frames) is int and self.semantic_frames >= 2 and isinstance(self.enabled, bool)): raise ValueError('Invalid or uncalibrated inspection contract') @dataclass(frozen=True) class Observation: camera: int owner: tuple source_seq: int observed_at: float proposal_sha: str proposal_names: tuple shape: tuple # bbox, RAW coarse confidence, coarse class ID. Never motion-boosted scores. detections: tuple @dataclass(frozen=True) class Recognition: camera: int inspection_id: int owner: tuple source_seq: int observed_at: float classifier_sha: str bbox: tuple shape: tuple scores: tuple # (semantic name, score), unique names sharpness: float clipped: bool = False occluded: bool = False @dataclass class Session: camera: int inspection_id: int owner: tuple started_mono: float deadline_mono: float phase: str = 'candidate' decision: str = 'unresolved' reason: str = 'confirming_object' bbox: tuple | None = None shape: tuple = () last_seq: int = 0 last_at: float = 0. proposal_votes: int = 0 semantic_seq: int = 0 semantic_at: float = 0. semantic_name: str = '' semantic_score: float = 0. semantic_votes: int = 0 recent: dict = field(default_factory=dict) contract: Settings | None = None def revoke_semantics(self, reason): self.semantic_votes = 0 self.semantic_score = 0. self.semantic_name = '' self.semantic_at = 0. self.decision = 'unresolved' self.reason = reason def live(self, mono): # A confirmed target hands over to ordinary tracking. The inspection # deadline itself never changes. Lost semantic freshness revokes this # permission before observe/control; it cannot renew an unknown budget. return (finite(mono) and self.phase != 'closed' and self.started_mono <= mono and (mono < self.deadline_mono or self.decision == 'target')) def observe(self, o, settings, now, mono): if self.phase == 'closed': return False if self.decision == 'target' and not 0 <= now-self.semantic_at <= .65: self.revoke_semantics('semantic_evidence_expired') if self.contract is None: self.contract = settings elif self.contract != settings: self.phase = 'closed' self.revoke_semantics('model_contract_changed') return False if not self.live(mono): self.phase = 'closed' self.revoke_semantics('inspection_timeout') return False if (o.camera != self.camera or o.owner != self.owner or o.proposal_sha != settings.proposal_sha or o.proposal_names != settings.proposal_names or not isinstance(o.source_seq, int) or o.source_seq <= self.last_seq or not finite(now, o.observed_at) or not 0 <= now-o.observed_at <= .65 or (self.last_at and o.observed_at <= self.last_at)): self.revoke_semantics('invalid_observation') return False candidates = [(tuple(b), float(c)) for b, c, cls in o.detections if cls == 0 and finite(c) and settings.proposal_min <= c <= 1 and valid_box(b, o.shape)] if self.bbox is not None: candidates = [(b, c) for b, c in candidates if o.shape == self.shape and same_object(self.bbox, b, o.shape)] if not candidates: self.proposal_votes = 0 self.revoke_semantics('no_current_same_object') return False bbox, _ = max(candidates, key=lambda x: x[1]) if self.last_at and o.observed_at-self.last_at > .65: self.proposal_votes = 0 self.revoke_semantics('evidence_gap') self.bbox, self.shape = bbox, o.shape self.last_at, self.last_seq = o.observed_at, o.source_seq self.proposal_votes += 1 self.recent[o.source_seq] = (o.observed_at, bbox, o.shape, o.owner) self.recent = {k: v for k, v in self.recent.items() if 0 <= now-v[0] <= .65} while len(self.recent) > 16: del self.recent[min(self.recent)] if self.proposal_votes >= settings.admission_frames: self.phase = 'inspection' self.reason = 'fresh_object_no_class_required' return self.proposal_votes >= settings.admission_frames def recognize(self, r, settings, now, mono): record = self.recent.get(r.source_seq) if (not self.live(mono) or self.phase != 'inspection' or r.camera != self.camera or r.inspection_id != self.inspection_id or r.owner != self.owner or r.classifier_sha != settings.classifier_sha or not finite(now, r.observed_at, r.sharpness) or not 0 <= now-r.observed_at <= .65 or record is None or record != (r.observed_at, r.bbox, r.shape, r.owner)): return False if r.source_seq <= self.semantic_seq: return False # duplicate/delayed answers cannot supply new votes self.semantic_seq = r.source_seq formatted = (type(r.scores) is tuple and len(r.scores) == 4 and all(type(p) is tuple and len(p) == 2 and type(p[0]) is str for p in r.scores)) names = [n for n, _ in r.scores] if formatted else [] good = (formatted and len(names) == len(set(names)) and set(names) == TARGETS | NON_TARGETS and all(finite(v) and 0 <= v <= 1 for _, v in r.scores) and abs(sum(v for _, v in r.scores)-1) <= 1e-4 and r.clipped is False and r.occluded is False and valid_box(r.bbox, r.shape) and min(r.bbox[2]-r.bbox[0], r.bbox[3]-r.bbox[1]) >= settings.min_side_px and r.sharpness >= settings.min_sharpness) ranked = sorted(r.scores, key=lambda x: x[1], reverse=True) if good else [] if (not good or ranked[0][1] < settings.semantic_min or ranked[0][1]-ranked[1][1] < settings.semantic_margin): self.revoke_semantics('insufficient_recognition') return False name, score = ranked[0] same = name == self.semantic_name and 0 < r.observed_at-self.semantic_at <= .65 self.semantic_votes = self.semantic_votes+1 if same else 1 self.semantic_name, self.semantic_score, self.semantic_at = name, score, r.observed_at self.decision = ('target' if name in TARGETS else 'non_target') \ if self.semantic_votes >= settings.semantic_frames else 'unresolved' self.reason = 'confirmed_'+self.decision return self.decision != 'unresolved' def alarm_allowed(self, now, mono, owner, bbox, shape): return bool(self.live(mono) and self.phase == 'inspection' and owner == self.owner and self.decision == 'target' and self.semantic_name in TARGETS and finite(now) and 0 <= now-self.semantic_at <= .65 and 0 <= now-self.last_at <= .65 and shape == self.shape and same_object(self.bbox, bbox, shape)) class LatestRecognition: """Bounded fair mailbox: one pending/result per camera, no frame FIFO. An external model worker takes tickets; control never waits for prediction. It stores metadata only. The producer owns the actual bounded crop buffer. """ def __init__(self, cameras): self.cameras = frozenset(cameras) self.pending, self.results = OrderedDict(), {} self.lock = threading.Lock() def submit(self, camera, ticket): if camera not in self.cameras: raise ValueError('Unknown physical camera') with self.lock: self.pending[camera] = ticket # replacement preserves fairness order def take(self): with self.lock: return self.pending.popitem(last=False) if self.pending else None def complete(self, result): if not isinstance(result, Recognition) or result.camera not in self.cameras: raise ValueError('Invalid recognition result') with self.lock: old = self.results.get(result.camera) if old is None or (result.inspection_id, result.source_seq) > (old.inspection_id, old.source_seq): self.results[result.camera] = result def poll(self, camera): with self.lock: return self.results.pop(camera, None)