diff --git a/integration/ptz17_causal_image_rate/README.md b/integration/ptz17_causal_image_rate/README.md new file mode 100644 index 0000000..7a1bf81 --- /dev/null +++ b/integration/ptz17_causal_image_rate/README.md @@ -0,0 +1,15 @@ +# PTZ17 · причинный расчёт скорости рамки + +Патч для точной полевой версии `postprocess.py` из PR №16. В потоке OSTrack `frame_utc` берётся из времени приёма декодированного изображения. Самостоятельный результат YOLO без парного образца получает время входа в контроллер. Последовательность `source_seq` упорядочивает кадры, а эти две метки измеряют разные события. Поэтому более позднее по номеру наблюдение может иметь более раннее время. В исходных журналах двух инверсий 08:19 канал отдельного решения не записан. В новой телеметрии `frame_clock` различает `visual_receipt` и `control_entry`. + +Для PTZ17 патч ведёт отдельно временную границу принятого отсчёта и базу производной. При нечисловой, обратной или повторной метке оценка скорости остаётся прежней, положительный зум не разрешается по этому кадру. При интервале меньше 40 мс сохраняются база и коэффициенты EMA. Короткий отсчёт может пройти проверку движения лишь при валидной предыдущей оценке и `(|Δx| + |Δy|) ≤ limit × Δt`; по X и Y используются доли полной ширины и высоты кадра. При достаточном интервале скорость считается по реальному Δt. Оба штатных сброса истории при восстановлении или смене TRACK очищают базу. Остальные камеры используют прежний фильтр с теми же параметрами. Модель, тревоги, лимиты импульсов и обработчики STOP не редактировались. + +## Проверка + +- 913 решений из шести пролётов PTZ17 17 ноября, 10 нарушений порядка в четырёх пролётах. Проверка нового входа по скорости пропустила все 25 зарегистрированных положительных решений, включая пять первых стартов в своих эпизодах. Это повтор наблюдателя и проверки скорости с зафиксированными полевыми решениями, а физический отклик альтернативного прогона не измеряется. +- На 08:19:19,774 оценка снизилась с 0,14505 до 0,04270 с⁻¹ при пороге 0,08 с⁻¹. Штатный код заявки допустил бы probe native10 с номиналом 100 мс и потолком 120 мс. Через 11,87 мс пришёл кадр с обратной меткой, и штатная обработка нуля аннулировала бы заявку в очереди, запросила бы отмену PUT в полёте либо дождалась STOP после ACK. Полезный оптический импульс в этом новом окне не подтверждён. +- В 08:53:04 первый записанный старт при 5,886 с сохранил допуск по скорости. В исходном пролёте HFOV после этого старта уменьшился с 59° до 54,12° при 6,473 с. +- Прошла 41 целевая проверка, включая семь новых тестов. Полный локальный набор с изоляцией сети и подменой входа модели дал идентичные результаты на полевой базе и кандидате — 905 успешных тестов, 407 ранее падавших проверок, 33 ошибки подготовки, 1188 успешных подтестов. Полный набор сам по себе остаётся красным. Дельта результатов по всем фазам и подтестам пустая. +- Прямое и обратное применение восстановили заявленные SHA-256 побайтно. Патч использует LF, при локальной проверке на Windows нужно выставить `core.autocrlf=false` и `core.eol=lf` для команды `git apply`. + +Для новых изолированных тестов переменная `PTZ17_RATE_SOURCE` указывает на копию `postprocess.py` после применения `image_rate.patch`. Запуск `python -m pytest -q test_image_rate.py` из каталога с тестом. На объекте исполнялось только чтение. diff --git a/integration/ptz17_causal_image_rate/image_rate.patch b/integration/ptz17_causal_image_rate/image_rate.patch new file mode 100644 index 0000000..a683f7d --- /dev/null +++ b/integration/ptz17_causal_image_rate/image_rate.patch @@ -0,0 +1,140 @@ +--- a/postprocess.py ++++ b/postprocess.py +@@ -761,6 +761,7 @@ + edge_margin_min: float = 0.30 + center_max_norm: float = 0.12 + image_rate_max_norm_s: float = 0.04 ++ image_rate_min_interval_s: float = 0.04 + + + _PTZ17_ZOOM = _PTZ17ZoomTuning() +@@ -3320,6 +3321,55 @@ + # TRACK/ACQUIRE boundary. + + ++def _update_image_rate_ema(st: dict, dx_norm: float, dy_norm: float, dt_s: float) -> None: ++ """Update X-right/Y-down rates in full frame fractions per second.""" ++ image_rate_max = max(0.1, float(getattr(config, "AIM_IMAGE_RATE_MAX", 2.0))) ++ vx_i = clipf(dx_norm / dt_s, -image_rate_max, image_rate_max) ++ vy_i = clipf(dy_norm / dt_s, -image_rate_max, image_rate_max) ++ vel_smooth = clipf(float(getattr(config, "VEL_SMOOTH", 0.85)), 0.0, 0.99) ++ st["vx"] = vel_smooth * st["vx"] + (1.0 - vel_smooth) * vx_i ++ st["vy"] = vel_smooth * st["vy"] + (1.0 - vel_smooth) * vy_i ++ fast_smooth = clipf(float(getattr(config, "AIM_IMAGE_RATE_FAST_SMOOTH", 0.45)), 0.0, 0.95) ++ st["vx_fast"] = fast_smooth * float(st.get("vx_fast", 0.0) or 0.0) + (1.0 - fast_smooth) * vx_i ++ st["vy_fast"] = fast_smooth * float(st.get("vy_fast", 0.0) or 0.0) + (1.0 - fast_smooth) * vy_i ++ ++ ++@dataclass(frozen=True, slots=True) ++class _ImageRateSample: ++ latest_at_s: float ++ baseline_at_s: float ++ x_norm: float ++ y_norm: float ++ have_rate: bool ++ ++ ++def _update_ptz17_image_rate(st: dict, measured_at_s: float, x_norm: float, y_norm: float) -> str: ++ """Use a causal baseline and accumulate short samples without inventing elapsed time.""" ++ if not all(map(math.isfinite, (measured_at_s, x_norm, y_norm))): ++ return "invalid" ++ previous = st.get("ptz17_image_rate_ref") ++ if previous is None: ++ st["ptz17_image_rate_ref"] = _ImageRateSample(measured_at_s, measured_at_s, x_norm, y_norm, False) ++ return "seed" ++ if measured_at_s <= previous.latest_at_s: ++ return "noncausal" ++ dt_s = measured_at_s - previous.baseline_at_s ++ dx_norm, dy_norm = x_norm - previous.x_norm, y_norm - previous.y_norm ++ if dt_s < _PTZ17_ZOOM.image_rate_min_interval_s: ++ # Advance the ordering barrier without moving the derivative baseline. ++ st["ptz17_image_rate_ref"] = _ImageRateSample( ++ measured_at_s, previous.baseline_at_s, previous.x_norm, previous.y_norm, previous.have_rate, ++ ) ++ # Use the prior rate only if the whole displacement fits the motion gate. ++ rate_max = min(0.08, float(getattr(config, "ZOOM_STEP_USEFUL_IMAGE_RATE_MAX", 0.08))) ++ if previous.have_rate and abs(dx_norm) + abs(dy_norm) <= rate_max * dt_s: ++ return "short_checked" ++ return "short" ++ _update_image_rate_ema(st, dx_norm, dy_norm, dt_s) ++ st["ptz17_image_rate_ref"] = _ImageRateSample(measured_at_s, measured_at_s, x_norm, y_norm, True) ++ return "updated" ++ ++ + def _reset_aim_motion_feedforward(st: dict, now: float) -> None: + """Clear stale target-motion estimates without disturbing TRACK/lens state. + +@@ -3333,6 +3383,7 @@ + its feedback barrier instead of erasing the lens transaction. + """ + st["prev_t"] = None ++ st.pop("ptz17_image_rate_ref", None) + st["prev_cx"] = 0.5 + st["prev_cy"] = 0.5 + st["vx"] = 0.0 +@@ -3416,6 +3467,7 @@ + ) -> None: + """Discard motion history that must not cross a new TRACK boundary.""" + st["prev_t"] = None ++ st.pop("ptz17_image_rate_ref", None) + st["prev_cx"] = 0.5 + st["prev_cy"] = 0.5 + st["vx"] = 0.0 +@@ -8907,18 +8959,12 @@ + min_margin = min(left, right, top, bottom) + + prev_t = st.get("prev_t") +- dt = None +- if prev_t is not None: +- dt = max(now - float(prev_t), 1e-3) +- image_rate_max = max(0.1, float(getattr(config, "AIM_IMAGE_RATE_MAX", 2.0))) +- vx_i = clipf((cxn - st["prev_cx"]) / dt, -image_rate_max, image_rate_max) +- vy_i = clipf((cyn - st["prev_cy"]) / dt, -image_rate_max, image_rate_max) +- vel_smooth = clipf(float(getattr(config, "VEL_SMOOTH", 0.85)), 0.0, 0.99) +- st["vx"] = vel_smooth * st["vx"] + (1.0 - vel_smooth) * vx_i +- st["vy"] = vel_smooth * st["vy"] + (1.0 - vel_smooth) * vy_i +- fast_smooth = clipf(float(getattr(config, "AIM_IMAGE_RATE_FAST_SMOOTH", 0.45)), 0.0, 0.95) +- st["vx_fast"] = fast_smooth * float(st.get("vx_fast", 0.0) or 0.0) + (1.0 - fast_smooth) * vx_i +- st["vy_fast"] = fast_smooth * float(st.get("vy_fast", 0.0) or 0.0) + (1.0 - fast_smooth) * vy_i ++ dt = max(now - float(prev_t), 1e-3) if prev_t is not None else None ++ image_rate_sample = "legacy" ++ if cam_idx == _PTZ17_CAM_IDX: ++ image_rate_sample = _update_ptz17_image_rate(st, now, cxn, cyn) ++ elif dt is not None: ++ _update_image_rate_ema(st, cxn - st["prev_cx"], cyn - st["prev_cy"], dt) + + # Convert image displacement to a true line-of-sight angle before any + # steering decisions. Normalized pixels are not a physical motion unit: +@@ -9705,6 +9751,7 @@ + ) + zoom_rearm_ready = _zoom_revalidation_ready(st) + stable_ok = stable_ok or predictive_entry or predictive_continuing ++ image_rate_ready = image_rate_sample in ("legacy", "updated", "short_checked") + can_zoom_in = ( + zoom_safe + and zoom_angular_safe +@@ -9716,6 +9763,7 @@ + or bounded_identification_request + ) + and fast_drift <= float(getattr(config, "ZOOM_IN_FAST_DRIFT_MAX", 0.45)) ++ and image_rate_ready + and now >= float(st.get("focus_settle_until", 0.0) or 0.0) + ) + +@@ -10739,6 +10787,7 @@ + ("edge", near_edge or edge_recovery_active), + ("lock", st.get("zoom_lock", False) and not bounded_identification_request), + ("drift", fast_drift > float(getattr(config, "ZOOM_IN_FAST_DRIFT_MAX", 0.45))), ++ ("image_rate_sample", not image_rate_ready), + ("focus", now < float(st.get("focus_settle_until", 0.0) or 0.0)), + ("coast", visual_control_coast), + ("stale", visual_control_stale), +@@ -10760,6 +10809,8 @@ + center_error_norm=max(abs(float(measured_dx)), abs(float(measured_dy))), + edge_margin_norm=float(edge_risk_margin), approach_margin_norm=approach_margin, + image_rate_norm_s=max(float(vel), float(fast_drift)), ++ image_rate_sample=image_rate_sample, ++ frame_clock="visual_receipt" if visual_only else "control_entry", + zoom_requested=bool(raw_zoom_needed), zoom_before_gate=ptz17_zoom_before_gate, + zoom_command=float(zoom_cmd), proposed_native=int(timing_native), + reason=zoom_zero_reason if zoom_cmd <= 0.0 else "positive_command", diff --git a/integration/ptz17_causal_image_rate/pins.json b/integration/ptz17_causal_image_rate/pins.json new file mode 100644 index 0000000..eceb1fa --- /dev/null +++ b/integration/ptz17_causal_image_rate/pins.json @@ -0,0 +1,5 @@ +{ + "base_sha256": "8e3cf93b2ab54bbc98b86761312c5d0034785578775bddaaee6450c28d370a9b", + "candidate_sha256": "987a8077abb44f9cecf3a98fb89b723bc2d0f77d827fc2b4bdf213c70beb04a5", + "patch_sha256": "911c4b53d3891d552b1706776e0b0cd5e28785d51590257413965ac37c74ac48" +} diff --git a/integration/ptz17_causal_image_rate/test_image_rate.py b/integration/ptz17_causal_image_rate/test_image_rate.py new file mode 100644 index 0000000..36c21dc --- /dev/null +++ b/integration/ptz17_causal_image_rate/test_image_rate.py @@ -0,0 +1,73 @@ +from __future__ import annotations + +import ast +from dataclasses import dataclass +import math +import os +from pathlib import Path +from types import SimpleNamespace + +import pytest + + +@pytest.fixture(scope="module") +def controller(): + source = Path(os.environ["PTZ17_RATE_SOURCE"]) + names = {"_PTZ17ZoomTuning", "_ImageRateSample", "_update_ptz17_image_rate", "_update_image_rate_ema"} + selected = [node for node in ast.parse(source.read_bytes()).body + if isinstance(node, (ast.FunctionDef, ast.ClassDef)) and node.name in names] + assert {node.name for node in selected} == names + ns = {"config": SimpleNamespace(VEL_SMOOTH=.75, AIM_IMAGE_RATE_FAST_SMOOTH=.45), + "math": math, "clipf": lambda value, lo, hi: min(hi, max(lo, value)), + "dataclass": dataclass, "__name__": __name__} + exec(compile(ast.Module(body=selected, type_ignores=[]), str(source), "exec"), ns) + ns["_PTZ17_ZOOM"] = ns["_PTZ17ZoomTuning"]() + return ns["_update_ptz17_image_rate"] + + +def state() -> dict: + return dict(vx=0., vy=0., vx_fast=0., vy_fast=0.) + + +@pytest.mark.parametrize("timestamp", [10.0, 9.992, math.nan, math.inf]) +def test_bad_sample_retains_the_causal_baseline(controller, timestamp): + st = state() + assert controller(st, 10.0, .5, .5) == "seed" + snapshot = st.copy() + assert controller(st, timestamp, .8, .6) in ("noncausal", "invalid") + assert st == snapshot + assert controller(st, 10.1, .502, .5) == "updated" + assert st["vx"] == pytest.approx(.005) + assert st["vx_fast"] == pytest.approx(.011) + + +def test_short_gaps_accumulate_without_polluting_filter(controller): + st = state() + assert controller(st, 10., .5, .5) == "seed" + assert controller(st, 10.02, .55, .5) == "short" + assert st["vx"] == 0 + assert controller(st, 10.015, .5, .5) == "noncausal" + assert controller(st, 10.05, .503, .5) == "updated" + assert st["vx"] == pytest.approx(.015) + assert st["vx_fast"] == pytest.approx(.033) + + +def test_short_valid_sample_cannot_suppress_a_large_excursion(controller): + st = state() + controller(st, 10., .5, .5) + controller(st, 10.1, .5, .5) + assert controller(st, 10.112, .5, .5) == "short_checked" + assert controller(st, 10.118, .505, .5) == "short" + assert st["vx"] == 0.0 + + +def test_patch_is_on_the_control_path_and_reset_on_owner_changes(): + source = Path(os.environ["PTZ17_RATE_SOURCE"]) + tree = ast.parse(source.read_bytes()) + methods = {node.name: ast.unparse(node) for node in tree.body if isinstance(node, ast.FunctionDef)} + control = methods["postprocess_control"] + assert "image_rate_sample = _update_ptz17_image_rate(st, now, cxn, cyn)" in control + assert "and image_rate_ready" in control + assert "frame_clock='visual_receipt' if visual_only else 'control_entry'" in control + for name in ("_reset_aim_motion_feedforward", "_reset_aim_controller_state"): + assert "st.pop('ptz17_image_rate_ref', None)" in methods[name]