Compare commits

..

16 Commits

Author SHA1 Message Date
Ярослав Карташов edfa2fff87 Capture ordered PTZ17 HOLD inputs for recovery replay 6 days ago
Ярослав Карташов c74c8fb82f Record PTZ17 HOLD and reacquisition frame evidence 7 days ago
Ярослав Карташов f90c7da682 Log PTZ17 zoom decisions and focus evidence per frame 1 week ago
Ярослав Карташов 25c94c1e8d Add PTZ17 optics replay and bounded focus recovery 1 week ago
Ярослав Карташов 05dcdcd06a Validate target sharpness on additional PTZ17 passages 1 week ago
Ярослав Карташов 9fd7738cd5 Prepare focus-aware PTZ17 zoom candidate 1 week ago
Ярослав Карташов 7cb391e727 Allow steering-only YOLO confirmation on PTZ17 1 week ago
Ярослав Карташов 5cc610a92a Add broad-to-tele zoom safety, latency-aware steering and calibration telemetry 2 weeks ago
Ярослав Карташов a7a017e7d1 Include delayed ISAPI PUT replay results 2 weeks ago
Ярослав Карташов a25d2bfc0f Record replay-only native10 profiles for PTZ19 and PTZ21 2 weeks ago
Ярослав Карташов 3b92c16bef Document byte-exact patch checks on Windows 2 weeks ago
Ярослав Карташов 0733a4b95c Add predictive TRACK zoom for calibrated PTZ cameras 2 weeks ago
Ярослав Карташов 273fb58c31 Log zoom framing and size controller thresholds 2 weeks ago
Ярослав Карташов fbf8017665 Log same-native zoom pulse continuation 2 weeks ago
Ярослав Карташов dc6c03f594 Preserve owned zoom pulse at identical native speed 2 weeks ago
Ярослав Карташов 5a2a2e9822 Log frame decisions ending PTZ zoom 2 weeks ago

6
.gitattributes vendored

@ -0,0 +1,6 @@
integration/ptz_zoom_zero_decision/server.patch text eol=lf -whitespace
integration/ptz_native_floor_continuation/server.patch text eol=lf -whitespace
integration/ptz_same_native_diagnostics/server.patch text eol=lf -whitespace
integration/ptz_zoom_threshold_diagnostics/server.patch text eol=lf -whitespace
integration/ptz_predictive_zoom/server.patch text eol=lf -whitespace
integration/ptz_predictive_zoom/*.py text eol=lf

@ -0,0 +1,52 @@
# PTZ17 · зум и контроль резкости
## Диагностика HOLD и повторного захвата
Событие `recovery_frame` в очереди JSONL PTZ17 связывает причину отказа или восстановления с поколением трека, номером кадра, временем наблюдения и размером изображения обработки. Координаты `xyxy` отсчитываются от левого верхнего угла. Для промежуточного OSTrack и привязанного к нему YOLO время наблюдения соответствует получению декодированного кадра. Для отдельного детекторного прохода оно соответствует входу в обработчик. Поле `input_kind` различает эти источники. Номера кадров OSTrack и управляющего прохода записываются отдельно.
Телеметрия содержит последнюю принятую рамку, опору сопоставления, рамку и оценку OSTrack, кандидатов YOLO с оценками и классами, результат сопоставления, выбранную рамку и результат переинициализации. Записываются счётчики голосов повторного захвата и разрешения зума. При геометрическом HOLD журнал различает отсутствие сопоставления, отбрасывание по площади относительно принятой рамки, ожидание подтверждения и отказ переинициализации. При позднем YOLO событие отмечает, что кадр использован для верификации или привёл к штатному STOP из-за конфликта.
Списки содержат до 12 рамок, которые дошли до соответствующих проверок контроллера. Общие количества и выбранная рамка записываются отдельно. Сырые результаты YOLO до фильтрации представлены счётчиком. Для событий, ожидающих подтверждения, `yolo_match` показывает возможное совпадение, а `yolo_selected` остаётся пустым. Писатель использует существующую ограниченную очередь. Переполнение увеличивает `dropped_before` у следующих событий.
Для офлайн-проверки `test_recovery_telemetry.py` укажите пути `PTZ17_TEST_RUNTIME`, `PTZ17_TEST_BASELINE` и `PTZ17_TEST_CANDIDATE`. Базовая версия для этих тестов — предыдущий коммит PR №14. Тесты сравнивают команды Pan/Tilt/Zoom, защитные STOP, вызовы тревог и состояние контроллера на одинаковых входах со смоделированными детекциями. Полевое время от HOLD до повторного разрешения зума остаётся измерить после сбора новых событий.
Локальный кандидат поверх установленного PR №13. Прямое и обратное применение патча проверены побайтно. SHA-256 базовой и кандидатной версий в `pins.json`.
На широком угле кандидат проверяет, может ли уже разрешённый первый обычный импульс native 10 начаться с длительностью до 340 мс и жёстким пределом 400 мс. Для этого нужны текущий кадр OSTrack, свежее подтверждение YOLO, свежая оптика, допустимая скорость в кадре и полная штатная проекция рамки. Повторное разрешение допускает только исходный запрос того же владельца. При запрете базового контроллера запрос остаётся нулевым. Функции модели, тревог и транспорт STOP сохранены.
При HFOV до 18° на PTZ17 оценка резкости проверяет область самой цели. Для решения о паузе подходят рамки с короткой стороной от 20 px. Штатный порог размера для автофокуса остаётся 24 px. Низкая резкость или неоцениваемый кадр удерживают текущее увеличение. Для выхода нужны два свежих резких кадра того же владельца с интервалом не более 250 мс. Один резкий отсчёт, дубликат и большой разрыв паузу не снимают. Пауза относится к новым положительным импульсам, поэтому Pan/Tilt и защитное расширение FOV сохраняют штатные пути.
При непрерывных 600 мс неоцениваемой резкости после остановки линзы, свежем подтверждении цели и устойчивом положении рамки кандидат может поставить один восстановительный запрос в штатную очередь автофокуса на владельца трека. Повторный запрос требует смены владельца и соблюдения штатного cooldown. ACK фокуса сам по себе зум не возобновляет.
Повторная проверка на пролёте 14:28 показала, что расширенная область низкоконтрастна и для размытого, и для различимого самолёта. Теперь при непригодной расширенной области проверяется ядро рамки с более строгим порогом. Для этого кандидата задан восьмикратный множитель относительно исходного порога дисперсии лапласиана. Множитель проверен на этой ограниченной выборке и остаётся параметром калибровки.
На записи пролёта 14:12:02 измерение рамки на PTS 95 возвращает `unassessable` и устанавливает паузу. На PTS 116 свежая резкая рамка снимает её. У трёх сохранённых кадров нет покадровой привязки к UTC. Замеры AIM разрежены. Первый записанный полный безопасный запас от края появился на +9,869 с, после первой полевой команды на +6,041 с. Ускорение первого оптического приближения на данном пролёте по доступным данным не подтверждено.
Проверки охватывают свежесть, владельца импульса, отказ при малом запасе от края, превышении угловой зоны и скорости, сохранение нулевого запроса, паузу по размытому кадру и снятие паузы по свежему резкому кадру. Реакция привода и время до распознаваемого кадра требуют дополнительных данных. Кандидат не установлен.
## Два дополнительных пролёта на PR №13
Время местное, UTC+7. Тайминги отсчитаны от входа в TRACK. Проекция берётся из разреженных строк AIM, поэтому её первое появление даёт только верхнюю границу времени появления в журнале.
| Начало TRACK | Первый физический старт | Первое подтверждение оптики | Первая записанная безопасная проекция | До 2× / 4× / 8× |
| --- | ---: | ---: | ---: | --- |
| 14:24:57,917 | +8,118 с | +17,020 с | +11,230 с | 28,163 / 47,218 / 76,182 с |
| 14:28:06,389 | +4,294 с | +16,985 с | +13,713 с | 45,665 / 70,481 / 97,097 с |
В первом пролёте два коротких импульса 100 и 220 мс не получили отдельного подтверждения оптики. Во втором исходный обычный импульс снят после PUT на фоне `image_motion`, два пробных импульса по 100 мс также остались без оптического подтверждения. Первое подтверждение получено на обычных запросах №3 и №5 соответственно. Первые записанные безопасные проекции в обоих случаях позже первого движения, поэтому изменение длительности из PR №14 ещё не подтверждает выигрыш на этих пролётах. Защитные остановки сохраняются.
На кадрах второго пролёта PTS 94 и 114 расширенная область вернула `None`. Энергия в ядре рамки составила 142 и 8994 соответственно. При пороге 280 первый кадр удерживает паузу, второй её снимает. Два различимых кадра из пролёта 14:24 проходят проверку. Сопоставление PTS с UTC на уровне отдельных кадров не выполнено. В окнах обоих пролётов журнал не показывает отправку тревоги по WebSocket.
## Воспроизводимый эталон первых 20 секунд
Для полевого сравнения PR №14 пишет `decision_frame` только для PTZ17 через существующую ограниченную асинхронную очередь. Событие связывает номер и время кадра с состоянием проверки, полем зрения, оценкой резкости, запросом зума, длительностью и итоговой командой. Ненулевые команды и идентификаторы проверяются по журналу доставки и замерам оптики. Для первого резкого кадра учитывается только измерение с текущего кадра и размер рамки от 20 px. Эталон предыдущей версии располагает лишь редкими строками оценки резкости и выборочными JPEG.
`replay_ptz17_reference.py` читает зафиксированные команды, завершения запросов и выборки свежего HFOV из `reference_fixture.json`. Запуск `python replay_ptz17_reference.py` восстанавливает `reference_replay.json`. В журнале время подтверждения и первое наблюдаемое изменение HFOV могут отличаться из-за округления меток и порядка записи. Время измеримого сужения определяется отдельно от подтверждения конкретного запроса.
| TRACK, UTC+7 | Первый старт → первое подтверждение | Первый подтверждённый запрос | Свежие замеры HFOV за 20 с |
| --- | ---: | --- | ---: |
| 14:12:02 | 4,512 с | №3, 340 мс | 257 |
| 14:24:57 | 8,902 с | №3, 340 мс | 259 |
| 14:28:06 | 12,691 с | №5, 220 мс | 253 |
Во всех трёх эпизодах поле зрения оставалось 59° до первого успешного запроса и затем сузилось до 54,12°. Это указывает на отсутствие измеримого сужения на ранних попытках. Из разреженных AIM нельзя восстановить разрешение более длинного первого импульса в момент решения или пересчитать физический контрфактический результат. Данные пригодны для сравнения по номеру запроса, времени первого оптического подтверждения и дальнейшим отметкам 2×/4×/8×. Для сравнения по времени до первого различимого резкого кадра нужна привязка PTS к UTC и покадровая проверка.

@ -0,0 +1,6 @@
{
"base_sha256": "6cf484271ef3659028b0b4d43041addb05102f91d2758ab472d968a52d24e911",
"candidate_sha256": "f04d8a8d7a4105fe6812afaed00655dc42cbf7e6fb014e01d9f5efb306db13ca",
"patch_sha256": "555d329a1c437187e254330384ec1dab60dc3fb8ac859c710c9cef517ac59dd5",
"installed": false
}

File diff suppressed because it is too large Load Diff

@ -0,0 +1,390 @@
{
"1412": {
"start_utc": "2026-11-13T07:12:02.328+00:00",
"status_samples": 257,
"first_send_s": 6.041,
"first_start_s": 6.115,
"first_confirmed_request": 3,
"first_optics_s": 10.627,
"startup_to_optics_s": 4.512,
"first_logged_projection_s": 9.869,
"first_request_projection_at_decision": "unknown",
"requests": [
{
"request": 1,
"kind": "normal",
"seq": 5714,
"start_s": 6.115,
"nominal_s": 0.1,
"hard_limit_s": 0.12,
"final": {
"time_s": 6.231,
"status": "delivered_wait_optics",
"accounted_duration_s": 0.191,
"required_duration_s": 0.07,
"optics_at_finalize": false,
"reason": "priority_stop:watchdog"
},
"explicit_confirmation_s": null,
"decisions": [],
"first_status_narrowing": null
},
{
"request": 2,
"kind": "normal",
"seq": 5724,
"start_s": 7.766,
"nominal_s": 0.22,
"hard_limit_s": 0.28,
"final": {
"time_s": 8.086,
"status": "delivered_wait_optics",
"accounted_duration_s": 0.402,
"required_duration_s": 0.154,
"optics_at_finalize": false,
"reason": "priority_stop:watchdog"
},
"explicit_confirmation_s": null,
"decisions": [],
"first_status_narrowing": null
},
{
"request": 3,
"kind": "normal",
"seq": 5736,
"start_s": 10.164,
"nominal_s": 0.34,
"hard_limit_s": 0.4,
"final": {
"time_s": 10.496,
"status": "delivered_wait_optics",
"accounted_duration_s": 0.395,
"required_duration_s": 0.238,
"optics_at_finalize": false,
"reason": "physical_stop"
},
"explicit_confirmation_s": 10.627,
"decisions": [
{
"time_s": 10.481,
"reason": "recenter",
"blockers": "angle"
}
],
"first_status_narrowing": {
"time_s": 10.627,
"hfov_deg": 54.12173440987275
}
},
{
"request": 4,
"kind": "normal",
"seq": 5757,
"start_s": 14.109,
"nominal_s": 0.1,
"hard_limit_s": 0.12,
"final": {
"time_s": 14.182,
"status": "discarded",
"accounted_duration_s": 0.147,
"required_duration_s": 0.07,
"optics_at_finalize": false,
"reason": "priority_stop:cancel_after_put"
},
"explicit_confirmation_s": null,
"decisions": [
{
"time_s": 14.055,
"reason": "recenter",
"blockers": "followup+angle+center_sample"
}
],
"first_status_narrowing": null
},
{
"request": 5,
"kind": "normal",
"seq": 5772,
"start_s": 16.382,
"nominal_s": 0.1,
"hard_limit_s": 0.12,
"final": {
"time_s": 16.419,
"status": "short",
"accounted_duration_s": 0.055,
"required_duration_s": 0.07,
"optics_at_finalize": false,
"reason": "physical_stop"
},
"explicit_confirmation_s": null,
"decisions": [
{
"time_s": 16.399,
"reason": "size_controller",
"blockers": "angle"
}
],
"first_status_narrowing": null
},
{
"request": 6,
"kind": "normal",
"seq": 5778,
"start_s": 17.247,
"nominal_s": 0.34,
"hard_limit_s": 0.4,
"final": {
"time_s": 17.445,
"status": "delivered_wait_optics",
"accounted_duration_s": 0.244,
"required_duration_s": 0.238,
"optics_at_finalize": false,
"reason": "physical_stop"
},
"explicit_confirmation_s": null,
"decisions": [
{
"time_s": 17.401,
"reason": "recenter",
"blockers": "angle"
},
{
"time_s": 17.444,
"reason": "size_controller",
"blockers": "followup+angle+center_history+track_history"
}
],
"first_status_narrowing": null
}
]
},
"1424": {
"start_utc": "2026-11-13T07:24:57.917+00:00",
"status_samples": 259,
"first_send_s": 8.054,
"first_start_s": 8.118,
"first_confirmed_request": 3,
"first_optics_s": 17.02,
"startup_to_optics_s": 8.902,
"first_logged_projection_s": 11.23,
"first_request_projection_at_decision": "unknown",
"requests": [
{
"request": 1,
"kind": "normal",
"seq": 7515,
"start_s": 8.118,
"nominal_s": 0.1,
"hard_limit_s": 0.12,
"final": {
"time_s": 8.245,
"status": "delivered_wait_optics",
"accounted_duration_s": 0.192,
"required_duration_s": 0.07,
"optics_at_finalize": false,
"reason": "priority_stop:watchdog"
},
"explicit_confirmation_s": null,
"decisions": [],
"first_status_narrowing": null
},
{
"request": 2,
"kind": "normal",
"seq": 7536,
"start_s": 12.205,
"nominal_s": 0.22,
"hard_limit_s": 0.28,
"final": {
"time_s": 12.392,
"status": "delivered_wait_optics",
"accounted_duration_s": 0.248,
"required_duration_s": 0.154,
"optics_at_finalize": false,
"reason": "physical_stop"
},
"explicit_confirmation_s": null,
"decisions": [
{
"time_s": 12.379,
"reason": "recenter",
"blockers": "angle+center_sample"
}
],
"first_status_narrowing": null
},
{
"request": 3,
"kind": "normal",
"seq": 7556,
"start_s": 16.563,
"nominal_s": 0.34,
"hard_limit_s": 0.4,
"final": {
"time_s": 17.018,
"status": "delivered_wait_optics",
"accounted_duration_s": 0.47,
"required_duration_s": 0.238,
"optics_at_finalize": false,
"reason": "priority_stop:watchdog"
},
"explicit_confirmation_s": 17.02,
"decisions": [],
"first_status_narrowing": {
"time_s": 17.02,
"hfov_deg": 54.12173440987275
}
},
{
"request": 4,
"kind": "normal",
"seq": 7572,
"start_s": 19.593,
"nominal_s": 0.34,
"hard_limit_s": 0.4,
"final": null,
"explicit_confirmation_s": null,
"decisions": [],
"first_status_narrowing": {
"time_s": 19.901,
"hfov_deg": 46.524147844879025
}
}
]
},
"1428": {
"start_utc": "2026-11-13T07:28:06.389+00:00",
"status_samples": 253,
"first_send_s": 4.227,
"first_start_s": 4.294,
"first_confirmed_request": 5,
"first_optics_s": 16.985,
"startup_to_optics_s": 12.691,
"first_logged_projection_s": 13.713,
"first_request_projection_at_decision": "unknown",
"requests": [
{
"request": 1,
"kind": "normal",
"seq": 8125,
"start_s": 4.294,
"nominal_s": 0.1,
"hard_limit_s": 0.12,
"final": {
"time_s": 4.399,
"status": "discarded",
"accounted_duration_s": 0.172,
"required_duration_s": 0.07,
"optics_at_finalize": false,
"reason": "priority_stop:cancel_after_put"
},
"explicit_confirmation_s": null,
"decisions": [
{
"time_s": 4.235,
"reason": "image_motion",
"blockers": "-"
}
],
"first_status_narrowing": null
},
{
"request": 2,
"kind": "probe",
"seq": 8137,
"start_s": 6.302,
"nominal_s": 0.1,
"hard_limit_s": 0.12,
"final": {
"time_s": 6.448,
"status": "discarded",
"accounted_duration_s": 0.208,
"required_duration_s": 0.07,
"optics_at_finalize": false,
"reason": "priority_stop:watchdog"
},
"explicit_confirmation_s": null,
"decisions": [],
"first_status_narrowing": null
},
{
"request": 3,
"kind": "probe",
"seq": 8157,
"start_s": 10.195,
"nominal_s": 0.1,
"hard_limit_s": 0.12,
"final": {
"time_s": 10.365,
"status": "delivered_wait_optics",
"accounted_duration_s": 0.208,
"required_duration_s": 0.07,
"optics_at_finalize": false,
"reason": "priority_stop:watchdog"
},
"explicit_confirmation_s": null,
"decisions": [
{
"time_s": 10.261,
"reason": "size_controller",
"blockers": "angle"
}
],
"first_status_narrowing": null
},
{
"request": 4,
"kind": "normal",
"seq": 8178,
"start_s": 14.181,
"nominal_s": 0.22,
"hard_limit_s": 0.28,
"final": {
"time_s": 14.273,
"status": "discarded",
"accounted_duration_s": 0.121,
"required_duration_s": 0.154,
"optics_at_finalize": false,
"reason": "priority_stop:cancel_after_put"
},
"explicit_confirmation_s": null,
"decisions": [
{
"time_s": 14.158,
"reason": "recenter",
"blockers": "angle+center_sample"
}
],
"first_status_narrowing": null
},
{
"request": 5,
"kind": "normal",
"seq": 8194,
"start_s": 16.639,
"nominal_s": 0.22,
"hard_limit_s": 0.28,
"final": {
"time_s": 16.942,
"status": "delivered_wait_optics",
"accounted_duration_s": 0.314,
"required_duration_s": 0.154,
"optics_at_finalize": false,
"reason": "priority_stop:watchdog"
},
"explicit_confirmation_s": 16.985,
"decisions": [
{
"time_s": 16.894,
"reason": "size_controller",
"blockers": "angle"
}
],
"first_status_narrowing": {
"time_s": 16.986,
"hfov_deg": 54.12173440987275
}
}
]
}
}

@ -0,0 +1,135 @@
"""Replay recorded PTZ17 lens transactions and their fresh HFOV samples."""
from __future__ import annotations
import argparse
from dataclasses import asdict, dataclass
import json
import math
from pathlib import Path
import re
from typing import Any
WINDOW_S = 20.0
MIN_HFOV_CHANGE_RATIO = 0.004
MAX_STATUS_AGE_S = 0.65
MIN_PROJECTION_MARGIN = 0.16
EPISODES = ("1412", "1424", "1428")
START = re.compile(r"request=(\d+) kind=(\w+) physical start seq=(\d+) pulse=([.\d]+)s hard=([.\d]+)s")
RESULT = re.compile(r"request=(\d+) result=(\w+) duration=([.\d]+)s min=([.\d]+)s optics=(True|False) reason=(\S+)")
DECISION = re.compile(r"request=(\d+).*?reason=(\S+) blockers=(\S+)")
CONFIRMED = re.compile(r"request=(\d+) optics confirmed\b")
@dataclass(frozen=True, slots=True)
class LensSample:
time_s: float
hfov_deg: float
def first_hfov_change(
baseline: LensSample, samples: list[LensSample], *, from_s: float, until_s: float,
) -> LensSample | None:
"""Return the first fresh HFOV narrowing of at least 0.4 percent."""
return next((
sample for sample in samples
if math.isfinite(sample.time_s) and math.isfinite(sample.hfov_deg)
and 0.0 < sample.hfov_deg < 180.0
and from_s <= sample.time_s < until_s and sample.time_s > baseline.time_s
and (baseline.hfov_deg - sample.hfov_deg) / baseline.hfov_deg >= MIN_HFOV_CHANGE_RATIO
), None)
def make_fixture(path: Path) -> dict[str, Any]:
report = json.loads(path.read_bytes())
assert report["status"] == "checked"
detail = report["detail"]
assert detail["covers"]
rows = detail["rows"]
own_status = [value["early_status"] for value in detail["telemetry"].values() if value["early_status"]]
assert len(own_status) == 1
keys = ("[ZOOM DELIVERY]", "[ZOOM DECISION]")
return {
"start_utc": report["start"],
"initial_send_s": detail["axis_commands"]["first"][0][0],
"rows": {key: [row for row in rows.get(key, []) if 0.0 <= row[0] <= WINDOW_S] for key in keys},
"status": own_status[0],
"first_logged_projection_s": next(
(t for t, row in rows.get("[AIM]", []) if 0.0 <= t <= WINDOW_S
and float(row.get("approach_margin", -1.0)) >= MIN_PROJECTION_MARGIN), None,
),
}
def replay(episode: dict[str, Any]) -> dict[str, Any]:
samples = [LensSample(*row) for row in episode["status"]]
assert all(math.isfinite(s.time_s) and 0.0 < s.hfov_deg < 180.0 for s in samples)
assert samples and samples == sorted(samples, key=lambda sample: sample.time_s)
requests: dict[int, dict[str, Any]] = {}
for time_s, line in episode["rows"]["[ZOOM DELIVERY]"]:
if match := START.search(line):
request_id, kind, seq, pulse, hard = match.groups()
assert int(request_id) not in requests
requests[int(request_id)] = dict(
request=int(request_id), kind=kind, seq=int(seq), start_s=time_s,
nominal_s=float(pulse), hard_limit_s=float(hard), final=None,
explicit_confirmation_s=None, decisions=[],
)
elif match := RESULT.search(line):
request_id, status, duration, minimum, optics, reason = match.groups()
request = requests[int(request_id)]
assert request["final"] is None
request["final"] = dict(
time_s=time_s, status=status, accounted_duration_s=float(duration),
required_duration_s=float(minimum), optics_at_finalize=optics == "True", reason=reason,
)
elif match := CONFIRMED.search(line):
requests[int(match[1])]["explicit_confirmation_s"] = time_s
for time_s, line in episode["rows"]["[ZOOM DECISION]"]:
if (match := DECISION.search(line)) and int(match[1]) in requests:
requests[int(match[1])]["decisions"].append(dict(time_s=time_s, reason=match[2], blockers=match[3]))
ordered = list(requests.values())
for index, request in enumerate(ordered):
start_s = request["start_s"]
assert 0.0 < request["nominal_s"] <= request["hard_limit_s"] <= 0.4
until_s = ordered[index + 1]["start_s"] if index + 1 < len(ordered) else math.nextafter(WINDOW_S, math.inf)
baseline = next((s for s in reversed(samples) if s.time_s < start_s), None)
measured = None
if baseline is not None and start_s - baseline.time_s <= MAX_STATUS_AGE_S:
measured = first_hfov_change(baseline, samples, from_s=start_s, until_s=until_s)
request["first_status_narrowing"] = asdict(measured) if measured is not None else None
final = request["final"]
if final is not None and final["status"] == "confirmed" and request["explicit_confirmation_s"] is None:
request["explicit_confirmation_s"] = final["time_s"]
first_confirmed = next((row for row in ordered if row["explicit_confirmation_s"] is not None), None)
first_s = ordered[0]["start_s"] if ordered else None
confirm_s = first_confirmed["explicit_confirmation_s"] if first_confirmed else None
return dict(
start_utc=episode["start_utc"], status_samples=len(samples),
first_send_s=episode["initial_send_s"], first_start_s=first_s,
first_confirmed_request=first_confirmed["request"] if first_confirmed else None,
first_optics_s=confirm_s,
startup_to_optics_s=round(confirm_s - first_s, 3) if confirm_s is not None else None,
first_logged_projection_s=episode["first_logged_projection_s"],
first_request_projection_at_decision="unknown",
requests=ordered,
)
def main() -> None:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--session", type=Path, help="Build the fixture from the three bounded observer reports")
parser.add_argument("--fixture", type=Path, default=Path(__file__).with_name("reference_fixture.json"))
parser.add_argument("--output", type=Path, default=Path(__file__).with_name("reference_replay.json"))
args = parser.parse_args()
if args.session:
fixture = {key: make_fixture(args.session / f"ref_{key}.json") for key in EPISODES}
args.fixture.write_text(json.dumps(fixture, indent=2) + "\n", encoding="utf-8")
fixture = json.loads(args.fixture.read_bytes())
result = {key: replay(value) for key, value in fixture.items()}
args.output.write_text(json.dumps(result, indent=2) + "\n", encoding="utf-8")
if __name__ == "__main__":
main()

@ -0,0 +1,782 @@
--- a/postprocess.py
+++ b/postprocess.py
@@ -12,7 +12,7 @@
from . import config, state, visual_control
from .zoom_controller import (
- ZoomFrame, controller_for_track, expire_calibration, flush_zoom_blocks, record_zoom_blocks, telemetry_tick,
+ ZoomFrame, _episode_telemetry, controller_for_track, expire_calibration, flush_zoom_blocks, record_zoom_blocks, telemetry_tick,
)
from . import motion_detector
from .utils import (
@@ -46,6 +46,7 @@
from .tracking_policy import should_allow_offsector_park, should_enforce_track_sector_limits
from .bt_tracker import ByteTracker
from .visual_tracker import (
+ VisualTrackResult,
bbox_center_distance_norm,
bbox_iou,
visual_tracker_manager,
@@ -690,6 +691,8 @@
def _focus_quality_score(
frame_bgr: np.ndarray,
bbox: Tuple[int, int, int, int] | list[int],
+ *,
+ roi_scale: float | None = None,
) -> float | None:
"""Return Laplacian focus energy from a bounded ROI around the target.
@@ -708,7 +711,7 @@
if not np.isfinite([x1, y1, x2, y2]).all() or x2 <= x1 or y2 <= y1:
return None
- scale = max(1.0, float(getattr(config, "AUTOFOCUS_ROI_SCALE", 2.5)))
+ scale = max(1.0, float(getattr(config, "AUTOFOCUS_ROI_SCALE", 2.5) if roi_scale is None else roi_scale))
cx = (x1 + x2) * 0.5
cy = (y1 + y2) * 0.5
roi_w = max(16.0, (x2 - x1) * scale)
@@ -741,6 +744,221 @@
return score if math.isfinite(score) else None
+@dataclass(frozen=True, slots=True)
+class _PTZ17ZoomTuning:
+ focus_max_hfov_deg: float = 18.0
+ focus_min_side_px: int = 20
+ focus_core_only_threshold_scale: float = 8.0
+ focus_unknown_retry_s: float = 0.60
+ focus_unknown_max_gap_s: float = 0.25
+ focus_recovery_samples: int = 2
+ frame_max_age_s: float = 0.25
+ detector_max_age_s: float = 0.65
+ first_pulse_s: float = 0.34
+ hard_stop_s: float = 0.40
+ startup_native: int = 10
+ projected_margin_min: float = 0.16
+ edge_margin_min: float = 0.30
+ center_max_norm: float = 0.12
+ image_rate_max_norm_s: float = 0.04
+
+
+_PTZ17_ZOOM = _PTZ17ZoomTuning()
+
+
+def _record_ptz17_decision(st: dict, at: float, **fields: Any) -> None:
+ """Publish decision metadata to the existing bounded asynchronous queue."""
+ generation, started_at = visual_control.owner(st)[1:3]
+ if started_at <= 0.0 or not math.isfinite(started_at):
+ return
+ values = {
+ key: None if isinstance(value, float) and not math.isfinite(value) else value
+ for key, value in fields.items()
+ }
+ _episode_telemetry(config, _PTZ17_CAM_IDX, (generation, started_at),
+ "decision_frame", at, **values)
+
+
+_PTZ17_RECOVERY_BOX_LIMIT = 12
+_PTZ17_RECOVERY_REASON_LIMIT = 160
+_DetectorBox = tuple[list[int], float, int]
+
+
+def _recovery_box_px(box: tuple[int, ...] | list[int] | None) -> list[int] | None:
+ """Snapshot xyxy pixels from the top left of the processing image, x right and y down."""
+ if box is None or len(box) != 4:
+ return None
+ try:
+ return [int(value) for value in box]
+ except (TypeError, ValueError, OverflowError):
+ return None
+
+
+def _recovery_detector_box(candidate: _DetectorBox | None) -> dict[str, Any] | None:
+ if candidate is None:
+ return None
+ box, score, class_id = candidate
+ confidence = float(score)
+ return dict(bbox_px=_recovery_box_px(box), confidence=confidence if math.isfinite(confidence) else None,
+ class_id=int(class_id))
+
+
+def _record_ptz17_recovery(
+ cam_idx: int, st: dict, observation_utc: float, source_seq: int | None,
+ frame_w: int, frame_h: int, visual_result: VisualTrackResult, *,
+ input_kind: str, outcome: str, trusted_bbox: tuple[int, ...] | list[int] | None,
+ reference_bbox: tuple[int, ...] | list[int] | None,
+ validation_targets: list[_DetectorBox], reacquire_targets: list[_DetectorBox],
+ raw_box_count: int, expected_track_class: int | None = None, detector_match: _DetectorBox | None = None,
+ selected: _DetectorBox | None = None, seeded: VisualTrackResult | None = None,
+) -> None:
+ """Record already available inputs and the recovery outcome off the control thread."""
+ if (cam_idx != _PTZ17_CAM_IDX or st.get("mode") != "TRACK" or not st.get("tracking_active")
+ or not getattr(config, "PREDICTIVE_ZOOM_TELEMETRY_DIR", "logs/ptz_zoom")):
+ return
+ _, generation, started_at, rearm_epoch = visual_control.owner(st)
+ if started_at <= 0.0 or not math.isfinite(started_at) or not math.isfinite(observation_utc):
+ return
+
+ def tracker_fields(result: VisualTrackResult) -> dict[str, Any]:
+ score = float(result.score)
+ return dict(bbox_px=_recovery_box_px(result.bbox), ok=bool(result.ok),
+ score=score if math.isfinite(score) else None, class_id=int(result.target_class),
+ frame_seq=int(result.source_seq) if result.source_seq is not None else None,
+ reason=str(result.reason)[:_PTZ17_RECOVERY_REASON_LIMIT])
+
+ _episode_telemetry(
+ config, cam_idx, (generation, started_at), "recovery_frame", time.time(),
+ observation_utc=observation_utc, frame_seq=int(source_seq) if source_seq is not None else None,
+ frame_size_px=[frame_w, frame_h], input_kind=input_kind, outcome=outcome,
+ expected_track_class=expected_track_class,
+ trusted_bbox_px=_recovery_box_px(trusted_bbox), association_reference_bbox_px=_recovery_box_px(reference_bbox),
+ ostrack=tracker_fields(visual_result), reinitialized_ostrack=tracker_fields(seeded) if seeded is not None else None,
+ yolo_raw_count=raw_box_count,
+ yolo_validation_count=len(validation_targets), yolo_reacquire_count=len(reacquire_targets),
+ yolo_validation=[_recovery_detector_box(box) for box in validation_targets[:_PTZ17_RECOVERY_BOX_LIMIT]],
+ yolo_reacquire=[_recovery_detector_box(box) for box in reacquire_targets[:_PTZ17_RECOVERY_BOX_LIMIT]],
+ yolo_match=_recovery_detector_box(detector_match), yolo_selected=_recovery_detector_box(selected),
+ reacquire_votes=int(st.get("visual_reacquire_votes", 0) or 0),
+ reacquire_vote_frame_seq=int(st.get("visual_reacquire_source_seq", -1)),
+ zoom_rearm_epoch=rearm_epoch, zoom_rearm_required=bool(st.get("zoom_rearm_required")),
+ zoom_rearm_votes=int(st.get("zoom_rearm_votes", 0) or 0),
+ )
+
+
+def _ptz17_target_focus_score(
+ frame_bgr: np.ndarray, bbox: tuple[int, int, int, int] | list[int],
+) -> float | None:
+ """Assess target detail when the wider crop has little contrast."""
+ core = _focus_quality_score(frame_bgr, bbox, roi_scale=1.0)
+ if core is None:
+ return None
+ expanded = _focus_quality_score(frame_bgr, bbox)
+ if expanded is not None:
+ return min(core, expanded)
+ threshold = max(0.0, float(getattr(config, "AUTOFOCUS_BLUR_THRESHOLD", 35.0)))
+ if core >= threshold * _PTZ17_ZOOM.focus_core_only_threshold_scale:
+ return core
+ return None
+
+
+def _ptz17_focus_hold(
+ st: dict, *, hfov_deg: float, side_px: int, frame_is_current: bool, captured_at: float,
+) -> str | None:
+ """Keep the lens at its current FOV while the settled target is blurry."""
+ owner = visual_control.owner(st)
+ if owner[2] <= 0.0 or not 0.0 < hfov_deg <= _PTZ17_ZOOM.focus_max_hfov_deg:
+ st.pop("ptz17_focus_hold", None)
+ st.pop("ptz17_focus_recovery", None)
+ return None
+ previous = st.get("ptz17_focus_hold")
+ reason = previous[1] if previous is not None and previous[0] == owner else None
+ if not frame_is_current or not math.isfinite(captured_at):
+ return reason
+ focus_state = st.get("focus_state")
+ if focus_state == "disabled":
+ reason = None
+ elif side_px >= _PTZ17_ZOOM.focus_min_side_px:
+ if focus_state == "sharp" and reason is not None:
+ recovery = st.get("ptz17_focus_recovery")
+ votes = 1
+ if recovery is not None and recovery[0] == owner:
+ gap_s = captured_at - recovery[1]
+ if gap_s <= 0.0:
+ return reason
+ if gap_s <= _PTZ17_ZOOM.focus_unknown_max_gap_s:
+ votes += recovery[2]
+ st["ptz17_focus_recovery"] = (owner, captured_at, votes)
+ if votes >= _PTZ17_ZOOM.focus_recovery_samples:
+ reason = None
+ elif focus_state in {
+ "blur_suspected", "blur_fast_suspected", "blur_cooldown", "blur_wait",
+ "unassessable", "requested", "settling",
+ }:
+ reason = str(focus_state)
+ if focus_state != "sharp" or side_px < _PTZ17_ZOOM.focus_min_side_px or reason is None:
+ st.pop("ptz17_focus_recovery", None)
+ if reason is not None:
+ st["ptz17_focus_hold"] = (owner, reason)
+ else:
+ st.pop("ptz17_focus_hold", None)
+ return reason
+
+
+def _ptz17_unassessable_retry_ready(st: dict, captured_at: float) -> bool:
+ """Authorize one recovery attempt per track owner after sustained low contrast."""
+ owner = visual_control.owner(st)
+ evidence = st.get("ptz17_focus_unknown")
+ if owner[2] <= 0.0 or not math.isfinite(captured_at):
+ return False
+ if evidence is None or evidence[0] != owner:
+ st["ptz17_focus_unknown"] = (owner, captured_at, captured_at)
+ return False
+ if st.get("ptz17_focus_unknown_attempt") == owner:
+ return False
+ gap_s = captured_at - evidence[2]
+ if gap_s <= 0.0:
+ return False
+ since = captured_at if gap_s > _PTZ17_ZOOM.focus_unknown_max_gap_s else evidence[1]
+ st["ptz17_focus_unknown"] = (owner, since, captured_at)
+ return captured_at - since >= _PTZ17_ZOOM.focus_unknown_retry_s
+
+
+def _ptz17_first_useful_timing(
+ st: dict, timing: tuple[float, float], *, native: int, normal_onset: bool,
+ frame_age_s: float, detector_age_s: float, hfov_deg: float, wide_hfov_deg: float,
+ approach_margin: float | None, edge_margin: float, center_error: float, image_rate: float,
+) -> tuple[float, float]:
+ """Select the longer measured-response candidate within existing deadlines."""
+ tuning = _PTZ17_ZOOM
+ if (
+ not normal_onset or timing[0] <= 0.0 or native != tuning.startup_native
+ or st.get("zoom_no_effect_blocked")
+ or st.get("zoom_stop_obligation_active") or st.get("lens_move_stop_required")
+ or not 0.0 <= frame_age_s <= tuning.frame_max_age_s
+ or not 0.0 <= detector_age_s <= tuning.detector_max_age_s
+ or not 0.0 < hfov_deg <= wide_hfov_deg < 180.0
+ or hfov_deg < wide_hfov_deg * max(.85, float(getattr(config, "ZOOM_RESPONSE_WIDE_RATIO", .85)))
+ or approach_margin is None or not tuning.projected_margin_min <= approach_margin <= .5
+ or not tuning.edge_margin_min <= edge_margin <= .5
+ or not 0.0 <= center_error <= tuning.center_max_norm
+ or not 0.0 <= image_rate <= tuning.image_rate_max_norm_s
+ ):
+ return timing
+ if st.get("zoom_step_pending"):
+ # Revalidate only the original request created by the PTZ17 profile.
+ # The existing pulse gate owns the pending timer and expiry.
+ marker = st.get("ptz17_first_timing_owner")
+ if marker == (visual_control.owner(st), st.get("zoom_step_pending_id")):
+ return (float(st["zoom_step_pending_pulse_sec"]), float(st["zoom_step_pending_hard_sec"]))
+ return timing
+ if int(st.get("zoom_step_request_id", 0) or 0) != 0:
+ return timing
+ pulse = min(tuning.first_pulse_s, float(getattr(config, "ZOOM_RESPONSE_MAX_PULSE_SEC", .34)))
+ hard = min(tuning.hard_stop_s, float(getattr(config, "ZOOM_RESPONSE_MAX_HARD_STOP_SEC", .40)))
+ return (pulse, hard) if timing[0] < pulse <= hard and timing[1] <= hard else timing
+
+
def _clear_focus_low_evidence(st: dict) -> None:
st["focus_quality_low_frames"] = 0
st["focus_quality_low_since"] = None
@@ -761,6 +979,7 @@
center_err: float,
hfov_deg: float,
validation_age: float,
+ allow_unassessable_retry: bool = False,
) -> bool:
"""Measure settled target detail and queue one bounded autofocus request."""
if not bool(getattr(config, "AUTOFOCUS_QUALITY_ENABLE", True)) or not bool(
@@ -833,14 +1052,31 @@
_clear_focus_low_evidence(st)
st["focus_last_hfov_deg"] = float(hfov_deg)
- score = _focus_quality_score(frame_bgr, bbox)
+ score = (
+ _ptz17_target_focus_score(frame_bgr, bbox)
+ if cam_idx == _PTZ17_CAM_IDX and float(hfov_deg) <= _PTZ17_ZOOM.focus_max_hfov_deg
+ else _focus_quality_score(frame_bgr, bbox)
+ )
st["focus_quality_last_eval_at"] = float(now)
st["focus_quality_score"] = score
+ unknown_retry = False
if score is None:
st["focus_state"] = "unassessable"
_clear_focus_low_evidence(st)
- return False
-
+ unknown_retry = (
+ allow_unassessable_retry and cam_idx == _PTZ17_CAM_IDX
+ and 0.0 < hfov_deg <= _PTZ17_ZOOM.focus_max_hfov_deg
+ and 0.0 <= validation_age <= _PTZ17_ZOOM.detector_max_age_s
+ and _ptz17_unassessable_retry_ready(st, now)
+ )
+ if not unknown_retry:
+ return False
+ else:
+ st.pop("ptz17_focus_unknown", None)
+
+ if unknown_retry:
+ return _queue_focus_recovery(cam_idx, st, now, reason="unassessable")
+ assert score is not None
alpha = clipf(float(getattr(config, "AUTOFOCUS_SCORE_EMA_ALPHA", 0.35)), 0.01, 1.0)
previous_ema = st.get("focus_quality_ema")
ema = float(score) if not isinstance(previous_ema, (int, float)) else (
@@ -870,7 +1106,10 @@
if ema >= threshold:
# Keep the independent raw-drop evidence while the deliberately slow
# EMA still describes the previously sharp scene.
- st["focus_state"] = "blur_fast_suspected" if raw_drop else "sharp"
+ ptz17_instant_low = (
+ allow_unassessable_retry and cam_idx == _PTZ17_CAM_IDX and score < threshold
+ )
+ st["focus_state"] = "blur_fast_suspected" if raw_drop or ptz17_instant_low else "sharp"
st["focus_quality_low_frames"] = 0
st["focus_quality_low_since"] = None
else:
@@ -916,12 +1155,19 @@
if not confirmed_low:
return False
+ return _queue_focus_recovery(cam_idx, st, now, reason="quality", score=score, ema=ema)
+
+
+def _queue_focus_recovery(
+ cam_idx: int, st: dict, now: float, *, reason: str,
+ score: float | None = None, ema: float | None = None,
+) -> bool:
request_cd = max(0.5, float(getattr(config, "AUTOFOCUS_REQUEST_COOLDOWN_SEC", 15.0)))
last_request = float(st.get("focus_last_request_at", 0.0) or 0.0)
if last_request > 0.0 and (float(now) - last_request) < request_cd:
st["focus_state"] = "blur_cooldown"
return False
- if not bool(call_autofocus(cam_idx, reason="quality")):
+ if not bool(call_autofocus(cam_idx, reason=reason)):
if str(st.get("focus_state", "")) not in {
"unsupported",
"unsupported_backoff",
@@ -931,6 +1177,8 @@
st["focus_state"] = "blur_wait"
return False
+ if reason == "unassessable":
+ st["ptz17_focus_unknown_attempt"] = visual_control.owner(st)
st["focus_state"] = "requested"
st["focus_last_request_at"] = float(now)
st["focus_settle_until"] = float(now) + max(
@@ -938,12 +1186,11 @@
float(getattr(config, "AUTOFOCUS_SETTLE_HOLD_SEC", 0.80)),
)
_clear_focus_low_evidence(st)
- logger.warning(
- "[FOCUS/QUALITY] cam=%s autofocus requested score=%.1f ema=%.1f",
- cam_idx,
- float(score),
- float(ema),
- )
+ if score is not None and ema is not None:
+ logger.warning("[FOCUS/QUALITY] cam=%s autofocus requested score=%.1f ema=%.1f",
+ cam_idx, score, ema)
+ else:
+ logger.warning("[FOCUS/QUALITY] cam=%s autofocus requested reason=%s", cam_idx, reason)
return True
@@ -6757,11 +7004,20 @@
detector_targets: list[tuple[list[int], float, int]],
validation_targets: list[tuple[list[int], float, int]], width: int, height: int,
steering_targets: list[tuple[list[float], float, int]] | None = None,
+ *, recovery_targets: list[_DetectorBox] | None = None, raw_box_count: int = 0,
) -> None:
"""Validate the same image without rewinding live control or loss recovery."""
result = sample.result
bbox = result.bbox
if not result.ok or bbox is None:
+ if recovery_targets is not None:
+ _record_ptz17_recovery(
+ cam_idx, st, float(sample.captured_at), sample.source_seq, width, height, result,
+ input_kind="paired_detector", outcome="paired_tracker_unusable",
+ trusted_bbox=st.get("last_bbox"), reference_bbox=bbox,
+ validation_targets=validation_targets, reacquire_targets=recovery_targets,
+ raw_box_count=raw_box_count,
+ )
return
now = float(sample.captured_at)
target_class = int(result.target_class)
@@ -6783,6 +7039,14 @@
visual_tracker_manager.reset(cam_idx, reason='paired detector identity mismatch')
stop_ptz(cam_idx, source='stop', generation=int(st.get('ptz_generation', 0) or 0))
alarms.ingest_detection(cam_idx, False)
+ if recovery_targets is not None:
+ _record_ptz17_recovery(
+ cam_idx, st, now, sample.source_seq, width, height, result,
+ input_kind="paired_detector", outcome="paired_identity_stop",
+ trusted_bbox=st.get("last_bbox"), reference_bbox=bbox,
+ validation_targets=candidates, reacquire_targets=recovery_targets,
+ raw_box_count=raw_box_count, expected_track_class=target_class,
+ )
return
st['visual_tracker_mismatch_frames'] = 0
if matched is not None and now >= float(st.get('visual_tracker_last_detector_at', 0.) or 0.):
@@ -6802,6 +7066,14 @@
detector_conf=max(alarm_conf, identity_conf),
alarm_eligible=alarm_eligible, cam_idx=cam_idx)
alarms.ingest_detection(cam_idx, alarm_eligible)
+ if recovery_targets is not None:
+ _record_ptz17_recovery(
+ cam_idx, st, now, sample.source_seq, width, height, result,
+ input_kind="paired_detector", outcome="validation_only",
+ trusted_bbox=st.get("last_bbox"), reference_bbox=bbox,
+ validation_targets=candidates, reacquire_targets=recovery_targets,
+ raw_box_count=raw_box_count, expected_track_class=target_class, detector_match=matched,
+ )
@visual_control.serialized_control
@@ -7259,8 +7531,14 @@
)
if evidence_only:
- _consume_paired_detector_evidence(cam_idx, st, visual_sample, detector_targets,
- validation_targets, w, h, steering_targets)
+ trace_recovery = cam_idx == _PTZ17_CAM_IDX and (
+ not visual_sample.result.ok or visual_sample.result.reason == "recovered"
+ or st.get("loss_since") is not None or st.get("zoom_rearm_reason") == "geometry_reject"
+ )
+ _consume_paired_detector_evidence(
+ cam_idx, st, visual_sample, detector_targets, validation_targets, w, h, steering_targets,
+ recovery_targets=reacquire_targets if trace_recovery else None, raw_box_count=raw_box_count,
+ )
return
if bt_active:
@@ -7580,6 +7858,7 @@
# its own gate, but a bad backend result/config override must still
# be unable to move the camera by following a remote cloud edge.
previous_control_bbox = st.get("last_bbox")
+ recovery_input_kind = "visual_control" if visual_only else "detector_control"
gross_visual_jump = False
visual_control_jump = 0.0
visual_control_limit = float(
@@ -7622,6 +7901,9 @@
("center jump", "area ratio", "validated area ratio")
)
)
+ geometry_match = validated_geometry_target = None
+ seeded_geometry = None
+ geometry_outcome = "geometry_no_box"
if (gross_visual_jump or geometric_reject) and visual_result.bbox is not None:
# A large motion is safe only when the *current* detector agrees
# with that new location. A backend result that passed its own
@@ -7643,6 +7925,8 @@
),
allow_target_class_compatibility=True,
)
+ geometry_match = validated_geometry_target
+ geometry_outcome = "geometry_no_match"
if (
validated_geometry_target is not None
and isinstance(previous_control_bbox, (tuple, list))
@@ -7673,6 +7957,7 @@
)
):
validated_geometry_target = None
+ geometry_outcome = "geometry_trusted_area_rejected"
if geometric_reject and validated_geometry_target is not None:
validated_geometry_target = _confirm_loss_reacquire_candidate(
st,
@@ -7682,6 +7967,7 @@
h,
source_seq=source_seq,
)
+ geometry_outcome = "geometry_confirmation_pending"
if validated_geometry_target is not None:
preserved_track_class = (
int(visual_result.target_class)
@@ -7701,6 +7987,7 @@
now=now,
source_seq=source_seq,
)
+ geometry_outcome = "geometry_seed_failed"
if seeded_geometry.ok and seeded_geometry.bbox is not None:
logger.info(
"[OSTRACK/IDENTITY] cam=%s detector validated geometry jump; reinitialized",
@@ -7714,6 +8001,16 @@
_arm_zoom_revalidation(
st, now, "geometry_reinitialized", cam_idx=cam_idx
)
+ if cam_idx == _PTZ17_CAM_IDX:
+ _record_ptz17_recovery(
+ cam_idx, st, now, source_seq, w, h, visual_result,
+ input_kind=recovery_input_kind, outcome="geometry_reinitialized",
+ trusted_bbox=previous_control_bbox, reference_bbox=visual_result.bbox,
+ validation_targets=validation_targets, reacquire_targets=reacquire_targets,
+ raw_box_count=raw_box_count, detector_match=geometry_match,
+ selected=validated_geometry_target, seeded=seeded_geometry,
+ expected_track_class=expected_track_class,
+ )
visual_result = seeded_geometry
reference_bbox = seeded_geometry.bbox
gross_visual_jump = False
@@ -7743,6 +8040,16 @@
source="stop",
generation=int(st.get("ptz_generation", 0) or 0),
)
+ if cam_idx == _PTZ17_CAM_IDX:
+ _record_ptz17_recovery(
+ cam_idx, st, now, source_seq, w, h, visual_result,
+ input_kind=recovery_input_kind, outcome=geometry_outcome,
+ trusted_bbox=previous_control_bbox, reference_bbox=visual_result.bbox,
+ validation_targets=validation_targets, reacquire_targets=reacquire_targets,
+ raw_box_count=raw_box_count,
+ detector_match=geometry_match, selected=validated_geometry_target,
+ seeded=seeded_geometry, expected_track_class=expected_track_class,
+ )
logger.warning(
"[OSTRACK/IDENTITY] cam=%s HOLD rejected geometry reason=%s; awaiting recovery",
cam_idx,
@@ -7771,6 +8078,16 @@
source="stop",
generation=int(st.get("ptz_generation", 0) or 0),
)
+ if cam_idx == _PTZ17_CAM_IDX:
+ _record_ptz17_recovery(
+ cam_idx, st, now, source_seq, w, h, visual_result,
+ input_kind=recovery_input_kind, outcome="control_jump_stop",
+ trusted_bbox=previous_control_bbox, reference_bbox=visual_result.bbox,
+ validation_targets=validation_targets, reacquire_targets=reacquire_targets,
+ raw_box_count=raw_box_count, detector_match=geometry_match,
+ selected=validated_geometry_target, seeded=seeded_geometry,
+ expected_track_class=expected_track_class,
+ )
logger.warning(
"[OSTRACK/IDENTITY] cam=%s STOP rejected geometry reason=%s",
cam_idx,
@@ -7782,6 +8099,7 @@
matched_validation = None
matched_reacquire = None
+ widened_candidate = None
if reference_bbox is not None:
matched_validation = _find_visual_validation_target(
reference_bbox,
@@ -8062,6 +8380,17 @@
det_xyxy.append(tuple(visual_result.bbox))
visual_track_label_index = len(det_labels)
det_labels.append("target track")
+ if cam_idx == _PTZ17_CAM_IDX and not geometry_reinitialized and (
+ visual_result.reason == "recovered" or st.get("loss_since") is not None
+ ):
+ _record_ptz17_recovery(
+ cam_idx, st, now, source_seq, w, h, visual_result,
+ input_kind=recovery_input_kind, outcome="visual_recovered",
+ trusted_bbox=previous_control_bbox, reference_bbox=reference_bbox,
+ validation_targets=validation_targets, reacquire_targets=reacquire_targets,
+ raw_box_count=raw_box_count, detector_match=matched_validation,
+ expected_track_class=expected_track_class,
+ )
else:
ptz17_validation_timeout = bool(
visual_only and _ptz17_validation_timeout_steering(
@@ -8105,6 +8434,7 @@
_arm_zoom_revalidation(
st, now, "visual_reacquire", cam_idx=cam_idx
)
+ seeded = None
if matched_reacquire is not None:
preserved_track_class = (
int(visual_result.target_class)
@@ -8148,6 +8478,19 @@
target_source = "none"
st["visual_tracker_score"] = float(visual_result.score)
st["visual_tracker_last_reason"] = visual_result.reason
+ if cam_idx == _PTZ17_CAM_IDX:
+ _record_ptz17_recovery(
+ cam_idx, st, now, source_seq, w, h, visual_result,
+ input_kind=recovery_input_kind,
+ outcome=target_source if matched_reacquire is not None else
+ "loss_confirmation_pending" if widened_candidate is not None else "loss_no_match",
+ trusted_bbox=previous_control_bbox, reference_bbox=reference_bbox,
+ validation_targets=validation_targets, reacquire_targets=reacquire_targets,
+ raw_box_count=raw_box_count,
+ detector_match=widened_candidate if widened_candidate is not None else matched_reacquire,
+ selected=matched_reacquire, seeded=seeded,
+ expected_track_class=expected_track_class,
+ )
elif best_target is not None:
# ACQUIRE has already approved this target. Seed the appearance
# tracker on the same frame before entering full TRACK.
@@ -9537,6 +9880,50 @@
max(0.0, float(getattr(config, min_key, 0.10))),
)
zoom_cmd = min(max_effective, max(float(zoom_cmd), min_effective))
+ ptz17_focus_reason = None
+ ptz17_focus_checked = False
+ if (cam_idx == _PTZ17_CAM_IDX and float(hfov_deg) <= _PTZ17_ZOOM.focus_max_hfov_deg
+ and not pulse_active and not st.get("zoom_step_pending")):
+ # Check the settled image before authorizing a fresh pulse. The
+ # existing autofocus worker and controller keep their own limits.
+ focus_wall_now = time.time()
+ lens_settled = (
+ not st.get("lens_move_put_inflight") and not st.get("zoom_stop_obligation_active")
+ and not st.get("lens_move_stop_required")
+ and (st.get("last_ptz_physical_cmd") or (0.0, 0.0, 0.0))[2] == 0.0
+ )
+ if (lens_settled and zoom_cmd >= 0.0 and visual_only
+ and visual_control.current(cam_idx, visual_sample, focus_wall_now,
+ max_age=_PTZ17_ZOOM.frame_max_age_s)):
+ _maybe_request_autofocus(
+ cam_idx, st, frame_bgr, (x1, y1, x2, y2), now=float(now),
+ pan_cmd=float(pan_speed) + float(pan_rate_ff),
+ tilt_cmd=float(tilt_speed) + float(tilt_rate_ff),
+ zoom_cmd=0.0, center_err=float(center_err), hfov_deg=float(hfov_deg),
+ validation_age=float(visual_control_validation_age),
+ allow_unassessable_retry=True,
+ )
+ ptz17_focus_checked = True
+ # A small but measurable crop can veto another zoom step.
+ # The higher size threshold for requesting autofocus still applies.
+ if (st.get("focus_state") == "target_too_small"
+ and min(x2 - x1, y2 - y1) >= _PTZ17_ZOOM.focus_min_side_px
+ and 0.0 <= visual_control_validation_age <= _PTZ17_ZOOM.detector_max_age_s):
+ target_score = _ptz17_target_focus_score(frame_bgr, (x1, y1, x2, y2))
+ st["ptz17_small_focus_at"] = now
+ st["focus_quality_score"] = target_score
+ threshold = float(getattr(config, "AUTOFOCUS_BLUR_THRESHOLD", 35.0))
+ st["focus_state"] = (
+ "unassessable" if target_score is None else
+ "sharp" if target_score >= threshold else "blur_suspected"
+ )
+ ptz17_focus_reason = _ptz17_focus_hold(
+ st, hfov_deg=float(hfov_deg), side_px=min(x2 - x1, y2 - y1),
+ frame_is_current=ptz17_focus_checked, captured_at=float(now),
+ )
+ if ptz17_focus_reason is not None and zoom_cmd > 0.0:
+ zoom_cmd = 0.0
+ zoom_zero_reason = "focus_hold"
if probe_start_candidate and identify_start_candidate:
pulse_kind = "probe_identify"
elif probe_start_candidate:
@@ -9645,8 +10032,30 @@
zoom_cmd = 0.0
st["zoom_useful_pulse_reason"] = "wait_response_framing"
zoom_zero_reason = "response_framing"
+ ptz17_timing_changed = False
+ if cam_idx == _PTZ17_CAM_IDX:
+ original_response_timing = response_timing
+ response_timing = _ptz17_first_useful_timing(
+ st, response_timing, native=timing_native,
+ normal_onset=(zoom_cmd > 0.0 and useful_reason == "useful" and useful_optics_fresh
+ and pulse_family == "normal"
+ and fast_approach and normal_zoom_quality_ok
+ and current_track_source == "visual" and not predictive_start
+ and bool(visual_only and visual_control.current(
+ cam_idx, visual_sample, zoom_gate_now,
+ max_age=_PTZ17_ZOOM.frame_max_age_s,
+ ))),
+ frame_age_s=zoom_gate_now - now,
+ detector_age_s=zoom_gate_now - last_visual_zoom_validation,
+ hfov_deg=float(hfov_deg), wide_hfov_deg=float(shared_wide_hfov),
+ approach_margin=approach_margin, edge_margin=float(edge_risk_margin),
+ center_error=max(abs(float(measured_dx)), abs(float(measured_dy))),
+ image_rate=max(float(vel), float(fast_drift)),
+ )
+ ptz17_timing_changed = response_timing != original_response_timing
gate_stop = [] if decision_request else None
continuation_trace = [] if decision_request else None
+ ptz17_zoom_before_gate = float(zoom_cmd) if cam_idx == _PTZ17_CAM_IDX else None
zoom_cmd = _gate_zoom_in_pulse(
st,
# Keep new-request expiry tied to the frame that authorized
@@ -9667,9 +10076,15 @@
)
if predictive_start and zoom_cmd > 0.0 and st["zoom_step_request_id"] > request_id_before_gate:
st["predictive_zoom_request"] = st["zoom_step_pending_id"]
+ if (ptz17_timing_changed and zoom_cmd > 0.0
+ and st["zoom_step_request_id"] > request_id_before_gate):
+ st["ptz17_first_timing_owner"] = (visual_control.owner(st), st["zoom_step_pending_id"])
if gate_stop:
zoom_zero_reason = gate_stop[-1]
decision_generation = st.get("ptz_generation")
+ ptz17_request_after_gate = (
+ int(st.get("zoom_step_pending_id", 0) or 0) if cam_idx == _PTZ17_CAM_IDX else 0
+ )
if (
probe_start_candidate
and zoom_cmd > 0.0
@@ -9693,23 +10108,24 @@
elif zoom_cmd < 0.0 and float(size_est) <= max(0.05, zoomed_size_thr * 0.75):
st["was_zoomed_in"] = False
- _maybe_request_autofocus(
- cam_idx,
- st,
- frame_bgr,
- (x1, y1, x2, y2),
- now=float(now),
- pan_cmd=float(pan_speed) + float(pan_rate_ff),
- tilt_cmd=float(tilt_speed) + float(tilt_rate_ff),
- zoom_cmd=float(zoom_cmd),
- center_err=float(center_err),
- hfov_deg=float(hfov_deg),
- validation_age=(
- float(visual_control_validation_age)
- if current_track_source == "visual"
- else 0.0
- ),
- )
+ if not ptz17_focus_checked:
+ _maybe_request_autofocus(
+ cam_idx,
+ st,
+ frame_bgr,
+ (x1, y1, x2, y2),
+ now=float(now),
+ pan_cmd=float(pan_speed) + float(pan_rate_ff),
+ tilt_cmd=float(tilt_speed) + float(tilt_rate_ff),
+ zoom_cmd=float(zoom_cmd),
+ center_err=float(center_err),
+ hfov_deg=float(hfov_deg),
+ validation_age=(
+ float(visual_control_validation_age)
+ if current_track_source == "visual"
+ else 0.0
+ ),
+ )
st["fallback_done"] = False
@@ -10191,7 +10607,7 @@
stop_ptz(cam_idx, source='stop', generation=int(st.get('ptz_generation', 0) or 0))
return
zoom_decision = None
- if decision_request and zoom_cmd <= 0.0:
+ if (decision_request or cam_idx == _PTZ17_CAM_IDX) and zoom_cmd <= 0.0:
blockers = tuple(name for name, blocked in (
("quality", not zoom_quality_ok),
("framing", not zoom_safe),
@@ -10210,7 +10626,36 @@
("stale", visual_control_stale),
("brake", final_guard_active),
) if blocked)
- zoom_decision = (source_seq, decision_request, zoom_zero_reason, "+".join(blockers) or "-")
+ if decision_request:
+ zoom_decision = (source_seq, decision_request, zoom_zero_reason, "+".join(blockers) or "-")
+ if (cam_idx == _PTZ17_CAM_IDX and st.get("mode") == "TRACK"
+ and st.get("tracking_active") and source_seq is not None
+ and int(source_seq) > 0):
+ _record_ptz17_decision(
+ st, time.time(), frame_seq=int(source_seq), frame_utc=float(now),
+ frame_age_at_gate_s=zoom_gate_now - now, source=current_track_source,
+ bbox_px=[int(x1), int(y1), int(x2), int(y2)],
+ detector_age_at_gate_s=zoom_gate_now - last_visual_zoom_validation,
+ detector_conf=float(st.get("visual_tracker_last_detector_conf", 0.0) or 0.0),
+ tracker_score=float(st.get("visual_tracker_score", 0.0) or 0.0),
+ hfov_deg=float(hfov_deg), optics_age_s=float(optics_age),
+ 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)),
+ 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",
+ blockers=list(blockers) if zoom_cmd <= 0.0 else [],
+ pulse_kind=str(pulse_kind), nominal_s=float(response_timing[0]),
+ hard_limit_s=float(response_timing[1]), timing_profile_changed=ptz17_timing_changed,
+ request_before_gate=decision_request, request_after_gate=ptz17_request_after_gate,
+ request_created=bool(ptz17_request_after_gate > request_id_before_gate),
+ focus_state=st.get("focus_state"), focus_hold=ptz17_focus_reason,
+ focus_sample_current=bool(st.get("focus_quality_last_eval_at") == now or (
+ ptz17_focus_checked and st.get("ptz17_small_focus_at") == now
+ )),
+ focus_score=st.get("focus_quality_score"),
+ )
if predictive_decision is not None:
with _zoom_command_lock(cam_idx):
telemetry_tick(
@@ -10222,6 +10667,8 @@
if getattr(config, "PREDICTIVE_ZOOM_TELEMETRY_DIR", "logs/ptz_zoom"):
blocked = {}
if zoom_cmd <= 0.0 and raw_zoom_needed:
+ if ptz17_focus_reason is not None:
+ blocked["focus_hold"] = {"state": ptz17_focus_reason}
if not stable_ok:
blocked["centering"] = {"error": center_err, "limit": lock_gate, "stable_frames": st.get("stable_frames")}
if not zoom_safe:

@ -0,0 +1,231 @@
"""Offline comparison of TRACK recovery with and without PTZ17 telemetry."""
from contextlib import ExitStack
import importlib.util
import json
import math
import os
from pathlib import Path
import sys
from types import SimpleNamespace
from unittest.mock import Mock, patch
import numpy as np
import pytest
import torch
HERE = Path(__file__).resolve().parent
TRUSTED = (620, 350, 640, 364)
REJECTED = (570, 325, 680, 382)
GOOD = [622, 351, 643, 365]
WRONG = [590, 335, 670, 372]
MOVED = [760, 350, 780, 364]
@pytest.fixture(scope="module")
def versions():
runtime = Path(os.environ["PTZ17_TEST_RUNTIME"])
package = "_ptz17_recovery_runtime"
paths = [runtime / "__init__.py", Path(os.environ["PTZ17_TEST_BASELINE"]),
Path(os.environ["PTZ17_TEST_CANDIDATE"])]
modules = []
for name, path in zip((package, package + ".baseline", package + ".candidate"), paths, strict=True):
spec = importlib.util.spec_from_file_location(
name, path, submodule_search_locations=[str(runtime)] if name == package else None,
)
assert spec and spec.loader
module = importlib.util.module_from_spec(spec)
sys.modules[name] = module
spec.loader.exec_module(module)
modules.append(module)
return modules[1:]
class Boxes:
def __init__(self, observations):
self.xyxy = torch.tensor([box for box, _, _ in observations], dtype=torch.float32)
self.conf = torch.tensor([confidence for _, confidence, _ in observations])
self.cls = torch.tensor([class_id for _, _, class_id in observations])
def __len__(self):
return len(self.conf)
def exercise(module, scenario, *, cam=6, enabled=True):
st = module.state._default_ptz_state(cam)
st.update(tracking_active=True, mode="TRACK", ptz_generation=31, track_started_at=90.0,
last_seen=99.8, last_zoom_seen=99.8, last_bbox=TRUSTED, track_source="visual",
hfov_deg=59.0, zoom_status_at=99.95, abs_zoom=1.0, identity_class=0,
visual_tracker_last_detector_at=99.9, visual_tracker_last_zoom_detector_at=99.9,
visual_tracker_last_detector_conf=0.80)
result_type = module.visual_tracker_manager.update.__globals__["VisualTrackResult"]
frame = np.zeros((720, 1280, 3), dtype=np.uint8)
operations, telemetry = [], []
def emit(_config, _cam, owner, name, at, **fields):
json.dumps(fields, allow_nan=False)
if name == "recovery_frame":
telemetry.append((owner, at, fields))
with ExitStack() as stack:
stack.enter_context(patch.dict(module.state.ptz_states, {cam: st}))
for key, value in {
"PTZ_VISUAL_CONTROL_ENABLE": True, "PREDICTIVE_ZOOM_TELEMETRY_DIR": "offline" if enabled else "",
"DETECT_CONF_BY_CLASS": {0: .65, 1: .65}, "DETECT_CONF": .65,
"DRONE_ONLY": False, "MOTION_DETECT_ENABLE": False, "BT_ENABLE": True,
"VISUAL_TRACKER_MATCH_CENTER_NORM": .10, "VISUAL_TRACKER_LOSS_REACQUIRE_CENTER_BASE": .15,
"VISUAL_TRACKER_LOSS_REACQUIRE_CONFIRM_MAX_GAP_SEC": .65,
}.items():
stack.enter_context(patch.object(module.config, key, value, create=True))
clock = stack.enter_context(patch.object(module.time, "time"))
update = stack.enter_context(patch.object(module.visual_tracker_manager, "update"))
for name in ("_publish_with_boxes", "notify_detected", "call_autofocus", "return_to_preset"):
stack.enter_context(patch.object(module, name))
for name in ("stop_ptz", "move_ptz_bounded"):
stack.enter_context(patch.object(module, name, side_effect=lambda *a, key=name, **kw:
operations.append((key, a, kw))))
stack.enter_context(patch.object(module.alarms, "is_armed", return_value=False))
stack.enter_context(patch.object(module.alarms, "ingest_detection", side_effect=lambda *a:
operations.append(("alarm", a, {}))))
stack.enter_context(patch.object(module.visual_tracker_manager, "record_detector_validation"))
stack.enter_context(patch.object(module.visual_tracker_manager, "reset"))
stack.enter_context(patch.object(module.visual_tracker_manager, "should_refresh", return_value=False))
stack.enter_context(patch.object(module, "_episode_telemetry", side_effect=emit))
zoom_module = sys.modules[module.record_zoom_blocks.__module__]
stack.enter_context(patch.object(zoom_module, "_episode_telemetry", side_effect=emit))
def start(cam_idx, _image, box, *, target_class, detector_conf, now, source_seq):
operations.append(("seed", (cam_idx, tuple(box), target_class, detector_conf, now, source_seq), {}))
ok = scenario != "seed_failed"
return result_type(ok, tuple(box) if ok else None, .8, target_class, detector_conf,
0, "initialized" if ok else "no template", source_seq)
stack.enter_context(patch.object(module.visual_tracker_manager, "start", side_effect=start))
def frame_step(seq, at, tracker_box, reason, observations=(), *, paired=False, visual_only=False):
ok = reason in ("tracked", "recovered")
result = result_type(ok, tracker_box, .80 if ok else .29, 0, .80, 40, reason, seq)
update.return_value = result
clock.return_value = at
sample = module.visual_control.VisualSample(module.visual_control.owner(st), seq, at - .010, result)
module.postprocess_control(cam, frame, SimpleNamespace(boxes=Boxes(observations)), True, seq,
visual_sample=sample if paired or visual_only else None,
visual_only=visual_only)
if scenario == "hold_then_strict":
frame_step(41, 100.0, REJECTED, "validated area ratio 11.34",
[(GOOD, .50, 0), (WRONG, .95, 0)])
frame_step(42, 100.2, REJECTED, "low score", [(GOOD, .51, 0)])
elif scenario == "wide_two_frames":
frame_step(41, 100.0, None, "low score", [(MOVED, .70, 0)])
frame_step(42, 100.3, None, "low score", [(MOVED, .71, 0)])
elif scenario == "seed_failed":
frame_step(41, 100.0, None, "low score", [(GOOD, .81, 0)])
elif scenario == "visual_recovers":
frame_step(41, 100.0, REJECTED, "validated area ratio 11.34", visual_only=True)
frame_step(42, 100.1, TRUSTED, "recovered", visual_only=True)
elif scenario == "paired_hold":
frame_step(41, 100.0, REJECTED, "validated area ratio 11.34", visual_only=True)
frame_step(42, 100.1, TRUSTED, "tracked", [(GOOD, .81, 0)], paired=True)
elif scenario == "geometry_two_frames":
frame_step(41, 100.0, TRUSTED, "center jump", [(GOOD, .81, 0)])
frame_step(42, 100.2, TRUSTED, "center jump", [(GOOD, .82, 0)])
elif scenario == "ordinary_track":
frame_step(41, 100.0, TRUSTED, "tracked", [(GOOD, .81, 0)])
else:
raise ValueError(scenario)
state_evidence = {key: st.get(key) for key in (
"track_source", "zoom_state", "zoom_rearm_epoch", "zoom_rearm_votes", "zoom_prev_cmd",
"visual_reacquire_votes", "identity_state", "alarm_gate_eligible", "last_bbox",
)}
return operations, state_evidence, [fields for _, _, fields in telemetry]
@pytest.mark.parametrize("scenario,outcomes", [
("hold_then_strict", ["geometry_trusted_area_rejected", "detector_reacquire"]),
("wide_two_frames", ["loss_confirmation_pending", "detector_reacquire"]),
("seed_failed", ["detector_fallback"]),
("visual_recovers", ["geometry_no_match", "visual_recovered"]),
("paired_hold", ["geometry_no_match", "validation_only"]),
("geometry_two_frames", ["geometry_confirmation_pending", "geometry_reinitialized"]),
("ordinary_track", []),
])
def test_command_and_alarm_parity(versions, scenario, outcomes):
base, candidate = versions
previous, previous_state, _ = exercise(base, scenario)
actual, actual_state, rows = exercise(candidate, scenario)
assert (actual, actual_state) == (previous, previous_state)
assert [row["outcome"] for row in rows] == outcomes
if scenario == "hold_then_strict":
reject, recover = rows
assert reject["trusted_bbox_px"] == list(TRUSTED)
assert reject["association_reference_bbox_px"] == list(REJECTED)
assert reject["ostrack"]["bbox_px"] == list(REJECTED)
assert reject["yolo_match"]["bbox_px"] == WRONG and reject["yolo_selected"] is None
assert {tuple(box["bbox_px"]) for box in reject["yolo_reacquire"]} == {tuple(WRONG), tuple(GOOD)}
assert recover["yolo_selected"]["bbox_px"] == GOOD
assert recover["reinitialized_ostrack"]["bbox_px"] == GOOD
if scenario == "wide_two_frames":
assert [row["reacquire_votes"] for row in rows] == [1, 2]
assert rows[0]["yolo_selected"] is None
assert rows[1]["yolo_selected"]["bbox_px"] == MOVED
if scenario == "paired_hold":
paired = rows[-1]
assert paired["frame_seq"] == paired["ostrack"]["frame_seq"] == 42
assert paired["observation_utc"] == pytest.approx(100.09)
assert paired["input_kind"] == "paired_detector"
assert paired["yolo_match"]["bbox_px"] == GOOD
if scenario == "geometry_two_frames":
assert [row["reacquire_votes"] for row in rows] == [1, 2]
assert rows[-1]["ostrack"]["ok"] is False
assert rows[-1]["reinitialized_ostrack"]["ok"] is True
assert rows[-1]["reinitialized_ostrack"]["bbox_px"] == GOOD
@pytest.mark.parametrize("cam,enabled", [(8, True), (6, False)])
def test_scope_and_disable(versions, cam, enabled):
assert exercise(versions[1], "hold_then_strict", cam=cam, enabled=enabled)[2] == []
def test_bounds_and_finite_json(versions):
module = versions[1]
valid = module.visual_tracker_manager.update.__globals__["VisualTrackResult"]
result = valid(False, (620, 350, 640, 364), math.nan, 0, .8, 40, "x" * 900, 17)
candidates = [([k, 4, k + 20, 17], math.inf if k == 0 else .8, 0) for k in range(33)]
selected = candidates[-1]
state = dict(mode="TRACK", tracking_active=True, track_started_at=90.0, ptz_generation=7)
sink = Mock()
with patch.object(module, "_episode_telemetry", sink):
module._record_ptz17_recovery(
6, state, 100.0, 17, 1280, 720, result, input_kind="detector_control",
outcome="geometry_hold", trusted_bbox=TRUSTED, reference_bbox=result.bbox,
validation_targets=candidates, reacquire_targets=candidates, raw_box_count=33, selected=selected,
)
assert sink.call_args.args[1:4] == (6, (7, 90.0), "recovery_frame")
row = sink.call_args.kwargs
assert len(row["yolo_validation"]) == len(row["yolo_reacquire"]) == 12
assert row["yolo_validation_count"] == row["yolo_reacquire_count"] == 33
assert row["yolo_selected"]["bbox_px"] == selected[0]
assert row["ostrack"]["score"] is None and row["yolo_validation"][0]["confidence"] is None
assert len(row["ostrack"]["reason"]) == 160
json.dumps(row, allow_nan=False)
def test_full_queue_drops_telemetry_without_waiting(versions, tmp_path):
module = versions[1]
log_module = sys.modules[module.record_zoom_blocks.__module__]
with patch.object(log_module, "Thread"):
writer = log_module.EpisodeTelemetryLogger(tmp_path, capacity=1)
result_type = module.visual_tracker_manager.update.__globals__["VisualTrackResult"]
result = result_type(False, REJECTED, .29, 0, .8, 40, "area ratio 11.34", 17)
state = dict(mode="TRACK", tracking_active=True, track_started_at=90.0, ptz_generation=7)
with patch.object(module.config, "PREDICTIVE_ZOOM_TELEMETRY_DIR", str(tmp_path), create=True):
with patch.dict(log_module._telemetry_loggers, {str(tmp_path): writer}):
for _ in range(2):
module._record_ptz17_recovery(
6, state, 100.0, 17, 1280, 720, result, input_kind="visual_control",
outcome="geometry_no_match", trusted_bbox=TRUSTED, reference_bbox=REJECTED,
validation_targets=[], reacquire_targets=[], raw_box_count=0,
)
assert writer.queue.qsize() == 1
assert writer.dropped == 1

@ -0,0 +1,30 @@
from pathlib import Path
import json
import pytest
from replay_ptz17_reference import LensSample, first_hfov_change, replay
@pytest.mark.parametrize("key,start,request_id,confirmation,delay", [
("1412", 6.115, 3, 10.627, 4.512),
("1424", 8.118, 3, 17.020, 8.902),
("1428", 4.294, 5, 16.985, 12.691),
])
def test_replays_observed_first_optics(
key: str, start: float, request_id: int, confirmation: float, delay: float,
) -> None:
fixture = json.loads(Path(__file__).with_name("reference_fixture.json").read_bytes())
result = replay(fixture[key])
assert result["first_start_s"] == start
assert result["first_confirmed_request"] == request_id
assert result["first_optics_s"] == confirmation and result["startup_to_optics_s"] == delay
assert all(row["first_status_narrowing"] is None for row in result["requests"][:request_id - 1])
assert result["requests"][request_id - 1]["first_status_narrowing"]["hfov_deg"] == pytest.approx(54.122, abs=.001)
def test_measurement_does_not_cross_request_boundary() -> None:
assert first_hfov_change(
LensSample(1., 59.), [LensSample(1.1, float("nan")), LensSample(1.2, 58.9), LensSample(1.3, 54.)],
from_s=1.1, until_s=1.3,
) is None

@ -0,0 +1,9 @@
# PTZ17 · сбор входов геометрического HOLD
Кандидат диагностики для полевой версии `postprocess.py` из `pins.json`. Патч включает телеметрию HOLD из PR №14 и расширяет её. Он не включает изменения восстановления из PR №15, чтобы получить входы на текущем контроллере. При подготовке патч проверен на локальной копии с точной контрольной суммой и обратным применением.
Когда PTZ17 отклоняет рамку по геометрии, в существующий асинхронный журнал `logs/ptz_zoom/ptz-6-<generation>-<track_start>.jsonl` поступают события `hold_capture_input`. Окно работает до трёх секунд после последнего геометрического HOLD или заканчивается вместе с TRACK. Рамки пишутся в пикселях исходного изображения контроллера, `[x1, y1, x2, y2]`, от верхнего левого угла. В записи есть исходная рамка OSTrack с причиной отказа, последняя принятая рамка, использованные списки кандидатов YOLO с классами и уверенностью, подтверждения восстановления до решения, номера кадров, размер кадра, время обработки и доступная метка захвата. События различают визуальное управление, самостоятельный YOLO и сопоставленный с кадром OSTrack результат YOLO. Для самостоятельного YOLO используется время входа в контроллер, когда метка захвата отсутствует.
После разрешённого включения сборщика выберите один файл эпизода и запустите локально `python summarize_capture.py <episode.jsonl>`. Код выхода 0 означает, что все найденные окна завершились и прошли проверки наличия кадров, порядка записей и полноты списков. Код 2 означает отсутствие окон или неполные данные. Пропуски в очереди и усечение списков видны в отчёте. Списки ограничены 64 записями каждый. Отчёт показывает, были ли отклонённая рамка OSTrack и кандидаты YOLO на одном кадре, и выводит зарегистрированные времена до восстановления и решения о зуме. Для повтора нужны сами записи `hold_capture_input` в порядке `input_idx`, с сохранением канала обработки и времени. Восстановление OSTrack и физический отклик камеры требуют дополнительных входов и полевых измерений.
Тесты проверяют запись в настоящую очередь JSONL, совпадение команд привода, STOP и входов тревоги с полевой базой, работу парного и самостоятельного YOLO и обнаружение неполных окон. Сборщик ничего не включает на объекте. Модель, правила тревоги и STOP не меняются.

@ -0,0 +1,440 @@
--- a/postprocess.py
+++ b/postprocess.py
@@ -46,6 +46,7 @@
from .tracking_policy import should_allow_offsector_park, should_enforce_track_sector_limits
from .bt_tracker import ByteTracker
from .visual_tracker import (
+ VisualTrackResult,
bbox_center_distance_norm,
bbox_iou,
visual_tracker_manager,
@@ -776,6 +777,157 @@
}
_episode_telemetry(config, _PTZ17_CAM_IDX, (generation, started_at),
"decision_frame", at, **values)
+
+
+_PTZ17_RECOVERY_BOX_LIMIT = 12
+_PTZ17_RECOVERY_REASON_LIMIT = 160
+_PTZ17_CAPTURE_BOX_LIMIT = 64
+_PTZ17_CAPTURE_TAIL_S = 3.0
+_PTZ17_CAPTURE_STATE_KEYS = (
+ "last_bbox", "last_seen", "loss_since", "visual_reacquire_bbox", "visual_reacquire_at",
+ "visual_reacquire_votes", "visual_reacquire_source_seq", "zoom_rearm_epoch",
+ "zoom_rearm_required", "zoom_rearm_reason",
+)
+_DetectorBox = tuple[list[int], float, int]
+
+
+def _recovery_box_px(box: tuple[int, ...] | list[int] | None) -> list[int] | None:
+ """Snapshot xyxy pixels from the top left of the processing image, x right and y down."""
+ if box is None or len(box) != 4:
+ return None
+ try:
+ return [int(value) for value in box]
+ except (TypeError, ValueError, OverflowError):
+ return None
+
+
+def _recovery_detector_box(candidate: _DetectorBox | None) -> dict[str, Any] | None:
+ if candidate is None:
+ return None
+ box, score, class_id = candidate
+ confidence = float(score)
+ return dict(bbox_px=_recovery_box_px(box), confidence=confidence if math.isfinite(confidence) else None,
+ class_id=int(class_id))
+
+
+def _record_ptz17_recovery(
+ cam_idx: int, st: dict, observation_utc: float, source_seq: int | None,
+ frame_w: int, frame_h: int, visual_result: VisualTrackResult, *,
+ input_kind: str, outcome: str, trusted_bbox: tuple[int, ...] | list[int] | None,
+ reference_bbox: tuple[int, ...] | list[int] | None,
+ validation_targets: list[_DetectorBox], reacquire_targets: list[_DetectorBox],
+ raw_box_count: int, expected_track_class: int | None = None, detector_match: _DetectorBox | None = None,
+ selected: _DetectorBox | None = None, seeded: VisualTrackResult | None = None,
+) -> None:
+ """Record already available inputs and the recovery outcome off the control thread."""
+ if (cam_idx != _PTZ17_CAM_IDX or st.get("mode") != "TRACK" or not st.get("tracking_active")
+ or not getattr(config, "PREDICTIVE_ZOOM_TELEMETRY_DIR", "logs/ptz_zoom")):
+ return
+ _, generation, started_at, rearm_epoch = visual_control.owner(st)
+ if started_at <= 0.0 or not math.isfinite(started_at) or not math.isfinite(observation_utc):
+ return
+
+ def tracker_fields(result: VisualTrackResult) -> dict[str, Any]:
+ score = float(result.score)
+ return dict(bbox_px=_recovery_box_px(result.bbox), ok=bool(result.ok),
+ score=score if math.isfinite(score) else None, class_id=int(result.target_class),
+ frame_seq=int(result.source_seq) if result.source_seq is not None else None,
+ reason=str(result.reason)[:_PTZ17_RECOVERY_REASON_LIMIT])
+
+ _episode_telemetry(
+ config, cam_idx, (generation, started_at), "recovery_frame", time.time(),
+ observation_utc=observation_utc, frame_seq=int(source_seq) if source_seq is not None else None,
+ frame_size_px=[frame_w, frame_h], input_kind=input_kind, outcome=outcome,
+ expected_track_class=expected_track_class,
+ trusted_bbox_px=_recovery_box_px(trusted_bbox), association_reference_bbox_px=_recovery_box_px(reference_bbox),
+ ostrack=tracker_fields(visual_result), reinitialized_ostrack=tracker_fields(seeded) if seeded is not None else None,
+ yolo_raw_count=raw_box_count,
+ yolo_validation_count=len(validation_targets), yolo_reacquire_count=len(reacquire_targets),
+ yolo_validation=[_recovery_detector_box(box) for box in validation_targets[:_PTZ17_RECOVERY_BOX_LIMIT]],
+ yolo_reacquire=[_recovery_detector_box(box) for box in reacquire_targets[:_PTZ17_RECOVERY_BOX_LIMIT]],
+ yolo_match=_recovery_detector_box(detector_match), yolo_selected=_recovery_detector_box(selected),
+ reacquire_votes=int(st.get("visual_reacquire_votes", 0) or 0),
+ reacquire_vote_frame_seq=int(st.get("visual_reacquire_source_seq", -1)),
+ zoom_rearm_epoch=rearm_epoch, zoom_rearm_required=bool(st.get("zoom_rearm_required")),
+ zoom_rearm_votes=int(st.get("zoom_rearm_votes", 0) or 0),
+ )
+
+
+def _finish_ptz17_hold_capture(st: dict, control_utc: float, reason: str) -> None:
+ window = st.pop("ptz17_hold_capture", None)
+ if window is None:
+ return
+ owner, window_utc, count, _ = window
+ _, generation, started_at, _ = visual_control.owner(st)
+ if owner == (generation, started_at):
+ _episode_telemetry(config, _PTZ17_CAM_IDX, owner, "hold_capture_end", control_utc,
+ schema=1, window_utc=window_utc, input_count=count, close_reason=reason)
+
+
+def _capture_ptz17_hold_input(
+ st: dict, control_entry_utc: float, observation_utc: float, source_seq: int | None,
+ frame_w: int, frame_h: int, visual_result: VisualTrackResult, *,
+ input_kind: str, geometry_hold: bool, captured_utc: float | None,
+ detector_result_present: bool, raw_box_count: int, expected_track_class: int | None,
+ validation_targets: list[_DetectorBox], reacquire_targets: list[_DetectorBox],
+ before: dict | None = None,
+) -> None:
+ """Queue ordered recovery inputs. Coordinates are xyxy pixels, origin top left."""
+ if (st.get("mode") != "TRACK" or not st.get("tracking_active")
+ or not getattr(config, "PREDICTIVE_ZOOM_TELEMETRY_DIR", "logs/ptz_zoom")):
+ return
+ _, generation, started_at, _ = visual_control.owner(st)
+ if started_at <= 0.0 or not all(map(math.isfinite, (started_at, control_entry_utc, observation_utc))):
+ return
+ owner = (generation, started_at)
+ window = st.get("ptz17_hold_capture")
+ if window is not None and window[0] != owner:
+ st.pop("ptz17_hold_capture", None)
+ window = None
+ if window is not None and control_entry_utc > window[3]:
+ _finish_ptz17_hold_capture(st, control_entry_utc, "tail_elapsed")
+ window = None
+ if window is None and not geometry_hold:
+ return
+ if window is None:
+ window = (owner, control_entry_utc, 0, control_entry_utc + _PTZ17_CAPTURE_TAIL_S)
+ _, window_utc, count, deadline_utc = window
+ if geometry_hold:
+ deadline_utc = max(deadline_utc, control_entry_utc + _PTZ17_CAPTURE_TAIL_S)
+ st["ptz17_hold_capture"] = (owner, window_utc, count + 1, deadline_utc)
+ evidence = st if before is None else before
+
+ def finite(value: float | None) -> float | None:
+ return value if value is not None and math.isfinite(value) else None
+
+ _episode_telemetry(
+ config, _PTZ17_CAM_IDX, owner, "hold_capture_input", control_entry_utc,
+ schema=1, window_utc=window_utc, input_idx=count + 1, geometry_hold=geometry_hold,
+ frame_seq=source_seq, frame_size_px=[frame_w, frame_h], input_kind=input_kind,
+ observation_utc=observation_utc, captured_utc=finite(captured_utc),
+ detector_frame_seq=source_seq if detector_result_present else None,
+ detector_result_present=detector_result_present, yolo_raw_count=raw_box_count,
+ expected_track_class=expected_track_class,
+ ostrack=dict(bbox_px=_recovery_box_px(visual_result.bbox), ok=bool(visual_result.ok),
+ score=finite(visual_result.score), class_id=int(visual_result.target_class),
+ detector_conf=finite(visual_result.detector_conf), age_frames=int(visual_result.age_frames),
+ frame_seq=visual_result.source_seq,
+ reason=str(visual_result.reason)[:_PTZ17_RECOVERY_REASON_LIMIT]),
+ trusted_bbox_px=_recovery_box_px(evidence.get("last_bbox")),
+ last_seen_utc=finite(evidence.get("last_seen")),
+ loss_since_utc=finite(evidence.get("loss_since")),
+ reacquire_before=dict(bbox_px=_recovery_box_px(evidence.get("visual_reacquire_bbox")),
+ at_utc=finite(evidence.get("visual_reacquire_at")),
+ votes=int(evidence.get("visual_reacquire_votes") or 0),
+ frame_seq=int(evidence["visual_reacquire_source_seq"])
+ if evidence.get("visual_reacquire_source_seq") is not None else -1),
+ zoom_rearm_before=dict(epoch=int(evidence.get("zoom_rearm_epoch") or 0),
+ required=bool(evidence.get("zoom_rearm_required")),
+ reason=str(evidence.get("zoom_rearm_reason") or "")[:_PTZ17_RECOVERY_REASON_LIMIT]),
+ validation_count=len(validation_targets), reacquire_count=len(reacquire_targets),
+ validation=[_recovery_detector_box(box) for box in validation_targets[:_PTZ17_CAPTURE_BOX_LIMIT]],
+ reacquire=[_recovery_detector_box(box) for box in reacquire_targets[:_PTZ17_CAPTURE_BOX_LIMIT]],
+ )
def _ptz17_target_focus_score(
@@ -6782,6 +6934,8 @@
source="stop",
generation=int(st.get("ptz_generation", 0) or 0),
)
+ if cam_idx == _PTZ17_CAM_IDX:
+ _finish_ptz17_hold_capture(st, now, "track_end")
_clear_acquire_fields(st)
visual_tracker_manager.reset(cam_idx, reason=reason)
# Помечаем что парковка уже сделана — watchdog не будет дублировать
@@ -6936,11 +7090,20 @@
detector_targets: list[tuple[list[int], float, int]],
validation_targets: list[tuple[list[int], float, int]], width: int, height: int,
steering_targets: list[tuple[list[float], float, int]] | None = None,
+ *, recovery_targets: list[_DetectorBox] | None = None, raw_box_count: int = 0,
) -> None:
"""Validate the same image without rewinding live control or loss recovery."""
result = sample.result
bbox = result.bbox
if not result.ok or bbox is None:
+ if recovery_targets is not None:
+ _record_ptz17_recovery(
+ cam_idx, st, float(sample.captured_at), sample.source_seq, width, height, result,
+ input_kind="paired_detector", outcome="paired_tracker_unusable",
+ trusted_bbox=st.get("last_bbox"), reference_bbox=bbox,
+ validation_targets=validation_targets, reacquire_targets=recovery_targets,
+ raw_box_count=raw_box_count,
+ )
return
now = float(sample.captured_at)
target_class = int(result.target_class)
@@ -6962,6 +7125,14 @@
visual_tracker_manager.reset(cam_idx, reason='paired detector identity mismatch')
stop_ptz(cam_idx, source='stop', generation=int(st.get('ptz_generation', 0) or 0))
alarms.ingest_detection(cam_idx, False)
+ if recovery_targets is not None:
+ _record_ptz17_recovery(
+ cam_idx, st, now, sample.source_seq, width, height, result,
+ input_kind="paired_detector", outcome="paired_identity_stop",
+ trusted_bbox=st.get("last_bbox"), reference_bbox=bbox,
+ validation_targets=candidates, reacquire_targets=recovery_targets,
+ raw_box_count=raw_box_count, expected_track_class=target_class,
+ )
return
st['visual_tracker_mismatch_frames'] = 0
if matched is not None and now >= float(st.get('visual_tracker_last_detector_at', 0.) or 0.):
@@ -6981,6 +7152,14 @@
detector_conf=max(alarm_conf, identity_conf),
alarm_eligible=alarm_eligible, cam_idx=cam_idx)
alarms.ingest_detection(cam_idx, alarm_eligible)
+ if recovery_targets is not None:
+ _record_ptz17_recovery(
+ cam_idx, st, now, sample.source_seq, width, height, result,
+ input_kind="paired_detector", outcome="validation_only",
+ trusted_bbox=st.get("last_bbox"), reference_bbox=bbox,
+ validation_targets=candidates, reacquire_targets=recovery_targets,
+ raw_box_count=raw_box_count, expected_track_class=target_class, detector_match=matched,
+ )
@visual_control.serialized_control
@@ -6998,6 +7177,7 @@
h, w = frame_bgr.shape[:2]
w_inv, h_inv = (1.0 / w), (1.0 / h)
now = time.time()
+ control_entry_utc = now
# Intermediate control and delayed detector evidence have different jobs.
# The latter must never replay old image coordinates into the actuator.
@@ -7438,8 +7618,22 @@
)
if evidence_only:
- _consume_paired_detector_evidence(cam_idx, st, visual_sample, detector_targets,
- validation_targets, w, h, steering_targets)
+ if cam_idx == _PTZ17_CAM_IDX and "ptz17_hold_capture" in st:
+ _capture_ptz17_hold_input(
+ st, control_entry_utc, now, source_seq, w, h, visual_sample.result,
+ input_kind="paired_detector", geometry_hold=False, captured_utc=visual_sample.captured_at,
+ detector_result_present=boxes_t is not None, raw_box_count=raw_box_count,
+ expected_track_class=int(visual_sample.result.target_class),
+ validation_targets=validation_targets, reacquire_targets=reacquire_targets,
+ )
+ trace_recovery = cam_idx == _PTZ17_CAM_IDX and (
+ not visual_sample.result.ok or visual_sample.result.reason == "recovered"
+ or st.get("loss_since") is not None or st.get("zoom_rearm_reason") == "geometry_reject"
+ )
+ _consume_paired_detector_evidence(
+ cam_idx, st, visual_sample, detector_targets, validation_targets, w, h, steering_targets,
+ recovery_targets=reacquire_targets if trace_recovery else None, raw_box_count=raw_box_count,
+ )
return
if bt_active:
@@ -7759,6 +7953,7 @@
# its own gate, but a bad backend result/config override must still
# be unable to move the camera by following a remote cloud edge.
previous_control_bbox = st.get("last_bbox")
+ recovery_input_kind = "visual_control" if visual_only else "detector_control"
gross_visual_jump = False
visual_control_jump = 0.0
visual_control_limit = float(
@@ -7801,6 +7996,26 @@
("center jump", "area ratio", "validated area ratio")
)
)
+ capture_input = None
+ if cam_idx == _PTZ17_CAM_IDX and (geometric_reject or "ptz17_hold_capture" in st):
+ capture_before = {key: st.get(key) for key in _PTZ17_CAPTURE_STATE_KEYS}
+
+ def capture_input(held: bool) -> None:
+ _capture_ptz17_hold_input(
+ st, control_entry_utc, now, source_seq, w, h, visual_result,
+ input_kind=recovery_input_kind, geometry_hold=held,
+ captured_utc=visual_sample.captured_at if visual_sample is not None else None,
+ detector_result_present=not visual_only and boxes_t is not None,
+ raw_box_count=raw_box_count, expected_track_class=expected_track_class,
+ validation_targets=validation_targets, reacquire_targets=reacquire_targets,
+ before=capture_before,
+ )
+
+ if not (geometric_reject or gross_visual_jump):
+ capture_input(False)
+ geometry_match = validated_geometry_target = None
+ seeded_geometry = None
+ geometry_outcome = "geometry_no_box"
if (gross_visual_jump or geometric_reject) and visual_result.bbox is not None:
# A large motion is safe only when the *current* detector agrees
# with that new location. A backend result that passed its own
@@ -7822,6 +8037,8 @@
),
allow_target_class_compatibility=True,
)
+ geometry_match = validated_geometry_target
+ geometry_outcome = "geometry_no_match"
if (
validated_geometry_target is not None
and isinstance(previous_control_bbox, (tuple, list))
@@ -7852,6 +8069,7 @@
)
):
validated_geometry_target = None
+ geometry_outcome = "geometry_trusted_area_rejected"
if geometric_reject and validated_geometry_target is not None:
validated_geometry_target = _confirm_loss_reacquire_candidate(
st,
@@ -7861,6 +8079,7 @@
h,
source_seq=source_seq,
)
+ geometry_outcome = "geometry_confirmation_pending"
if validated_geometry_target is not None:
preserved_track_class = (
int(visual_result.target_class)
@@ -7880,6 +8099,7 @@
now=now,
source_seq=source_seq,
)
+ geometry_outcome = "geometry_seed_failed"
if seeded_geometry.ok and seeded_geometry.bbox is not None:
logger.info(
"[OSTRACK/IDENTITY] cam=%s detector validated geometry jump; reinitialized",
@@ -7893,6 +8113,18 @@
_arm_zoom_revalidation(
st, now, "geometry_reinitialized", cam_idx=cam_idx
)
+ if cam_idx == _PTZ17_CAM_IDX:
+ if capture_input is not None:
+ capture_input(geometric_reject)
+ _record_ptz17_recovery(
+ cam_idx, st, now, source_seq, w, h, visual_result,
+ input_kind=recovery_input_kind, outcome="geometry_reinitialized",
+ trusted_bbox=previous_control_bbox, reference_bbox=visual_result.bbox,
+ validation_targets=validation_targets, reacquire_targets=reacquire_targets,
+ raw_box_count=raw_box_count, detector_match=geometry_match,
+ selected=validated_geometry_target, seeded=seeded_geometry,
+ expected_track_class=expected_track_class,
+ )
visual_result = seeded_geometry
reference_bbox = seeded_geometry.bbox
gross_visual_jump = False
@@ -7922,6 +8154,18 @@
source="stop",
generation=int(st.get("ptz_generation", 0) or 0),
)
+ if cam_idx == _PTZ17_CAM_IDX:
+ if capture_input is not None:
+ capture_input(True)
+ _record_ptz17_recovery(
+ cam_idx, st, now, source_seq, w, h, visual_result,
+ input_kind=recovery_input_kind, outcome=geometry_outcome,
+ trusted_bbox=previous_control_bbox, reference_bbox=visual_result.bbox,
+ validation_targets=validation_targets, reacquire_targets=reacquire_targets,
+ raw_box_count=raw_box_count,
+ detector_match=geometry_match, selected=validated_geometry_target,
+ seeded=seeded_geometry, expected_track_class=expected_track_class,
+ )
logger.warning(
"[OSTRACK/IDENTITY] cam=%s HOLD rejected geometry reason=%s; awaiting recovery",
cam_idx,
@@ -7950,6 +8194,18 @@
source="stop",
generation=int(st.get("ptz_generation", 0) or 0),
)
+ if cam_idx == _PTZ17_CAM_IDX:
+ if capture_input is not None:
+ capture_input(False)
+ _record_ptz17_recovery(
+ cam_idx, st, now, source_seq, w, h, visual_result,
+ input_kind=recovery_input_kind, outcome="control_jump_stop",
+ trusted_bbox=previous_control_bbox, reference_bbox=visual_result.bbox,
+ validation_targets=validation_targets, reacquire_targets=reacquire_targets,
+ raw_box_count=raw_box_count, detector_match=geometry_match,
+ selected=validated_geometry_target, seeded=seeded_geometry,
+ expected_track_class=expected_track_class,
+ )
logger.warning(
"[OSTRACK/IDENTITY] cam=%s STOP rejected geometry reason=%s",
cam_idx,
@@ -7961,6 +8217,7 @@
matched_validation = None
matched_reacquire = None
+ widened_candidate = None
if reference_bbox is not None:
matched_validation = _find_visual_validation_target(
reference_bbox,
@@ -8241,6 +8498,17 @@
det_xyxy.append(tuple(visual_result.bbox))
visual_track_label_index = len(det_labels)
det_labels.append("target track")
+ if cam_idx == _PTZ17_CAM_IDX and not geometry_reinitialized and (
+ visual_result.reason == "recovered" or st.get("loss_since") is not None
+ ):
+ _record_ptz17_recovery(
+ cam_idx, st, now, source_seq, w, h, visual_result,
+ input_kind=recovery_input_kind, outcome="visual_recovered",
+ trusted_bbox=previous_control_bbox, reference_bbox=reference_bbox,
+ validation_targets=validation_targets, reacquire_targets=reacquire_targets,
+ raw_box_count=raw_box_count, detector_match=matched_validation,
+ expected_track_class=expected_track_class,
+ )
else:
ptz17_validation_timeout = bool(
visual_only and _ptz17_validation_timeout_steering(
@@ -8284,6 +8552,7 @@
_arm_zoom_revalidation(
st, now, "visual_reacquire", cam_idx=cam_idx
)
+ seeded = None
if matched_reacquire is not None:
preserved_track_class = (
int(visual_result.target_class)
@@ -8327,6 +8596,19 @@
target_source = "none"
st["visual_tracker_score"] = float(visual_result.score)
st["visual_tracker_last_reason"] = visual_result.reason
+ if cam_idx == _PTZ17_CAM_IDX:
+ _record_ptz17_recovery(
+ cam_idx, st, now, source_seq, w, h, visual_result,
+ input_kind=recovery_input_kind,
+ outcome=target_source if matched_reacquire is not None else
+ "loss_confirmation_pending" if widened_candidate is not None else "loss_no_match",
+ trusted_bbox=previous_control_bbox, reference_bbox=reference_bbox,
+ validation_targets=validation_targets, reacquire_targets=reacquire_targets,
+ raw_box_count=raw_box_count,
+ detector_match=widened_candidate if widened_candidate is not None else matched_reacquire,
+ selected=matched_reacquire, seeded=seeded,
+ expected_track_class=expected_track_class,
+ )
elif best_target is not None:
# ACQUIRE has already approved this target. Seed the appearance
# tracker on the same frame before entering full TRACK.

@ -0,0 +1,6 @@
{
"base_sha256": "fc0deb0c54fbd94a916493ee0c3159b02407876b32deebbbc3d819cc58a17500",
"candidate_sha256": "8e3cf93b2ab54bbc98b86761312c5d0034785578775bddaaee6450c28d370a9b",
"patch_sha256": "1bbcfb9897861bb8c1cde2566827389d0fc6933e3f3c27d2623e56cb0da6091f",
"installed": false
}

@ -0,0 +1,101 @@
"""Check a PTZ17 episode JSONL before replaying its accepted HOLD inputs."""
from __future__ import annotations
import argparse
from collections import defaultdict
from pathlib import Path
import json
from typing import Any, Iterable
Row = dict[str, Any]
def read_jsonl(path: Path) -> Iterable[Row]:
with path.open(encoding="utf-8") as stream:
for number, line in enumerate(stream, 1):
row = json.loads(line)
if not isinstance(row, dict) or not line.endswith("\n"):
raise ValueError(f"Incomplete JSONL row {number}")
yield row
def summarize(rows: Iterable[Row]) -> list[Row]:
episodes = defaultdict(list)
for row in rows:
if row.get("cam") == 6:
episodes[(row["generation"], row["track_start_utc"])].append(row)
reports = []
for (generation, started_utc), events in episodes.items():
windows = defaultdict(list)
for row in events:
if row["event"] in ("hold_capture_input", "hold_capture_end"):
windows[row["window_utc"]].append(row)
for window_utc, captured in sorted(windows.items()):
inputs = [r for r in captured if r["event"] == "hold_capture_input"]
ends = [r for r in captured if r["event"] == "hold_capture_end"]
problems = []
if any(r.get("schema") != 1 for r in captured):
problems.append("unknown_schema")
if len(ends) != 1 or captured[-1] is not ends[0]:
problems.append("missing_or_misordered_close")
elif ends[0]["input_count"] != len(inputs):
problems.append("input_count_mismatch")
if [r["input_idx"] for r in inputs] != list(range(1, len(inputs) + 1)):
problems.append("missing_or_out_of_order_input")
if not inputs or not inputs[0].get("geometry_hold") or inputs[0]["utc"] != window_utc:
problems.append("missing_first_hold")
if any(r["validation_count"] != len(r["validation"])
or r["reacquire_count"] != len(r["reacquire"]) for r in inputs):
problems.append("candidate_list_truncated")
if any(not isinstance(r.get("frame_seq"), int) or r["frame_seq"] <= 0 for r in inputs):
problems.append("missing_frame_number")
dropped = {r.get("dropped_before") for r in captured}
if None in dropped or len(dropped) > 1:
problems.append("telemetry_drop_detected_or_unknown")
if any(a["utc"] > b["utc"] for a, b in zip(captured, captured[1:])):
problems.append("clock_went_back")
first_hold = next((r for r in inputs if r["geometry_hold"]), None)
last_hold = next((r for r in reversed(inputs) if r["geometry_hold"]), None)
closed_utc = ends[0]["utc"] if len(ends) == 1 else captured[-1]["utc"]
outcomes = [r for r in events if r["event"] == "recovery_frame"
and window_utc <= r["utc"] <= closed_utc]
recovered = next((r for r in outcomes if last_hold and r["utc"] >= last_hold["utc"]
and r["observation_utc"] >= last_hold["observation_utc"]
and r.get("outcome") in ("detector_reacquire", "visual_recovered",
"geometry_reinitialized")), None)
# Measure a request before another HOLD window could own the result.
next_window = next((stamp for stamp in sorted(windows) if stamp > window_utc), float("inf"))
zoom = next((r for r in events if r["event"] == "decision_frame" and last_hold
and last_hold["utc"] <= r["utc"] < next_window and r.get("zoom_command", 0) > 0), None)
candidates = [r for r in inputs if r["geometry_hold"]
and r["input_kind"] == "detector_control"
and r["detector_result_present"]
and r["detector_frame_seq"] == r["frame_seq"] == r["ostrack"]["frame_seq"]]
reports.append(dict(generation=generation, track_start_utc=started_utc, window_utc=window_utc,
complete=not problems, issues=problems, inputs=len(inputs),
first_hold_frame=first_hold["frame_seq"] if first_hold else None,
last_hold_frame=last_hold["frame_seq"] if last_hold else None,
direct_same_frame_hold_inputs=len(candidates),
same_frame_hold_with_reacquire_boxes=sum(bool(r["reacquire"]) for r in candidates),
recovery_frame=recovered["frame_seq"] if recovered else None,
zoom_frame=zoom["frame_seq"] if zoom else None,
hold_to_recovery_ms=round((recovered["observation_utc"]
- last_hold["observation_utc"]) * 1000, 1)
if recovered else None,
hold_to_zoom_decision_ms=round((zoom["utc"] - last_hold["utc"]) * 1000, 1)
if zoom else None))
return reports
def main() -> int:
cli = argparse.ArgumentParser(description=__doc__)
cli.add_argument("episode", type=Path)
reports = summarize(read_jsonl(cli.parse_args().episode))
print(json.dumps({"windows": reports}, indent=2, allow_nan=False))
return 0 if reports and all(r["complete"] for r in reports) else 2
if __name__ == "__main__":
raise SystemExit(main())

@ -0,0 +1,117 @@
"""Verify PTZ17 capture on the control path and through the actual JSONL queue."""
from __future__ import annotations
from copy import deepcopy
import importlib.util
import os
from pathlib import Path
from unittest.mock import patch
import pytest
from summarize_capture import read_jsonl, summarize
spec = importlib.util.spec_from_file_location("ptz17_existing_test", Path(os.environ["PTZ17_PARITY_TEST"]))
assert spec and spec.loader
existing = importlib.util.module_from_spec(spec)
spec.loader.exec_module(existing)
versions = existing.versions
@pytest.mark.parametrize("scenario", [
"hold_then_strict", "visual_recovers", "paired_hold", "geometry_two_frames",
"wide_two_frames", "ordinary_track", "seed_failed",
])
def test_control_parity_and_capture_paths(versions, scenario):
baseline, candidate = versions
previous = existing.exercise(baseline, scenario)[:2]
original_capture = candidate._capture_ptz17_hold_input
stop_at_first_hold = []
def capture_after_stop(*args, **kwargs):
if kwargs["geometry_hold"] and not stop_at_first_hold:
stop_at_first_hold.append(candidate.stop_ptz.called)
return original_capture(*args, **kwargs)
with patch.object(candidate, "_capture_ptz17_hold_input",
side_effect=capture_after_stop) as spy:
assert existing.exercise(candidate, scenario)[:2] == previous
expected = {
"hold_then_strict": [(41, "detector_control", True), (42, "detector_control", False)],
"visual_recovers": [(41, "visual_control", True), (42, "visual_control", False)],
"paired_hold": [(41, "visual_control", True), (42, "paired_detector", False)],
"geometry_two_frames": [(41, "detector_control", True), (42, "detector_control", True)],
}
assert [(call.args[3], call.kwargs["input_kind"], call.kwargs["geometry_hold"]) for call in spy.call_args_list
] == expected.get(scenario, [])
if scenario in expected:
assert stop_at_first_hold == [True]
@pytest.fixture()
def episode(versions, tmp_path):
_baseline, module = versions
directory = str(tmp_path)
state = dict(mode="TRACK", tracking_active=True, ptz_generation=7, track_started_at=90.0,
last_bbox=existing.TRUSTED, last_seen=99.8)
result_cls = module.visual_tracker_manager.update.__globals__["VisualTrackResult"]
candidates = [(existing.GOOD, .51, 0), (existing.WRONG, .95, 0)]
original = result_cls(False, existing.REJECTED, .29, 0, .80, 40, "area ratio 5.45", 41)
next_result = result_cls(True, existing.GOOD, .85, 0, .80, 41, "recovered", 42)
capture = module._capture_ptz17_hold_input
with patch.object(module.config, "PREDICTIVE_ZOOM_TELEMETRY_DIR", directory, create=True):
capture(state, 100.05, 100.0, 41, 1280, 720, original,
input_kind="detector_control", geometry_hold=True, captured_utc=None,
detector_result_present=True, raw_box_count=2, expected_track_class=0,
validation_targets=candidates, reacquire_targets=candidates)
capture(state, 100.25, 100.2, 42, 1280, 720, next_result,
input_kind="paired_detector", geometry_hold=False, captured_utc=100.2,
detector_result_present=True, raw_box_count=2, expected_track_class=0,
validation_targets=candidates, reacquire_targets=candidates)
module._episode_telemetry(module.config, 6, (7, 90.), "recovery_frame", 100.25,
frame_seq=42, outcome="detector_reacquire", observation_utc=100.2)
module._episode_telemetry(module.config, 6, (7, 90.), "decision_frame", 100.80,
frame_seq=48, zoom_command=.1)
module._finish_ptz17_hold_capture(state, 101.0, "track_end")
logger = module._episode_telemetry.__globals__["_telemetry_loggers"][directory]
logger.queue.join()
path, = tmp_path.glob("*.jsonl")
return list(read_jsonl(path))
def test_real_writer_preserves_frames_and_order(episode):
hold, paired, _, _, end = episode
assert (hold["utc"], hold["observation_utc"], hold["captured_utc"]) == (100.05, 100.0, None)
assert hold["frame_seq"] == hold["detector_frame_seq"] == hold["ostrack"]["frame_seq"] == 41
assert hold["trusted_bbox_px"] == list(existing.TRUSTED)
assert hold["ostrack"]["bbox_px"] == list(existing.REJECTED)
assert [b["bbox_px"] for b in hold["reacquire"]] == [existing.GOOD, existing.WRONG]
assert (paired["input_idx"], paired["captured_utc"], paired["detector_frame_seq"]) == (2, 100.2, 42)
assert end["input_count"] == 2 and end["close_reason"] == "track_end"
report, = summarize(episode)
assert report["complete"] and report["direct_same_frame_hold_inputs"] == 1
assert report["hold_to_recovery_ms"] == 200 and report["hold_to_zoom_decision_ms"] == 750
@pytest.mark.parametrize("case,issue", [
("missing", "missing_or_out_of_order_input"),
("open", "missing_or_misordered_close"),
("drop", "telemetry_drop_detected_or_unknown"),
("truncated", "candidate_list_truncated"),
("no_seq", "missing_frame_number"),
])
def test_refuse_incomplete_capture(episode, case, issue):
rows = deepcopy(episode)
if case == "missing":
rows.pop(0)
elif case == "open":
rows.pop()
elif case == "drop":
rows[1]["dropped_before"] += 1
elif case == "truncated":
rows[0]["reacquire"].pop()
elif case == "no_seq":
rows[0]["frame_seq"] = None
result, = summarize(rows)
assert not result["complete"] and issue in result["issues"]

@ -0,0 +1,7 @@
# PTZ17. YOLO evidence for steering after validation timeout
Apply `server.patch` from the production module directory after checking the baseline SHA-256 in `pins.json`. The production base is the PR10 field release. The repository carries its field deltas as pinned patches.
Camera 17 (internal ID 6) can use a same-frame YOLO box at confidence ≥0.45 to continue steering an existing target. Normal acquisition, verified zoom, full STOP and alarm processing keep their existing paths. Field logs mark entry, continuation and exit from steering-only control. The installed module is a shared service, but the new behavior applies only to camera 17.
Three offline YOLO observations from the 17:44:55 PTZ17 flight matched. With the assumed frame timing the candidate retained the tracker through the sampled tick 944 ms after the original timeout. Two observations produced non-zero native pan/tilt queue values. Zoom-out occurred at the original sampled tick. The replay uses extracted frames with no verified PTS-to-UTC mapping, so live retention duration remains to be measured.

@ -0,0 +1,5 @@
{
"base_sha256": "dba9b3dc69768526777e166a8ef3270ee54a5d9ed7415a3f905b65e05a8534a5",
"candidate_sha256": "6cf484271ef3659028b0b4d43041addb05102f91d2758ab472d968a52d24e911",
"patch_sha256": "80643ee70d884bbdd41786673cc46c09c43b6d312f2f318a5ee80f6afcd60e43"
}

@ -0,0 +1,362 @@
--- a/postprocess.py
+++ b/postprocess.py
@@ -3,6 +3,7 @@
import math
import logging
import json
+from dataclasses import dataclass
from typing import Any, List, Tuple
import numpy as np
@@ -16,6 +17,7 @@
from . import motion_detector
from .utils import (
clipf,
+ quantf,
deg_to_compass,
hfov_ptz_from_zoom_ratio,
vfov_from_hfov,
@@ -6613,8 +6615,149 @@
return_to_preset(cam_idx, reason=reason)
return True
-def _consume_paired_detector_evidence(cam_idx, st, sample, detector_targets,
- validation_targets, width, height):
+_PTZ17_CAM_IDX = 6
+_PTZ17_STEERING_MIN_CONF = 0.45
+
+
+@dataclass(frozen=True, slots=True)
+class _SteeringEvidence:
+ owner: tuple[int, int, float, int]
+ source_seq: int
+ captured_at: float
+ target_class: int
+
+
+@dataclass(frozen=True, slots=True)
+class _SteeringTimeout:
+ track_owner: tuple[int, int, float]
+ last_normal_validation_at: float
+
+
+def _ptz17_remember_steering_evidence(
+ st: dict,
+ sample: visual_control.VisualSample,
+ candidates: list[tuple[list[float], float, int]],
+ width: int,
+ height: int,
+ wall_now: float,
+) -> None:
+ if not visual_control.current(_PTZ17_CAM_IDX, sample, wall_now, max_age=.65):
+ return
+ bbox = sample.result.bbox
+ target_class = int(sample.result.target_class)
+ if not sample.result.ok or bbox is None or target_class < 0:
+ return
+ min_overlap = float(getattr(config, "VISUAL_TRACKER_MATCH_IOU", .08))
+ overlapping = [
+ (box, confidence, cls)
+ for box, confidence, cls in candidates
+ if cls == target_class and 0.0 <= confidence <= 1.0
+ and all(math.isfinite(value) for value in box)
+ and 0 <= box[0] < box[2] <= width and 0 <= box[1] < box[3] <= height
+ and bbox_iou(bbox, box) >= min_overlap
+ ]
+ matched = _find_visual_validation_target(bbox, overlapping, width, height,
+ target_class=target_class)
+ if matched is not None:
+ st["ptz17_steering_evidence"] = _SteeringEvidence(
+ sample.owner, sample.source_seq, sample.captured_at, target_class,
+ )
+
+
+def _ptz17_validation_timeout_steering(
+ cam_idx: int,
+ st: dict,
+ sample: visual_control.VisualSample | None,
+ width: int,
+ height: int,
+ wall_now: float,
+) -> tuple[float, float] | None:
+ """Return bounded logical pan/tilt from a fresh box, right/down positive.
+
+ Box coordinates are in pixels from the upper left. Position feedback is
+ scaled by tan(FOV/2) / tan(wide FOV/2) before the normal transport clamps.
+ """
+ if cam_idx != _PTZ17_CAM_IDX or sample is None:
+ return None
+ evidence = st.get("ptz17_steering_evidence")
+ if (
+ not isinstance(evidence, _SteeringEvidence)
+ or not visual_control.current(cam_idx, sample, wall_now, max_age=.25)
+ or not sample.result.ok or sample.result.bbox is None
+ or sample.owner != evidence.owner or sample.source_seq <= evidence.source_seq
+ or int(sample.result.target_class) != evidence.target_class
+ or st.get("visual_tracker_mismatch_frames")
+ or st.get("aim_final_pan_recovering") or st.get("aim_final_tilt_recovering")
+ or float(st.get("aim_final_pan_predict_cooldown_until", 0.0) or 0.0) > wall_now
+ or float(st.get("aim_final_tilt_predict_cooldown_until", 0.0) or 0.0) > wall_now
+ or st.get("zoom_edge_recovery_active")
+ or st.get("zoom_step_pending") or st.get("lens_move_put_inflight")
+ or float(st.get("zoom_step_until", 0.0) or 0.0) > wall_now
+ or float(st.get("zoom_prev_cmd", 0.0) or 0.0) > 0.0
+ or (st.get("last_ptz_physical_cmd") or (0.0, 0.0, 0.0))[2] != 0.0
+ ):
+ return None
+ max_age_s = float(getattr(config, "VISUAL_TRACKER_CONTROL_MAX_UNVALIDATED_SEC", 2.0))
+ if not 0.0 <= sample.captured_at - evidence.captured_at <= wall_now - evidence.captured_at <= max_age_s:
+ return None
+ x1_px, y1_px, x2_px, y2_px = map(float, sample.result.bbox)
+ margin_x = float(getattr(config, "EDGE_LOSS_MARGIN", .015))
+ margin_y = float(getattr(config, "VERT_LOSS_MARGIN", .05))
+ if not (
+ width * margin_x <= x1_px < x2_px <= width * (1.0 - margin_x)
+ and height * margin_y <= y1_px < y2_px <= height * (1.0 - margin_y)
+ ):
+ return None
+ hfov_deg = float(st.get("hfov_deg", 0.0) or 0.0)
+ optics_at = float(st.get("zoom_status_at", 0.0) or 0.0)
+ optics_max_age_s = float(getattr(config, "AIM_FINAL_PREDICT_STATUS_MAX_AGE_SEC", .65))
+ wide_hfov_deg = float(config.CAMERA_CONFIG[cam_idx].get(
+ "ptz_hfov_wide_deg", getattr(config, "PTZ_HFOV_WIDE_DEG", 59.0),
+ ))
+ if not (
+ 0.0 < hfov_deg < 180.0 and 0.0 < wide_hfov_deg < 180.0
+ and optics_at > 0.0 and 0.0 <= wall_now - optics_at <= optics_max_age_s
+ ):
+ return None
+ dx_norm = (x1_px + x2_px) / (2.0 * width) - .5
+ dy_norm = (y1_px + y2_px) / (2.0 * height) - .5
+ gain, _, _, _, dead_zone = _aim_schedule(
+ max(abs(dx_norm), abs(dy_norm)), 0.0, (x2_px - x1_px) / width,
+ )
+ fov_scale = min(1.0, math.tan(math.radians(hfov_deg / 2.0))
+ / math.tan(math.radians(wide_hfov_deg / 2.0)))
+ dead_zone = max(dead_zone, float(getattr(config, "AIM_HOLD_ENTER_ERR", .020)))
+ cap = float(getattr(config, "TRACK_LOSS_LAST_COMMAND_MAX", .18))
+ quantum = float(getattr(config, "PTZ_QUANT", .01))
+ transport_min = max(.01, float(getattr(config, "PTZ_EPS", .01)))
+ if (
+ not all(math.isfinite(value) and value >= 0.0
+ for value in (gain, dead_zone, cap, quantum, transport_min))
+ or gain <= 0.0
+ ):
+ return None
+ # ISAPI encodes each axis as integer hundredths. Apply one encodable step
+ # outside the centre deadband so small telephoto corrections reach the queue.
+ minimum = math.ceil(transport_min / quantum) * quantum if quantum else transport_min
+ if quantf(minimum, quantum) < transport_min:
+ minimum += quantum
+ if minimum > cap:
+ return None
+
+ def axis(error_norm: float) -> float:
+ if abs(error_norm) <= dead_zone:
+ return 0.0
+ return math.copysign(clipf(abs(error_norm) * gain * fov_scale, minimum, cap), error_norm)
+
+ return axis(dx_norm), axis(dy_norm)
+
+
+def _consume_paired_detector_evidence(
+ cam_idx: int, st: dict, sample: visual_control.VisualSample,
+ detector_targets: list[tuple[list[int], float, int]],
+ validation_targets: list[tuple[list[int], float, int]], width: int, height: int,
+ steering_targets: list[tuple[list[float], float, int]] | None = None,
+) -> None:
"""Validate the same image without rewinding live control or loss recovery."""
result = sample.result
bbox = result.bbox
@@ -6629,6 +6772,8 @@
conflict = matched is None and _has_nearby_detector_identity_conflict(
bbox, candidates, width, height, target_class=target_class)
if conflict:
+ if cam_idx == _PTZ17_CAM_IDX:
+ st.pop("ptz17_steering_evidence", None)
votes = int(st.get('visual_tracker_mismatch_frames', 0) or 0) + 1
_arm_zoom_revalidation(st, time.time(), 'identity_conflict', cam_idx=cam_idx)
st['visual_tracker_mismatch_frames'] = votes
@@ -6641,8 +6786,13 @@
return
st['visual_tracker_mismatch_frames'] = 0
if matched is not None and now >= float(st.get('visual_tracker_last_detector_at', 0.) or 0.):
+ if cam_idx == _PTZ17_CAM_IDX:
+ st.pop("ptz17_steering_evidence", None)
+ st.pop("ptz17_steering_timeout", None)
visual_tracker_manager.record_detector_validation(cam_idx, matched[0])
_record_visual_detector_validation(st, now, float(matched[1]), source_seq=sample.source_seq)
+ elif matched is None and cam_idx == _PTZ17_CAM_IDX and steering_targets:
+ _ptz17_remember_steering_evidence(st, sample, steering_targets, width, height, time.time())
alarm_eligible, alarm_conf = _alarm_eligible_for_target(
bbox, target_class, detector_targets, width, height)
identity_conf = float(matched[1]) if matched is not None and int(matched[2]) == target_class else 0.
@@ -6946,6 +7096,7 @@
max_model_conf = 0.0
target_max_conf = 0.0
cls_hist_diag = ""
+ steering_targets: list[tuple[list[float], float, int]] = []
if boxes_t is not None and len(boxes_t) > 0:
raw_box_count = int(len(boxes_t))
@@ -6999,6 +7150,10 @@
continue
conf_thr = torch.where(clss == cls_id, torch.as_tensor(thr, device=confs.device), conf_thr)
+ steering_mask = (
+ mask & torch.isfinite(confs) & (confs >= _PTZ17_STEERING_MIN_CONF) & (confs < conf_thr)
+ if cam_idx == _PTZ17_CAM_IDX and evidence_only else None
+ )
# === Motion-aided detection: boost conf для боксов внутри motion ROI ===
# Только для PTZ-камер с включённым motion detector и статичной позицией.
# Это позволяет пропустить мелкие/неуверенные NN-детекции, которые в обычном
@@ -7045,6 +7200,8 @@
for drone_id in drone_ids:
drone_mask = drone_mask | (clss == int(drone_id))
mask = mask & ((~drone_mask) | size_ok)
+ if steering_mask is not None:
+ steering_mask &= (~drone_mask) | size_ok
if getattr(config, "ANTI_CLOUD_FILTER", True):
xyxy = boxes_t.xyxy
@@ -7058,6 +7215,14 @@
| (h_fr > float(getattr(config, "ANTI_CLOUD_MAX_H_FRAC", 0.24)))
)
mask = mask & (~(low_conf & cloud_like))
+ if steering_mask is not None:
+ steering_mask &= ~(low_conf & cloud_like)
+ if steering_mask is not None and steering_mask.any():
+ steering_targets = list(zip(
+ boxes_t.xyxy[steering_mask].detach().cpu().tolist(),
+ confs[steering_mask].detach().cpu().tolist(),
+ clss[steering_mask].detach().cpu().to(dtype=torch.int64).tolist(),
+ ))
try:
pass_box_count = int(mask.sum().detach().cpu().item())
except Exception:
@@ -7095,7 +7260,7 @@
if evidence_only:
_consume_paired_detector_evidence(cam_idx, st, visual_sample, detector_targets,
- validation_targets, w, h)
+ validation_targets, w, h, steering_targets)
return
if bt_active:
@@ -7377,6 +7542,7 @@
# measurement is not sufficient for initial acquisition.
best_target = None
+ ptz17_validation_timeout = False
# PTZ target ownership after acquisition:
# YOLO/ByteTrack -> confirm/reacquire; OSTrack -> frame-to-frame control.
# This branch intentionally runs after weak-candidate confirmation so a
@@ -7730,6 +7896,8 @@
)
)
if nearby_identity_conflict:
+ if cam_idx == _PTZ17_CAM_IDX:
+ st.pop("ptz17_steering_evidence", None)
mismatch_frames = int(st.get("visual_tracker_mismatch_frames", 0) or 0) + 1
st["visual_tracker_mismatch_frames"] = mismatch_frames
st["visual_tracker_last_zoom_detector_at"] = 0.0
@@ -7867,7 +8035,13 @@
max_unvalidated > strong_unvalidated
and validation_age > strong_unvalidated
)
- if validation_age <= max_unvalidated:
+ steering_timeout = st.get("ptz17_steering_timeout") if cam_idx == _PTZ17_CAM_IDX else None
+ steering_only_after_timeout = (
+ isinstance(steering_timeout, _SteeringTimeout)
+ and steering_timeout.track_owner == visual_control.owner(st)[:3]
+ and last_validation <= steering_timeout.last_normal_validation_at
+ )
+ if validation_age <= max_unvalidated and not steering_only_after_timeout:
visual_conf = max(
float(visual_result.score),
float(matched_validation[1]) if matched_validation is not None else 0.0,
@@ -7889,19 +8063,36 @@
visual_track_label_index = len(det_labels)
det_labels.append("target track")
else:
- logger.info(
- "[OSTRACK/VALIDATION] cam=%s timeout age=%.2fs "
- "limit=%.2fs score=%.2f zoomed_grace=%s",
- cam_idx,
- validation_age,
- max_unvalidated,
- float(visual_result.score),
- bool(st.get("visual_tracker_validation_grace_active", False)),
+ ptz17_validation_timeout = bool(
+ visual_only and _ptz17_validation_timeout_steering(
+ cam_idx, st, visual_sample, w, h, time.time(),
+ ) is not None
)
- visual_tracker_manager.reset(cam_idx, reason="detector validation timeout")
+ if ptz17_validation_timeout:
+ # A recovered OSTrack score alone must not undo the
+ # normal detector timeout for the lens or alarm path.
+ if not steering_only_after_timeout:
+ st["ptz17_steering_timeout"] = _SteeringTimeout(
+ visual_control.owner(st)[:3], last_validation,
+ )
+ st["visual_tracker_last_reason"] = "detector timeout: PTZ17 steering only"
+ else:
+ logger.info(
+ "[OSTRACK/VALIDATION] cam=%s timeout age=%.2fs "
+ "limit=%.2fs score=%.2f zoomed_grace=%s",
+ cam_idx,
+ validation_age,
+ max_unvalidated,
+ float(visual_result.score),
+ bool(st.get("visual_tracker_validation_grace_active", False)),
+ )
+ visual_tracker_manager.reset(cam_idx, reason="detector validation timeout")
+ if cam_idx == _PTZ17_CAM_IDX:
+ st.pop("ptz17_steering_timeout", None)
+ st.pop("ptz17_steering_evidence", None)
+ st["visual_tracker_last_reason"] = "detector validation timeout"
best_target = None
target_source = "none"
- st["visual_tracker_last_reason"] = "detector validation timeout"
st["visual_tracker_validation_limit_sec"] = 0.0
st["visual_tracker_validation_grace_active"] = False
else:
@@ -10308,6 +10499,20 @@
decay,
)
+ if ptz17_validation_timeout:
+ steering = (
+ _ptz17_validation_timeout_steering(cam_idx, st, visual_sample, w, h, time.time())
+ if zoom_cmd_track == 0.0 else None
+ )
+ if steering is not None:
+ base_pan, base_tilt = steering
+ else:
+ logger.info("[PTZ17/STEERING] cam=%s end reason=%s", cam_idx,
+ "loss_zoom" if zoom_cmd_track != 0.0 else "steering_veto")
+ visual_tracker_manager.reset(cam_idx, reason="detector validation timeout")
+ st.pop("ptz17_steering_timeout", None)
+ st.pop("ptz17_steering_evidence", None)
+
pan_cmd = _PAN_SIGN * base_pan
tilt_cmd = _TILT_SIGN * base_tilt
st["track_loss_active"] = True
@@ -10327,6 +10532,16 @@
dmax_s = abs(ang_diff_signed(float(smax), float(az)))
if min(dmin_s, dmax_s) > soft_leash:
pan_cmd = 0.0 # не толкаем дальше от сектора
+
+ if ptz17_validation_timeout and steering is not None:
+ last_log = float(st.get("ptz17_steering_log_at", 0.0) or 0.0)
+ if not steering_only_after_timeout or now - last_log >= .25:
+ st["ptz17_steering_log_at"] = now
+ logger.info(
+ "[PTZ17/STEERING] cam=%s %s frame=%s pan=%.4f tilt=%.4f zoom=%.2f",
+ cam_idx, "continue" if steering_only_after_timeout else "start",
+ source_seq, pan_cmd, tilt_cmd, zoom_cmd_track,
+ )
st["track_loss_pan_cmd"] = float(pan_cmd)
st["track_loss_tilt_cmd"] = float(tilt_cmd)

@ -0,0 +1,9 @@
# Продолжение импульса при той же скорости камеры
У уже начавшегося импульса TRACK дробная команда на следующем кадре может стать меньше исходной, сохраняя ту же целую скорость камеры. Сравнение дробей прерывает такой импульс. Патч разрешает продолжение только после повторной проверки кадра, владельца, исходного запроса и таймера. Камера получает ту же скорость до прежнего срока. При снижении целой скорости, запрете или смене владельца действует прежняя остановка.
В журналах PTZ19 и PTZ21 ветка `pending_native_floor` сработала после 91 и 95 мс при native 10 и минимуме доставки 238 мс. При сохранённых настройках альтернативные условия дают другие ветки. Дробные значения команд в этих записях отсутствуют. Офлайн-повтор использует синтетические 0,106 → 0,103 при зарегистрированных скоростях и длительностях.
Прошли по 16 тестов на исходном коде и кандидате. Офлайн-повтор проверяет неизменность номинального и жёсткого сроков, а также остановку при снижении до native 9, отзыве разрешения, смене запроса и других запретах. Прямой и обратный патчи проверены побайтно. Патч рассчитан на серверный код PR №4 с хешами из `pins.json`.
Для проверки используйте команду из соседнего пакета `ptz_zoom_zero_decision` и добавьте после `RESULT_JSON` путь к телеметрии PR №4 и режим `baseline` или `fixed`. Исходный снимок телеметрии остаётся в локальном рабочем контуре.

@ -0,0 +1,12 @@
{
"requires": "PTZ zoom decision PR #4",
"files": {
"ptz_tracker_modular/postprocess.py": {
"before": "8eb5f6beb79141ef1f1ce9dbad3577006821202557a87c7195e770bbba7b4ba3",
"after": "376f705fb3be06ab04afc1ebb718cb71a2c27a67987023b099f5d921148b64ad"
}
},
"unchanged": {
"ptz_tracker_modular/ptz_io.py": "13d31539193b1a773a5d1db2187cc2a0c8db67d0aacaad89082face64df07499"
}
}

@ -0,0 +1,37 @@
--- a/ptz_tracker_modular/postprocess.py
+++ b/ptz_tracker_modular/postprocess.py
@@ -4619,10 +4619,33 @@
if useful_cmd > 0.0:
# A useful-pulse caller revalidates its entire framing envelope on
# every frame. Never turn one accepted pulse into 10 -> 5 -> 1.
+ below_useful = float(zoom_cmd) < useful_cmd - 1e-9
+ same_native = False
+ if below_useful and (
+ pulse_kind == st.get("zoom_step_pending_kind") == "normal"
+ and pulse_timing is not None
+ and optics_observed_now is not None
+ and max(float(now), float(optics_observed_now)) < pulse_until
+ and not st.get("zoom_stop_obligation_active", False)
+ and st.get("zoom_step_stop_started", False)
+ and st.get("zoom_step_stop_timer") is not None
+ and st.get("zoom_step_stop_source") == "track"
+ and st.get("zoom_step_stop_direction") == 1
+ and st.get("zoom_step_stop_generation") == st.get("ptz_generation")
+ ):
+ # A newly authorized fraction in the same native bucket
+ # sends the same lens speed for the original owned pulse.
+ native = _zoom_speed_to_int(useful_cmd)
+ same_native = (
+ 10 <= native <= 12
+ and _zoom_speed_to_int(zoom_cmd) == native
+ and _zoom_speed_to_int(pulse_floor) == native
+ and _zoom_native_pending_matches(st, native)
+ )
if (
not math.isfinite(float(pulse_floor))
or float(pulse_floor) <= 0.0
- or float(zoom_cmd) < useful_cmd - 1e-9
+ or (below_useful and not same_native)
or float(getattr(config, "ZOOM_STEP_MAX_IN_CMD", 0.12)) < useful_cmd
):
_finish_zoom_step(st, now, stable_key=stable_key)

@ -0,0 +1,11 @@
{
"baseline_tests": 16,
"candidate_tests": 16,
"matched_real_stop_windows": 2,
"fractional_frame_inputs": "synthetic",
"original_nominal_and_hard_deadlines_preserved": true,
"matched_earlier_worker_cases": 19,
"unchanged_controller_frames": 23,
"exact_patch_round_trip": true,
"real_device_or_model_access": false
}

@ -0,0 +1,44 @@
# Предсказательный зум Chameleon-C
Кандидат поверх установленного PR №7. Точки интеграции находятся в TRACK, обработчике ISAPI-статуса и обработчике подтверждённых команд транспорта. Контрольные суммы исходных и изменённых файлов приведены в [pins.json](pins.json). [server.patch](server.patch) применяется к точной серверной копии трёх файлов, а [zoom_controller.py](zoom_controller.py) размещается рядом с ними в пакете PTZ.
Для локальной проверки на Windows используйте git -c core.autocrlf=false apply --check server.patch. Для прямого и обратного применения используйте тот же параметр, чтобы сохранить LF и совпадение SHA-256.
## Профиль камеры
Ускоренный путь включается индивидуально через ключ predictive_zoom в CAMERA_CONFIG. Его значения передаются в ZoomConfig. Требуются nominal_gain и upper_gain для native10, измеренные на этой камере. Коэффициенты масштабируют логарифмический темп изменения фокусного расстояния. Паспортные 5,5 с для 6–252 мм задают единицу отсчёта. Для верхней границы используют измеренный максимальный отклик с запасом. Числа из тестов относятся к виртуальному приводу. Камера без настроенного профиля использует политику PR №7.
Первый импульс использует три последовательных кадра OSTrack с согласованной траекторией и последний принятый YOLO-матч того же объекта в пределах 650 мс. На 59° допуск составляет до 30% полуширины кадра, сужаясь до штатной зелёной зоны при 35°. Контроллер отдельно проверяет остаточное угловое движение и прогнозирует запас до обеих границ кадра. Целевой размер по умолчанию 48 × 48 px относится к остановке приближения. Качество распознавания зависит от изображения и модели.
Статус корректирует оценку HFOV асинхронно. После подтверждённого STOP уже подтверждённый оптический шаг может дать следующий импульс на ближайшем свежем кадре. Это снимает ожидание дополнительного опроса после STOP. Если подтверждение оптики задерживается, продолжение остаётся за действующим учётом доставки и оптики. Предсказанный HFOV используется для запаса кадра и компенсации Pan/Tilt. Подтверждение оптики поступает из ISAPI.
Длительность от 340 мс при HFOV от 25° до 120 мс при HFOV до 15°. У каждого импульса собственный неизменяемый дедлайн с верхним пределом watchdog 400 мс. Ранний STOP использует действующий приоритетный канал. Он сохраняет свежий доворот там, где аппаратная политика разрешает раздельную остановку осей. Требуемый полный STOP сохраняется. Весовые файлы, YOLO, OSTrack и тревоги используют прежние пути.
## Управление широким углом и телеуглом
Профили PR №8 с двумя коэффициентами по-прежнему загружаются. Дополнительные параметры задаются в том же predictive_zoom для камеры.
| Параметр | По умолчанию | Назначение |
|---|---:|---|
| initial_gate_relax_factor | 1,45 | Расширяет допуск начального захвата только на широком угле при сходящейся траектории. |
| tele_edge_margin_ratio | 0,32 | Буфер до края на HFOV 12° и ниже. Плавно растёт от 0,16 при 25°. |
| min_allowed_hfov_deg | 10,0° | Нижний предел прогноза для непрерывного положительного зума. Проверяется перед отправкой PUT. |
| latency_horizon_ms | 245 | Горизонт от захвата кадра до действия доворота. |
| tele_pan_native10_deg_s, tele_tilt_native10_deg_s | 0,65 и 0,85 | Калибровка преобразования угловой скорости в команду. |
| tele_position_gain, tele_rate_gain | 2,7 и 0,85 | Угловая коррекция и упреждение. |
| tele_calibration_enabled | true | На HFOV ниже 15° между положительными импульсами допускает ожидание стабилизации статуса до 1,2 с. |
Ускоренный вход разрешается при последовательных достоверных кадрах, допустимой текущей рамке и безопасном прогнозе. Неподтверждённые кадры, конфликт владельца и транспортные запреты продолжают блокировать движение. На телеугле профиль уменьшает вес старого PID по мере сужения поля и подмешивает угловую коррекцию с учётом задержки и синхронизированной скорости приводов. При угрозе краю выполняется отдельный короткий импульс расширения с действующими ограничителями отрицательного зума. Полный STOP остаётся приоритетным.
Предел 10° относится к прогнозу разрешённых импульсов. Настоящая линза и задержки могут отличаться от профиля, поэтому первую полевую серию проверяют по свежему статусу. Абсолютные переходы к пресету обслуживаются прежним кодом.
## Телеметрия и проверки
По умолчанию сводка zoom_block_summary записывается в JSONL в logs/ptz_zoom через ограниченную очередь. Параметр PREDICTIVE_ZOOM_TELEMETRY_DIR задаёт путь или отключает запись значением None. Сводка включает накопленные centering, bbox_check, angle_tol, edge_margin, min_hfov_limit и put_inflight с последними значениями. Снимок появляется не чаще раза в секунду и при завершении TRACK. Камера, время начала и поколение команд идентифицируют эпизод.
Событие native10_pulse_calibration связывает окно команды, монотонные RTT PUT и STOP, статус до импульса, первый статус после STOP и установившийся HFOV. Поле post_stop_tail_deg показывает наблюдённое сужение между двумя статусами после STOP. Если известен свежий замер до STOP, stop_bracket_narrowing_deg дополнительно показывает изменение между ним и установившимся статусом. Оба измерения ограничены частотой опроса. Отменённые, пересекающиеся и незавершённые окна помечаются. Команда python fit_tele_profile.py episode.jsonl собирает предварительный профиль из допустимых окон для отдельной проверки. Автоматического применения нет.
- Unit-тесты: python -m unittest discover -s integration/ptz_predictive_zoom -v
- Полный повтор TRACK и транспорта: run_local_replay.py принимает каталог снимков Codex, каталог пакета, корень Electro-pribory, вариант before или after и необязательный путь к материализованной серверной копии.
- Парный стенд: replay_broad_tele.py запускается с --camera 19 и --camera 21, дополнительно с --edge-stress, --put-rtt и --problem. Каталог с candidate и pins.json задаёт PTZ_BROAD_TELE_REPLAY_DIR. Нужны сохранённые записи AIM и стенд предыдущего PR в соседних каталогах снимков.
- График одного эпизода: python plot_episode.py episode.jsonl episode.svg

@ -0,0 +1,105 @@
{
"paired_cases": 32,
"problem_cases": 3,
"runtime_after_sha": {
"postprocess.py": "dba9b3dc69768526777e166a8ef3270ee54a5d9ed7415a3f905b65e05a8534a5",
"ptz_io.py": "a469c6683c9afc93a1499dd45146e1198bbd752505ba9045704ce5fb8a5d378b",
"status.py": "0f0b91414e04eedc547a5e6931825974f9b5bc09d5795babe5c6ac6179f0882d",
"zoom_controller.py": "6bb81b19e7125daa4ab3ae387ac8ba963bde86f0a51a938d72684ec32d755be3"
},
"minimum_margin_at_6_deg": {
"PR8": 0.1844,
"BT": 0.2508
},
"step_back_cases_at_6_deg": 10,
"joint_below_18_by_camera_starts_at_least_12_deg": {
"19": {
"PR8_pct": 81.54,
"BT_pct": 100.0,
"paired_samples": 661
},
"21": {
"PR8_pct": 81.45,
"BT_pct": 99.92,
"paired_samples": 1256
}
},
"joint_below_18_by_camera_wide_starts": {
"19": {
"PR8_pct": 100.0,
"BT_pct": 100.0,
"paired_samples": 379
},
"21": {
"PR8_pct": 86.45,
"BT_pct": 99.9,
"paired_samples": 974
}
},
"joint_11_to_18_by_camera": {
"19": {
"PR8_pct": 100.0,
"BT_pct": 100.0,
"paired_samples": 407
},
"21": {
"PR8_pct": 86.83,
"BT_pct": 99.9,
"paired_samples": 1002
}
},
"below_18_by_controller_at_own_exposure": {
"19:59.0": {
"PR8_pct": 100.0,
"BT_pct": 100.0,
"PR8_samples": 873,
"BT_samples": 383
},
"19:12.0": {
"PR8_pct": 56.74,
"BT_pct": 100.0,
"PR8_samples": 282,
"BT_samples": 282
},
"19:6.0": {
"PR8_pct": 50.44,
"BT_pct": 93.88,
"PR8_samples": 686,
"BT_samples": 686
},
"21:59.0": {
"PR8_pct": 85.56,
"BT_pct": 99.21,
"PR8_samples": 990,
"BT_samples": 1008
},
"21:12.0": {
"PR8_pct": 64.18,
"BT_pct": 100.0,
"PR8_samples": 282,
"BT_samples": 282
},
"21:6.0": {
"PR8_pct": 41.98,
"BT_pct": 90.23,
"PR8_samples": 686,
"BT_samples": 686
}
},
"problem_first_start_s": [
{
"PR8": 2.18,
"BT": 1.68
},
{
"PR8": 2.22,
"BT": 1.72
},
{
"PR8": 2.25,
"BT": 1.75
}
],
"no_common_tele_exposure_pairs": 5,
"field_calibration_performed": false
}

@ -0,0 +1,45 @@
{
"scope": "offline_replay_only",
"production_enable": false,
"cameras": {
"19": {
"paired_pulses": 3,
"observed_effective_log_rate_range": [
0.26096,
0.51553
],
"replay_settings": {
"nominal_gain": 0.44648,
"upper_gain": 0.95109
},
"telephoto_rate_measured": false
},
"21": {
"paired_pulses": 2,
"observed_effective_log_rate_range": [
0.40197,
0.59657
],
"replay_settings": {
"nominal_gain": 0.73468,
"upper_gain": 1.09732
},
"telephoto_rate_measured": false
}
},
"validation": {
"wide_pairs": 12,
"narrow_pairs": 8,
"narrow_lateral_acceleration_pairs": 4,
"first_zoom_speedup_s_range": [
0.0,
2.7
],
"candidate_smallest_model_margin_narrow": 0.2164,
"candidate_smallest_model_margin_lateral": 0.1844,
"candidate_model_edge_clips": 0,
"confirmed_live_retention_or_speed": false,
"additional_put_rtt_pairs": 8,
"candidate_smallest_model_margin_put_rtt_narrow": 0.1852
}
}

@ -0,0 +1,68 @@
"""Summarize qualified telephoto pulses from episode JSONL into review candidates."""
import argparse
from collections import defaultdict
import json
import math
from pathlib import Path
from statistics import median
def focal(fov):
return -math.log(math.tan(math.radians(fov / 2)))
def summarize(files):
grouped = defaultdict(dict)
for file in files:
with file.open(encoding="utf-8") as rows:
for line in rows:
item = json.loads(line)
if item.get("event") != "native10_pulse_calibration":
continue
key = (item["track_start_utc"], item["generation"], item["request"])
grouped[item["cam"]][key] = item
result = {}
for camera, records in sorted(grouped.items()):
accepted = []
for item in records.values():
rate = item.get("effective_tele_log_rate_s")
if (item.get("outcome") != "settled" or not isinstance(rate, (float, int))
or not math.isfinite(rate) or rate <= 0):
continue
before, after = item["HFOV_before"], item["HFOV_after"]
if not 0 < after < before < 15:
continue
if item.get("put_rtt_ms") is None or item.get("stop_rtt_ms") is None:
continue
accepted.append(item)
result[str(camera)] = {"qualified": len(accepted), "seen": len(records),
"candidate_for_review": None}
# A single track may have a common framing or status-timing bias.
if len(accepted) < 3 or len({x["track_start_utc"] for x in accepted}) < 2:
continue
rates = [x["effective_tele_log_rate_s"] for x in accepted]
bracket = [
max(0., focal(x["HFOV_after"]) - focal(x["HFOV_stop_sample"]))
for x in accepted if x.get("stop_status_at") is not None
and x["put_at"] <= x["stop_status_at"] <= x["stop_issued_at"]
and 0 <= x["stop_issued_at"] - x["stop_status_at"] <= .18
]
full_sweep_rate = math.log(252 / 6) / 5.5
result[str(camera)]["candidate_for_review"] = {
"observed_hfov_before_deg": [min(x["HFOV_before"] for x in accepted),
max(x["HFOV_before"] for x in accepted)],
"median_effective_tele_log_rate_s": median(rates),
"stress_upper_gain": max(rates) * 1.25 / full_sweep_rate,
"qualified_stop_brackets": len(bracket),
"max_stop_bracket_log_narrowing": max(bracket, default=None),
"max_put_rtt_ms": max(x["put_rtt_ms"] for x in accepted),
"max_stop_rtt_ms": max(x["stop_rtt_ms"] for x in accepted),
}
return {"scope": "observed_telephoto_windows_only", "production_enable": False, "cameras": result}
if __name__ == "__main__":
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("files", nargs="+", type=Path)
args = parser.parse_args()
print(json.dumps(summarize(args.files), indent=2, allow_nan=False))

@ -0,0 +1,17 @@
{
"postprocess.py": {
"before": "776b5b337e5f898e69770fec517c4459560f4cc6adeb951af40ac8f0b2178534",
"after": "dba9b3dc69768526777e166a8ef3270ee54a5d9ed7415a3f905b65e05a8534a5"
},
"ptz_io.py": {
"before": "13d31539193b1a773a5d1db2187cc2a0c8db67d0aacaad89082face64df07499",
"after": "a469c6683c9afc93a1499dd45146e1198bbd752505ba9045704ce5fb8a5d378b"
},
"status.py": {
"before": "2fca9a2000c2cac9af42ad3f637416c66e1bb87f2f8166c7aefbbebbe5d07b06",
"after": "0f0b91414e04eedc547a5e6931825974f9b5bc09d5795babe5c6ac6179f0882d"
},
"zoom_controller.py": {
"after": "6bb81b19e7125daa4ab3ae387ac8ba963bde86f0a51a938d72684ec32d755be3"
}
}

@ -0,0 +1,73 @@
"""Render an episode JSONL as a static SVG without plotting dependencies."""
import argparse
import json
from pathlib import Path
from xml.sax.saxutils import escape
def render(rows):
samples = sorted((r for r in rows if r["event"] == "tick"), key=lambda r: r["elapsed_ms"])
if not samples:
raise ValueError("The episode has no TRACK ticks.")
last = max(1.0, samples[-1]["elapsed_ms"])
groups = (
("HFOV (deg)", 60.0, (
("ISAPI actual", "#2563eb", lambda r: r["FOV_actual"]),
("Estimated", "#c2410c", lambda r: r["FOV_estimated"]),
("Narrow bound", "#64748b", lambda r: r["FOV_min_estimated"]),
)),
("BBox (px)", max(48.0, max(max(r["bbox_px"]) for r in samples)), (
("Width", "#2563eb", lambda r: r["bbox_px"][0]),
("Height", "#c2410c", lambda r: r["bbox_px"][1]),
)),
("Confidence", 1.0, (
("YOLO last match", "#2563eb", lambda r: r["detector_conf"]),
("OSTrack score", "#c2410c", lambda r: r["tracker_score"]),
)),
)
content = [
'<svg xmlns="http://www.w3.org/2000/svg" width="980" height="680" viewBox="0 0 980 680">',
'<rect width="100%" height="100%" fill="white"/>',
'<g fill="#0f172a" font-family="sans-serif" font-size="15">',
f'<text x="68" y="27">PTZ {escape(str(samples[0]["cam"]))} · TRACK telemetry</text>',
]
first = next((r.get("t_to_first_zoom_ms") for r in rows if r["event"] == "first_zoom"), None)
for panel, (title, ymax, series) in enumerate(groups):
y0 = 76 + 190 * panel
plot_h = 133
content.append(f'<text x="68" y="{y0-12}">{title}</text>')
content.append(f'<path d="M68 {y0} v{plot_h} h850" fill="none" stroke="#94a3b8"/>')
for frac in (0, .5, 1):
content.append(f'<text x="17" y="{y0 + plot_h * (1-frac) + 5}">{ymax*frac:.1f}</text>')
for number, (label, color, extract) in enumerate(series):
content.append(f'<text fill="{color}" x="{265 + 170 * number}" y="{y0-12}">{label}</text>')
path = []
for row in samples:
value = extract(row)
if value is None:
if path and path[-1]:
path.append("")
continue
x = 68 + 850 * row["elapsed_ms"] / last
y = y0 + plot_h * (1 - value / ymax)
command = "L" if path and path[-1] else "M"
path.append(f"{command}{x:.1f} {y:.1f}")
content.append(f'<path d="{" ".join(path)}" stroke="{color}" stroke-width="2" fill="none"/>')
if first is not None and 0 <= first <= last:
x = 68 + 850 * first / last
content.append(f'<path d="M{x:.1f} {y0} v{plot_h}" stroke="#334155" stroke-dasharray="3 3"/>')
for k in range(6):
content.append(f'<text x="{68 + 170*k}" y="623">{last*k/5000:.2f}</text>')
content.append('<text x="68" y="654">Seconds since TRACK_START. Dashed marker = first acknowledged zoom.</text>')
content.append('</g></svg>')
return "\n".join(content) + "\n"
if __name__ == "__main__":
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("episode", type=Path)
parser.add_argument("output", type=Path)
args = parser.parse_args()
rows = [json.loads(line) for line in args.episode.read_text(encoding="utf-8").splitlines() if line]
args.output.write_text(render(rows), encoding="utf-8")

@ -0,0 +1,484 @@
"""Run PR7 and PR8 on identical trajectories reconstructed from logged AIM."""
from bisect import bisect_right
from collections import Counter, deque
from contextlib import ExitStack
from hashlib import sha256
from pathlib import Path
from statistics import median
from types import ModuleType, SimpleNamespace
from unittest.mock import patch
import argparse
import cv2
import json
from inspect import unwrap
import logging
import math
import os
import socket
import sys
OUT = Path(os.environ.get(
"PTZ_BROAD_TELE_REPLAY_DIR",
Path(__file__).resolve().parents[3] / "ptz_broad_tele_20261111",
))
DATA = OUT.parent / "ptz_native10_profiles_20261111"
sys.path.insert(0, str(DATA))
from measure_native10 import FIELD, PULSES, PR7, FULL_SWEEP_LOG_RATE, ROOT, read, utc
LAB = ROOT / "ptz_virtual_lab_20261111"
sys.path.insert(0, str(LAB))
import simulator as sim
CANDIDATE = ROOT / "ptz_predictive_zoom_candidate_20261111"
BUNDLE = ROOT / "chameleon_predictive_zoom_git_20261111/integration/ptz_predictive_zoom"
BASE_STATUS = sim.SOURCE / "status.py"
NEW = OUT / "candidate"
NEW_PINS = OUT / "pins.json"
TRACE_KEYS = ("normal_zoom_quality_ok", "zoom_quality_ok", "zoom_rearm_ready", "zoom_safe",
"zoom_angular_safe", "stable_ok", "near_edge", "edge_recovery_active",
"followup_ready", "raw_zoom_needed", "normal_size_hold", "final_guard_active",
"visual_control_stale", "visual_control_coast", "zoom_zero_reason",
"zoom_cmd", "can_zoom_in", "predictive_decision")
FLIGHTS = {
"19": ("03:11:07", "04:54:08"),
"21": ("04:13:33", "04:37:45"),
}
def angle(error, fov):
return math.degrees(math.atan(2*error*math.tan(math.radians(fov/2))))
def trajectory(camera, episode, source):
start, end = map(utc, (episode["started_at"], episode["ended_at"]))
candidates = [r for r in source["cameras"][camera]["samples"]
if start <= r["t"] <= min(end, start+25)
and r["err"] and r["fov"] and r["gimbal"] and r["optics_age"] is not None
and r["optics_age"] <= .65 and r["source"] in ("visual","detector","acquire")]
groups = []
for r in candidates:
if not groups or r["t"] - groups[-1][-1]["t"] > 1.65:
groups.append([])
groups[-1].append(r)
# Prefer the longest contiguous trace so neither controller bridges a gap.
rows = max(groups, key=lambda g: g[-1]["t"]-g[0]["t"])
origin = rows[0]["t"]
pose = [0.0, 0.0]
samples = []
for i,r in enumerate(rows):
if i:
previous = rows[i-1]
dt = r["t"] - previous["t"]
for axis, sign in enumerate((1,-1)):
pose[axis] += sign * dt * (r["gimbal"][axis]+previous["gimbal"][axis])/2
bearing = tuple(pose[k]+angle(r["err"][k], r["fov"][k]) for k in range(2))
samples.append((r["t"]-origin,*bearing))
duration = math.floor(samples[-1][0]*100)/100
if duration < 3:
raise ValueError(f"Insufficient contiguous AIM trace: camera {camera} {episode['started_at']}")
# Only a scalar filtered size is available. Use a projected square with that
# geometric mean at initial FOV and hold angular extent constant.
first_size = episode["size_first"] or .018
fov_x, fov_y = rows[0]["fov"]
angular = tuple(2*angle(first_size/2, fov) for fov in (fov_x, fov_y))
return dict(camera=int(camera), episode=episode["started_at"], aim_start=origin,
duration=duration, knots=samples, angular_extent=angular,
source_rows=len(samples), observed_hfov=rows[0]["fov"])
class FlightCamera(sim.Camera):
def __init__(self, parameters, pan_sign, tilt_sign, trace, initial_fov):
super().__init__(parameters, pan_sign, tilt_sign)
self.trace = trace
self.times = [x[0] for x in trace["knots"]]
self.magnification = sim.OPTICAL_ZOOM ** (
math.log(math.tan(math.radians(59/2))/math.tan(math.radians(initial_fov/2)))
/ math.log(math.tan(math.radians(59/2))/math.tan(math.radians(2/2)))
)
if initial_fov < 20:
_, az, el = trace["knots"][0]
# Keep this synthetic narrow-angle stress start inside the aperture.
self.pan, self.tilt = az-.10*initial_fov, el-.05*initial_fov
def target(self, t):
i = min(len(self.times)-2, max(0, bisect_right(self.times,t)-1))
a,b = self.trace["knots"][i:i+2]
frac = min(1,max(0,(t-a[0])/(b[0]-a[0])))
az, el = (x+(y-x)*frac for x,y in zip(a[1:],b[1:]))
if self.trace.get("edge_stress"):
# Same finite lateral acceleration for both controllers.
push = min(1.1,max(0.0,t-.90))
az += 2.8 * push*push / 1.21
return az,el
def project(self, t, *, clipped=True):
center = self.target(t)
bounds = []
for bearing, pose, width, fov, pixels in zip(
center,(self.pan,self.tilt),self.trace["angular_extent"],(self.hfov,self.vfov),(1280,720)
):
# stress small angles with a tiny object that still asks for zoom
if self.trace.get("stress"):
width *= .22
deviation = bearing-pose
if abs(deviation)+width/2 >= 85:
return None
focal = (pixels/2)/math.tan(math.radians(fov/2))
lo,hi = [round(pixels/2+focal*math.tan(math.radians(deviation+o*width/2))) for o in (-1,1)]
if clipped:
lo,hi = max(0,lo),min(pixels-1,hi)
if hi <= lo:
return None
bounds.append((lo,hi))
return (bounds[0][0],bounds[1][0],bounds[0][1],bounds[1][1])
def capture_control(pp, function):
row = {}
code = unwrap(pp.postprocess_control).__code__
def trace(frame,event,arg):
if event == "call" and frame.f_code is code:
frame.f_trace_lines = False
return trace
if event == "return" and frame.f_code is code:
row.update({k:frame.f_locals[k] for k in TRACE_KEYS if k in frame.f_locals})
row["return_line"] = frame.f_lineno
return None
original = sys.gettrace()
sys.settrace(trace)
try:
function()
finally:
sys.settrace(original)
return row
def blocker(row, st):
"""Primary gate plus all simultaneous blockers. Locals come from live policy."""
if "zoom_cmd" not in row:
return "track_or_frame_rejected", []
if row["zoom_cmd"] > 0:
return None,[]
reasons = [
(row.get("final_guard_active"), "gimbal_brake"),
(row.get("near_edge") or row.get("edge_recovery_active"), "edge_margin_low"),
(row.get("visual_control_stale") or row.get("visual_control_coast"), "stale_visual"),
(not row.get("zoom_rearm_ready",True), "geometry_rearm"),
(not row.get("raw_zoom_needed",True) or row.get("normal_size_hold"), "size_controller"),
(not row.get("zoom_quality_ok",True), "quality_or_validation"),
(not row.get("followup_ready",True), "fov_cooldown"),
(not row.get("zoom_safe",True), "framing"),
(not row.get("zoom_angular_safe",True), "angular_limit"),
(not row.get("stable_ok",True), "not_centered_or_not_stable"),
]
flags = [why for enabled,why in reasons if enabled]
predictive = row.get("predictive_decision")
if predictive and predictive.stop:
return predictive.reason,flags
return (flags[0] if flags else row.get("zoom_zero_reason") or st.get("zoom_useful_pulse_reason") or "unknown"),flags
def run(trace, profile, steering, revision, video_ms, isapi_ms, initial_fov=59.,
plant_stress=False, put_rtt=False):
import numpy
import torch
cam = trace["camera"]-11
cfg = sim.Parameters(camera=trace["camera"], seconds=trace["duration"],
video_ms=video_ms, command_ms=isapi_ms, optics_report_ms=isapi_ms,
frame_hz=10, status_hz=4, steering_exponent=2,
pan_at_10=steering["pan"]["native10_equivalent_deg_s"],
tilt_at_10=steering["tilt"]["native10_equivalent_deg_s"],
zoom_at_10=profile["upper_gain" if plant_stress else "nominal_gain"] * FULL_SWEEP_LOG_RATE
/ math.log(math.tan(math.radians(59/2))/math.tan(math.radians(2/2))) * math.log(42)/math.log(2))
with ExitStack() as stack:
for owner,name in ((socket.socket,"connect"),(socket.socket,"connect_ex"),
(socket,"create_connection"),(torch,"load"),(torch.cuda,"_lazy_init")):
stack.enter_context(patch.object(owner,name,sim.deny))
stack.enter_context(patch.object(torch.cuda,"is_available",return_value=False))
pkg = ModuleType(sim.PKG)
pkg.__path__ = [str(sim.BASE/"geometry_candidate/ptz_tracker_modular"),str(sim.ROOT)]
stale_modules = {k:m for k,m in sys.modules.items() if k.startswith(sim.PKG+".")}
for k in stale_modules:
sys.modules.pop(k)
stack.enter_context(patch.dict(sys.modules,{sim.PKG:pkg}))
model = ModuleType(sim.PKG+".model")
model.model_shared,model.yolo_forward=object(),sim.deny
sys.modules[model.__name__] = model
sim.load(sim.PKG+".visual_control_probe",sim.SOURCE/"visual_control_probe.py")
control = sim.load(sim.PKG+".visual_control",sim.SOURCE/"visual_control.py")
pins = read(NEW_PINS if revision=="BT" else BUNDLE/"pins.json")
bundle = NEW if revision=="BT" else BUNDLE
candidate = NEW if revision=="BT" else CANDIDATE
for filename, values in pins.items():
path = (bundle if filename == "zoom_controller.py" else candidate) / filename
assert sha256(path.read_bytes()).hexdigest() == values["after"], filename
sim.load(sim.PKG+".zoom_controller",bundle/"zoom_controller.py")
io_path, pp_path, status_path = [candidate/f for f in ("ptz_io.py","postprocess.py","status.py")]
io = sim.load(sim.PKG+".ptz_io",io_path)
status = sim.load(sim.PKG+".status",status_path)
pp = sim.load(sim.PKG+".postprocess",pp_path)
from ptz_tracker_modular import config,state,visual_tracker
values = read(sim.BASE/"zoom_continuation_candidate/runtime_policy_snapshot.json")["values"]
for key,value in values.items():
stack.enter_context(patch.object(config,key,value,create=True))
stack.enter_context(patch.object(config,"PTZ_CAM_IDS",[cam,*[x for x in config.PTZ_CAM_IDS if x!=cam]]))
transport = sim.load("native10_mock_transport",sim.ROOT/"tests/test_zoom_useful_transport.py")
before = sim.load("native10_control_fixture",sim.REPLAY)
before.np,before.torch,before.config,before.state = numpy,torch,config,state
before.ptz_io,before.pp,before.tracker,before.control,before.transport = io,pp,visual_tracker,control,transport
case = before.Replay()
case.setUp()
stack.callback(case.doCleanups)
f,st = case.fixture,case.st
cam_config = config.CAMERA_CONFIG[cam]
settings = dict(ptz_hfov_wide_deg=59.,ptz_hfov_tele_deg=2.)
settings["predictive_zoom"] = dict(profile)
if revision=="BT":
settings["predictive_zoom"].update(
tele_pan_native10_deg_s=cfg.pan_at_10, tele_tilt_native10_deg_s=cfg.tilt_at_10,
latency_horizon_ms=video_ms+isapi_ms/2,
)
settings["predictive_zoom"].update(trace.get("tuning",{}))
stack.enter_context(patch.object(config,"PREDICTIVE_ZOOM_TELEMETRY_DIR",None,create=True))
stack.enter_context(patch.dict(cam_config,settings))
for key in ("ZOOM_STEP_PULSE_SEC","ZOOM_STEP_HARD_STOP_SEC"):
stack.enter_context(patch.object(config,key,values[key]))
plant = FlightCamera(cfg,float(cam_config.get("pan_sign",1)),float(cam_config.get("tilt_sign",-1)),trace,initial_fov)
initial = plant.project(0)
if initial is None:
raise ValueError("Invalid initial viewport")
st.update(last_bbox=initial,prev_cx=(initial[0]+initial[2])/2560,
prev_cy=(initial[1]+initial[3])/1440,stable_frames=0,
track_started_at=100.,last_seen=100.,visual_tracker_last_detector_at=100.,
visual_tracker_last_zoom_detector_at=100.,visual_tracker_last_detector_conf=.8)
status._update_runtime_state(cam,None,None,99.99,zoom_ratio=plant.magnification,hfov_deg=plant.hfov)
st["vfov_deg"]=plant.vfov
# Replace only the asynchronous STOP thread's scheduler so it runs at
# this virtual tick; the actual priority STOP path still runs.
if revision in ("PR8","BT"):
class InlineThread:
def __init__(self, *, target, **_): self.target=target
def start(self): self.target()
original_thread = io.threading.Thread
def choose_thread(*args, **kwargs):
if kwargs.get("name") == "ptz-predictive-stop":
return InlineThread(**kwargs)
return original_thread(*args, **kwargs)
stack.enter_context(patch.object(io.threading,"Thread",choose_thread))
t = 0.
commands, rows, decisions = [], [], []
statuses, frames = deque(),deque()
request_starts, request_ids = [],set()
prior_lens = 0
busy_until = 0.0
def send(_url, *, data=b"", **_kw):
nonlocal prior_lens, busy_until
axes = tuple(transport.xml_axis(str(data),name) for name in ("pan","tilt","zoom"))
# Model physical propagation and GET response separately. PUT
# success and STOP timers use the existing deterministic fixture.
issue = max(t,f.wall-100) if put_rtt else t
response = issue+isapi_ms/1000 if put_rtt else issue
propagation = isapi_ms/(2000 if put_rtt else 1000)
plant.commands.append((issue+propagation,axes))
commands.append((round(issue,4),axes))
if put_rtt:
busy_until = max(busy_until,response)
f.wall,f.mono=100+response,1000+response
request = st.get("zoom_step_pending_id")
if axes[2]>0 and prior_lens<=0 and request and request not in request_ids:
request_starts.append(round(response,4))
request_ids.add(request)
prior_lens=axes[2]
return True,200,""
stack.enter_context(patch.object(io,"_ptz_put",side_effect=send))
stack.enter_context(patch.object(io,"_ptz_put_priority_stop",side_effect=send))
logger=logging.getLogger("PTZTracker")
saved=logger.level
logger.setLevel(logging.ERROR)
stack.callback(logger.setLevel,saved)
interval = video_ms//10
stop_step = round(trace["duration"]*100)
optics_count=0
for step in range(stop_step+1):
t=step/100
now = max(t,busy_until)
f.wall,f.mono=100+now,1000+now
if step:
plant.step(t,.01)
if step%25==0:
statuses.append((step+isapi_ms//10,step,plant.magnification,plant.hfov,plant.vfov,
plant.pan_rate*plant.pan_sign,plant.tilt_rate*plant.tilt_sign))
while statuses and statuses[0][0]<=step and t+1e-8>=busy_until:
_,origin,mag,hfov,vfov,pan,tilt=statuses.popleft()
measured_at=100+origin/100
st.update(status_rate_at=measured_at,pan_rate_at=measured_at,tilt_rate_at=measured_at,
pan_rate_deg_s=pan,tilt_rate_deg_s=tilt,vfov_deg=vfov)
st["status_rate_history"] = (st.get("status_rate_history", []) +
[(measured_at,pan,tilt)])[-20:]
status._update_runtime_state(cam,None,None,f.wall,zoom_ratio=mag,hfov_deg=hfov,
zoom_age_sec=(step-origin)/100)
timer=st.get("zoom_step_stop_timer")
if (timer and timer.is_alive() and f.mono+1e-8>=st["zoom_step_stop_started_mono"]+timer.delay):
timer.fire()
if step%10==0:
frames.append((step+interval,step,plant.project(t)))
while frames and frames[0][0]<=step and t+1e-8>=busy_until:
due,origin,box=frames.popleft()
case.seq+=1
track=visual_tracker.VisualTrackResult(box is not None,box,.8 if box else 0.,0,.8,
case.seq,"telemetry projection",case.seq)
age=(step-origin)/100
captured_at=f.wall-age
visual=control.VisualSample(control.owner(st),case.seq,captured_at,track)
if origin%40==0 and box is not None:
detection=SimpleNamespace(boxes=before.Boxes([(*box,.8,0)]))
pp.postprocess_control(cam,case.frame,detection,True,case.seq,visual_sample=visual)
frame=SimpleNamespace(boxes=before.Boxes([]))
row=capture_control(pp,lambda: pp.postprocess_control(
cam,case.frame,frame,True,case.seq,visual_sample=visual,visual_only=True))
reason,flags=blocker(row,st)
decisions.append(dict(t=t, zoom_block_reason=reason, flags=flags,
requested=row.get("zoom_cmd"), source_seq=case.seq,
return_line=row.get("return_line"),
actual_hfov=plant.hfov,
forecast_reason=getattr(row.get("predictive_decision"),"reason",None)))
if not state.ptz_cmd_q.empty():
state.ptz_cmd_q.put_nowait(None)
io._ptz_worker()
optics_count=max(optics_count,st.get("zoom_in_pulse_count",0))
if step%5==0 or step==stop_step:
box=plant.project(t,clipped=False)
if box is None:
error,margin,px=None,-.5,None
else:
x0,y0,x1,y1=box
error=max(abs((x0+x1)/2560-.5),abs((y0+y1)/1440-.5))
margin=min(x0/1280,1-x1/1280,y0/720,1-y1/720)
px=(x1-x0,y1-y0)
rows.append(dict(t=t,hfov=plant.hfov,margin=margin,center_err=error,bbox_px=px,
mode=st.get("mode"),zoom=plant.active[2],
tele_steering=st.get("tele_steering_active",False)))
first=request_starts[0] if request_starts else None
prefix=[row for row in decisions if first is None or row["t"]<=first]
errors=[r["center_err"] for r in rows if r["center_err"] is not None]
tele = [r for r in rows if r["hfov"] < 18]
telemetry=dict(
trace={k:val for k,val in trace.items() if k!="knots"}, revision=revision,
tested_after_sha={file:row["after"] for file,row in pins.items()},
video_ms=video_ms,isapi_ms=isapi_ms,initial_fov=initial_fov,plant_stress=plant_stress,
put_rtt_ms=isapi_ms if put_rtt else 0,
observed_model=dict(profile=profile,pan_at_native10=cfg.pan_at_10,tilt_at_native10=cfg.tilt_at_10),
metrics=dict(first_zoom_s=first,positive_starts=len(request_starts),optics_confirmed_max=optics_count,
hfov_min=round(min(r["hfov"] for r in rows),3),
tele_samples=len(tele),
tele_center_pct=round(100*sum(r["center_err"] is not None and
r["center_err"]<=.1 for r in tele)/len(tele),1) if tele else None,
tele_steering_samples=sum(bool(r["tele_steering"]) for r in tele),
fully_in_frame_pct=round(100*sum(r["margin"]>=0 for r in rows)/len(rows),1),
inside_center_10pct=round(100*sum(r["center_err"] is not None and r["center_err"]<=.1 for r in rows)/len(rows),1),
min_edge_margin=round(min(r["margin"] for r in rows),4),
peak_center_error=round(max(errors),4) if errors else None,
narrow_lens_active_samples=sum(r["hfov"]<=15 and r["zoom"]>0 for r in rows),
narrowing_with_edge_clip_samples=sum(r["margin"]<0 and r["zoom"]>0 for r in rows),
first_edge_clip_s=next((r["t"] for r in rows if r["margin"]<0),None),
positive_native=dict(Counter(axes[2] for _,axes in commands if axes[2]>0)),
max_bbox_short_px=max((min(r["bbox_px"]) for r in rows if r["bbox_px"]),default=0)),
zoom_block_reason_before_first=dict(Counter(r["zoom_block_reason"] for r in prefix if r["zoom_block_reason"])),
zoom_block_reason=dict(Counter(r["zoom_block_reason"] for r in decisions if r["zoom_block_reason"])),
simultaneous_flags_before_first=dict(Counter(x for r in prefix for x in r["flags"])),
request_starts=request_starts,commands=commands,rows=rows,decisions=decisions)
return telemetry
def main():
parser=argparse.ArgumentParser(description=__doc__)
parser.add_argument("--camera",choices=sorted(FLIGHTS))
parser.add_argument("--tune",action="store_true")
parser.add_argument("--problem",action="store_true")
parser.add_argument("--tuning-json",default="{}")
parser.add_argument("--smoke",action="store_true")
parser.add_argument("--edge-stress",action="store_true")
parser.add_argument("--put-rtt",action="store_true")
parser.add_argument("--counters",action="store_true",
help="repeat the first six seconds with per-tick controller diagnostics")
args=parser.parse_args()
import torch
torch.set_num_threads(1)
dest=OUT/"final"
dest.mkdir(exist_ok=True)
profiles=read(DATA/"profiles.json")["cameras"]
field,pulses=read(FIELD),read(PULSES)
steering=read(LAB/"field-calibration-report.json")["cameras"]
jobs=[]
for camera, keys in FLIGHTS.items():
if args.camera and args.camera!=camera:
continue
traces=[trajectory(camera,next(e for e in pulses["episodes"][camera] if e["started_at"][11:19]==key),field)
for key in keys]
if args.problem:
if camera=="19":
ep=next(e for e in read(PR7)["episodes"][camera] if "05:49:18" in e["started_at"] or "12:49:18" in e["started_at"])
trace=trajectory(camera,ep,field)
for video,api in ((180,40),(220,50),(250,60)):
jobs.append((trace,video,api,59.,False))
continue
if args.tune:
trace = {**traces[0],"stress":True,"edge_stress":True,
"duration":min(5.,traces[0]["duration"])}
jobs.extend(((traces[-1],220,50,59.,False),(trace,250,60,6.,True),
({**traces[0],"stress":True,"duration":7.},250,60,12.,True)))
continue
if args.put_rtt:
for video,api in ((180,40),(250,60)):
jobs.append(({**traces[1],"duration":min(7.,traces[1]["duration"])},video,api,59.,False))
jobs.append(({**traces[0],"stress":True,"edge_stress":True,
"duration":min(5.,traces[0]["duration"])},video,api,6.,True))
continue
if args.edge_stress:
trace = {**traces[0],"stress":True,"edge_stress":True,
"duration":min(5.,traces[0]["duration"])}
for video,api in ((180,40),(250,60)):
jobs.append((trace,video,api,6.,True))
continue
if args.counters:
for trace in traces:
jobs.append(({**trace,"duration":min(6.,trace["duration"])},220,50,59.,False))
continue
if args.smoke:
jobs.append((traces[0],220,50,59.,False))
continue
for trace in traces:
for video,api in ((180,40),(220,50),(250,60)):
jobs.append((trace,video,api,59.,False))
for fov in (12.,6.):
for video,api in ((180,40),(250,60)):
stress = {**traces[0],"stress":True,"duration":min(traces[0]["duration"],7.)}
jobs.append((stress,video,api,fov,True))
summaries=[]
for trace,video,api,fov,stress in jobs:
cam=str(trace["camera"])
versions=[]
for revision in ("PR8","BT"):
configured_trace = {**trace,"tuning":json.loads(args.tuning_json)}
result=run(configured_trace,profiles[cam]["replay_settings"],steering[cam]["fit"],
revision,video,api,fov,stress,put_rtt=args.put_rtt)
name=f"{cam}-{trace['episode'][11:19].replace(':','')}-{video}-{api}-{int(fov)}-{revision}{'-counters' if args.counters else ''}{'-edge' if args.edge_stress else ''}{'-put' if args.put_rtt else '-tune' if args.tune else '-problem' if args.problem else ''}.json"
(dest/name).write_text(json.dumps(result,allow_nan=False,separators=(",",":"))+"\n",encoding="utf-8")
versions.append({k:result[k] for k in ("revision","metrics","zoom_block_reason_before_first","tested_after_sha")}|{"trace_file":name})
summaries.append(dict(camera=int(cam),episode=trace["episode"],video_ms=video,isapi_ms=api,
initial_fov=fov,stress=stress,put_rtt_ms=api if args.put_rtt else 0,runs=versions))
print(cam,trace["episode"][11:19],video,api,fov,
[(x["metrics"]["first_zoom_s"],x["metrics"]["hfov_min"],x["metrics"]["tele_center_pct"],
x["metrics"]["min_edge_margin"],x["metrics"]["tele_steering_samples"]) for x in versions],
flush=True)
name = f"comparison{('-'+args.camera) if args.camera else ''}{'-smoke' if args.smoke else ''}{'-counters' if args.counters else ''}{'-edge' if args.edge_stress else ''}{'-put' if args.put_rtt else '-tune' if args.tune else '-problem' if args.problem else ''}.json"
(dest/name).write_text(json.dumps(summaries,indent=2,allow_nan=False)+"\n",encoding="utf-8")
if __name__=="__main__":
main()

@ -0,0 +1,46 @@
from pathlib import Path
import json, os, sys
v,z,root,variant=map(Path,sys.argv[1:5])
candidate=Path(sys.argv[5]) if len(sys.argv)>5 else v/"ptz_broad_tele_20261111/candidate"
pr7=v/"ptz_zoom_threshold_diagnostics_20261111"
pins=json.loads((z/"pins.json").read_text())
dest=candidate.parent/f"regression_{variant}.json"
before=str(variant)=="before"
p=(v/"ptz_zoom_threshold_maintenance_20261111" if before else candidate)/"postprocess.py"
i=(v/"ptz_zoom_zero_decision_20261109" if before else candidate)/"ptz_io.py"
s=(v/"ptz_monitor/server_unknown_source_20261109_043525" if before else candidate)/"status.py"
source=v/"ptz_monitor/server_unknown_source_20261109_043525"
key="before" if before else "after"
sys.path.insert(0,str(pr7))
if not before:
sys.path.insert(0,str(z))
sys.argv=[str(pr7/"replay.py"),str(source),str(i),
str(v/"ptz_zoom_stop_maintenance_20261109/ssh_7c7ae84464cc400dbc7dc1327124bbf7/telemetry.json"),
str(v/"cc1_cc2_control_replay_20261026/test_control_replay.py"),str(p),
pins["postprocess.py"][key],pins["ptz_io.py"][key],str(root),str(dest),
str(v/"ptz_zoom_zero_maintenance_20261109/ssh_8f0f9accd24b4f40b6466d0566cafbce/telemetry.json"),"fixed","--thresholds"]
r=(pr7/"replay.py").read_text(encoding="utf-8")
if not before:
r=r.replace(" ptz_io=load",f" load(PKG+'.zoom_controller', Path({str(z/'zoom_controller.py')!r}))\n ptz_io=load")
r=r.replace(" pp=load",f" status=load(PKG+'.status', Path({str(s)!r}))\n pp=load")
r=r.replace(" values=json.loads", """ stack.enter_context(patch.object(
config, 'PREDICTIVE_ZOOM_TELEMETRY_DIR', None, create=True))
values=json.loads""")
r=r.replace(" result=unittest.TextTestRunner", """ from track_integration import TRACE as zoom_trace, build_track_cases
integration = build_track_cases(before, pp, ptz_io, config, state, status)
for case in ("test_track_runs_burst_without_post_stop_status",
"test_track_same_flight_legacy_reference",
"test_track_starts_at_26_percent_of_half_frame",
"test_track_legacy_reference_at_26_percent_of_half_frame",
"test_priority_zoom_stop_honors_axis_policy",
"test_priority_zoom_stop_does_not_override_full_stop",
"test_transport_floor_preserves_gimbal_and_rejects_lens"):
suite.addTest(integration(case))
result=unittest.TextTestRunner""")
r=r.replace(" result_file=Path", f""" if result.wasSuccessful():
Path({str(candidate.parent/"regression_episode.jsonl")!r}).write_text(
"".join(json.dumps(row, allow_nan=False) + "\\n" for row in zoom_trace), encoding="utf-8")
result_file=Path""")
code=compile(r,str(pr7/"replay.py"),"exec")
exec(code,{"__file__":str(pr7/"replay.py"),"__name__":"__main__"})

@ -0,0 +1,609 @@
--- a/postprocess.py
+++ b/postprocess.py
@@ -10,6 +10,9 @@
import cv2
from . import config, state, visual_control
+from .zoom_controller import (
+ ZoomFrame, controller_for_track, expire_calibration, flush_zoom_blocks, record_zoom_blocks, telemetry_tick,
+)
from . import motion_detector
from .utils import (
clipf,
@@ -30,6 +33,7 @@
_zoom_command_lock,
zoom_step_optics_delta,
_zoom_speed_to_int,
+ stop_predictive_zoom_async,
)
from .geom import ang_diff_signed, sector_contains
from .patrol import (
@@ -4597,6 +4601,7 @@
optics_observed_now: float | None = None,
stop_trace: list[str] | None = None,
continuation_trace: list[tuple[int, int, float, float, float, float, float]] | None = None,
+ predictive=None,
) -> float:
"""Break continuous zoom-in into short feedback-controlled steps."""
pulse_until = float(st.get("zoom_step_until", 0.0) or 0.0)
@@ -4706,18 +4711,23 @@
_finish_zoom_step(st, now, stable_key=stable_key)
return 0.0
if pulse_until <= 0.0:
- if (
+ observed = now if optics_observed_now is None else optics_observed_now
+ early_repeat = bool(predictive and predictive.repeat_after_stop(st, observed))
+ if not early_repeat and (
float(now) < cooldown_until
or float(now) < float(st.get("zoom_recenter_until", 0.0) or 0.0)
):
return 0.0
- if (
+ if early_repeat:
+ # The original transaction is already committed. Consume its single
+ # credit under the transport lock, before publishing a new request.
+ predictive.confirmed_stop = None
+ st["zoom_feedback_required_after"] = 0.0
+ elif (
int(st.get("zoom_in_pulse_count", 0) or 0) > 0
or float(st.get("zoom_feedback_required_after", 0.0) or 0.0) > 0.0
):
- feedback_ready, feedback_reason = _zoom_optics_feedback_state(
- st, now if optics_observed_now is None else optics_observed_now,
- )
+ feedback_ready, feedback_reason = _zoom_optics_feedback_state(st, observed)
if not feedback_ready:
st["zoom_followup_reason"] = str(feedback_reason)
return 0.0
@@ -6553,6 +6563,8 @@
if (now - last) < TRACK_END_RETURN_COOLDOWN_SEC:
return False
st["last_track_end_return_at"] = now
+ flush_zoom_blocks(config, cam_idx, st, now, final=True)
+ expire_calibration(config, cam_idx, st, now, final=True)
# СРАЗУ ставим "за нято goto", чтобы второй источник не успел добавить ещё один goto
settle = float(getattr(config, "GOTO_SETTLE_SEC", 2.5))
@@ -8778,6 +8790,76 @@
react_margin = clipf(react_margin_base + react_margin_gain * vel, react_margin_base, react_margin_max)
near_react_edge = min_margin < react_margin
+ predictive = None
+ predictive_frame = None
+ predictive_decision = None
+ if cfg_ptz.get("predictive_zoom") is not None:
+ with _zoom_command_lock(cam_idx):
+ predictive = controller_for_track(st, cfg_ptz)
+ if predictive is not None:
+ decision_wall = time.time()
+ expire_calibration(config, cam_idx, st, decision_wall)
+ sample_is_current = bool(
+ visual_sample is not None
+ and visual_control.current(
+ cam_idx, visual_sample, decision_wall,
+ max_age=predictive.cfg.frame_age_s,
+ )
+ )
+ predictive_frame = ZoomFrame(
+ at=now, seq=int(source_seq or 0),
+ offset=(measured_dx, measured_dy),
+ bbox_frac=(w_frac, h_frac), bbox_px=(x2 - x1, y2 - y1),
+ angles=(los_pan_angle_deg, los_tilt_angle_deg),
+ rates=(los_pan_rate_deg_s, los_tilt_rate_deg_s),
+ aspect=h / w,
+ tracker_score=(
+ float(st.get("visual_tracker_score", 0.0) or 0.0)
+ if current_track_source == "visual" else None
+ ),
+ detector_at=(last_visual_zoom_validation if normal_zoom_quality_ok
+ and last_visual_zoom_validation == last_visual_control_validation else 0.0),
+ detector_conf=float(st.get("visual_tracker_last_detector_conf", 0.0) or 0.0),
+ geometry_ok=bool(
+ sample_is_current and not st.get("visual_tracker_mismatch_frames")
+ ),
+ rearm_ready=_zoom_revalidation_ready(st),
+ los_valid=bool(
+ st.get("aim_los_rate_valid")
+ or predictive.request is not None
+ or predictive.repeat_after_stop(st, decision_wall)
+ or (st.get("zoom_step_pending") and predictive.history)
+ or hfov_deg < predictive.cfg.tele_steering_start_fov
+ ),
+ )
+ skip_wait = predictive.repeat_after_stop(st, decision_wall)
+ same_pending = bool(
+ st.get("zoom_step_pending")
+ and st.get("predictive_zoom_request") == st.get("zoom_step_pending_id")
+ and not st.get("zoom_step_cancel_requested")
+ and not st.get("zoom_step_discard_on_finalize")
+ )
+ predictive_decision = predictive.decide(
+ predictive_frame, decision_wall,
+ first=pulse_count == 0 and predictive.first_ack_at is None,
+ cooldown=not skip_wait and decision_wall < max(
+ float(st.get("zoom_step_cooldown_until", 0.0) or 0.0),
+ float(st.get("zoom_recenter_until", 0.0) or 0.0),
+ ),
+ transport_clear=bool(
+ same_pending or skip_wait or (pulse_count == 0
+ and not st.get("zoom_feedback_required_after")
+ and not st.get("zoom_step_feedback_pending"))
+ or _zoom_optics_feedback_state(st, decision_wall)[0]
+ ) and not (
+ st.get("zoom_stop_obligation_active")
+ or st.get("lens_move_stop_required")
+ or st.get("zoom_step_cancel_requested")
+ or st.get("zoom_no_effect_blocked")
+ or (st.get("zoom_step_pending") and not same_pending)
+ ),
+ )
+
zoom_quality_ok = bool(
normal_zoom_quality_ok
or probe_allowed
@@ -8819,6 +8901,21 @@
pan_rate_deg_s=float(los_pan_rate_deg_s),
tilt_rate_deg_s=float(los_tilt_rate_deg_s),
)
+ predictive_entry = bool(
+ predictive_decision and predictive_decision.window
+ and normal_zoom_quality_ok and not bounded_identification_request
+ and not st.get("zoom_probe_active", False)
+ and not _zoom_identify_matches_current_track(st)
+ and not st.get("zoom_stop_obligation_active")
+ and not st.get("zoom_step_cancel_requested")
+ )
+ predictive_continuing = bool(
+ predictive_decision and same_pending and not predictive_decision.stop
+ and (predictive_decision.window or predictive_decision.reason == "pulse_active")
+ and normal_zoom_quality_ok and not bounded_identification_request
+ )
+ if (predictive_entry and (skip_wait or same_pending)) or predictive_continuing:
+ followup_ready = True
angular_rejection = {} if pulse_active else None
zoom_angular_safe = followup_ready and _zoom_angular_motion_safe(
pan_error_deg=float(los_pan_angle_deg),
@@ -8832,6 +8929,9 @@
)
if approach_margin is not None and followup_ready:
zoom_angular_safe = True
+ if (predictive_entry or predictive_continuing) and followup_ready:
+ zoom_angular_safe = True
+ zoom_safe, zoom_safe_scale = True, 1.0
st["zoom_safe_pred_margin"] = float(zoom_pred_margin)
st["zoom_safe_center_limit"] = float(zoom_center_max)
st["zoom_quality_ok"] = bool(zoom_quality_ok)
@@ -8952,6 +9052,7 @@
or bounded_identification_request
)
zoom_rearm_ready = _zoom_revalidation_ready(st)
+ stable_ok = stable_ok or predictive_entry or predictive_continuing
can_zoom_in = (
zoom_safe
and zoom_angular_safe
@@ -9099,6 +9200,14 @@
zoom_zero_reason = "deadband"
zoom_cmd = 0.0
+ predictive_drive = bool(
+ (predictive_entry or predictive_continuing) and can_zoom_in and raw_zoom_needed
+ and prev_z >= 0.0 and not want_out
+ and not normal_size_hold and not edge_recovery_active
+ and float(getattr(config, "ZOOM_STEP_MAX_IN_CMD", 0.12)) >= 0.10
+ )
+ if predictive_drive:
+ zoom_cmd = 0.10
zoom_after_size_minimum = zoom_cmd
cmd_mag_est = max(
abs(float(pan_speed) + float(pan_rate_ff)),
@@ -9151,7 +9260,7 @@
center_err=float(center_err),
moving_out=bool(moving_out),
recent_zoom=bool(recent_zoom_steering),
- approach_margin=approach_margin,
+ approach_margin=(predictive_decision.margin if predictive_drive else approach_margin),
)
if before_recenter > 0.0 and zoom_cmd <= 0.0:
zoom_zero_reason = "recenter"
@@ -9159,21 +9268,27 @@
out_edge_effective
or float(min_margin) < float(getattr(config, "Z_SAFETY_EDGE", 0.05))
)
- zoom_cmd, routine_zoom_out_blocked = _gate_routine_zoom_out_hold(
+ predictive_step_back = bool(
+ predictive_decision and predictive_decision.step_back
+ and not zoom_out_emergency and not st.get("zoom_step_pending")
+ and not st.get("lens_move_put_inflight") and not st.get("zoom_stop_obligation_active")
+ and float(st.get("last_ptz_physical_cmd", (0., 0., 0.))[2]) <= 0
+ )
+ if predictive_step_back:
+ zoom_cmd = -predictive.cfg.step_back_cmd
+ routine_zoom_out_blocked = False
+ else:
+ zoom_cmd, routine_zoom_out_blocked = _gate_routine_zoom_out_hold(
+ st, now, zoom_cmd, emergency=zoom_out_emergency,
+ )
+ zoom_cmd = _gate_zoom_out_pulse(
st,
- now,
+ time.time() if predictive_step_back else now,
zoom_cmd,
emergency=zoom_out_emergency,
)
- zoom_cmd = _gate_zoom_out_pulse(
- st,
- now,
- zoom_cmd,
- emergency=zoom_out_emergency,
- )
- if float(zoom_cmd) < 0.0 and float(prev_z) >= 0.0 and not bool(
- st.get("zoom_rearm_required", False)
- ):
+ if (not predictive_step_back and float(zoom_cmd) < 0.0 and float(prev_z) >= 0.0
+ and not st.get("zoom_rearm_required", False)):
_arm_zoom_revalidation(st, now, "zoom_out", cam_idx=cam_idx)
pre_ramp_zoom_cmd = float(zoom_cmd)
if zoom_cmd > 0.0:
@@ -9272,6 +9387,25 @@
proposed_zoom_cmd = max(zoom_cmd, min(pre_ramp_zoom_cmd, pulse_cap, .12))
if _zoom_native_response_available(st, _zoom_speed_to_int(proposed_zoom_cmd), hfov_deg, shared_wide_hfov):
zoom_cmd = proposed_zoom_cmd
+ # A separately checked predictive window supplies the normal native-10
+ # shape. Preserve the original ticket and timing on subsequent frames.
+ predictive_active = bool(
+ predictive_continuing and predictive_drive and can_zoom_in and zoom_cmd > 0.0
+ and pulse_family == "normal" and st.get("zoom_step_pending")
+ and predictive.owns(st)
+ and st.get("zoom_step_pending_id") == decision_request
+ and st.get("predictive_zoom_request") == decision_request
+ and 0 <= zoom_gate_now - now <= predictive.cfg.frame_age_s
+ )
+ predictive_start = bool(
+ predictive_entry and predictive_drive and pulse_family == "normal"
+ and zoom_cmd > 0.0 and not st.get("zoom_step_pending") and predictive.owns(st)
+ and not st.get("zoom_stop_obligation_active") and not st.get("lens_move_stop_required")
+ and 0 <= zoom_gate_now - now <= predictive.cfg.frame_age_s
+ and 0 <= zoom_gate_now - predictive_frame.detector_at <= predictive.cfg.detector_age_s
+ and predictive.optics.fresh(zoom_gate_now)
+ and (not skip_wait or predictive.repeat_after_stop(st, zoom_gate_now))
+ )
before_shape = zoom_cmd
zoom_cmd, useful_reason = _shape_useful_zoom_pulse(
zoom_cmd,
@@ -9299,6 +9433,23 @@
requested_native=timing_native,
rejection=response_rejection,
)
+ if predictive_start or (predictive_active and not near_edge and not edge_recovery_active
+ and zoom_rearm_ready and not normal_size_hold and not want_out):
+ zoom_cmd = 0.10
+ useful_reason = "useful"
+ st["zoom_useful_pulse_reason"] = useful_reason
+ response_timing = predictive_decision.window if predictive_start else (
+ float(st["zoom_step_pending_pulse_sec"]),
+ float(st["zoom_step_pending_hard_sec"]),
+ )
+ if predictive_decision and (
+ predictive_decision.stop or predictive_decision.reason in ("min_hfov_limit", "tele_calibration_wait")
+ or (predictive_decision.reason == "edge_margin_low"
+ and hfov_deg <= predictive.cfg.tele_pulse_fov)
+ or (predictive_decision.reason == "size_reached" and pulse_family == "normal")
+ ):
+ zoom_cmd = min(zoom_cmd, 0.0)
+ zoom_zero_reason = predictive_decision.reason
if useful_reason == "useful" and response_timing == (0.0, 0.0):
zoom_cmd = 0.0
st["zoom_useful_pulse_reason"] = "wait_response_framing"
@@ -9321,7 +9472,10 @@
optics_observed_now=zoom_gate_now,
stop_trace=gate_stop,
continuation_trace=continuation_trace,
- )
+ predictive=predictive if predictive_start else None,
+ )
+ if predictive_start and zoom_cmd > 0.0 and st["zoom_step_request_id"] > request_id_before_gate:
+ st["predictive_zoom_request"] = st["zoom_step_pending_id"]
if gate_stop:
zoom_zero_reason = gate_stop[-1]
decision_generation = st.get("ptz_generation")
@@ -9380,6 +9534,12 @@
adj_pan, adj_tilt = _shape_tracking_cmd(st, now, adj_pan, adj_tilt, center_err)
pan_feedback_cmd, tilt_feedback_cmd = float(adj_pan), float(adj_tilt)
+ if predictive_active and predictive.request is not None and zoom_cmd > 0.0:
+ pan_optical, tilt_optical = predictive_decision.ff_deg_s
+ pan_ref = max(1.0, float(cfg_ptz.get("ptz_pan_max_speed_deg_s", getattr(config, "AIM_PAN_SPEED_DEG_S", 160.0))))
+ tilt_ref = max(1.0, float(cfg_ptz.get("ptz_tilt_max_speed_deg_s", getattr(config, "AIM_TILT_SPEED_DEG_S", 120.0))))
+ pan_rate_ff += pan_optical / pan_ref
+ tilt_rate_ff += tilt_optical / tilt_ref
adj_pan, adj_tilt = _merge_gimbal_rate_feedforward(
st,
now,
@@ -9398,6 +9558,22 @@
precenter_optics_at = st.get("zoom_status_at")
precenter_measured_hfov = st.get("hfov_deg")
status_observed_now = time.time()
+ tele_rate_history = tuple(st.get("status_rate_history", ())) if predictive else ()
+ if predictive and predictive_frame and predictive.optics.actual is not None:
+ st["tele_steering_active"] = False
+ aligned = next((x for x in reversed(tele_rate_history)
+ if 0 <= now - x[0] <= predictive.cfg.frame_age_s), None)
+ if aligned and status_observed_now - aligned[0] <= predictive.cfg.status_age_s:
+ steering = predictive.tele_aim(
+ predictive_frame, status_observed_now,
+ (float(aligned[1]) * _PAN_SIGN, float(aligned[2]) * _TILT_SIGN),
+ predictive_decision.ff_deg_s if predictive_decision else (0., 0.),
+ )
+ if steering is not None:
+ (pan_tele, tilt_tele), blend = steering
+ adj_pan += blend * (pan_tele - adj_pan)
+ adj_tilt += blend * (tilt_tele - adj_tilt)
+ st["tele_steering_active"] = True
guard_status_fresh = bool(
guard_status_at > 0.0
and 0.0 <= (status_observed_now - guard_status_at)
@@ -9844,12 +10020,53 @@
("brake", final_guard_active),
) if blocked)
zoom_decision = (source_seq, decision_request, zoom_zero_reason, "+".join(blockers) or "-")
+ if predictive_decision is not None:
+ with _zoom_command_lock(cam_idx):
+ telemetry_tick(
+ config, cam_idx, predictive, predictive_frame, predictive_decision,
+ zoom_cmd, zoom_zero_reason, time.time(),
+ )
+ if predictive_decision.stop and predictive.request is not None:
+ stop_predictive_zoom_async(cam_idx, predictive, predictive_decision.reason)
+ if getattr(config, "PREDICTIVE_ZOOM_TELEMETRY_DIR", "logs/ptz_zoom"):
+ blocked = {}
+ if zoom_cmd <= 0.0 and raw_zoom_needed:
+ if not stable_ok:
+ blocked["centering"] = {"error": center_err, "limit": lock_gate, "stable_frames": st.get("stable_frames")}
+ if not zoom_safe:
+ blocked["bbox_check"] = {"margin": zoom_pred_margin, "limit": zoom_center_max,
+ "bbox_px": [x2-x1, y2-y1]}
+ if not zoom_angular_safe and followup_ready:
+ blocked["angle_tol"] = {"pan_deg": los_pan_angle_deg, "tilt_deg": los_tilt_angle_deg,
+ "limit_deg": angular_max}
+ if near_edge or edge_recovery_active or (
+ predictive_decision and predictive_decision.reason in ("edge_margin_low", "edge_acceleration")):
+ blocked["edge_margin"] = {"measured": min_margin,
+ "predicted": predictive_decision.margin if predictive_decision else None,
+ "required": predictive_decision.edge_margin_required if predictive_decision else None}
+ if predictive_decision and predictive_decision.reason == "min_hfov_limit":
+ blocked["min_hfov_limit"] = {"hfov": hfov_deg, "minimum": predictive.cfg.min_allowed_hfov_deg}
+ if st.get("lens_move_put_inflight"):
+ blocked["put_inflight"] = {"kind": st.get("lens_move_put_kind"), "request": decision_request}
+ with _zoom_command_lock(cam_idx):
+ record_zoom_blocks(config, cam_idx, st, time.time(), blocked)
dispatch_kwargs = {"force": force_track_ptz}
if zoom_decision is not None:
dispatch_kwargs["zoom_decision"] = zoom_decision
- _dispatch_owned_zoom_tracking(
- cam_idx, _PAN_SIGN * adj_pan, _TILT_SIGN * adj_tilt, zoom_cmd, **dispatch_kwargs
- )
+ if predictive_step_back and zoom_cmd < 0.0:
+ with _zoom_command_lock(cam_idx):
+ if not visual_control.current(cam_idx, visual_sample, time.time(), max_age=.25):
+ return
+ if not st.get("zoom_rearm_required"):
+ _arm_zoom_revalidation_locked(st, time.time(), "tele_step_back")
+ dispatch_kwargs["force"] = True
+ _dispatch_owned_zoom_tracking(
+ cam_idx, _PAN_SIGN * adj_pan, _TILT_SIGN * adj_tilt, zoom_cmd, **dispatch_kwargs
+ )
+ else:
+ _dispatch_owned_zoom_tracking(
+ cam_idx, _PAN_SIGN * adj_pan, _TILT_SIGN * adj_tilt, zoom_cmd, **dispatch_kwargs
+ )
if visual_control.enabled():
dispatch_at = time.monotonic()
samples = st.setdefault('control_dispatch_samples', [])
--- a/ptz_io.py
+++ b/ptz_io.py
@@ -14,6 +14,9 @@
from requests.adapters import HTTPAdapter
from . import config, state
+from .zoom_controller import (
+ record_zoom_blocks, transport_accepted, transport_confirmed, transport_stopped, transport_zoom_block_reason,
+)
from .utils import clipf, hfov_ptz_from_abs_zoom, hfov_ptz_from_zoom_ratio, quantf
from .geom import sector_contains, ang_diff_signed, normalize360
@@ -550,6 +553,7 @@
cmd: PTZCommand,
now: float,
*, native_cmd: int = 0,
+ put_rtt_s: float | None = None,
) -> bool:
"""Anchor a pending +zoom window to the successful camera HTTP PUT."""
if not _pending_zoom_request_matches(st, cmd):
@@ -582,6 +586,10 @@
st["zoom_last_motion_at"] = float(now)
st["zoom_followup_reason"] = "physical_pulse"
st["zoom_step_last_delivery_result"] = "physical_started"
+ transport_accepted(
+ config, cam_idx, st, request_id, native_cmd, deadline_origin, now,
+ deadline_origin + hard_sec, put_rtt_s,
+ )
logger.info(
"[ZOOM DELIVERY] cam=%s request=%s kind=%s physical start seq=%s pulse=%.3fs hard=%.3fs",
cam_idx,
@@ -744,6 +752,8 @@
float(st.get("zoom_recenter_until", 0.0) or 0.0),
float(now) + float(getattr(config, "ZOOM_STEP_RECENTER_SEC", 0.14)),
)
+ if reason == "status_poll":
+ transport_confirmed(config, st, request_id, now)
logger.info(
"[ZOOM DELIVERY] cam=%s request=%s optics confirmed source=%s zstep=%s",
cam_idx,
@@ -800,6 +810,8 @@
reason: str,
stop_axes: Optional[tuple[int, int, int]] = None,
stop_command: Optional[MoveTuple] = None,
+ stop_issued_at: float | None = None,
+ stop_rtt_s: float | None = None,
) -> bool:
"""Finalize transport delivery; charge a pulse only with optical evidence."""
if not bool(st.get("zoom_step_pending", False)):
@@ -922,6 +934,13 @@
+ max(0.0, float(getattr(config, "ZOOM_STEP_RETRY_COOLDOWN_SEC", 0.12))),
)
+ transport_stopped(
+ config, cam_idx, st, request_id, now, reason=reason,
+ confirmed=confirmed and not discard,
+ clean=bool(not discard and kind == "normal" and delivered + 1e-6 >= full_window
+ and stop_axes is not None and stop_axes[2] == 0),
+ duration_s=delivered, stop_issued_at=stop_issued_at, stop_rtt_s=stop_rtt_s,
+ )
st["zoom_step_last_delivered_sec"] = float(delivered)
st["zoom_step_pending"] = False
st["zoom_step_pending_id"] = 0
@@ -1257,6 +1276,7 @@
float(getattr(config, "PTZ_LENS_STOP_DIRECT_TIMEOUT_SEC", 0.75)),
),
)
+ stop_issued_at, stop_issued_mono = time.time(), time.monotonic()
ok, code, body = _ptz_put_priority_stop(
url,
data=xml,
@@ -1266,6 +1286,7 @@
verify=verify,
)
now = time.time()
+ stop_rtt_s = time.monotonic() - stop_issued_mono
st["zoom_stop_obligation_attempts"] = int(
st.get("zoom_stop_obligation_attempts", 0) or 0
) + 1
@@ -1328,6 +1349,7 @@
now,
reason=f"priority_stop:{reason}",
stop_axes=(pan_i, tilt_i, 0),
+ stop_issued_at=stop_issued_at, stop_rtt_s=stop_rtt_s,
)
_cancel_zoom_step_watchdog(st)
if ordering_inflight:
@@ -2121,6 +2143,35 @@
return None
+def stop_predictive_zoom_async(cam_idx, controller, reason):
+ """Order an early lens STOP independently of the ordinary MOVE queue."""
+ with _zoom_command_lock(cam_idx):
+ st = state.ptz_states.get(cam_idx, {})
+ request = controller.request
+ if (not controller.owns(st) or request is None
+ or st.get("zoom_step_physical_request_id") != request
+ or st.get("predictive_zoom_early_stop") == request):
+ return
+ st["predictive_zoom_early_stop"] = request
+ st["zoom_step_cancel_requested"] = True
+
+ def stop_if_current():
+ with _zoom_command_lock(cam_idx):
+ current = state.ptz_states.get(cam_idx, {})
+ if (controller.owns(current)
+ and current.get("zoom_step_physical_request_id") == request):
+ _deliver_priority_lens_stop_locked(
+ cam_idx, current, reason=f"predictive:{reason}",
+ guard_inflight_after_put=_generic_put_has_lens_motion(current),
+ )
+
+ try:
+ threading.Thread(target=stop_if_current, name="ptz-predictive-stop", daemon=True).start()
+ except RuntimeError:
+ # The scheduled watchdog remains the independent hard STOP.
+ logger.exception("Unable to start early lens STOP cam=%s", cam_idx)
+
+
def stop_ptz(cam_idx: int, *, source: str = "stop", generation: Optional[int] = None) -> None:
"""
Жёсткий стоп PTZ.
@@ -3308,6 +3359,23 @@
reserve_wall = time.time()
reserve_mono = time.monotonic()
+ camera_profile = config.CAMERA_CONFIG.get(cam_idx, {})
+ floor_block = (transport_zoom_block_reason(
+ st, camera_profile, reserve_wall, _zoom_step_timing(st)[1],
+ ) if int(zoom_i) > 0 else None)
+ if floor_block:
+ if pending_matches and not st.get("zoom_step_physical_started_at"):
+ _clear_pending_zoom_delivery(st, reserve_wall, reason=floor_block, force=True)
+ pending_matches = False
+ if st.get("mode") == "TRACK":
+ record_zoom_blocks(config, cam_idx, st, reserve_wall, {
+ floor_block: {"hfov": st.get("hfov_deg"), "stage": "pre_put",
+ "request": _cmd_move_seq(cmd)},
+ })
+ zoom_i = 0
+ if bool(getattr(config, "PTZ_ZOOM_STOP_FORCE_AXES_ZERO", True)):
+ pan_i = tilt_i = 0
+ xml = f"<PTZData><pan>{pan_i}</pan><tilt>{tilt_i}</tilt><zoom>0</zoom></PTZData>"
if int(zoom_i) > 0 and pending_matches and float(
st.get("zoom_step_physical_started_at", 0.0) or 0.0
) <= 0.0:
@@ -3481,6 +3549,7 @@
sent_nonzero_move = bool(
int(pan_i) != 0 or int(tilt_i) != 0 or int(zoom_i) != 0
)
+ put_call_at, put_call_mono = time.time(), time.monotonic()
ok, code, body = _ptz_put(
url,
data=xml,
@@ -3489,6 +3558,7 @@
timeout=timeout,
verify=verify,
)
+ put_rtt_s = time.monotonic() - put_call_mono
if ok:
break
if attempt < retry_count:
@@ -3560,7 +3630,7 @@
st,
cmd,
physical_now,
- native_cmd=int(zoom_i),
+ native_cmd=int(zoom_i), put_rtt_s=put_rtt_s,
)
elif int(zoom_i) <= 0:
if float(previous_physical_zoom) > 0.0:
@@ -3571,6 +3641,8 @@
reason="physical_stop",
stop_axes=(pan_i, tilt_i, zoom_i),
stop_command=cmd,
+ stop_issued_at=put_call_at if int(zoom_i) == 0 else None,
+ stop_rtt_s=put_rtt_s,
)
elif (
int(zoom_i) == 0
--- a/status.py
+++ b/status.py
@@ -14,6 +14,9 @@
# ---------------- Публичные утилиты статуса ----------------
+from .zoom_controller import observe_calibration
+
+
def get_cached_angles(cam_id: int) -> Tuple[Optional[float], Optional[float], Optional[float]]:
"""
Вернёт (pan_deg, tilt_deg, t_epoch) из кэша, если есть (иначе None).
@@ -170,6 +173,14 @@
if isinstance(hfov_deg, (int, float)) and float(hfov_deg) > 0.0:
st["hfov_deg"] = float(hfov_deg)
st["zoom_status_at"] = zoom_observed_at
+ if config.CAMERA_CONFIG.get(int(cam_id), {}).get("predictive_zoom") is not None:
+ previous = st.get("predictive_zoom_hfov", (0.0, 0.0))
+ if zoom_observed_at > previous[0]:
+ st["predictive_zoom_hfov"] = (zoom_observed_at, float(hfov_deg))
+ controller = st.get("predictive_zoom_controller")
+ if controller is not None and controller.owns(st):
+ controller.optics.observe(zoom_observed_at, float(hfov_deg), float(now))
+ observe_calibration(config, cam_id, st, zoom_observed_at, float(hfov_deg), float(now))
if isinstance(zoom_raw, (int, float)):
st["zoom_position_raw"] = float(zoom_raw)
st["zoom_position_tag"] = str(zoom_tag or "")

@ -0,0 +1,120 @@
import json
from pathlib import Path
from tempfile import TemporaryDirectory
import unittest
from types import SimpleNamespace
from unittest.mock import patch
import zoom_controller as z
from fit_tele_profile import summarize
from test_zoom_controller import frame, tick
class BroadTeleTests(unittest.TestCase):
def make(self, fov, **settings):
c = z.ZoomController(z.ZoomConfig(.5, .9, **settings), (3, 100.))
c.optics.observe(99.99, fov, 100.)
return c
def test_broad_converging_entry_beyond_static_band(self):
ctrl = self.make(59)
for k, x in enumerate((.173, .167, .161)):
decision = tick(ctrl, frame(100 + .08*k, k+1,
offset=(x,0), detector_at=99.99))
self.assertEqual(decision.reason, "fast_start")
self.assertEqual(decision.gate, "initial")
self.assertGreater(decision.margin, ctrl.cfg.edge_margin)
ctrl = self.make(59)
for k in range(3):
decision = tick(ctrl, frame(100+.08*k,k+1,offset=(.161,0),detector_at=99.99))
self.assertEqual(decision.reason, "not_centered")
def test_margin_curve_and_floor_keep_legacy_wire_from_bypassing(self):
ctrl = self.make(10.6)
self.assertAlmostEqual(ctrl.cfg.margin_for(59), .16)
self.assertAlmostEqual(ctrl.cfg.margin_for(12), .32)
self.assertGreater(ctrl.cfg.margin_for(15), ctrl.cfg.margin_for(20))
decision = tick(ctrl, frame(100.08, 1, offset=(.2,0), detector_at=99.99))
self.assertEqual(decision.reason, "min_hfov_limit")
self.assertIsNone(decision.window)
self.assertTrue(decision.step_back)
profile = {"predictive_zoom": {"nominal_gain": .5, "upper_gain": .9}}
self.assertEqual(z.transport_zoom_block_reason({"predictive_zoom_hfov":(99.9,10.6)},
profile,100.,.12),"min_hfov_limit")
self.assertIsNone(z.transport_zoom_block_reason({"predictive_zoom_hfov":(99.9,59.)},
profile,100.,.40))
self.assertEqual(z.transport_zoom_block_reason({"predictive_zoom_hfov":(98.9,59.)},
profile,100.,.40),"min_hfov_limit")
self.assertIsNone(z.transport_zoom_block_reason({}, {}, 100., .40))
def test_latency_horizon_moves_prediction_in_residual_direction(self):
def command(horizon):
ctrl = self.make(14, latency_horizon_ms=horizon)
f = frame(100.20,2,offset=(.025, -.03),detector_at=99.99)
ctrl.latest_pose = (2,(.34,-.20),(.5,-.2),True)
result=ctrl.tele_aim(f,100.25,(0.,0.))
self.assertIsNotNone(result)
return result[0]
slow,fast = command(120),command(245)
self.assertGreater(fast[0],slow[0])
self.assertLess(fast[1],slow[1])
def test_measured_pulse_reports_settled_delta_rtt_and_tail(self):
ctrl = self.make(14.5)
st=dict(predictive_zoom_controller=ctrl,mode="TRACK",tracking_active=True,
ptz_generation=3,track_started_at=100.,
predictive_zoom_request=1,zoom_step_start_status_at=99.99,
zoom_step_start_hfov_deg=14.5,last_ptz_physical_cmd=(0.,0.,0.))
with patch.object(z,"_episode_telemetry") as submit:
cfg=SimpleNamespace()
z.transport_accepted(cfg,8,st,1,10,100.03,100.08,100.21,.05)
ctrl.optics.observe(100.15,13.9,100.15)
z.transport_stopped(cfg,8,st,1,100.21,reason="priority_stop:watchdog",
confirmed=True,clean=True,duration_s=.18,stop_issued_at=100.16,
stop_rtt_s=.05)
self.assertTrue(ctrl.calibration_hold(100.22))
for at,fov in ((100.25,13.6),(100.48,13.4),(100.63,13.4)):
z.observe_calibration(cfg,8,st,at,fov,at)
self.assertFalse(ctrl.calibration_hold(100.64))
row=submit.call_args.kwargs
self.assertEqual(row["outcome"],"settled")
self.assertEqual(row["put_rtt_ms"],50.)
self.assertEqual(row["stop_rtt_ms"],50.)
self.assertAlmostEqual(row["delta_hfov_deg"],-1.1)
self.assertAlmostEqual(row["post_stop_tail_deg"],.2)
self.assertAlmostEqual(row["stop_bracket_narrowing_deg"],.5)
self.assertGreater(row["effective_tele_log_rate_s"],0.)
def test_offline_fit_excludes_censored_rows_and_duplicate_requests(self):
base=dict(event="native10_pulse_calibration", cam=8, generation=3,
outcome="settled", effective_tele_log_rate_s=.4, HFOV_before=14.,
HFOV_after=13., put_rtt_ms=50., stop_rtt_ms=55., put_at=101.,
stop_status_at=101.11, stop_issued_at=101.16, HFOV_stop_sample=13.2)
records = [dict(base, track_start_utc=100.+i//2, request=i+1) for i in range(3)]
records += [records[0], dict(base, track_start_utc=102., request=5, outcome="next_pulse")]
with TemporaryDirectory() as tmp:
path=Path(tmp)/"episode.jsonl"
path.write_text("".join(json.dumps(x)+"\n" for x in records),encoding="utf-8")
result=summarize([path])
self.assertFalse(result["production_enable"])
camera=result["cameras"]["8"]
self.assertEqual(camera["qualified"],3)
self.assertEqual(camera["candidate_for_review"]["qualified_stop_brackets"],3)
def test_episode_counts_and_snapshot_values(self):
cfg=SimpleNamespace()
st=dict(ptz_generation=2,track_started_at=100.)
with patch.object(z,"_episode_telemetry") as emit:
z.record_zoom_blocks(cfg,8,st,100.1,{"angle_tol":{"pan_deg":4.}})
z.record_zoom_blocks(cfg,8,st,100.2,{"angle_tol":{"pan_deg":4.2},"put_inflight":{"request":2}})
self.assertEqual(emit.call_count,1)
z.flush_zoom_blocks(cfg,8,st,100.3,final=True)
last=emit.call_args.kwargs
self.assertEqual(last["zoom_block_reason"],{"angle_tol":2,"put_inflight":1})
self.assertEqual(last["last_values"]["angle_tol"]["pan_deg"],4.2)
self.assertTrue(last["final"])
self.assertNotIn("episode_zoom_blocks",st)
if __name__=="__main__":
unittest.main()

@ -0,0 +1,172 @@
import math
from pathlib import Path
import tempfile
import unittest
from zoom_controller import EpisodeTelemetryLogger, OpticalStateEstimator, ZoomConfig, ZoomController, ZoomFrame
def frame(at, seq, *, offset=(0.13, -0.03), pixels=(20.0, 16.0),
detector_at=None, score=0.8, geometry=True):
return ZoomFrame(
at=at, seq=seq, offset=offset, bbox_frac=(pixels[0] / 1280, pixels[1] / 720),
bbox_px=pixels, angles=(0.0, 0.0), rates=(0.0, 0.0), aspect=720 / 1280,
tracker_score=score, detector_at=at if detector_at is None else detector_at,
detector_conf=0.71, geometry_ok=geometry, los_valid=True,
)
def tick(controller, sample, now=None, **kw):
flags = {"first": controller.first_ack_at is None, "cooldown": False, "transport_clear": True}
flags.update(kw)
return controller.decide(sample, sample.at if now is None else now, **flags)
class PredictiveZoomTests(unittest.TestCase):
def setUp(self):
self.cfg = ZoomConfig(nominal_gain=0.65, upper_gain=1.0)
self.c = ZoomController(self.cfg, (4, 100.0))
self.c.optics.observe(99.99, 59.0, 100.0)
def test_short_3_6_second_flight_with_delayed_yolo_and_status(self):
c = self.c
focal = math.tan(math.radians(59 / 2))
duration = 3.6
active = None
pulses, stops = [], []
actual_status = 99.99
between_without_poll = 0
last_stop = None
visible = 0
for k in range(181):
t = k * 0.02
now = 100.0 + t
if active is not None:
focal *= math.exp(-self.cfg.log_rate * 0.02)
actual = math.degrees(2 * math.atan(focal))
# One status response every 250 ms, no forced request after STOP.
if k % 13 == 8:
c.optics.observe(now, actual, now)
actual_status = now
if active and now >= active[1]:
pulse, _, started, status_at_start = active
confirmed = actual_status > status_at_start
c.stopped(pulse, now, confirmed=confirmed, clean=True)
stops.append(now)
active = None
last_stop = now
if k % 4 != 0:
continue
# Same aircraft, steady closing LOS and native-10 synthetic plant.
x = 0.129 - min(0.069, t * 0.12)
optical_scale = math.tan(math.radians(59 / 2)) / focal
px = (20 * optical_scale, 16 * optical_scale)
self.assertLess(abs(x) + px[0] / 2560, 0.5)
visible += 1
detector = 100.0 + math.floor((t + 1e-9) / 0.52) * 0.52
can_repeat = last_stop is None or c.can_reuse_feedback(now, last_stop) or actual_status > last_stop
decision = tick(c, frame(now, k + 1, offset=(x, -0.025), pixels=px,
detector_at=detector),
transport_clear=active is None and can_repeat)
if decision.window:
if last_stop is not None and actual_status <= last_stop:
between_without_poll += 1
self.assertIsNone(active)
pulse = len(pulses) + 1
nominal, hard = decision.window
c.accepted(pulse, now, now, now + hard)
active = pulse, now + nominal, now, actual_status
pulses.append(t)
else:
if decision.stop:
self.assertIn(decision.reason, ("size_reached", "edge_margin_low", "min_hfov_limit"))
c.stopped(active[0], now, clean=False, confirmed=False)
last_stop = now
stops.append(now)
active = None
self.assertEqual(visible, 46)
self.assertLess(pulses[0], 0.25)
self.assertGreaterEqual(len(pulses), 4)
self.assertGreaterEqual(between_without_poll, 2)
self.assertGreaterEqual(len(stops), 3)
self.assertLess(actual, 42.0)
def test_wide_entry_without_next_detector_and_narrow_entry_is_stricter(self):
for k in range(3):
self.assertEqual(tick(self.c, frame(100 + .08 * k, k + 1, detector_at=99.96)).reason,
"fast_start" if k == 2 else "low_tracker_score")
other = ZoomController(self.cfg, (4, 100))
other.optics.observe(99.99, 28.0, 100.0)
for k in range(3):
d = tick(other, frame(100 + .08 * k, k + 1, detector_at=99.96))
self.assertEqual(d.reason, "not_centered")
def test_reject_outward_low_score_and_expired_detector(self):
for k in range(3):
d = tick(self.c, frame(100 + .08 * k, k + 1, offset=(.075 + .003 * k, -.02)))
self.assertEqual(d.reason, "not_centered")
self.assertEqual(tick(self.c, frame(100.20, 4, score=.2)).reason, "low_tracker_score")
self.assertEqual(tick(self.c, frame(100.28, 5, detector_at=99.0)).reason, "waiting_yolo")
def test_positive_ff_and_edge_stop_preserve_request_deadline(self):
self.c.accepted(4, 100.0, 100.01, 100.4)
active = self.c.optics.active
d = tick(self.c, frame(100.05, 1, offset=(.08, -.05)))
self.assertGreater(d.ff_deg_s[0], 0)
self.assertLess(d.ff_deg_s[1], 0)
d = tick(self.c, frame(100.12, 2, offset=(.32, -.05)))
self.assertTrue(d.stop)
self.assertEqual(d.reason, "edge_margin_low")
self.assertEqual(d.ff_deg_s, (0.0, 0.0))
self.assertEqual(self.c.optics.active, active)
def test_edge_acceleration_can_stop_before_margin_crosses(self):
c = ZoomController(ZoomConfig(.28, .45, edge_accel=.1, edge_watch_margin=.35), (4, 100))
c.optics.observe(99.99, 59, 100)
c.accepted(2, 100, 100.01, 100.4)
for seq, off in enumerate((.145, .145, .153), 1):
decision = tick(c, frame(100 + seq * .06, seq, offset=(off, -.02)))
self.assertGreater(decision.margin, c.cfg.edge_margin)
self.assertEqual(decision.reason, "edge_acceleration")
self.assertTrue(decision.stop)
def test_causal_status_and_failed_or_ambiguous_stop_cannot_rearm(self):
c = self.c
c.accepted(4, 100.0, 100.01, 100.4)
before = c.optics.estimate(100.1)
c.optics.observe(100.18, 55, 100.2)
c.optics.observe(100.08, 57, 100.21)
self.assertEqual(c.optics.estimate(100.1), before)
self.assertEqual(c.optics.status_at, 100.18)
self.assertFalse(c.can_reuse_feedback(100.35, 100.34))
c.stopped(4, 100.34, confirmed=True, clean=False)
self.assertFalse(c.can_reuse_feedback(100.35, 100.34))
def test_fov_curves_and_watchdog_bounds(self):
self.assertEqual(self.cfg.window(59), (.34, .40))
self.assertEqual(self.cfg.window(10), (.12, .18))
self.assertGreater(self.cfg.window(21)[0], self.cfg.window(13)[0])
for invalid in (dict(wide_pulse_s=.5), dict(native=20), dict(frame_age_s=.26),
dict(upper_gain=.4), dict(nominal_gain=float("nan"))):
args = {"nominal_gain": .65, "upper_gain": 1.0}
args.update(invalid)
with self.assertRaises(ValueError):
ZoomConfig(**args)
def test_telemetry_writes_first_and_ticks_separately(self):
import json
with tempfile.TemporaryDirectory() as directory:
logger = EpisodeTelemetryLogger(directory)
logger.submit(8, (4, 100.0), "first_zoom", 100.2, t_to_first_zoom_ms=200)
logger.submit(8, (4, 100.0), "tick", 100.25, FOV_actual=59.0,
FOV_estimated=57.0, bbox_px=[20, 16], detector_conf=.71)
logger.queue.join()
path, = Path(directory).glob("*.jsonl")
first, second = map(json.loads, path.read_text().splitlines())
self.assertEqual(first["t_to_first_zoom_ms"], 200)
self.assertEqual(second["elapsed_ms"], 250)
self.assertEqual(second["FOV_estimated"], 57)
if __name__ == "__main__":
unittest.main()

@ -0,0 +1,172 @@
"""Integration cases for the PR #7 mock transport/control replay fixture."""
import math
from types import SimpleNamespace
from unittest.mock import patch
TRACE = []
def build_track_cases(fixture, pp, ptz_io, config, state, status):
class PredictiveTrack(fixture.Replay):
def setUp(self):
cameras = [8, *[cam for cam in config.PTZ_CAM_IDS if cam != 8]]
with patch.object(config, 'PTZ_CAM_IDS', cameras):
super().setUp()
def flight(self, enabled, center_x=720, *, record=False):
f, st = self.fixture, self.st
if enabled:
self.stack.enter_context(patch.dict(config.CAMERA_CONFIG[self.cam], {
"predictive_zoom": {"nominal_gain": .45, "upper_gain": .8},
}))
self.stack.enter_context(patch.object(config, "PTZ_ZOOM_STOP_FORCE_AXES_ZERO", False, create=True))
self.stack.enter_context(patch.object(config, "PREDICTIVE_ZOOM_TELEMETRY_DIR", None, create=True))
decisions = []
capture = pp.telemetry_tick
def remember(config, cam, controller, frame, decision, zoom, why, at):
decisions.append((round(at-100, 2), decision.reason, round(zoom, 3), why,
st.get("zoom_followup_reason"), st.get("zoom_step_last_delivery_result")))
estimated, narrowest = controller.optics.estimate(at)
if record:
TRACE.append({
"event": "tick", "cam": cam + 11, "elapsed_ms": round((at-100)*1000, 1),
"FOV_actual": controller.optics.actual, "FOV_estimated": estimated,
"FOV_min_estimated": narrowest, "bbox_px": frame.bbox_px,
"detector_conf": frame.detector_conf, "tracker_score": frame.tracker_score,
"reason": decision.reason,
})
capture(config, cam, controller, frame, decision, zoom, why, at)
self.stack.enter_context(patch.object(pp, "telemetry_tick", side_effect=remember))
box = (center_x - 13, 347, center_x + 13, 371)
st.update(track_started_at=99.95, last_bbox=box,
prev_cx=center_x / 1280, prev_cy=359 / 720, stable_frames=0)
fov, zoom = 59.0, 1.0
status._update_runtime_state(self.cam, None, None, 99.99, zoom_ratio=zoom, hfov_deg=fov)
delivered = []
last_status = 99.99
completed = []
early = []
for k in range(46):
f._advance(.08 if k else 0)
now = f.wall
if k % 6 == 0:
st.update(visual_tracker_last_detector_at=now - .015,
visual_tracker_last_zoom_detector_at=now - .015,
visual_tracker_last_detector_conf=.8)
if k % 3 == 1:
if st.get("zoom_step_physical_request_id"):
fov *= .97
zoom *= 1.03
status._update_runtime_state(self.cam, None, None, now - .012,
zoom_ratio=zoom, hfov_deg=fov)
last_status = now - .012
st.update(status_rate_at=now - .01, pan_rate_at=now - .01,
tilt_rate_at=now - .01, pan_rate_deg_s=.4, tilt_rate_deg_s=0.0)
timer = st.get("zoom_step_stop_timer")
if (timer and timer.is_alive()
and f.mono + 1e-9 >= st["zoom_step_stop_started_mono"] + timer.delay):
timer.fire()
request_before = st.get("zoom_step_physical_request_id")
self.seq += 1
scale = math.tan(math.radians(59 / 2)) / math.tan(math.radians(fov / 2))
half_w, half_h = round(13 * scale), round(12 * scale)
box = (center_x - half_w, 359 - half_h, center_x + half_w, 359 + half_h)
self.assertTrue(0 < box[0] < box[2] < 1280 and 0 < box[1] < box[3] < 720)
track = fixture.tracker.VisualTrackResult(True, box, .8, 0, .8, 30,
"synthetic captured", self.seq)
sample = fixture.control.VisualSample(fixture.control.owner(st), self.seq, now-.01, track)
pp.postprocess_control(self.cam, self.frame, SimpleNamespace(boxes=fixture.Boxes([])),
True, self.seq, visual_sample=sample, visual_only=True)
if not state.ptz_cmd_q.empty():
f._flush()
request = st.get("zoom_step_physical_request_id")
if request and request != request_before:
delivered.append((round(now-100, 2), request, last_status))
if st.get("predictive_zoom_request") == request and st["zoom_step_finished_at"] > last_status:
early.append(request)
if request_before and not request:
completed.append(request_before)
self.assertEqual(st["mode"], "TRACK")
return delivered, early, fov, decisions, completed
def test_track_runs_burst_without_post_stop_status(self):
delivered, early, fov, decisions, completed = self.flight(True, record=True)
self.assertTrue(delivered, decisions)
TRACE.insert(0, {"event": "first_zoom", "t_to_first_zoom_ms": delivered[0][0]*1000})
self.assertGreaterEqual(len(delivered), 3, (delivered, decisions))
self.assertLess(delivered[0][0], .5, decisions)
self.assertGreaterEqual(len(early), 1, (early, delivered, decisions))
print(f"3.6s TRACK: {len(delivered)} starts, first {delivered[0][0]:.2f}s, "
f"{len(early)} before a post-STOP poll, terminal simulated HFOV {fov:.1f} deg")
self.assertTrue(any(row[1] == "burst" for row in decisions), decisions)
self.assertGreaterEqual(self.st["zoom_in_pulse_count"], 2, (completed, decisions))
self.assertLess(fov, 59.0)
def test_track_same_flight_legacy_reference(self):
delivered, early, fov, decisions, completed = self.flight(False)
first = delivered[0][0] if delivered else None
print(f"3.6s legacy TRACK: {len(delivered)} starts, first {first}s, terminal simulated HFOV {fov:.1f} deg")
self.assertLess(len(delivered), 7)
self.assertFalse(early)
def test_track_starts_at_26_percent_of_half_frame(self):
delivered, _, _, decisions, _ = self.flight(True, 806)
self.assertTrue(delivered, decisions)
self.assertLess(delivered[0][0], .5)
self.assertTrue(any(reason == "fast_start" and zoom > 0
for _, reason, zoom, *_ in decisions), decisions)
def test_track_legacy_reference_at_26_percent_of_half_frame(self):
delivered, _, _, _, _ = self.flight(False, 806)
print(f"3.6s legacy TRACK at 26% half-frame: {len(delivered)} starts")
self.assertFalse(delivered)
def assert_early_stop_axes(self, full_stop):
f, st = self.fixture, self.st
from ptz_tracker_modular.zoom_controller import controller_for_track
self.stack.enter_context(patch.dict(config.CAMERA_CONFIG[self.cam], {
"predictive_zoom": {"nominal_gain": .45, "upper_gain": .8},
}))
controller = controller_for_track(st, config.CAMERA_CONFIG[self.cam])
controller.optics.observe(99.95, 59.0, f.wall)
cmd = pp._gate_zoom_in_pulse(st, f.wall, .10, True, pulse_floor=.10, pulse_timing=(.34, .40))
st["predictive_zoom_request"] = st["zoom_step_pending_id"]
f._enqueue(cmd, pan=.12, tilt=-.08)
f._flush()
request = controller.request
self.assertIsNotNone(request)
class InlineThread:
def __init__(self, *, target, **_):
self.target = target
def start(self):
self.target()
self.stack.enter_context(patch.object(ptz_io.threading, "Thread", InlineThread))
self.stack.enter_context(patch.object(config, "PTZ_ZOOM_STOP_FORCE_AXES_ZERO", full_stop, create=True))
ptz_io.stop_predictive_zoom_async(self.cam, controller, "edge_acceleration")
axes = tuple(fixture.transport.xml_axis(f.sent[-1], axis) for axis in ("pan", "tilt", "zoom"))
self.assertEqual(axes, (0, 0, 0) if full_stop else (12, -8, 0))
self.assertIsNone(controller.request)
self.assertFalse(controller.repeat_after_stop(st, f.wall))
def test_priority_zoom_stop_honors_axis_policy(self):
self.assert_early_stop_axes(full_stop=False)
def test_priority_zoom_stop_does_not_override_full_stop(self):
self.assert_early_stop_axes(full_stop=True)
def test_transport_floor_preserves_gimbal_and_rejects_lens(self):
f, st = self.fixture, self.st
self.stack.enter_context(patch.dict(config.CAMERA_CONFIG[self.cam], {
"predictive_zoom": {"nominal_gain": .45, "upper_gain": .8},
}))
self.stack.enter_context(patch.object(config, "PTZ_ZOOM_STOP_FORCE_AXES_ZERO", False, create=True))
self.stack.enter_context(patch.object(config, "PREDICTIVE_ZOOM_TELEMETRY_DIR", None, create=True))
status._update_runtime_state(self.cam, None, None, f.wall-.05, zoom_ratio=6., hfov_deg=10.6)
command = pp._gate_zoom_in_pulse(st, f.wall, .10, True, pulse_floor=.10, pulse_timing=(.12, .18))
self.assertGreater(command, 0.)
f._enqueue(command, pan=.12, tilt=-.08)
f._flush()
self.assertFalse(st.get("zoom_step_pending"))
axes = tuple(fixture.transport.xml_axis(f.sent[-1], axis) for axis in ("pan", "tilt", "zoom"))
self.assertEqual(axes, (12, -8, 0))
return PredictiveTrack

@ -0,0 +1,793 @@
"""Predictive TRACK zoom policy. All time inputs are seconds on the same clock."""
from collections import deque
from dataclasses import dataclass, replace
import json
import math
from pathlib import Path
from queue import Full, Queue
from threading import Lock, Thread
@dataclass(frozen=True)
class ZoomConfig:
# Fit per camera and native command. Gains multiply ln(252/6)/full_travel_s.
nominal_gain: float
upper_gain: float
wide_fov: float = 59.0
tele_fov: float = 2.0
full_travel_s: float = 5.5
native: int = 10
entry_fov: float = 35.0
initial_gate_relax_factor: float = 1.45
tele_edge_margin_ratio: float = 0.32
min_allowed_hfov_deg: float = 10.0
latency_horizon_ms: float = 245.0
tele_pan_native10_deg_s: float = 0.65
tele_tilt_native10_deg_s: float = 0.85
tele_position_gain: float = 2.7
tele_rate_gain: float = 0.85
tele_native_max: float = 35.0
tele_steering_start_fov: float = 20.0
tele_full_steering_fov: float = 16.0
step_back_cmd: float = 0.10
tele_calibration_enabled: bool = True
calibration_settle_s: float = .35
calibration_timeout_s: float = 1.2
calibration_stable_deg: float = .10
entry_center: float = 0.15 # fraction of full frame, 30% of half-width
repeat_center: float = 0.09
edge_margin: float = 0.16
tracker_score: float = 0.55
tracker_frames: int = 3
frame_age_s: float = 0.25
detector_age_s: float = 0.65
status_age_s: float = 0.65
evidence_gap_s: float = 0.20
max_outward_deg_s: float = 0.15
trajectory_slack_deg: float = 0.6
edge_accel: float = 0.55 # full frame / sВІ, outward
edge_watch_margin: float = 0.24
steering_delay_s: float = 0.18
max_residual_deg_s: float = 12.0
wide_pulse_fov: float = 25.0
tele_pulse_fov: float = 15.0
wide_pulse_s: float = 0.34
tele_pulse_s: float = 0.12
stop_slack_s: float = 0.06
stop_ack_slack_s: float = 0.08
target_px: float = 48.0
status_gain: float = 0.7
status_error_log: float = 0.08
ff_gain: float = 0.7
ff_max_deg_s: float = 3.0
def __post_init__(self):
for name, value in vars(self).items():
if name == "tele_calibration_enabled" and isinstance(value, bool):
continue
if not math.isfinite(value) or value <= 0:
raise ValueError(f"invalid zoom setting {name}")
if not (
self.native == 10 and 0 < self.nominal_gain <= self.upper_gain
and 0 < self.tele_fov < self.tele_pulse_fov < self.wide_pulse_fov
< self.entry_fov < self.wide_fov < 90
and 0 < self.repeat_center <= self.entry_center <= 0.15
and 0 < self.edge_margin <= self.edge_watch_margin < 0.5
and isinstance(self.tracker_frames, int) and 2 <= self.tracker_frames <= 12
and self.tracker_score <= 1 and self.status_gain <= 1
and self.frame_age_s <= 0.25 and self.detector_age_s <= 0.65
and self.status_age_s <= 0.65
and 1 <= self.initial_gate_relax_factor <= 1.8
and self.edge_margin <= self.tele_edge_margin_ratio <= .38
and self.tele_fov <= self.min_allowed_hfov_deg <= self.tele_pulse_fov
and self.wide_pulse_fov > 12
and 40 <= self.latency_horizon_ms <= 400
and 0 < self.tele_full_steering_fov < self.tele_steering_start_fov <= self.wide_pulse_fov
and self.tele_native_max <= 45 and self.tele_rate_gain <= 1
and self.step_back_cmd <= .12
and isinstance(self.tele_calibration_enabled, bool)
and 0.25 <= self.calibration_settle_s < self.calibration_timeout_s <= 2
and self.calibration_stable_deg <= .25
and 0.10 <= self.tele_pulse_s <= self.wide_pulse_s <= 0.34
and self.wide_pulse_s + self.stop_slack_s <= 0.40 + 1e-9
and self.stop_ack_slack_s <= 0.12
):
raise ValueError("zoom settings exceed the native/geometry/watchdog limits")
@property
def log_rate(self):
return self.nominal_gain * math.log(252 / 6) / self.full_travel_s
@property
def upper_log_rate(self):
return self.upper_gain * math.log(252 / 6) / self.full_travel_s
def margin_for(self, fov):
weight = min(1.0, max(0.0, (self.wide_pulse_fov - fov) / (self.wide_pulse_fov - 12.0)))
return self.edge_margin + weight * (self.tele_edge_margin_ratio - self.edge_margin)
def limits_window(self, fov, seconds):
next_focal = _log_focal(fov) + self.upper_log_rate * seconds
return next_focal <= _log_focal(self.min_allowed_hfov_deg)
def window(self, fov):
scale = min(1.0, max(0.0, (fov - self.tele_pulse_fov)
/ (self.wide_pulse_fov - self.tele_pulse_fov)))
nominal = self.tele_pulse_s + scale * (self.wide_pulse_s - self.tele_pulse_s)
return nominal, min(0.40, nominal + self.stop_slack_s)
def _log_focal(fov):
return -math.log(math.tan(math.radians(fov / 2)))
def _fov(log_focal):
return math.degrees(2 * math.atan(math.exp(-log_focal)))
class OpticalStateEstimator:
"""Integrate accepted native-10 windows, then correct with timestamped status."""
def __init__(self, config):
self.cfg = config
self.actual = None
self.status_at = 0.0
self.nominal = self.upper = 0.0
self.spans = deque()
self.samples = deque()
self.active = None
self.valid = False
def _seconds_since_status(self, at, status_at=None):
status_at = self.status_at if status_at is None else status_at
spans = self.spans
if self.active:
start, hard_end = self.active
spans = (*spans, (start, hard_end))
return sum(max(0.0, min(end, at) - max(start, status_at))
for start, end in spans)
def estimate(self, at):
for status_at, nominal, upper, _ in reversed(self.samples):
if status_at <= at:
elapsed = self._seconds_since_status(at, status_at)
tele = _log_focal(self.cfg.tele_fov)
return (_fov(min(tele, nominal + self.cfg.log_rate * elapsed)),
_fov(min(tele, upper + self.cfg.upper_log_rate * elapsed)))
return None, None
def observe(self, at, hfov, now):
if not (self.status_at < at <= now and math.isfinite(hfov)
and self.cfg.tele_fov - 0.1 <= hfov <= self.cfg.wide_fov + 1.0):
return
measured = _log_focal(hfov)
estimated, upper = self.estimate(at)
had_motion = self._seconds_since_status(at) > 0.0
discrepancy = (had_motion and estimated is not None
and (measured > _log_focal(upper) + self.cfg.status_error_log
or measured < _log_focal(self.actual) - self.cfg.status_error_log))
if discrepancy:
self.valid = False
elif not self.active:
self.valid = True
if not had_motion or estimated is None or discrepancy:
self.nominal = measured
else:
prediction = _log_focal(estimated)
self.nominal = prediction + self.cfg.status_gain * (measured - prediction)
# The filtered estimate never reduces the conservative edge envelope.
self.upper = max(self.nominal, measured + self.cfg.status_error_log)
self.actual, self.status_at = hfov, at
self.samples.append((at, self.nominal, self.upper, measured))
cutoff = at - self.cfg.status_age_s - self.cfg.frame_age_s
while len(self.samples) > 1 and self.samples[1][0] <= cutoff:
self.samples.popleft()
while self.spans and self.spans[0][1] <= self.samples[0][0]:
self.spans.popleft()
def start(self, put_at, ack_at, hard_end):
if self.active or not self.fresh(ack_at) or not put_at <= ack_at < hard_end:
self.valid = False
self.active = (put_at, hard_end)
def stop(self, at, *, clean):
if self.active:
start, hard_end = self.active
if at > hard_end + self.cfg.stop_ack_slack_s or at < start or not clean:
self.valid = False
if at > start:
self.spans.append((start, min(at, hard_end + self.cfg.stop_ack_slack_s)))
self.active = None
def fresh(self, now):
return self.valid and 0 <= now - self.status_at <= self.cfg.status_age_s
@dataclass(frozen=True)
class ZoomFrame:
at: float
seq: int
offset: tuple[float, float] # positive right/down; fractions of full frame
bbox_frac: tuple[float, float]
bbox_px: tuple[float, float]
angles: tuple[float, float] # camera-signed LOS error in degrees
rates: tuple[float, float] # camera-signed LOS residual, deg/s
aspect: float # image height / width
tracker_score: float | None
detector_at: float
detector_conf: float | None
geometry_ok: bool
los_valid: bool
rearm_ready: bool = True
@dataclass(frozen=True)
class ZoomDecision:
reason: str
window: tuple[float, float] | None = None
stop: bool = False
ff_deg_s: tuple[float, float] = (0.0, 0.0)
margin: float | None = None
step_back: bool = False
gate: str = "tracking_zoom"
edge_margin_required: float | None = None
class ZoomController:
"""Per TRACK epoch; the existing worker retains ownership and all STOPs."""
def __init__(self, config, owner):
self.cfg = config
self.owner = owner
self.optics = OpticalStateEstimator(config)
self.history = deque(maxlen=config.tracker_frames)
self.request = None
self.first_ack_at = None
self.confirmed_stop = None
self.completed_request = None
self.stop_cooldowns = None
self.latest_pose = None
self.calibration = None
def accepted(self, request, put_at, ack_at, hard_end):
if self.request == request:
return
self.request = request
self.confirmed_stop = None
self.completed_request = None
self.stop_cooldowns = None
if self.first_ack_at is None:
self.first_ack_at = ack_at
self.optics.start(put_at, ack_at, hard_end)
def stopped(self, request, at, *, confirmed, clean):
if self.request != request:
return
self.optics.stop(at, clean=clean)
self.request = None
if clean and self.optics.fresh(at):
self.completed_request = request
if confirmed:
self.confirmed_stop = (at, self.optics.status_at)
def optical_confirmation(self, request, at):
if self.completed_request == request and self.request is None and self.optics.fresh(at):
self.confirmed_stop = (at, self.optics.status_at)
def can_reuse_feedback(self, now, feedback_after):
return (self.confirmed_stop is not None and self.request is None
and self.confirmed_stop[0] == feedback_after and self.optics.fresh(now)
and self.optics.status_at >= self.confirmed_stop[1])
def owns(self, st):
return (st.get("predictive_zoom_controller") is self and _owner(st) == self.owner
and st.get("mode") == "TRACK" and st.get("tracking_active"))
def repeat_after_stop(self, st, now):
return bool(
self.owns(st) and self.can_reuse_feedback(
now, float(st.get("zoom_feedback_required_after", 0.0) or 0.0)
)
and st.get("zoom_step_last_delivery_result") == "confirmed"
and not any(st.get(key) for key in (
"zoom_step_feedback_pending", "zoom_step_pending",
"zoom_stop_obligation_active", "zoom_no_effect_blocked",
"zoom_step_cancel_requested", "zoom_rearm_required", "lens_move_stop_required",
"lens_move_put_inflight",
))
and self.stop_cooldowns == _cooldowns(st)
and tuple(st.get("last_ptz_physical_cmd", (None, None, None)))[2] == 0
)
def _record(self, frame, fresh):
history = self.history
if (not fresh or frame.tracker_score is None
or frame.tracker_score < self.cfg.tracker_score):
history.clear()
return
if history:
prev = history[-1]
if frame.seq <= prev.seq or frame.at <= prev.at:
history.clear()
return
dt = frame.at - prev.at
if (dt > self.cfg.evidence_gap_s
or any(abs(b - a - rate * dt) > self.cfg.trajectory_slack_deg
for a, b, rate in zip(prev.angles, frame.angles, prev.rates))):
history.clear()
history.append(frame)
def calibration_hold(self, now):
item = self.calibration
return bool(self.cfg.tele_calibration_enabled and item and item.get("stop_ack_at") is not None
and item.get("HFOV_before") and item["HFOV_before"] < 15.0
and 0 <= now - item["stop_ack_at"] <= self.cfg.calibration_timeout_s)
def tele_aim(self, frame, now, camera_rates, optical_rates=(0.0, 0.0)):
# Angular position predicts the image at actuation. The rate term
# reconstructs target motion from residual plus measured gimbal motion.
sample = self.latest_pose
cfg = self.cfg
if (sample is None or sample[0] != frame.seq or not self.optics.fresh(now)
or self.optics.actual >= cfg.tele_steering_start_fov
or not all(math.isfinite(rate) for rate in camera_rates)):
return None
_, angles, rates, reliable = sample
if not reliable:
return None
horizon = max(cfg.latency_horizon_ms / 1000, now - frame.at)
blend = min(1.0, (cfg.tele_steering_start_fov - self.optics.actual) /
(cfg.tele_steering_start_fov - cfg.tele_full_steering_fov))
command = []
for angle, residual, gimbal, optical, reference in zip(
angles, rates, camera_rates, optical_rates,
(cfg.tele_pan_native10_deg_s, cfg.tele_tilt_native10_deg_s)):
predicted = angle + residual * horizon
target_rate = gimbal + residual
demand = cfg.tele_position_gain * predicted + cfg.tele_rate_gain * target_rate + optical
native = min(cfg.tele_native_max, 10 * math.sqrt(abs(demand) / reference))
command.append(math.copysign(native / 100, demand))
return tuple(command), blend
def decide(self, frame, now, *, first, cooldown, transport_clear):
cfg = self.cfg
gate = "initial" if first else "tracking_zoom"
self.latest_pose = None
values = (*frame.offset, *frame.bbox_frac, *frame.bbox_px,
*frame.angles, *frame.rates, frame.at, frame.aspect)
fresh = (frame.geometry_ok and frame.los_valid and frame.seq > 0
and all(math.isfinite(x) for x in values)
and 0 < frame.aspect <= 4 and min(frame.bbox_frac + frame.bbox_px) > 0
and 0 <= now - frame.at <= cfg.frame_age_s)
prev = self.history[-1] if self.history else None
moving = self.request is not None
if frame.tracker_score is not None and not (
math.isfinite(frame.tracker_score) and frame.tracker_score >= cfg.tracker_score
):
self.history.clear()
return ZoomDecision("low_tracker_score", stop=moving, gate=gate)
if not fresh or (prev is not None and (frame.at <= prev.at or frame.seq <= prev.seq)):
self.history.clear()
return ZoomDecision("stale_or_geometry", stop=moving, gate=gate)
if not self.optics.fresh(now):
return ZoomDecision("fov_cooldown", stop=moving, gate=gate)
fov, min_fov = self.optics.estimate(now)
captured_fov, captured_min = self.optics.estimate(frame.at)
if captured_fov is None:
return ZoomDecision("fov_cooldown", stop=moving, gate=gate)
captured_base = next(measured for at, _, _, measured in reversed(self.optics.samples)
if at <= frame.at)
def projection(hfov):
horizontal = math.tan(math.radians(hfov / 2))
return horizontal, horizontal * frame.aspect
axes_at_capture = projection(captured_fov)
angles = tuple(math.degrees(math.atan(2 * offset * axis))
for offset, axis in zip(frame.offset, axes_at_capture))
if prev and 0 < frame.at - prev.at <= cfg.evidence_gap_s:
dt = frame.at - prev.at
rates = tuple((value - old) / dt for value, old in zip(angles, prev.angles))
frame = replace(frame, rates=rates)
frame = replace(frame, angles=angles)
self._record(frame, fresh)
residual_ok = max(map(abs, frame.rates)) <= cfg.max_residual_deg_s
self.latest_pose = (frame.seq, frame.angles, frame.rates,
residual_ok and len(self.history) >= 2)
if not residual_ok:
return ZoomDecision("edge_margin_low", stop=moving, gate=gate)
window = cfg.window(min_fov)
if moving:
remaining = max(0.0, self.optics.active[1] - now)
else:
remaining = window[1]
remaining += cfg.stop_ack_slack_s
horizon = max(cfg.latency_horizon_ms / 1000, now - frame.at) + remaining
broad_initial = first and fov > cfg.entry_fov and len(self.history) >= cfg.tracker_frames
# Residual is signed in camera coordinates. Use its magnitude for the
# edge projection, so a sign flip or overshoot cannot shrink the bound.
narrowed = min(_log_focal(cfg.tele_fov),
_log_focal(min_fov) + cfg.upper_log_rate * remaining)
# Use the widest supported captured view as the reference so a
# narrower prediction never understates the pixel magnification.
growth = math.exp(max(0.0, narrowed - captured_base + cfg.status_error_log))
half_tan = projection(captured_min)
motion = [math.tan(math.radians(min(80, abs(rate) * horizon))) / (2 * axis)
for rate, axis in zip(frame.rates, half_tan)]
bounds = []
for off, size, move, rate in zip(frame.offset, frame.bbox_frac, motion, frame.rates):
# A converging trajectory may reduce the projected excursion at wide
# entry. Preserve the current offset as a bound against early braking.
extent = (max(abs(off), abs(off + math.copysign(move, rate)))
if broad_initial and off * rate < 0 else abs(off) + move)
bounds.append(extent + size / 2)
margin = min(0.5 - extent * growth for extent in bounds)
required = cfg.margin_for(min_fov)
observed_margin = min(.5 - abs(off) - size / 2 for off,size in zip(frame.offset,frame.bbox_frac))
detector_fresh = (0 <= frame.at - frame.detector_at <= cfg.detector_age_s
and 0 <= now - frame.detector_at <= cfg.detector_age_s)
steering_horizon = max(cfg.latency_horizon_ms / 1000, now - frame.at)
forecast_margin = min(
.5 - abs(math.tan(math.radians(max(-80, min(80, angle + rate * steering_horizon))))
/ (2 * axis)) - size/2
for angle, rate, axis, size in zip(frame.angles, frame.rates, half_tan, frame.bbox_frac)
)
step_back = (min_fov <= 12.0 and not moving and detector_fresh
and min(observed_margin, forecast_margin) < required + .025)
if min_fov <= cfg.min_allowed_hfov_deg or not cfg.limits_window(min_fov, remaining):
return ZoomDecision("min_hfov_limit", stop=moving, margin=margin,
step_back=step_back, gate=gate, edge_margin_required=required)
if margin < required:
return ZoomDecision("edge_margin_low", stop=moving, margin=margin,
step_back=step_back, gate=gate, edge_margin_required=required)
if moving and prev and 0 < frame.at - prev.at <= cfg.evidence_gap_s:
dt = frame.at - prev.at
for off, rate, old_rate, axis in zip(frame.angles, frame.rates, prev.rates, half_tan):
outward_accel = math.copysign(1, off) * (rate - old_rate) / (dt * 2 * math.degrees(axis))
outward_rate = math.copysign(1, off) * rate
if margin < max(cfg.edge_watch_margin, required + .04) and outward_rate > 0 and outward_accel > cfg.edge_accel:
return ZoomDecision("edge_acceleration", stop=True, margin=margin, gate=gate)
norm = math.hypot(*frame.angles)
outward = sum(a * r for a, r in zip(frame.angles, frame.rates)) / norm if norm else 0.0
wide_fraction = max(0.0, (fov - cfg.entry_fov) / (cfg.wide_fov - cfg.entry_fov))
center_limit = cfg.repeat_center
if broad_initial:
center_limit = cfg.entry_center
if outward < 0.0:
center_limit *= 1 + min(1.0, wide_fraction) * (cfg.initial_gate_relax_factor - 1)
outward_limit = cfg.max_outward_deg_s * (cfg.initial_gate_relax_factor if broad_initial else 1)
if moving:
if not detector_fresh:
return ZoomDecision("waiting_yolo", stop=True, margin=margin, gate=gate)
if min(frame.bbox_px) >= cfg.target_px:
return ZoomDecision("size_reached", stop=True, margin=margin, gate=gate)
if now >= self.optics.active[1]:
return ZoomDecision("fov_cooldown", stop=True, margin=margin, gate=gate)
# d(theta)/dt needed to cancel (df/f)*tan(theta) on each axis.
optical_gain = cfg.ff_gain * min(1.0, fov / cfg.tele_steering_start_fov)
ff = tuple(max(-cfg.ff_max_deg_s, min(cfg.ff_max_deg_s,
math.degrees(optical_gain * cfg.log_rate * math.sin(math.radians(a))
* math.cos(math.radians(a))))) for a in frame.angles)
return ZoomDecision("pulse_active", ff_deg_s=ff, margin=margin, gate=gate)
if min(frame.bbox_px) >= cfg.target_px:
return ZoomDecision("size_reached", margin=margin, gate=gate)
if not frame.rearm_ready:
return ZoomDecision("geometry_rearm", margin=margin, gate=gate)
if self.calibration_hold(now):
return ZoomDecision("tele_calibration_wait", margin=margin, gate=gate,
edge_margin_required=required)
if not transport_clear or cooldown or min_fov <= cfg.tele_fov + 0.05:
return ZoomDecision("fov_cooldown", margin=margin, gate=gate,
edge_margin_required=required)
if not detector_fresh:
return ZoomDecision("waiting_yolo", margin=margin, gate=gate)
if frame.tracker_score is None or len(self.history) < cfg.tracker_frames:
return ZoomDecision("low_tracker_score", margin=margin, gate=gate)
if max(map(abs, frame.offset)) > center_limit or outward > outward_limit:
return ZoomDecision("not_centered", margin=margin, gate=gate, edge_margin_required=required)
return ZoomDecision("fast_start" if first else "burst", window=window, margin=margin,
gate=gate, edge_margin_required=required)
class EpisodeTelemetryLogger:
"""Write JSONL off the control/STOP threads, with a bounded queue."""
def __init__(self, directory, capacity=4096):
self.directory = Path(directory)
self.queue = Queue(maxsize=capacity)
self.dropped = 0
Thread(target=self._write, name="ptz-zoom-telemetry", daemon=True).start()
def submit(self, camera, owner, event, at, **fields):
generation, started = owner
try:
self.queue.put_nowait((camera, generation, started, {
"cam": camera, "generation": generation, "track_start_utc": started,
"utc": at, "elapsed_ms": round((at - started) * 1000, 1),
"event": event, **fields,
}))
except Full:
self.dropped += 1
def _write(self):
import logging
log = logging.getLogger("PTZTracker")
while True:
camera, generation, started, row = self.queue.get()
try:
self.directory.mkdir(parents=True, exist_ok=True)
path = self.directory / f"ptz-{camera}-{generation}-{started:.6f}.jsonl"
with path.open("a", encoding="utf-8") as out:
out.write(json.dumps(row, allow_nan=False) + "\n")
except (OSError, ValueError):
log.exception("Unable to write PTZ zoom telemetry")
finally:
self.queue.task_done()
def _owner(st):
return int(st.get("ptz_generation", 0) or 0), float(st.get("track_started_at", 0.0) or 0.0)
def controller_for_track(st, camera_config):
"""Called only from TRACK, under the same lock used by status and the worker."""
if not st.get("tracking_active") or st.get("mode") != "TRACK" or _owner(st)[1] <= 0:
return None
current = st.get("predictive_zoom_controller")
if current is None or not current.owns(st):
try:
settings = ZoomConfig(**camera_config["predictive_zoom"])
except (TypeError, ValueError):
# A malformed per-camera calibration must leave legacy control available.
return None
current = ZoomController(settings, _owner(st))
st["predictive_zoom_controller"] = current
sample = st.get("predictive_zoom_hfov")
if sample is not None:
current.optics.observe(*sample, now=sample[0])
return current
def transport_accepted(config, camera, st, request, native, put_at, ack_at, hard_end,
put_rtt_s=None):
controller = st.get("predictive_zoom_controller")
if controller is None or not controller.owns(st):
return
if controller.calibration and controller.calibration["request"] != request:
_close_calibration(config, camera, controller, ack_at, "next_pulse")
if controller.calibration is None:
before_at = float(st.get("zoom_step_start_status_at", 0.0) or 0.0)
before = st.get("zoom_step_start_hfov_deg")
controller.calibration = dict(
request=request, native=native, put_at=put_at, ack_at=ack_at,
put_rtt_ms=None if put_rtt_s is None else round(1000 * put_rtt_s, 2),
HFOV_before=before, before_at=before_at, stop_issued_at=None,
)
if controller.first_ack_at is None:
controller.first_ack_at = ack_at
_telemetry(config, camera, controller, "first_zoom", ack_at,
t_to_first_zoom_ms=round((ack_at - controller.owner[1]) * 1000, 1),
t_to_first_zoom_put_ms=round((put_at - controller.owner[1]) * 1000, 1),
request=request, native=native)
if (st.get("predictive_zoom_request") == request
and native == controller.cfg.native):
controller.accepted(request, put_at, ack_at, hard_end)
def _cooldowns(st):
return (float(st.get("zoom_step_cooldown_until", 0.0) or 0.0),
float(st.get("zoom_recenter_until", 0.0) or 0.0))
def _reusable_optics(controller, st, at):
before = st.get("zoom_step_start_hfov_deg")
actual = controller.optics.actual
return bool(before and actual and actual < before
and controller.optics.status_at == st.get("zoom_status_at")
and float(st.get("zoom_step_started_at", 0.0)) < controller.optics.status_at <= at)
def _normal_stop_cooldowns(config, st, at):
expected = (getattr(config, "ZOOM_STEP_COOLDOWN_SEC", 0.14),
getattr(config, "ZOOM_STEP_RECENTER_SEC", 0.14))
return all(observed <= at + delay for observed, delay in zip(_cooldowns(st), expected))
def transport_confirmed(config, st, request, at):
controller = st.get("predictive_zoom_controller")
if (controller is not None and controller.owns(st)
and _reusable_optics(controller, st, at) and _normal_stop_cooldowns(config, st, at)):
controller.optical_confirmation(request, at)
controller.stop_cooldowns = _cooldowns(st)
def transport_stopped(config, camera, st, request, at, *, reason, confirmed, clean,
duration_s=None, stop_issued_at=None, stop_rtt_s=None):
controller = st.get("predictive_zoom_controller")
if controller is None or not controller.owns(st):
return
calibration = controller.calibration
if calibration and calibration["request"] == request:
sample = next(((t, _fov(measured)) for t, _, _, measured
in reversed(controller.optics.samples)
if stop_issued_at and t <= stop_issued_at), (None, None))
calibration.update(stop_issued_at=stop_issued_at, stop_ack_at=at,
stop_rtt_ms=None if stop_rtt_s is None else round(1000 * stop_rtt_s, 2),
duration_s=duration_s, stop_reason=reason,
stop_status_at=sample[0], HFOV_stop_sample=sample[1],
clean_stop=bool(clean), first_post_stop=None, latest_post_stop=None)
if stop_issued_at is None:
_close_calibration(config, camera, controller, at, "stop_timing_missing")
if controller.request != request:
return
clean = clean and st.get("predictive_zoom_early_stop") != request
reusable = confirmed and _reusable_optics(controller, st, at)
controller.stopped(request, at, clean=clean, confirmed=reusable and _normal_stop_cooldowns(config, st, at))
controller.stop_cooldowns = _cooldowns(st)
_telemetry(config, camera, controller, "stop", at,
request=request, reason=reason, confirmed=confirmed, clean=clean)
_telemetry_loggers = {}
_telemetry_lock = Lock()
def _telemetry(config, camera, controller, event, at, **fields):
_episode_telemetry(config, camera, controller.owner, event, at, **fields)
def _episode_telemetry(config, camera, owner, event, at, **fields):
directory = getattr(config, "PREDICTIVE_ZOOM_TELEMETRY_DIR", "logs/ptz_zoom")
if not directory:
return
with _telemetry_lock:
log = _telemetry_loggers.get(directory)
if log is None:
log = EpisodeTelemetryLogger(directory)
_telemetry_loggers[directory] = log
log.submit(camera, owner, event, at, **fields, dropped_before=log.dropped)
def telemetry_tick(config, camera, controller, frame, decision, zoom, legacy_reason, at):
estimated, narrowest = controller.optics.estimate(at)
reason = decision.reason
if zoom <= 0.0 and decision.window is not None:
reason = legacy_reason
_telemetry(config, camera, controller, "tick", at, seq=frame.seq,
frame_utc=frame.at, zoom_cmd=zoom, reason=reason,
stop_requested=decision.stop, FOV_actual=controller.optics.actual,
FOV_status_utc=controller.optics.status_at or None,
FOV_estimated=estimated, FOV_min_estimated=narrowest,
bbox_px=frame.bbox_px, tracker_score=frame.tracker_score,
detector_conf=frame.detector_conf, detector_utc=frame.detector_at or None,
margin=decision.margin, ff_deg_s=decision.ff_deg_s, gate=decision.gate,
edge_margin_required=decision.edge_margin_required)
def transport_zoom_block_reason(st, camera_config, now, hard_s):
settings = camera_config.get("predictive_zoom")
if settings is None:
return None
controller = st.get("predictive_zoom_controller")
if controller is not None and controller.owns(st):
cfg = controller.cfg
if controller.calibration_hold(now):
return "tele_calibration_wait"
if not controller.optics.fresh(now):
return "min_hfov_limit"
_, narrowest = controller.optics.estimate(now)
if controller.optics.active:
hard_s = max(0.0, controller.optics.active[1] - now)
else:
try:
cfg = ZoomConfig(**settings)
at, hfov = st.get("predictive_zoom_hfov", (0.0, 0.0))
if not (0 <= now - at <= cfg.status_age_s and cfg.tele_fov <= hfov <= cfg.wide_fov + 1):
return "min_hfov_limit"
narrowest = _fov(_log_focal(hfov) + cfg.status_error_log)
except (TypeError, ValueError):
return "min_hfov_limit"
if narrowest is None or not cfg.limits_window(narrowest, hard_s + cfg.stop_ack_slack_s):
return "min_hfov_limit"
return None
def _close_calibration(config, camera, controller, now, outcome):
item = controller.calibration
if item is None:
return
controller.calibration = None
after = item.pop("latest_post_stop", None)
first = item.pop("first_post_stop", None)
before, stop_sample = item["HFOV_before"], item.get("HFOV_stop_sample")
after_fov = after[1] if after else None
# A request-bound measurement always has independent device timestamps.
# HTTP acknowledgement establishes ordering, not physical lens motion.
duration = item.get("duration_s")
qualified = (outcome == "settled" and item["native"] == 10 and before is not None
and before < 15 and after_fov is not None and after_fov < before
and item.get("clean_stop") and duration and duration > 0
and 0 <= item["put_at"] - item["before_at"] <= controller.cfg.status_age_s)
rate = (_log_focal(after_fov) - _log_focal(before)) / duration if qualified else None
_telemetry(config, camera, controller, "native10_pulse_calibration", now, **item,
outcome=outcome, HFOV_after=after_fov, after_at=after[0] if after else None,
delta_hfov_deg=None if before is None or after_fov is None else after_fov - before,
first_post_stop_at=first[0] if first else None,
HFOV_first_post_stop=first[1] if first else None,
post_stop_tail_deg=first[1] - after_fov if first and after else None,
stop_bracket_narrowing_deg=stop_sample - after_fov if stop_sample and after else None,
stop_sample_age_ms=None if not item.get("stop_status_at") else
1000 * (item["stop_issued_at"] - item["stop_status_at"]),
effective_tele_log_rate_s=rate)
def expire_calibration(config, camera, st, now, *, final=False):
controller = st.get("predictive_zoom_controller")
item = controller.calibration if controller else None
if item is None:
return
if final or (item.get("stop_ack_at") and now-item["stop_ack_at"] > controller.cfg.calibration_timeout_s):
_close_calibration(config, camera, controller, now, "episode_ended" if final else "settle_timeout")
def observe_calibration(config, camera, st, at, hfov, now):
controller = st.get("predictive_zoom_controller")
if controller is None or controller.calibration is None:
return
if not controller.owns(st):
_close_calibration(config, camera, controller, now, "owner_changed")
return
item = controller.calibration
ack = item.get("stop_ack_at")
if ack is None or at < ack:
return
if (st.get("zoom_step_pending") or st.get("lens_move_stop_required")
or st.get("lens_move_put_inflight") and (
st.get("lens_move_put_kind") == "goto"
or float(st.get("lens_move_put_zoom", 0.) or 0.) != 0
)
or abs(float(st.get("last_ptz_physical_cmd", (0., 0., 0.))[2])) > 0):
_close_calibration(config, camera, controller, now, "intervening_lens_motion")
return
if item["first_post_stop"] is None:
item["first_post_stop"] = (at, hfov)
previous = item["latest_post_stop"]
item["latest_post_stop"] = (at, hfov)
if at - ack > controller.cfg.calibration_timeout_s:
_close_calibration(config, camera, controller, now, "unsettled")
elif (previous and at - ack >= controller.cfg.calibration_settle_s
and abs(previous[1] - hfov) <= controller.cfg.calibration_stable_deg):
_close_calibration(config, camera, controller, now, "settled")
def record_zoom_blocks(config, camera, st, at, blocked):
if not getattr(config, "PREDICTIVE_ZOOM_TELEMETRY_DIR", "logs/ptz_zoom"):
return
owner = _owner(st)
record = st.get("episode_zoom_blocks")
if record is None or record["owner"] != owner:
if record is not None:
flush_zoom_blocks(config, camera, st, at, final=True)
record = {"owner": owner, "counts": {}, "last_values": {}, "last_write": at - 1}
st["episode_zoom_blocks"] = record
for reason, values in blocked.items():
record["counts"][reason] = record["counts"].get(reason, 0) + 1
record["last_values"][reason] = values
if at - record["last_write"] >= 1.0:
flush_zoom_blocks(config, camera, st, at)
def flush_zoom_blocks(config, camera, st, at, *, final=False):
record = st.get("episode_zoom_blocks")
if record is None:
return
_episode_telemetry(config, camera, record["owner"], "zoom_block_summary", at,
final=final, zoom_block_reason=dict(record["counts"]),
last_values=dict(record["last_values"]))
record["last_write"] = at
if final:
st.pop("episode_zoom_blocks", None)

@ -0,0 +1,7 @@
# Диагностика продолжения импульса same_native
`ZOOM CONTINUE reason=same_native` фиксирует кадр, камеру, поколение и номер уже начавшегося запроса. `proposed` и `held` показывают дробные значения, `native` — скорость камеры. `nominal_until` содержит исходный срок, `pulse` и `hard` — исходные длительности. `dispatch_zoom` показывает команду на выходе контроллера после остальных ограничений.
Сопоставляйте запись с `ZOOM DELIVERY` по камере, запросу и поколению. Факт и длительность доставки берите из записи завершения. Для одного запроса могут появиться записи по нескольким кадрам.
Патч рассчитан на установленный PR №5. На исходном коде и кандидате прошли по 16 офлайн-тестов. Повтор подтвердил одинаковые команды в общих сценариях и запись при сохранении native10. Проверено побайтное применение и обратное применение патча.

@ -0,0 +1,12 @@
{
"requires": "PR #5",
"files": {
"ptz_tracker_modular/postprocess.py": {
"before": "376f705fb3be06ab04afc1ebb718cb71a2c27a67987023b099f5d921148b64ad",
"after": "d85439504ebf56fc39ee8a883c44b1bfc6db721df938aedc85d6c6484cb97776"
}
},
"unchanged": {
"ptz_tracker_modular/ptz_io.py": "13d31539193b1a773a5d1db2187cc2a0c8db67d0aacaad89082face64df07499"
}
}

@ -0,0 +1,55 @@
--- a/ptz_tracker_modular/postprocess.py
+++ b/ptz_tracker_modular/postprocess.py
@@ -4577,6 +4577,7 @@
pulse_timing: Tuple[float, float] | None = None,
optics_observed_now: float | None = None,
stop_trace: list[str] | None = None,
+ continuation_trace: list[tuple[int, int, float, float, float, float, float]] | None = None,
) -> float:
"""Break continuous zoom-in into short feedback-controlled steps."""
pulse_until = float(st.get("zoom_step_until", 0.0) or 0.0)
@@ -4650,6 +4651,12 @@
):
_finish_zoom_step(st, now, stable_key=stable_key)
return _reject_zoom_step("pending_native_floor", stop_trace)
+ if same_native and continuation_trace is not None:
+ continuation_trace.append((
+ st["ptz_generation"], native, float(zoom_cmd), useful_cmd, pulse_until,
+ float(st.get("zoom_step_pending_pulse_sec", 0.0) or 0.0),
+ float(st.get("zoom_step_pending_hard_sec", 0.0) or 0.0),
+ ))
zoom_cmd = useful_cmd
physical_started = float(st.get("zoom_step_physical_started_at", 0.0) or 0.0)
if physical_started > 0.0:
@@ -9232,6 +9239,7 @@
st["zoom_useful_pulse_reason"] = "wait_response_framing"
zoom_zero_reason = "response_framing"
gate_stop = [] if decision_request else None
+ continuation_trace = [] if decision_request else None
zoom_cmd = _gate_zoom_in_pulse(
st,
# Keep new-request expiry tied to the frame that authorized
@@ -9247,6 +9255,7 @@
pulse_timing=response_timing,
optics_observed_now=zoom_gate_now,
stop_trace=gate_stop,
+ continuation_trace=continuation_trace,
)
if gate_stop:
zoom_zero_reason = gate_stop[-1]
@@ -9788,6 +9797,15 @@
cam_idx, prepared_fps, visual_only, max(0., time.time()-now)*1000.,
st.get('control_updates', 0), st.get('control_visual_updates', 0))
ingest_detection(alarm_eligible)
+ if continuation_trace:
+ generation, native, proposed, held, until, pulse_sec, hard_sec = continuation_trace[0]
+ logger.info(
+ "[ZOOM CONTINUE] cam=%s frame=%s request=%s gen=%s reason=same_native "
+ "native=%s proposed=%.12g held=%.12g nominal_until=%.6f "
+ "pulse=%.3fs hard=%.3fs dispatch_zoom=%.12g",
+ cam_idx, source_seq, decision_request, generation, native, proposed,
+ held, until, pulse_sec, hard_sec, zoom_cmd,
+ )
return
# =========================

@ -0,0 +1,7 @@
# Значения и пороги при остановке зума
`ZOOM THRESHOLD` дополняет `ZOOM DECISION` для `response_framing` и `size_controller`. Строки связываются по `cam`, `gen`, `request` и `frame`. Номер команды в `ZOOM DECISION` связывает решение с `ZOOM DELIVERY`.
Для `response_framing` поле `detail` содержит проверку, на которой расчёт вернул нулевую длительность, и её фактические значения и пределы. Для `size_controller` оно показывает ошибку размера, пороги переключения и значения команды на этапах регулятора. При отклонённой угловой проверке оно показывает фактическую и прогнозируемую ошибки и пределы для каждой оси.
Код рассчитан на установленный PR №6. В офлайн-повторе прошли 16 исходных проверок и две новые. Общие сценарии дали одинаковые команды и остановки. Прямое и обратное применение патча проверены побайтно. Для новых тестов добавьте `--thresholds` к команде офлайн-повтора в режиме `fixed`.

@ -0,0 +1,12 @@
{
"requires": "PR #6",
"files": {
"ptz_tracker_modular/postprocess.py": {
"before": "d85439504ebf56fc39ee8a883c44b1bfc6db721df938aedc85d6c6484cb97776",
"after": "776b5b337e5f898e69770fec517c4459560f4cc6adeb951af40ac8f0b2178534"
}
},
"unchanged": {
"ptz_tracker_modular/ptz_io.py": "13d31539193b1a773a5d1db2187cc2a0c8db67d0aacaad89082face64df07499"
}
}

@ -0,0 +1,314 @@
--- a/ptz_tracker_modular/postprocess.py
+++ b/ptz_tracker_modular/postprocess.py
@@ -2,6 +2,7 @@
import time
import math
import logging
+import json
from typing import Any, List, Tuple
import numpy as np
@@ -454,6 +455,7 @@
hfov_deg: float,
vfov_deg: float,
max_error_deg: float | None = None,
+ rejection: dict | None = None,
) -> bool:
"""Allow a lens pulse only when angular steering reserve is available."""
max_error = max(
@@ -486,7 +488,7 @@
float(tilt_error_deg) * float(tilt_rate_deg_s) > 0.0
and abs(float(tilt_rate_deg_s)) > max_outward
)
- return bool(
+ allowed = bool(
not pan_escaping
and not tilt_escaping
and abs(float(pan_error_deg)) <= pan_limit
@@ -494,6 +496,23 @@
and abs(predicted_pan) <= pan_limit
and abs(predicted_tilt) <= tilt_limit
)
+ if not allowed and rejection is not None:
+ rejection.update(
+ failed=[name for name, failed in (
+ ("pan_outward_rate", pan_escaping),
+ ("tilt_outward_rate", tilt_escaping),
+ ("pan_error", not abs(float(pan_error_deg)) <= pan_limit),
+ ("tilt_error", not abs(float(tilt_error_deg)) <= tilt_limit),
+ ("predicted_pan", not abs(predicted_pan) <= pan_limit),
+ ("predicted_tilt", not abs(predicted_tilt) <= tilt_limit),
+ ) if failed],
+ pan_error_deg=pan_error_deg, tilt_error_deg=tilt_error_deg,
+ pan_rate_deg_s=pan_rate_deg_s, tilt_rate_deg_s=tilt_rate_deg_s,
+ predicted_pan_deg=predicted_pan, predicted_tilt_deg=predicted_tilt,
+ pan_limit_deg=pan_limit, tilt_limit_deg=tilt_limit,
+ outward_rate_limit_deg_s=max_outward, prediction_s=horizon,
+ )
+ return allowed
def _zoom_probe_used_for_current_track(st: dict) -> bool:
@@ -4877,12 +4896,21 @@
return min(cap, max(command, minimum)), "useful"
+def _zoom_response_fallback(
+ timing: Tuple[float, float], rejection: dict | None, failed: str, **values,
+) -> Tuple[float, float]:
+ if rejection is not None and timing == (0.0, 0.0):
+ rejection.update(check=failed, **values)
+ return timing
+
+
def _select_zoom_response_timing(
st: dict, *, useful: bool, hfov_deg: float, wide_hfov_deg: float,
center_err: float, margin: float, image_rate: float,
approach_margin: float | None = None,
fast_approach: bool = False,
requested_native: int | None = None,
+ rejection: dict | None = None,
) -> Tuple[float, float]:
"""Explore at wide angle; reuse optically proven timing after narrowing.
@@ -4897,10 +4925,13 @@
"""
if requested_native is not None:
if st.get("zoom_no_effect_blocked", False):
- return 0.0, 0.0
+ return _zoom_response_fallback((0.0, 0.0), rejection, "no_effect_limit")
native = int(requested_native)
if not _zoom_native_response_available(st, native, hfov_deg, wide_hfov_deg):
- return 0.0, 0.0
+ return _zoom_response_fallback(
+ (0.0, 0.0), rejection, "native_profile",
+ native=native, hfov_deg=hfov_deg, wide_hfov_deg=wide_hfov_deg,
+ )
proof_native = int(st.get("zoom_response_native_cmd", 0) or 0)
retry_native = int(st.get("zoom_response_retry_native_cmd", 0) or 0)
legacy_proof10 = native == 10 and proof_native == 0
@@ -4923,9 +4954,9 @@
try:
learned = float(st.get("zoom_response_effective_sec", 0.0) or 0.0)
if not math.isfinite(learned):
- return 0.0, 0.0
+ return _zoom_response_fallback((0.0, 0.0), rejection, "invalid_learned_duration")
except (TypeError, ValueError, OverflowError):
- return 0.0, 0.0
+ return _zoom_response_fallback((0.0, 0.0), rejection, "invalid_learned_duration")
fallback = (0.0, 0.0) if learned > base else (base, hard)
try:
hfov, wide, error, edge, rate = map(float, (hfov_deg, wide_hfov_deg, center_err, margin, image_rate))
@@ -4936,14 +4967,20 @@
video_lag = float(getattr(config, "AIM_GIMBAL_FF_VIDEO_LATENCY_SEC", 0.45))
stop_timeout = float(getattr(config, "PTZ_LENS_STOP_DIRECT_TIMEOUT_SEC", 0.75))
if not all(math.isfinite(v) for v in (base, hard, hfov, wide, error, edge, rate, extra, max_pulse, max_hard, ratio, learned, video_lag, stop_timeout)):
- return fallback
+ return _zoom_response_fallback(fallback, rejection, "invalid_timing_inputs")
max_pulse, max_hard, ratio = min(0.34, max_pulse), min(0.40, max_hard), max(0.85, ratio)
video_lag, stop_timeout = max(0.0, video_lag), max(0.0, stop_timeout)
approach = approach_margin is not None and math.isfinite(approach_margin) and .16 <= approach_margin <= .5
+ center_limit = .12 if approach else .065
if not (0.0 < hfov <= wide < 180.0
- and 0.0 <= error <= (.12 if approach else .065)
+ and 0.0 <= error <= center_limit
and edge >= 0.30 and 0.0 <= rate <= 0.04):
- return fallback
+ return _zoom_response_fallback(
+ fallback, rejection, "framing",
+ hfov_deg=hfov, wide_hfov_deg=wide, center_error=error, center_limit=center_limit,
+ margin=edge, margin_min=.30, image_rate=rate, image_rate_max=.04,
+ approach_margin=approach_margin,
+ )
attempts = min(2, max(0, int(st.get("zoom_no_effect_count", 0) or 0)))
if hfov >= wide * ratio:
pulse = min(max_pulse, max(base + attempts * max(0.0, extra), learned))
@@ -4951,7 +4988,13 @@
if not (base < learned <= 0.34 and (
approach or (error <= 0.04 and edge >= 0.40 and rate <= 0.02)
)):
- return fallback
+ return _zoom_response_fallback(
+ fallback, rejection, "narrow_fov",
+ hfov_deg=hfov, wide_cutoff_deg=wide * ratio, learned_s=learned,
+ base_s=base, learned_max_s=.34, approach=approach,
+ approach_margin=approach_margin, center_error=error, center_limit=.04,
+ margin=edge, margin_min=.40, image_rate=rate, image_rate_max=.02,
+ )
# A nominal duration learned at wide FOV may become ineffective
# after narrowing (or may have benefited from STOP transport lag).
# Repeating it until the no-effect latch fires is not adaptation.
@@ -4988,16 +5031,24 @@
# increase either configured hard ceiling or the compiled 400ms limit.
deadline = min(max_hard, max(hard, pulse + 0.06))
if pulse <= base or deadline < pulse or pulse + 1e-9 < learned:
- return fallback
+ return _zoom_response_fallback(
+ fallback, rejection, "duration",
+ pulse_s=pulse, base_s=base, hard_s=deadline, learned_s=learned,
+ )
# Stress the projection with 2x apparent offset/box/rate and include
# video lag + STOP network timeout. This is a conservative software
# envelope, not a measured bound on this particular lens's zoom rate.
# The ordinary enlarged-bbox predictor is also independently checked.
- if 2.0 * edge - 0.5 - 2.0 * rate * (deadline + video_lag + stop_timeout) < 0.10:
- return fallback
+ projected_margin = 2.0 * edge - 0.5 - 2.0 * rate * (deadline + video_lag + stop_timeout)
+ if projected_margin < 0.10:
+ return _zoom_response_fallback(
+ fallback, rejection, "projected_margin",
+ projected_margin=projected_margin, margin_min=.10, margin=edge,
+ image_rate=rate, hard_s=deadline, video_lag_s=video_lag, stop_timeout_s=stop_timeout,
+ )
return pulse, deadline
except (TypeError, ValueError, OverflowError):
- return fallback
+ return _zoom_response_fallback(fallback, rejection, "invalid_timing_inputs")
def _apply_zoom_in_minimum(
@@ -8516,7 +8567,9 @@
tilt_speed = 0.0
# === zoom logic (V3): target-size + alpha-beta filter + hysteresis ===
state_zoom = int(st.get("zoom_state", 0) or 0)
- can_switch = (now - float(st.get("zoom_last_change", 0.0) or 0.0)) >= float(getattr(config, "Z_MIN_SWITCH_INTERVAL", 0.50))
+ switch_age = now - float(st.get("zoom_last_change", 0.0) or 0.0)
+ switch_interval = float(getattr(config, "Z_MIN_SWITCH_INTERVAL", 0.50))
+ can_switch = switch_age >= switch_interval
gate_dyn = max(0.05, _Z_CENTER_GATE_IN + _Z_CENTER_GATE_SCALE * (1.0 - clipf(w_smooth, 0.0, 1.0)))
center_good = measured_center_err < gate_dyn
@@ -8766,6 +8819,7 @@
pan_rate_deg_s=float(los_pan_rate_deg_s),
tilt_rate_deg_s=float(los_tilt_rate_deg_s),
)
+ angular_rejection = {} if pulse_active else None
zoom_angular_safe = followup_ready and _zoom_angular_motion_safe(
pan_error_deg=float(los_pan_angle_deg),
tilt_error_deg=float(los_tilt_angle_deg),
@@ -8774,6 +8828,7 @@
hfov_deg=float(hfov_deg),
vfov_deg=float(vfov_deg),
max_error_deg=float(angular_max),
+ rejection=angular_rejection,
)
if approach_margin is not None and followup_ready:
zoom_angular_safe = True
@@ -8961,6 +9016,8 @@
elif can_switch and int(st.get("zoom_v3_neutral_votes", 0) or 0) >= confirm_frames:
next_state = 0
+ size_votes = (st.get("zoom_v3_in_votes", 0), st.get("zoom_v3_out_votes", 0),
+ st.get("zoom_v3_neutral_votes", 0))
if next_state != state_zoom:
st["zoom_state"] = next_state
st["zoom_last_change"] = now
@@ -8968,19 +9025,21 @@
st["zoom_int"] = 0.0
err_size = z_target - size_ctrl
- if abs(err_size) < float(getattr(config, "Z_DEADBAND", 0.010)):
+ size_deadband = float(getattr(config, "Z_DEADBAND", 0.010))
+ if abs(err_size) < size_deadband:
err_size = 0.0
st["zoom_int"] = clipf(float(st.get("zoom_int", 0.0) or 0.0) + err_size * 0.04, -_Z_INT_CLAMP, _Z_INT_CLAMP)
zoom_pi = _Z_P * err_size + _Z_I * st["zoom_int"]
zoom_ff = _Z_FF_GAIN * (-float(size_rate))
- if size_err_abs <= float(getattr(config, "ZOOM_V3_BRAKE_ERR", 0.030)):
+ brake_err = float(getattr(config, "ZOOM_V3_BRAKE_ERR", 0.030))
+ if size_err_abs <= brake_err:
zoom_ff = 0.0
zoom_cmd = clipf(zoom_pi + zoom_ff, _Z_SPEED_LIMIT_OUT, _Z_SPEED_LIMIT_IN)
zoom_zero_reason = "size_controller"
if not out_edge_crit:
- brake_err = float(getattr(config, "ZOOM_V3_BRAKE_ERR", 0.030))
brake_k = clipf(abs(err_size) / max(1e-6, brake_err), 0.0, 1.0)
zoom_cmd *= brake_k
+ zoom_before_size_state = zoom_cmd
if st.get("zoom_lock", False) and not bounded_identification_request:
zoom_cmd = min(zoom_cmd, -0.12) if out_edge_effective else 0.0
@@ -9005,6 +9064,7 @@
if zoom_cmd < 0.0:
zoom_cmd = 0.0
+ zoom_after_size_state = zoom_cmd
prev_z = float(st.get("zoom_prev_cmd", 0.0) or 0.0)
max_step = float(getattr(config, "ZOOM_V3_CMD_MAX_STEP", 0.04))
positive_slew_limit = prev_z + max_step
@@ -9018,6 +9078,7 @@
and approach_margin is not None and .16 <= approach_margin <= .5):
positive_slew_limit = max(positive_slew_limit, min(.12, float(getattr(config, "ZOOM_STEP_MAX_IN_CMD", .12))))
zoom_cmd = clipf(zoom_cmd, prev_z - max_step, positive_slew_limit)
+ zoom_after_size_slew = zoom_cmd
if (prev_z * zoom_cmd) < 0.0 and abs(err_size) < (lock_err_thr * 2.0):
sign_cd = float(getattr(config, "ZOOM_V3_SIGN_COOLDOWN_SEC", 0.80))
last_flip = float(st.get("zoom_v3_last_sign_flip_t", 0.0) or 0.0)
@@ -9038,6 +9099,7 @@
zoom_zero_reason = "deadband"
zoom_cmd = 0.0
+ zoom_after_size_minimum = zoom_cmd
cmd_mag_est = max(
abs(float(pan_speed) + float(pan_rate_ff)),
abs(float(tilt_speed) + float(tilt_rate_ff)),
@@ -9225,6 +9287,8 @@
st["zoom_useful_pulse_reason"] = useful_reason
if before_shape > 0.0 and zoom_cmd <= 0.0:
zoom_zero_reason = useful_reason
+ response_rejection = {} if decision_request and useful_reason == "useful" else None
+ timing_native = _zoom_native_timing_request(st, zoom_cmd)
response_timing = _select_zoom_response_timing(
st, useful=useful_reason == "useful",
hfov_deg=float(hfov_deg), wide_hfov_deg=float(shared_wide_hfov),
@@ -9232,7 +9296,8 @@
margin=float(edge_risk_margin), image_rate=max(float(vel), float(fast_drift)),
approach_margin=approach_margin,
fast_approach=bool(fast_approach and normal_zoom_quality_ok and pulse_family == "normal"),
- requested_native=_zoom_native_timing_request(st, zoom_cmd),
+ requested_native=timing_native,
+ rejection=response_rejection,
)
if useful_reason == "useful" and response_timing == (0.0, 0.0):
zoom_cmd = 0.0
@@ -9259,6 +9324,7 @@
)
if gate_stop:
zoom_zero_reason = gate_stop[-1]
+ decision_generation = st.get("ptz_generation")
if (
probe_start_candidate
and zoom_cmd > 0.0
@@ -9797,6 +9863,32 @@
cam_idx, prepared_fps, visual_only, max(0., time.time()-now)*1000.,
st.get('control_updates', 0), st.get('control_visual_updates', 0))
ingest_detection(alarm_eligible)
+ if zoom_decision is not None and zoom_zero_reason in ("response_framing", "size_controller"):
+ if zoom_zero_reason == "response_framing":
+ detail = {"native": timing_native, **(response_rejection or {})}
+ else:
+ detail = dict(
+ size=size_ctrl, size_target=z_target, zoom_in_below=z_band_min - _Z_SIGN_HYST,
+ size_error=err_size, size_deadband=size_deadband, brake_error=brake_err,
+ pi=zoom_pi, feed_forward=zoom_ff, previous_state=state_zoom,
+ next_state=next_state, can_switch=can_switch, want_in=want_in, want_out=want_out,
+ in_votes=size_votes[0], out_votes=size_votes[1], neutral_votes=size_votes[2],
+ confirm_frames=confirm_frames, switch_age_s=switch_age, switch_interval_s=switch_interval,
+ can_zoom_in=can_zoom_in, followup_ready=followup_ready, angular_safe=zoom_angular_safe,
+ angular=angular_rejection,
+ before_state=zoom_before_size_state, after_state=zoom_after_size_state,
+ previous_zoom=prev_z, slew_min=prev_z - max_step, slew_max=positive_slew_limit,
+ after_slew=zoom_after_size_slew, command_min=_Z_MIN_CMD,
+ after_minimum=zoom_after_size_minimum, before_recenter=before_recenter,
+ before_ramp=pre_ramp_zoom_cmd, before_shape=before_shape,
+ center_error=center_err, center_priority_error=center_prio_err,
+ margin=min_margin, center_priority_margin=center_prio_margin,
+ )
+ logger.info(
+ "[ZOOM THRESHOLD] cam=%s frame=%s request=%s gen=%s reason=%s detail=%s",
+ cam_idx, source_seq, decision_request, decision_generation, zoom_zero_reason,
+ json.dumps(detail, separators=(",", ":"), default=str),
+ )
if continuation_trace:
generation, native, proposed, held, until, pulse_sec, hard_sec = continuation_trace[0]
logger.info(

@ -0,0 +1,17 @@
# Диагностика решения об остановке зума
При активном или ожидающем импульсе TRACK записывает `ZOOM DECISION`, когда итоговая команда кадра прекращает приближение и MOVE принят очередью. Строка содержит кадр, идентификатор импульса, причину, действующие ограничения, источник и native zoom. Пара `cam`, `gen`, `seq` сопоставляется с `cam`, `stop_gen`, `stop_seq` из `ZOOM DELIVERY` PR №3. Для однозначной атрибуции импульса сверяется и `request`. Порядок строк зависит от работы потока доставки.
`reason` показывает ветку решения. `blockers` показывает ограничения того же кадра, включая раздельные признаки недостаточной истории центровки, отклонённого текущего кадра и недостаточной истории трека. `size_controller` объединяет случаи без более конкретной причины. Прямые защитные остановки продолжают использовать прежний путь. Подтверждение доставки берётся из `ZOOM DELIVERY`.
## Офлайн-проверка
Патч рассчитан на две точные серверные копии из `pins.json`. Репозиторий хранит патч отдельно от своих исходных файлов, которые отличаются от серверных. Прямой и обратный патчи проверены побайтно. При проверке на Windows задайте `git -c core.autocrlf=false apply`.
```text
python -B replay.py SERVER_SNAPSHOT PTZ_IO TELEMETRY_JSON CONTROLLER_FIXTURE POSTPROCESS PP_SHA IO_SHA PROJECT_ROOT RESULT_JSON
```
`SERVER_SNAPSHOT` содержит `visual_control.py` и `visual_control_probe.py`. `CONTROLLER_FIXTURE` — локальный `cc1_cc2_control_replay_20261026/test_control_replay.py`. `PROJECT_ROOT` предоставляет существующие фикстуры из `tests` и `analysis_outputs/visual_probe_20261019`. Историческая телеметрия и серверные снимки остаются в локальном рабочем контуре.
В `verification.json` зафиксированы 10 базовых и 13 кандидатных тестов. Совпали решения, команды и остановки на 23 синтетических кадрах. Воспроизведены 19 исторических доставок PTZ19 и PTZ21 от границы очереди. Исторические журналы не содержат причин решения на исходных кадрах. Защитный STOP, модель и правила тревоги сохранены. Патч проверен локально.

@ -0,0 +1,13 @@
{
"requires": "PTZ stop attribution PR #3",
"files": {
"ptz_tracker_modular/postprocess.py": {
"before": "5326c9d3093b7c863310b9c0a7a85010a1a83ff014631a054ac9a16cc31c8fc5",
"after": "8eb5f6beb79141ef1f1ce9dbad3577006821202557a87c7195e770bbba7b4ba3"
},
"ptz_tracker_modular/ptz_io.py": {
"before": "3c3f10eaebc2a1c0f67725d6a487bad9e1537b1bb277705fc503c2526c779600",
"after": "13d31539193b1a773a5d1db2187cc2a0c8db67d0aacaad89082face64df07499"
}
}
}

@ -0,0 +1,223 @@
"""Reconstruct logged stop boundaries through the installed gate and worker, offline."""
from contextlib import ExitStack
import ast
import hashlib
import json
import logging
import math
from pathlib import Path
import socket
import sys
from types import ModuleType, SimpleNamespace
import unittest
from unittest.mock import patch
import importlib.util
WORK = Path(__file__).resolve().parent
PP = Path(sys.argv[5])
SOURCE, PTZ, INPUT, PRIOR = map(Path,sys.argv[1:5])
ROOT = Path(sys.argv[8])
BASE = ROOT/'analysis_outputs/visual_probe_20261019'
PKG='ptz_tracker_modular'
TRACE=[]
DETAIL=[]
PINS = {PP: sys.argv[6], PTZ: sys.argv[7]}
def sha(path):
return hashlib.sha256(path.read_bytes()).hexdigest()
def load(name,path):
spec=importlib.util.spec_from_file_location(name,path)
module=importlib.util.module_from_spec(spec)
sys.modules[name]=module
spec.loader.exec_module(module)
return module
def deny(*args,**kwargs):
raise AssertionError('No real network, CUDA, camera RPC, or model access in replay')
def as_native(value):
return math.nextafter(value/100,math.copysign(math.inf,value)) if value else 0.
def xml_sent(fixture):
return [tuple(transport.xml_axis(xml,axis) for axis in ('pan','tilt','zoom')) for xml in fixture.sent]
def captured():
report=json.loads(INPUT.read_text(encoding='utf-8'))
assert report['stable'] is True
assert report['container']['started_at']=='2026-11-09T06:24:10.287783596Z'
for camera, episodes in report['episodes'].items():
for episode in episodes:
assert episode['short_count']==len(episode['short_examples'])
for sample in episode['short_examples']:
yield camera,episode,sample
def sec(value):
return float(value.removesuffix('s'))
class StopBoundary(unittest.TestCase):
def fixture(self, cam, kind, native, pulse):
fixture=transport.UsefulZoomTransportTests()
fixture.setUp()
self.addCleanup(fixture.doCleanups)
fixture.cam=cam
fixture.stack.enter_context(patch.dict(state.ptz_states,{cam:fixture.st}))
# Seed each authorized pulse independently. The log gives accounting
# duration/minimum and speed, but lacks the original hard-stop deadline.
command=as_native(native)
allowed=pp._gate_zoom_in_pulse(fixture.st,fixture.wall,command,True,
pulse_kind=kind,pulse_floor=command,pulse_timing=(pulse,.4))
self.assertGreater(allowed,0)
fixture._enqueue(allowed)
fixture._flush()
self.assertEqual(xml_sent(fixture)[-1][2],native)
self.assertTrue(fixture.st['zoom_step_pending'])
return fixture
def test_all_observed_short_deliveries_replay_at_worker(self):
for cam,e,row in captured():
with self.subTest(camera=cam,request=row['request']):
internal={'19':8,'21':10}[cam]
pulse=round(sec(row['minimum'])/.7,3)
f=self.fixture(internal,row['kind'],int(row['native']),pulse)
f._advance(sec(row['duration']))
pan,tilt,zoom=row['requested']
self.assertEqual(zoom,0)
self.assertNotEqual((pan,tilt),(0,0))
with self.assertLogs('PTZTracker.PTZ',level='INFO') as logs:
# These are the recorded native values already past quantization.
seq=int(row['seq'])
f.st['ptz_move_seq']=seq
queued=ptz_io.MoveTuple(ptz_io.PTZCmd.MOVE,internal,pan,tilt,0,
source='track',generation=f.st['ptz_generation'],preset_floor_checked=True,
seq=seq,safety_stop=True)
state.ptz_cmd_q.put_nowait(queued)
self.assertEqual((queued.pan_i,queued.tilt_i,queued.zoom_i),tuple(row['requested']))
f._flush()
last=xml_sent(f)[-1]
self.assertEqual(last,tuple(row['effective']))
self.assertEqual(f.st['zoom_step_last_delivery_result'],'short')
self.assertEqual(f.st['zoom_in_pulse_count'],0)
self.assertAlmostEqual(f.st['zoom_step_last_delivered_sec'],sec(row['duration']))
record=next(x for x in logs.output if 'result=short' in x)
self.assertIn('stop_effective=(0,0,0)',record)
TRACE.append(dict(camera=cam,episode=e['started_at'],complete=e['complete'],
source_request=row['request'],kind=row['kind'],native=int(row['native']),
logged_s=sec(row['duration']),minimum_s=sec(row['minimum']),requested=row['requested'],
replay_effective=last,replay_result=f.st['zoom_step_last_delivery_result'],
controller_trigger_recovered=False))
def test_positive_revalidation_keeps_original_owned_pulse_deadline(self):
for cam,native in ((8,10),(10,11)):
with self.subTest(cam=cam,native=native):
f=self.fixture(cam,'normal',native,.34)
hard_deadline=f.st['zoom_step_stop_started_mono']+f.st['zoom_step_stop_timer'].delay
origin=f.st['zoom_step_put_started_mono']
deadline=f.st['zoom_step_until']
request=f.st['zoom_step_physical_request_id']
for _ in range(3):
f._advance(.045)
command=pp._gate_zoom_in_pulse(f.st,f.wall,.12,True,pulse_floor=.12,pulse_timing=(.34,.4))
self.assertEqual(ptz_io._zoom_speed_to_int(command),native)
f._enqueue(command)
f._flush()
self.assertEqual(f.st['zoom_step_put_started_mono'],origin)
self.assertEqual(f.st['zoom_step_until'],deadline)
self.assertEqual(f.st['zoom_step_physical_request_id'],request)
self.assertAlmostEqual(f.st['zoom_step_stop_started_mono']+
f.st['zoom_step_stop_timer'].delay,hard_deadline,places=6)
self.assertLessEqual(hard_deadline-origin,.400001)
f._advance(hard_deadline-f.mono)
f.st['zoom_step_stop_timer'].fire()
self.assertEqual(xml_sent(f)[-1],(0,0,0))
def test_identical_zero_when_only_vote_fails_or_safety_fails(self):
tree=ast.parse((PP).read_bytes())
main=next(n for n in tree.body if getattr(n,'name','')=='postprocess_control')
expr=next(n.value for n in ast.walk(main) if isinstance(n,ast.Assign)
and any(isinstance(target,ast.Name) and target.id=='can_zoom_in' for target in n.targets)
and 'zoom_angular_safe' in ast.unparse(n.value))
compiled=compile(ast.Expression(expr),'<server can_zoom_in>','eval')
for label,changes in (
('synthetic_stable_history_only',{'stable_ok':False}),
('synthetic_edge_veto',{'near_edge':True}),
('synthetic_angular_veto',{'zoom_angular_safe':False}),
('synthetic_quality_veto',{'zoom_safe':False}),
):
with self.subTest(label=label):
f=self.fixture(8,'normal',10,.34)
f._advance(.110)
env=dict(zoom_safe=True,zoom_angular_safe=True,stable_ok=True,
zoom_rearm_ready=True,near_edge=False,st={},bounded_identification_request=False,
fast_drift=.02,config=config,now=f.wall)
can=eval(compiled,{},{**env,**changes})
self.assertFalse(can)
actual=pp._gate_zoom_in_pulse(f.st,f.wall,.1,can,
pulse_floor=.1,pulse_timing=(.34,.4))
self.assertEqual(actual,0.)
f._enqueue(actual)
f._flush()
self.assertEqual(xml_sent(f)[-1],(0,0,0))
self.assertEqual(f.st['zoom_step_last_delivery_result'],'short')
DETAIL.append(dict(label=label,zoom=actual,axes=xml_sent(f)[-1],status='short'))
def main():
import torch
import numpy
global config,state,ptz_io,pp,transport
assert all(sha(path)==expected for path,expected in PINS.items())
before=load('prior_replay_fixture',PRIOR)
from test_frame_decision import build_cases
from test_native_floor import build_floor_cases
logging.getLogger('PTZTracker').setLevel(logging.ERROR)
with ExitStack() as stack:
for owner,name in ((socket.socket,'connect'),(socket.socket,'connect_ex'),
(socket,'create_connection'),(torch,'load'),(torch.cuda,'_lazy_init')):
stack.enter_context(patch.object(owner,name,deny))
stack.enter_context(patch.object(torch.cuda,'is_available',return_value=False))
package=ModuleType(PKG)
package.__path__=[str(BASE/'geometry_candidate/ptz_tracker_modular'),str(ROOT)]
sys.modules[PKG]=package
model=ModuleType(PKG+'.model')
model.model_shared,model.yolo_forward=object(),deny
sys.modules[model.__name__]=model
load(PKG+'.visual_control_probe', SOURCE/'visual_control_probe.py')
control=load(PKG+'.visual_control',SOURCE/'visual_control.py')
ptz_io=load(PKG+'.ptz_io',PTZ)
pp=load(PKG+'.postprocess',PP)
from ptz_tracker_modular import config,state,visual_tracker
values=json.loads((BASE/'zoom_continuation_candidate/runtime_policy_snapshot.json').read_text())['values']
for key,value in values.items():
stack.enter_context(patch.object(config,key,value,create=True))
transport=load('test_zoom_useful_transport',ROOT/'tests/test_zoom_useful_transport.py')
before.np,before.torch,before.config,before.state=numpy,torch,config,state
before.ptz_io,before.pp,before.tracker,before.control,before.transport=ptz_io,pp,visual_tracker,control,transport
suite=unittest.defaultTestLoader.loadTestsFromTestCase(StopBoundary)
for name in ('test_geometry_hold_short_delivery_has_exact_synthetic_stop_caller',
'test_started_controller_pulse_keeps_hard_stop_after_owner_change',
'test_joint_steering_update_cannot_extend_original_started_pulse',
'test_visual_age_over_250ms_cannot_move_or_advance_control',
'test_detector_age_over_650ms_cannot_refresh_evidence',
'test_old_owner_sample_cannot_refresh_or_stop_new_owner',
'test_reacquire_does_not_clear_no_effect_limit'):
suite.addTest(before.Replay(name))
candidate = "zoom_decision" in __import__("inspect").signature(ptz_io.move_ptz).parameters
if candidate:
suite.addTests(build_cases(before.Replay, pp, ptz_io))
suite.addTests(build_floor_cases(StopBoundary, before.Replay, pp, ptz_io, config,
Path(sys.argv[10]), sys.argv[11] == "fixed",
threshold_diagnostics="--thresholds" in sys.argv[12:]))
result=unittest.TextTestRunner(verbosity=2).run(suite)
result_file=Path(sys.argv[9])
result_file.write_text(json.dumps(dict(passed=result.wasSuccessful(),tests=result.testsRun,
observed_expected=len(list(captured())),observed_matched=len(TRACE),telemetry_sha256=sha(INPUT),
tested_source_sha256={path.name:pin for path,pin in PINS.items()},observed_rows=TRACE,synthetic=DETAIL,
shared_controller_rows={key: rows for key, rows in before.TRACE.items()
if not key.startswith(("test_frame_decision", "test_center_history", "test_dropped_move"))},
exact_observed_controller_replay=False,real_ptz_or_nn=False,
conclusion='The same short-delivery output is compatible with a synthetic admission-only condition and mandatory safety stops. The observed controller trigger and exact deadlines are missing.'),indent=2)+'\n',encoding='utf-8')
return not result.wasSuccessful()
if __name__=='__main__':
raise SystemExit(main())

@ -0,0 +1,406 @@
--- a/ptz_tracker_modular/postprocess.py
+++ b/ptz_tracker_modular/postprocess.py
@@ -4357,6 +4357,7 @@
max_image_rate: float,
max_outward_rate: float,
err_growth_tol: float,
+ settled_sample: list[bool] | None = None,
) -> bool:
"""Return True only after a tight, non-diverging image-space hold.
@@ -4381,6 +4382,8 @@
and outward_rate <= max(0.0, float(max_outward_rate))
and non_diverging
)
+ if settled_sample is not None:
+ settled_sample.append(bool(settled))
previous_frames = int(st.get(frames_key, 0) or 0)
if settled:
frames = previous_frames + 1
@@ -4411,6 +4414,7 @@
vx: float,
vy: float,
center_gate: float | None = None,
+ settled_sample: list[bool] | None = None,
) -> bool:
return _update_center_lock_state(
st,
@@ -4436,6 +4440,7 @@
max_image_rate=float(getattr(config, "ZOOM_CENTER_LOCK_MAX_IMAGE_RATE", 0.28)),
max_outward_rate=float(getattr(config, "ZOOM_CENTER_LOCK_MAX_OUTWARD_RATE", 0.08)),
err_growth_tol=float(getattr(config, "ZOOM_CENTER_LOCK_ERR_GROWTH_TOL", 0.018)),
+ settled_sample=settled_sample,
)
@@ -4553,6 +4558,12 @@
st["acquire_zoom_prev_err"] = None
+def _reject_zoom_step(reason: str, trace: list[str] | None) -> float:
+ if trace is not None:
+ trace.append(reason)
+ return 0.0
+
+
def _gate_zoom_in_pulse(
st: dict,
now: float,
@@ -4565,6 +4576,7 @@
pulse_floor: float = 0.0,
pulse_timing: Tuple[float, float] | None = None,
optics_observed_now: float | None = None,
+ stop_trace: list[str] | None = None,
) -> float:
"""Break continuous zoom-in into short feedback-controlled steps."""
pulse_until = float(st.get("zoom_step_until", 0.0) or 0.0)
@@ -4581,15 +4593,15 @@
return float(zoom_cmd if can_zoom_in else 0.0)
if bool(st.get("zoom_no_effect_blocked", False)):
st["zoom_followup_reason"] = "no_effect_limit"
- return 0.0
+ return _reject_zoom_step("no_effect_limit", stop_trace)
if not can_zoom_in:
if pulse_until > 0.0 or bool(st.get("zoom_step_pending", False)):
_finish_zoom_step(st, now, stable_key=stable_key)
- return 0.0
+ return _reject_zoom_step("permission", stop_trace)
if bool(st.get("zoom_step_pending", False)):
if bool(st.get("zoom_step_cancel_requested", False)):
- return 0.0
+ return _reject_zoom_step("cancel_requested", stop_trace)
if pulse_timing is not None:
try:
authorized = tuple(map(float, pulse_timing))
@@ -4602,7 +4614,7 @@
timing_ok = False
if not timing_ok:
_finish_zoom_step(st, now, stable_key=stable_key)
- return 0.0
+ return _reject_zoom_step("pending_timing", stop_trace)
useful_cmd = float(st.get("zoom_step_pending_useful_cmd", 0.0) or 0.0)
if useful_cmd > 0.0:
# A useful-pulse caller revalidates its entire framing envelope on
@@ -4614,7 +4626,7 @@
or float(getattr(config, "ZOOM_STEP_MAX_IN_CMD", 0.12)) < useful_cmd
):
_finish_zoom_step(st, now, stable_key=stable_key)
- return 0.0
+ return _reject_zoom_step("pending_native_floor", stop_trace)
zoom_cmd = useful_cmd
physical_started = float(st.get("zoom_step_physical_started_at", 0.0) or 0.0)
if physical_started > 0.0:
@@ -4624,7 +4636,7 @@
float(getattr(config, "ZOOM_STEP_MAX_IN_CMD", 0.18)),
)
_finish_zoom_step(st, now, stable_key=stable_key)
- return 0.0
+ return _reject_zoom_step("pulse_window_ended", stop_trace)
expires_at = float(st.get("zoom_step_pending_expires_at", 0.0) or 0.0)
if expires_at > 0.0 and float(now) >= expires_at:
_clear_pending_zoom_request(
@@ -4633,7 +4645,7 @@
reason="delivery_timeout",
retry_cooldown=True,
)
- return 0.0
+ return _reject_zoom_step("delivery_timeout", stop_trace)
# Keep authorizing the same request until the worker either delivers it
# or a newer safety command cancels it. No counters are consumed here.
return min(
@@ -8614,6 +8626,7 @@
)
if approach_margin is not None:
lock_gate = max(lock_gate, .12)
+ center_sample = []
center_locked_for_zoom = _update_zoom_center_lock(
st,
now,
@@ -8625,6 +8638,7 @@
vx=float(zoom_vx),
vy=float(zoom_vy),
center_gate=lock_gate,
+ settled_sample=center_sample,
)
use_zoom_v3 = bool(getattr(config, "ZOOM_V3_ENABLE", True))
@@ -8867,6 +8881,9 @@
and now >= float(st.get("focus_settle_until", 0.0) or 0.0)
)
+ center_settled = center_sample[0] if center_sample else None
+ track_stable = int(st.get("stable_frames", 0) or 0) >= min_stable
+
# A safe probe is an explicit bounded identification request, not merely
# permission for the ordinary size controller. Without this request a
# tiny distant aircraft could pass every probe gate yet never zoom because
@@ -8929,6 +8946,7 @@
if size_err_abs <= float(getattr(config, "ZOOM_V3_BRAKE_ERR", 0.030)):
zoom_ff = 0.0
zoom_cmd = clipf(zoom_pi + zoom_ff, _Z_SPEED_LIMIT_OUT, _Z_SPEED_LIMIT_IN)
+ zoom_zero_reason = "size_controller"
if not out_edge_crit:
brake_err = float(getattr(config, "ZOOM_V3_BRAKE_ERR", 0.030))
brake_k = clipf(abs(err_size) / max(1e-6, brake_err), 0.0, 1.0)
@@ -8936,6 +8954,7 @@
if st.get("zoom_lock", False) and not bounded_identification_request:
zoom_cmd = min(zoom_cmd, -0.12) if out_edge_effective else 0.0
+ zoom_zero_reason = "zoom_lock"
st["zoom_int"] *= 0.90
else:
if st["zoom_state"] > 0:
@@ -8947,6 +8966,7 @@
if normal_size_hold and not out_edge_effective:
st["zoom_state"] = 0
zoom_cmd = 0.0
+ zoom_zero_reason = "size_hold"
st["zoom_int"] *= 0.70
st["zoom_size_rate"] = float(st.get("zoom_size_rate", 0.0) or 0.0) * 0.6
if cruise_active and (not approaching) and (not out_edge_effective) and (not near_react_edge):
@@ -8973,6 +8993,7 @@
last_flip = float(st.get("zoom_v3_last_sign_flip_t", 0.0) or 0.0)
if (now - last_flip) < sign_cd:
zoom_cmd = 0.0
+ zoom_zero_reason = "sign_cooldown"
else:
st["zoom_v3_last_sign_flip_t"] = now
@@ -8983,6 +9004,8 @@
elif z_state < 0:
zoom_cmd = -_Z_MIN_CMD
else:
+ if zoom_cmd != 0.0:
+ zoom_zero_reason = "deadband"
zoom_cmd = 0.0
cmd_mag_est = max(
@@ -8993,10 +9016,14 @@
gate_v = float(getattr(config, "Z_VELOCITY_GATE", 0.45))
over_v = max(0.0, cmd_mag_est - gate_v)
zoom_cmd *= clipf(1.0 - over_v / max(1e-6, gate_v * 1.2), 0.0, 1.0)
+ if zoom_cmd == 0.0:
+ zoom_zero_reason = "steering_speed"
err_gate = float(getattr(config, "Z_ERR_GATE", 0.18))
if (max(abs(sm_dx), abs(sm_dy)) > err_gate) and (zoom_cmd > 0.0):
over_e = max(0.0, max(abs(sm_dx), abs(sm_dy)) - err_gate)
zoom_cmd *= clipf(1.0 - over_e / max(1e-6, err_gate * 1.5), 0.0, 1.0)
+ if zoom_cmd == 0.0:
+ zoom_zero_reason = "center_error"
# Center-first policy: when target is noticeably off-center, prioritize pan/tilt over zoom-in.
center_prio_err = float(getattr(config, "ZOOM_CENTER_PRIORITY_ERR", 0.11))
center_prio_margin = float(getattr(config, "ZOOM_CENTER_PRIORITY_MARGIN", 0.14))
@@ -9007,19 +9034,26 @@
zoom_cmd *= clipf(min_margin / max(1e-6, center_prio_margin), 0.0, 1.0)
if near_edge and zoom_cmd > 0.0:
zoom_cmd = 0.0
+ zoom_zero_reason = "near_edge"
if zoom_cmd > 0.0:
vel_ref = float(getattr(config, "ZOOM_IN_SCALE_VEL_REF", 0.22))
vel_k = clipf(1.0 - vel / max(1e-6, vel_ref), float(getattr(config, "ZOOM_IN_SCALE_MIN", 0.20)), 1.0)
zoom_cmd *= min(zoom_safe_scale, vel_k)
-
+ if zoom_cmd == 0.0:
+ zoom_zero_reason = "framing_scale"
+
+ before_edge = zoom_cmd
zoom_cmd = _apply_predictive_edge_zoom_out(
zoom_cmd,
risk_margin=edge_risk_margin,
react_margin=react_margin,
moving_out=moving_out,
)
+ if before_edge > 0.0 and zoom_cmd <= 0.0:
+ zoom_zero_reason = "predictive_edge"
recent_zoom_steering = _recent_zoom_steering_active(st, now, zoom_cmd)
+ before_recenter = zoom_cmd
zoom_cmd = _apply_zoom_recenter_guard(
zoom_cmd,
center_err=float(center_err),
@@ -9027,6 +9061,8 @@
recent_zoom=bool(recent_zoom_steering),
approach_margin=approach_margin,
)
+ if before_recenter > 0.0 and zoom_cmd <= 0.0:
+ zoom_zero_reason = "recenter"
zoom_out_emergency = bool(
out_edge_effective
or float(min_margin) < float(getattr(config, "Z_SAFETY_EDGE", 0.05))
@@ -9114,6 +9150,8 @@
request_id_before_gate = int(st.get("zoom_step_request_id", 0) or 0)
with _zoom_command_lock(cam_idx):
zoom_gate_now = time.time()
+ decision_request = int(st.get("zoom_step_physical_request_id", 0) or
+ st.get("zoom_step_pending_id", 0) or 0)
pulse_family = str(st.get("zoom_step_pending_kind") or pulse_kind)
pulse_cap = float(getattr(config, "ZOOM_STEP_MAX_IN_CMD", 0.12))
if "probe" in pulse_family:
@@ -9142,6 +9180,7 @@
proposed_zoom_cmd = max(zoom_cmd, min(pre_ramp_zoom_cmd, pulse_cap, .12))
if _zoom_native_response_available(st, _zoom_speed_to_int(proposed_zoom_cmd), hfov_deg, shared_wide_hfov):
zoom_cmd = proposed_zoom_cmd
+ before_shape = zoom_cmd
zoom_cmd, useful_reason = _shape_useful_zoom_pulse(
zoom_cmd,
can_zoom_in=can_zoom_in,
@@ -9154,6 +9193,8 @@
approach_margin=approach_margin,
)
st["zoom_useful_pulse_reason"] = useful_reason
+ if before_shape > 0.0 and zoom_cmd <= 0.0:
+ zoom_zero_reason = useful_reason
response_timing = _select_zoom_response_timing(
st, useful=useful_reason == "useful",
hfov_deg=float(hfov_deg), wide_hfov_deg=float(shared_wide_hfov),
@@ -9166,6 +9207,8 @@
if useful_reason == "useful" and response_timing == (0.0, 0.0):
zoom_cmd = 0.0
st["zoom_useful_pulse_reason"] = "wait_response_framing"
+ zoom_zero_reason = "response_framing"
+ gate_stop = [] if decision_request else None
zoom_cmd = _gate_zoom_in_pulse(
st,
# Keep new-request expiry tied to the frame that authorized
@@ -9180,7 +9223,10 @@
pulse_floor=(zoom_cmd if useful_reason == "useful" else 0.0),
pulse_timing=response_timing,
optics_observed_now=zoom_gate_now,
+ stop_trace=gate_stop,
)
+ if gate_stop:
+ zoom_zero_reason = gate_stop[-1]
if (
probe_start_candidate
and zoom_cmd > 0.0
@@ -9433,6 +9479,7 @@
or visual_control_coast != was_visual_control_coast
)
if visual_control_coast:
+ before_coast = zoom_cmd
adj_pan, adj_tilt, zoom_cmd = _bound_visual_coast_commands(
st,
adj_pan,
@@ -9463,7 +9510,11 @@
# Appearance continuity is sufficient for bounded steering only.
# It never authorizes an alarm without a current detector match.
alarm_eligible = False
+ if before_coast > 0.0 and zoom_cmd <= 0.0:
+ zoom_zero_reason = "visual_coast"
elif visual_control_stale:
+ if zoom_cmd > 0.0:
+ zoom_zero_reason = "visual_stale"
# Stale detector validation makes image-space steering unsafe, but a
# previously calculated edge-recovery zoom-out only widens the field
# of view. Preserve that bounded negative command while cancelling
@@ -9532,6 +9583,7 @@
# immediately by the forced command below.
if float(zoom_cmd) > 0.0:
zoom_cmd = 0.0
+ zoom_zero_reason = "final_brake"
st["zoom_prev_cmd"] = 0.0
st["stable_frames"] = 0
@@ -9673,7 +9725,33 @@
_arm_zoom_revalidation_locked(st, time.time(), 'visual_control_expired')
stop_ptz(cam_idx, source='stop', generation=int(st.get('ptz_generation', 0) or 0))
return
- _dispatch_owned_zoom_tracking(cam_idx, _PAN_SIGN * adj_pan, _TILT_SIGN * adj_tilt, zoom_cmd, force=force_track_ptz)
+ zoom_decision = None
+ if decision_request and zoom_cmd <= 0.0:
+ blockers = tuple(name for name, blocked in (
+ ("quality", not zoom_quality_ok),
+ ("framing", not zoom_safe),
+ ("followup", not followup_ready),
+ ("angle", not zoom_angular_safe),
+ ("center_sample_unknown", center_settled is None),
+ ("center_sample", center_settled is False),
+ ("center_history", center_settled is True and not center_locked_for_zoom),
+ ("track_history", not track_stable),
+ ("rearm", not zoom_rearm_ready),
+ ("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))),
+ ("focus", now < float(st.get("focus_settle_until", 0.0) or 0.0)),
+ ("coast", visual_control_coast),
+ ("stale", visual_control_stale),
+ ("brake", final_guard_active),
+ ) if blocked)
+ zoom_decision = (source_seq, decision_request, zoom_zero_reason, "+".join(blockers) or "-")
+ dispatch_kwargs = {"force": force_track_ptz}
+ if zoom_decision is not None:
+ dispatch_kwargs["zoom_decision"] = zoom_decision
+ _dispatch_owned_zoom_tracking(
+ cam_idx, _PAN_SIGN * adj_pan, _TILT_SIGN * adj_tilt, zoom_cmd, **dispatch_kwargs
+ )
if visual_control.enabled():
dispatch_at = time.monotonic()
samples = st.setdefault('control_dispatch_samples', [])
--- a/ptz_tracker_modular/ptz_io.py
+++ b/ptz_tracker_modular/ptz_io.py
@@ -1903,10 +1903,11 @@
source: Optional[str] = None,
generation: Optional[int] = None,
preset_floor_checked: bool = False,
+ zoom_decision: Optional[Tuple[Optional[int], int, str, str]] = None,
) -> None:
"""Serialize frame commands with the independent lens hard-stop timer."""
with _zoom_command_lock(cam_idx):
- _move_ptz_locked(
+ queued = _move_ptz_locked(
cam_idx,
pan,
tilt,
@@ -1915,6 +1916,15 @@
source=source,
generation=generation,
preset_floor_checked=preset_floor_checked,
+ zoom_decision=zoom_decision,
+ )
+ if zoom_decision is not None and queued is not None:
+ cmd_source, generation, seq, native_zoom = queued
+ frame, request, reason, blockers = zoom_decision
+ logger.info(
+ "[ZOOM DECISION] cam=%s frame=%s request=%s source=%s gen=%s seq=%s "
+ "queued_zoom=%s reason=%s blockers=%s",
+ cam_idx, frame, request, cmd_source, generation, seq, native_zoom, reason, blockers,
)
@@ -1929,7 +1939,8 @@
generation: Optional[int] = None,
preset_floor_checked: bool = False,
hard_stop: bool = False,
-) -> None:
+ zoom_decision: Optional[Tuple[Optional[int], int, str, str]] = None,
+) -> Optional[Tuple[str, int, int, int]]:
"""
Отправка relative/continuous PTZ-команды.
@@ -2105,6 +2116,9 @@
# The MOVE is already queued. Report watchdog setup separately;
# pretending that the MOVE was dropped would corrupt dedupe state.
logger.error("[ZOOM WATCHDOG] setup failed cam=%s: %s", cam_idx, exc)
+ if zoom_decision is not None:
+ return cmd_source, cmd_generation, move_seq, zoom_i
+ return None
def stop_ptz(cam_idx: int, *, source: str = "stop", generation: Optional[int] = None) -> None:
@@ -2253,6 +2267,7 @@
force: bool = False,
source: Optional[str] = None,
generation: Optional[int] = None,
+ zoom_decision: Optional[Tuple[Optional[int], int, str, str]] = None,
) -> None:
"""
Обёртка над move_ptz.
@@ -2295,6 +2310,7 @@
source=source,
generation=generation,
preset_floor_checked=True,
+ zoom_decision=zoom_decision,
)

@ -0,0 +1,71 @@
"""Offline frame-to-queue/ACK tests built on the established fake PTZ worker."""
from unittest.mock import patch
def build_cases(replay_base, controller, transport):
class FrameDecision(replay_base):
def test_frame_decision_joins_protective_stop_ack(self):
self.start_pulse()
request = self.st["zoom_step_physical_request_id"]
with patch.object(controller, "_shape_useful_zoom_pulse",
return_value=(0.0, "stale_optics")) as shape:
with self.assertLogs("PTZTracker.PTZ", level="INFO") as logs:
row = self.tick(.035)
self.assertGreater(shape.call_args.args[0], 0.0)
decision = self.log_fields(logs, "[ZOOM DECISION]")
delivery = self.log_fields(logs, "[ZOOM DELIVERY]")
self.assertEqual(decision["frame"], str(row["seq"]))
self.assertEqual(decision["request"], str(request))
self.assertEqual(decision["reason"], "stale_optics")
self.assertEqual(decision["queued_zoom"], "0")
self.assertEqual(decision["source"], "track")
self.assertEqual(decision["gen"], delivery["stop_gen"])
self.assertEqual(decision["seq"], delivery["stop_seq"])
self.assertEqual(delivery["request"], str(request))
self.assertEqual(delivery["stop_effective"], "(0,0,0)")
self.assertEqual(row["sent"][-1], (0, 0, 0))
def test_center_history_is_distinct_from_current_sample(self):
for settled, expected in ((True, "center_history"), (False, "center_sample")):
with self.subTest(settled=settled):
self.start_pulse()
def unsettled(*args, settled_sample, **kwargs):
settled_sample.append(settled)
return False
with patch.object(controller, "_update_zoom_center_lock", side_effect=unsettled):
with self.assertLogs("PTZTracker.PTZ", level="INFO") as logs:
row = self.tick(.035)
decision = self.log_fields(logs, "[ZOOM DECISION]")
blockers = decision["blockers"].split("+")
self.assertEqual(decision["frame"], str(row["seq"]))
self.assertIn(expected, blockers)
self.assertNotIn("center_sample" if settled else "center_history", blockers)
self.assertEqual(row["sent"][-1], (0, 0, 0))
def test_dropped_move_does_not_emit_decision(self):
with patch.object(transport.state.ptz_cmd_q, "put_nowait", side_effect=RuntimeError("queue full")):
with self.assertLogs("PTZTracker.PTZ", level="INFO") as logs:
transport.move_ptz_bounded(self.cam, .1, .05, 0., force=True,
zoom_decision=(104, 7, "permission", "center_history"))
self.assertTrue(any("[PTZ QUEUE] drop" in entry for entry in logs.output))
self.assertFalse(any("[ZOOM DECISION]" in entry for entry in logs.output))
def start_pulse(self):
for _ in range(24):
row = self.tick(.1)
if any(axes[2] > 0 for axes in row["sent"]):
self.assertGreater(self.st["zoom_step_physical_request_id"], 0)
return
self.fail("No authorized zoom pulse in the offline fixture")
def log_fields(self, logs, tag):
entries = [entry for entry in logs.output if tag in entry]
self.assertEqual(len(entries), 1, logs.output)
return dict(part.split("=", 1) for part in entries[0].split(tag, 1)[1].split()
if "=" in part)
return [FrameDecision(name) for name in (
"test_frame_decision_joins_protective_stop_ack",
"test_center_history_is_distinct_from_current_sample",
"test_dropped_move_does_not_emit_decision",
)]

@ -0,0 +1,250 @@
"""Replay the observed timing with synthetic intra-native demands."""
import json
from unittest.mock import patch
def build_floor_cases(boundary, controller_replay, pp, ptz_io, config, report_path, fixed,
*, threshold_diagnostics=False):
report = json.loads(report_path.read_bytes())
observed = [
(int(camera), decision)
for camera, episodes in report["episodes"].items()
for episode in episodes
for decision in episode["matched_decisions"]
if decision["reason"] == "pending_native_floor" and decision["result"] == "short"
]
class NativeFloor(boundary):
def seed(self, camera):
f = self.fixture(camera, "normal", 10, .34)
# The observed logs record native 10. This synthetic fraction has
# the same wire representation but a larger controller value.
f.st["zoom_step_pending_useful_cmd"] = .106
return f
def gate(self, f, command=.103, *, can=True, floor=None, timing=(.34, .40),
kind="normal", observed_now=None):
trace = []
value = pp._gate_zoom_in_pulse(
f.st, f.wall, command, can, pulse_kind=kind,
pulse_floor=command if floor is None else floor,
pulse_timing=timing,
optics_observed_now=f.wall if observed_now is None else observed_now,
stop_trace=trace,
)
return value, trace
def test_observed_native10_windows(self):
self.assertEqual(sorted(camera for camera, _ in observed), [19, 21])
for camera, row in observed:
with self.subTest(camera=camera, frame=row["frame"]):
self.assertEqual(row["native"], "10")
self.assertEqual(row["minimum"], "0.238s")
f = self.seed({19: 8, 21: 10}[camera])
timer = f.st["zoom_step_stop_timer"]
request = f.st["zoom_step_physical_request_id"]
deadline = f.st["zoom_step_until"]
hard = f.st["zoom_step_stop_started_mono"] + timer.delay
origin = f.st["zoom_step_put_started_mono"]
f._advance(float(row["duration"].removesuffix("s")))
shaped = f._shape(.103)
self.assertEqual(shaped, .103)
self.assertEqual(ptz_io._zoom_speed_to_int(shaped), 10)
self.assertEqual(ptz_io._zoom_speed_to_int(.106), 10)
with patch.object(config, "ZOOM_STEP_PULSE_SEC", .10):
self.assertEqual(pp._select_zoom_response_timing(
f.st, useful=False, hfov_deg=59., wide_hfov_deg=59.,
center_err=.02, margin=.45, image_rate=.01, requested_native=10
), (.10, .12))
timing = pp._select_zoom_response_timing(
f.st, useful=True, hfov_deg=59., wide_hfov_deg=59.,
center_err=.02, margin=.45, image_rate=.01, requested_native=10
)
self.assertEqual(timing, (.34, .40))
command, trace = self.gate(f, shaped, timing=timing)
self.assertEqual((command, trace), (.106, []) if fixed else (0., ["pending_native_floor"]))
pan, tilt, _ = row["requested"]
f._enqueue(command, pan=pan / 100, tilt=tilt / 100)
f._flush()
if not fixed:
self.assertEqual(f._zooms()[-1], 0)
self.assertEqual(f.st["zoom_step_last_delivery_result"], "short")
self.assertAlmostEqual(f.st["zoom_step_last_delivered_sec"],
float(row["duration"].removesuffix("s")))
continue
self.assertEqual(f._zooms()[-1], 10)
self.assertEqual(f.st["zoom_step_physical_request_id"], request)
self.assertEqual(f.st["zoom_step_until"], deadline)
self.assertEqual(f.st["zoom_step_put_started_mono"], origin)
active_timer = f.st["zoom_step_stop_timer"]
self.assertAlmostEqual(f.st["zoom_step_stop_started_mono"] + active_timer.delay, hard)
self.assertAlmostEqual(hard - origin, .40)
f._advance(hard - f.mono)
active_timer.fire()
self.assertEqual(f._zooms()[-1], 0)
self.assertEqual(f.st["zoom_step_physical_request_id"], 0)
self.assertNotEqual(f.st["zoom_step_last_delivery_result"], "short")
def test_stop_vetoes_keep_zero(self):
for name, state_change, gate_args, expected in (
("below_native10", {}, {"command": .0999999999}, "pending_native_floor"),
("floor_missing", {}, {"floor": 0.}, "pending_native_floor"),
("floor_invalid", {}, {"floor": float("nan")}, "pending_native_floor"),
("shorter_timing", {}, {"timing": (.10, .12)}, "pending_timing"),
("no_timing", {}, {"timing": None}, "pending_native_floor"),
("permission", {}, {"can": False}, "permission"),
("cancel", {"zoom_step_cancel_requested": True}, {}, "cancel_requested"),
("discard", {"zoom_step_discard_on_finalize": True}, {}, "pending_native_floor"),
("no_effect", {"zoom_no_effect_blocked": True}, {}, "no_effect_limit"),
("new_owner", {"ptz_generation": 5}, {}, "pending_native_floor"),
("new_track", {"track_started_at": 91.}, {}, "pending_native_floor"),
("new_request", {"zoom_step_physical_request_id": 7}, {}, "pending_native_floor"),
("no_delivery", {"zoom_step_physical_started_at": 0.}, {}, "pending_native_floor"),
("protective_stop", {"zoom_stop_obligation_active": True}, {}, "pending_native_floor"),
("watchdog_missing", {"zoom_step_stop_timer": None}, {}, "pending_native_floor"),
("watchdog_other_source", {"zoom_step_stop_source": "acquire"}, {}, "pending_native_floor"),
("probe", {"zoom_step_pending_kind": "probe"}, {"kind": "probe"}, "pending_native_floor"),
("reached_nominal_end", {}, {"observed_now": 101.}, "pending_native_floor"),
("real_zero", {}, {"command": 0.}, None),
):
with self.subTest(name=name):
f = self.seed(8)
f._advance(.05)
f.st.update(state_change)
value, trace = self.gate(f, **gate_args)
self.assertEqual(value, 0.)
self.assertEqual(trace, [expected] if expected else [])
f = self.seed(8)
f._advance(.05)
with patch.object(config, "ZOOM_STEP_MAX_IN_CMD", .104):
self.assertEqual(self.gate(f), (0., ["pending_native_floor"]))
class FrameFloor(controller_replay):
def test_track_frame_uses_native_continuation(self):
self.stack.enter_context(patch.object(config, "ZOOM_PROBE_ENABLE", False))
self.stack.enter_context(patch.object(config, "ZOOM_IDENTIFY_ENABLE", False))
shape = pp._shape_useful_zoom_pulse
def fraction(command, **kwargs):
demand = .103 if self.st.get("zoom_step_physical_request_id") else .106
return shape(demand if command > 0. else command, **kwargs)
with patch.object(pp, "_shape_useful_zoom_pulse", side_effect=fraction):
for _ in range(24):
row = self.tick(.1)
if any(axes[2] > 0 for axes in row["sent"]):
break
self.assertEqual(self.st["zoom_step_pending_useful_cmd"], .106)
deadline = self.st["zoom_step_until"]
with (patch.object(pp, "_gate_zoom_in_pulse", wraps=pp._gate_zoom_in_pulse) as gate,
patch.object(pp.logger, "info", wraps=pp.logger.info) as log):
row = self.tick(.06)
events = [call.args for call in log.call_args_list if "[ZOOM CONTINUE]" in call.args[0]]
self.assertEqual(len(events), int(fixed))
if events:
fmt, *values = events[0]
self.assertEqual(values[0:2], [self.cam, row["seq"]])
self.assertEqual(values[2], self.st["zoom_step_physical_request_id"])
self.assertEqual(values[3], self.st["ptz_generation"])
self.assertEqual(values[4:8], [10, .103, .106, deadline])
self.assertEqual(values[8:11], [.34, .40, .106])
self.assertIn("reason=same_native", fmt % tuple(values))
self.assertEqual(gate.call_args.args[2], .103)
if fixed:
self.assertEqual(self.st["zoom_step_until"], deadline)
self.assertEqual(self.fixture._zooms()[-1], 10)
else:
self.assertEqual(row["sent"][-1], (0, 0, 0))
self.assertEqual(self.st["zoom_step_last_delivery_result"], "short")
with patch.object(pp.logger, "info", wraps=pp.logger.info) as log:
self.tick(.05, detector=False, score=.1)
self.assertFalse(any("[ZOOM CONTINUE]" in call.args[0] for call in log.call_args_list))
class Thresholds(controller_replay):
def begin_normal_pulse(self):
self.stack.enter_context(patch.object(config, "ZOOM_PROBE_ENABLE", False))
self.stack.enter_context(patch.object(config, "ZOOM_IDENTIFY_ENABLE", False))
self.stack.enter_context(patch.dict(config.CAMERA_CONFIG[self.cam], {"zoom_fast_approach": False}))
for _ in range(24):
row = self.tick(.1)
if any(axes[2] > 0 for axes in row["sent"]):
return self.st["zoom_step_physical_request_id"]
self.fail("Normal pulse did not start")
def test_response_framing_reports_the_rejected_frame(self):
request = self.begin_normal_pulse()
select = pp._select_zoom_response_timing
def with_excess_rate(st, **values):
return select(st, **{**values, "image_rate": .041})
with (patch.object(config, "ZOOM_STEP_PULSE_SEC", .10),
patch.object(pp, "_select_zoom_response_timing", side_effect=with_excess_rate),
patch.object(pp.logger, "info", wraps=pp.logger.info) as log):
row = self.tick(.06)
events = [c.args for c in log.call_args_list if "[ZOOM THRESHOLD]" in c.args[0]]
self.assertEqual(len(events), 1, (row, log.call_args_list))
fmt, cam, frame, logged_request, generation, reason, raw = events[0]
self.assertEqual((cam, frame, logged_request, reason),
(self.cam, row["seq"], request, "response_framing"))
detail = json.loads(raw)
self.assertEqual(detail["check"], "framing")
self.assertEqual((detail["image_rate"], detail["image_rate_max"]), (.041, .04))
self.assertEqual(row["sent"][-1], (0, 0, 0))
with (patch.object(config, "ZOOM_STEP_PULSE_SEC", .10),
patch.object(config, "AIM_GIMBAL_FF_VIDEO_LATENCY_SEC", .45),
patch.object(config, "PTZ_LENS_STOP_DIRECT_TIMEOUT_SEC", .75)):
for change, check, observed, limit in (
({"hfov_deg": 40., "image_rate": .021}, "narrow_fov", "image_rate", "image_rate_max"),
({"margin": .35, "image_rate": .04}, "projected_margin", "projected_margin", "margin_min"),
):
trace = {}
inputs = dict(useful=True, hfov_deg=59., wide_hfov_deg=59.,
center_err=.01, margin=.45, image_rate=.01)
inputs.update(change)
state = {"zoom_response_effective_sec": .34}
self.assertEqual(select(state, **inputs), (0., 0.))
self.assertEqual(select(state, rejection=trace, **inputs), (0., 0.))
self.assertEqual(trace["check"], check)
if check == "narrow_fov":
self.assertGreater(trace[observed], trace[limit])
else:
self.assertLess(trace[observed], trace[limit])
def test_size_controller_reports_the_failed_angle_and_zero_stage(self):
request = self.begin_normal_pulse()
safe = pp._zoom_angular_motion_safe
def with_excess_pan(**values):
return safe(**{**values, "pan_error_deg": 9., "pan_rate_deg_s": 0.})
with (patch.object(pp, "_zoom_angular_motion_safe", side_effect=with_excess_pan),
patch.object(pp, "_zoom_approach_margin", return_value=None),
patch.object(config, "Z_DEADBAND", .99),
patch.object(config, "ZOOM_V3_CMD_MAX_STEP", .2),
patch.object(pp, "_Z_I", 0.),
patch.object(pp, "_Z_FF_GAIN", 0.),
patch.object(pp.logger, "info", wraps=pp.logger.info) as log):
row = self.tick(.06)
events = [c.args for c in log.call_args_list if "[ZOOM THRESHOLD]" in c.args[0]]
self.assertEqual(len(events), 1, (row, log.call_args_list))
fmt, cam, frame, logged_request, generation, reason, raw = events[0]
self.assertEqual((cam, frame, logged_request, reason),
(self.cam, row["seq"], request, "size_controller"))
detail = json.loads(raw)
self.assertEqual(detail["angular"]["pan_error_deg"], 9.)
self.assertIn("pan_error", detail["angular"]["failed"])
self.assertLess(detail["angular"]["pan_limit_deg"], 9.)
self.assertEqual((detail["size_error"], detail["after_minimum"]), (0., 0.))
self.assertEqual(row["sent"][-1], (0, 0, 0))
cases = [
NativeFloor("test_observed_native10_windows"),
NativeFloor("test_stop_vetoes_keep_zero"),
FrameFloor("test_track_frame_uses_native_continuation"),
]
if threshold_diagnostics:
cases += [
Thresholds("test_response_framing_reports_the_rejected_frame"),
Thresholds("test_size_controller_reports_the_failed_angle_and_zero_stage"),
]
return cases

@ -0,0 +1,9 @@
{
"baseline_tests_passed": 10,
"candidate_tests_passed": 13,
"historical_worker_cases_matched": 19,
"shared_controller_frames_identical": 23,
"real_camera_or_model_access": false,
"patch_apply_and_reverse_byte_exact": true,
"historical_decision_reason_recovered": false
}
Loading…
Cancel
Save