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.
268 lines
11 KiB
Python
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=(",", ":"))
|