You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Chameleon/ptz_tracker_modular/frame_time.py

268 lines
11 KiB
Python

"""Offline CC-11 metadata adapter. No camera, model, network or filesystem I/O.
Caller supplies existing source_seq; this module never invents capture timestamps.
Instances belong to one producer/consumer and must not be shared between threads.
"""
from collections import deque
from dataclasses import asdict, dataclass
from fractions import Fraction
import json
import re
NS = 1_000_000_000
def integer(value, name, minimum=None):
if type(value) is not int or (minimum is not None and value < minimum):
raise ValueError(name)
return value
def identifier(value):
if not isinstance(value, str) or re.fullmatch(r"[A-Za-z0-9_-]{1,96}", value) is None:
raise ValueError("opaque identifier required; URLs/credentials are forbidden")
return value
def timebase(num, den):
return Fraction(integer(num, "tb_num", 1), integer(den, "tb_den", 1))
@dataclass(frozen=True)
class FrameStamp:
camera_id: int
source_id: str
stream_epoch: str
source_seq: int
origin_id: str | None
raw_pts: int | None
raw_dts: int | None
tb_num: int | None
tb_den: int | None
decode_mono_ns: int
decode_utc_ns: int
decode_utc_uncertainty_ns: int | None
clock_epoch: int
capture_utc_ns: int | None = None
capture_utc_uncertainty_ns: int | None = None
capture_anchor_id: str | None = None
def __post_init__(self):
for v in (self.source_id, self.stream_epoch):
identifier(v)
if self.origin_id is not None:
identifier(self.origin_id)
for name in ("camera_id", "decode_mono_ns", "decode_utc_ns", "clock_epoch"):
integer(getattr(self, name), name, 0)
integer(self.source_seq, "source_seq", 1)
if (self.tb_num is None) != (self.tb_den is None):
raise ValueError("partial timebase")
if self.tb_num is not None:
timebase(self.tb_num, self.tb_den)
for name in ("raw_pts", "raw_dts"):
if getattr(self, name) is not None:
integer(getattr(self, name), name)
if self.tb_num is None:
raise ValueError("timestamp without timebase")
for name in ("decode_utc_uncertainty_ns", "capture_utc_uncertainty_ns"):
if getattr(self, name) is not None:
integer(getattr(self, name), name, 0)
capture_fields = (self.capture_utc_ns, self.capture_utc_uncertainty_ns, self.capture_anchor_id)
if any(x is not None for x in capture_fields):
if any(x is None for x in capture_fields):
raise ValueError("partial capture anchor")
integer(self.capture_utc_ns, "capture_utc_ns", 0)
identifier(self.capture_anchor_id)
@dataclass(frozen=True)
class CaptureAnchor:
"""Externally verified source-clock anchor, NOT host receive/decode UTC.
Bounds and drift must come from a measured camera clock contract. This class
validates structure, not the truth of that external measurement.
"""
anchor_id: str
source_id: str
stream_epoch: str
pts: int
tb_num: int
tb_den: int
utc_ns: int
uncertainty_ns: int
valid_pts_min: int
valid_pts_max: int
max_drift_ppm: int
def __post_init__(self):
for v in (self.anchor_id, self.source_id, self.stream_epoch):
identifier(v)
timebase(self.tb_num, self.tb_den)
for name in ("pts", "valid_pts_min", "valid_pts_max"):
integer(getattr(self, name), name)
for name in ("utc_ns", "uncertainty_ns", "max_drift_ppm"):
integer(getattr(self, name), name, 0)
if not self.valid_pts_min <= self.pts <= self.valid_pts_max:
raise ValueError("anchor outside calibrated range")
class FrameClock:
def __init__(self, camera_id, source_id, stream_epoch, *, clock_jump_ns=50_000_000):
self.camera_id = integer(camera_id, "camera_id", 0)
self.source_id, self.stream_epoch = identifier(source_id), identifier(stream_epoch)
self.clock_jump_ns = integer(clock_jump_ns, "clock_jump_ns", 0)
self.last = None
self.clock_epoch = 0
def observe(self, *, source_seq, mono_before_ns, mono_after_ns, utc_ns,
sync_uncertainty_ns=None, raw_pts=None, raw_dts=None,
tb_num=None, tb_den=None, origin_id=None, anchor=None):
"""Called once at original frame acceptance, before sampling/queueing.
Bracket UTC read with monotonic reads. Unknown host synchronization error
stays None. Reuse the stamp with the exact pixels; never restamp a crop.
"""
source_seq = integer(source_seq, "source_seq", 1)
before = integer(mono_before_ns, "mono_before_ns", 0)
after = integer(mono_after_ns, "mono_after_ns", before)
utc_ns = integer(utc_ns, "utc_ns", 0)
mono = (before + after) // 2
if origin_id is not None:
identifier(origin_id)
uncertainty = None
if sync_uncertainty_ns is not None:
uncertainty = integer(sync_uncertainty_ns, "sync_uncertainty_ns", 0) + (after-before+1)//2
if (tb_num is None) != (tb_den is None):
raise ValueError("partial timebase")
if tb_num is not None:
timebase(tb_num, tb_den)
for name, v in (("raw_pts", raw_pts), ("raw_dts", raw_dts)):
if v is not None:
integer(v, name)
if tb_num is None:
raise ValueError("timestamp without timebase")
clock_epoch = self.clock_epoch
if self.last:
if source_seq <= self.last.source_seq or mono <= self.last.decode_mono_ns:
raise ValueError("duplicate/late sequence or monotonic clock")
jump = abs((utc_ns-self.last.decode_utc_ns)-(mono-self.last.decode_mono_ns))
if jump > self.clock_jump_ns:
clock_epoch += 1
capture, capture_uncertainty, anchor_id = None, None, None
if anchor is not None:
if (anchor.source_id, anchor.stream_epoch) != (self.source_id, self.stream_epoch):
raise ValueError("foreign capture anchor")
if raw_pts is not None and timebase(tb_num, tb_den) == timebase(anchor.tb_num, anchor.tb_den):
if anchor.valid_pts_min <= raw_pts <= anchor.valid_pts_max:
delta = (raw_pts-anchor.pts) * timebase(tb_num, tb_den) * NS
capture = anchor.utc_ns + round(delta)
# Round upward; never hide timestamp quantization or drift.
drift = abs(delta) * anchor.max_drift_ppm / 1_000_000
capture_uncertainty = anchor.uncertainty_ns + (drift.numerator+drift.denominator-1)//drift.denominator + 1
anchor_id = anchor.anchor_id
stamp = FrameStamp(self.camera_id, self.source_id, self.stream_epoch, source_seq,
origin_id, raw_pts, raw_dts, tb_num, tb_den, mono, utc_ns,
uncertainty, clock_epoch, capture, capture_uncertainty, anchor_id)
self.clock_epoch = clock_epoch
self.last = stamp
return stamp
def require_current(self, stamp, *, now_mono_ns, max_age_ns, owner, expected_owner):
if owner is None or expected_owner is None or owner != expected_owner:
raise ValueError("wrong owner")
if (stamp.camera_id, stamp.source_id, stamp.stream_epoch) != (self.camera_id, self.source_id, self.stream_epoch):
raise ValueError("wrong source/epoch")
age = integer(now_mono_ns, "now_mono_ns", 0) - stamp.decode_mono_ns
if not 0 <= age <= integer(max_age_ns, "max_age_ns", 0):
raise ValueError("late/future frame")
return stamp
@dataclass(frozen=True)
class RecorderMap:
"""Actual per-packet values observed around mux; never predicted from tail.
origin_id must be propagated by the same upstream producer to image and mux
paths. Independently generated decoder counters are not common identities.
"""
camera_id: int
recording_id: str
source_id: str
stream_epoch: str
origin_id: str
source_pts: int
source_dts: int | None
source_tb_num: int
source_tb_den: int
output_pts: int
output_dts: int
output_tb_num: int
output_tb_den: int
timeline_segment: int
def __post_init__(self):
integer(self.camera_id, "camera_id", 0)
for v in (self.recording_id, self.source_id, self.stream_epoch, self.origin_id):
identifier(v)
timebase(self.source_tb_num, self.source_tb_den)
timebase(self.output_tb_num, self.output_tb_den)
for name in ("source_pts", "output_pts", "output_dts", "timeline_segment"):
integer(getattr(self, name), name)
if self.source_dts is not None:
integer(self.source_dts, "source_dts")
integer(self.timeline_segment, "timeline_segment", 0)
class RecorderIndex:
def __init__(self, recording_id, source_id, stream_epoch, *, camera_id, capacity=4096):
self.camera_id = integer(camera_id, "camera_id", 0)
self.identity = tuple(identifier(x) for x in (recording_id, source_id, stream_epoch))
self.rows = deque(maxlen=integer(capacity, "capacity", 1))
self.evicted = 0
def append(self, row):
if row.camera_id != self.camera_id or (row.recording_id, row.source_id, row.stream_epoch) != self.identity:
raise ValueError("foreign recording source")
if self.rows:
last = self.rows[-1]
if row.output_dts*timebase(row.output_tb_num,row.output_tb_den) <= last.output_dts*timebase(last.output_tb_num,last.output_tb_den):
raise ValueError("mux DTS not strictly increasing")
if row.timeline_segment < last.timeline_segment:
raise ValueError("late timeline segment")
if len(self.rows) == self.rows.maxlen:
self.evicted += 1
self.rows.append(row)
def output_time(self, stamp):
if stamp.camera_id != self.camera_id or (stamp.source_id, stamp.stream_epoch) != self.identity[1:]:
raise ValueError("foreign frame source")
if stamp.origin_id is None or stamp.raw_pts is None:
raise ValueError("no shared upstream frame identity")
matches = [r for r in self.rows if r.origin_id == stamp.origin_id and
r.source_pts*timebase(r.source_tb_num,r.source_tb_den) == stamp.raw_pts*timebase(stamp.tb_num,stamp.tb_den)]
if len(matches) != 1:
raise ValueError("absent/ambiguous mapping; do not interpolate")
row = matches[0]
return Fraction(row.output_pts) * timebase(row.output_tb_num,row.output_tb_den)
class BoundedJournal:
"""Bounded memory only. A separate diagnostic consumer may serialize snapshot.
ponytail: one deque per stream; no disk writes or asynchronous logging worker
until an actual bound runtime integration and its latency budget are reviewed.
"""
def __init__(self, capacity=4096):
self.rows = deque(maxlen=integer(capacity, "capacity", 1))
self.evicted = 0
def append(self, row):
if type(row) not in (FrameStamp, RecorderMap):
raise ValueError("only validated metadata; no payload/log dictionaries")
if len(self.rows) == self.rows.maxlen:
self.evicted += 1
self.rows.append(row)
def snapshot_json(self):
return json.dumps({"evicted": self.evicted, "rows": [asdict(x) for x in self.rows]}, allow_nan=False, separators=(",", ":"))