# Водопад

`src/soniks_client/waterfall/` делает две разные вещи: рисует PNG-водопад для
портала и проводит самостоятельный анализ сигнала, результат которого уезжает
как `metadata["signal"]`.

Пакет разложен по слоям — каждый следующий зависит только от предыдущего:

| Модуль | Что внутри | Зависимости |
|---|---|---|
| `dsp.py` | 12 приватных примитивов numpy: обнаружение всплесков, поиск пиков, полосы, k-means-2 | только `numpy` |
| `deviation.py` | `_estimate_deviation_v7` — единственный оценщик девиации, вызывает примитивы из `dsp` | `numpy`, `dsp` |
| `plot.py` | класс `Waterfall`: чтение `.dat`, отрисовка, метаданные. Весь matplotlib | `deviation`, `core` |
| `__init__.py` | реэкспорт `Waterfall` — импорт снаружи остаётся `from soniks_client.waterfall import Waterfall` | — |

Всё, кроме класса `Waterfall`, приватное: имена начинаются с `_` и наружу не
выдаются.

```{note}
До фазы 3 это был один файл на 2214 строк, в котором **около 900 строк не
вызывались ниоткуда** — остатки прежних поколений оценщика
(`_estimate_deviation_fft_only`, `_compute_collision_doppler_curve` и их
хелперы). Они удалены; оценщик теперь один, и запасных веток у него нет. Если
имя из старых обсуждений не находится — ищите его в истории git, а не в коде.
```

## Публичный интерфейс

```python
wf = Waterfall(datafile_path, output_path)   # читает .dat, может бросить исключение
wf.plot(vmin=None, vmax=None)                # обе границы необязательны
signal = wf.get_signal_metadata()            # dict | None
```

Конструктор сразу читает файл и проверяет, что данные есть. Три исключения:

| Исключение | Когда |
|---|---|
| `WaterfallFileError` | Файл не найден, это не файл, заголовок обрезан или не читается |
| `EmptyWaterfallError` | Файл прочитан, но массив отсчётов пуст |
| `TimestampError` | Метка времени в заголовке не разбирается |

Вызывающий код — `post_processing.build_waterfall()` — ловит все три и продолжает
выгрузку без водопада: отсутствие картинки не повод терять аудио и кадры. Сырой
`.dat` при этом **остаётся на диске** — он удаляется только после успешного
`plot()`, чтобы упавшее построение можно было воспроизвести.

`get_signal_metadata()`, вызванный **до** `plot()`, возвращает `None`: анализ
наполняется в ходе отрисовки.

## Формат файла

Потоковый граф пишет сырой водопад в бинарный `.dat` с заголовком
фиксированного размера, затем строками спектра:

| Поле | Тип | Смысл |
|---|---|---|
| `timestamp` | `S32` | Метка времени начала, ASCII |
| `nchan` | `>i4` | Число частотных каналов (ширина БПФ) |
| `samp_rate` | `>i4` | Частота дискретизации |
| `nfft_per_row` | `>i4` | Сколько БПФ усреднено в одну строку |
| `center_freq` | `>f4` | Центральная частота |
| `endianness` | `<i4` | Порядок байтов остальных данных |

Далее — записи `(tabs: i8, spec: f4[nchan])`: относительная метка времени и
строка спектра. Порядок байтов определяется полем `endianness`, поле
`center_freq` при этом всегда читается big-endian — так пишет граф.

Из этого восстанавливаются ось времени (`trel`) и ось частот (`freq`,
симметричная относительно нуля в диапазоне ±`samp_rate/2`).

Файл крупный и по умолчанию удаляется после отрисовки
(`OBSERVATION__REMOVE_WATERFALL_RAW_FILES=True`). Для отладки алгоритмов
выключите удаление — иначе воспроизвести обработку будет не на чем.

## Отрисовка

`plot()` рисует PNG размером `WATERFALL__WIDTH` × `WATERFALL__HEIGHT` дюймов с
раскладкой из `WATERFALL__GRIDSPEC` (полотно плюс цветовая шкала).

Границы динамического диапазона подбираются, только если хотя бы одна из них не
передана в `plot()`. Штатный вызов из `post_processing()` идёт без аргументов,
поэтому настройки ниже действительно работают:

* `WATERFALL__AUTORANGE=False` (по умолчанию) — фиксированные
  `WATERFALL__MIN_VALUE` / `MAX_VALUE`, по умолчанию −110 и −50 дБ;
* `AUTORANGE=True` — робастная оценка уровня шума по данным (сигма-клиппинг).
  Отсчёты фильтруются `np.isfinite` **и** порогом `WATERFALL__THRESHOLD`
  (−200 дБ): `isfinite` убирает `-inf` пустых бинов, порог — заведомо
  нефизические уровни. Если после фильтрации осталось меньше
  `WATERFALL__MIN_VALID_SAMPLES` (10000) отсчётов, берутся
  `DEFAULT_MIN_VALUE` / `DEFAULT_MAX_VALUE`, а в лог уходит `warning`.

`WATERFALL__HELP_LINES=True` добавляет поверх водопада вспомогательную сетку.

## Анализ сигнала

`get_signal_metadata()` форматирует накопленный в `self.analysis` результат в
плоский словарь под схему портала. Ключи со значением `None` выбрасываются,
поэтому состав ответа зависит от того, что удалось измерить. Если анализа не
было (`plot()` ещё не вызывался), метод возвращает `None` целиком.

Группы измерений:

| Группа | Ключи |
|---|---|
| Отношение сигнал/шум | `snr_db`, `snr_quality`, `noise_db`, `noise_std_db`, `peak_db`, `peak_freq_hz` |
| Модуляция | `modulation`, `n_spec_peaks`, `valley_depth_db` |
| Девиация | `deviation_hz`, `deviation_uncertainty_hz`, `deviation_confidence`, `deviation_method`, `f_low_hz`, `f_high_hz` |
| Полоса | `bw_3db_hz`, `bw_10db_hz`, `bw_20db_hz`, `bw_26db_hz`, `bw99_hz`, `sigma_rms_hz` |
| Активность | `n_bursts`, `n_valid_rows`, `saturated` |
| Частота | `carrier_offset_hz`, `ppm_error`, `drift_ppb`, `measured_freq_mhz` |
| Прочее | `method` — текстовая пометка о том, каким путём получен результат |
| Геометрия водопада | `samp_rate_hz`, `bin_hz`, `nchan`, `nfft_per_row`, `noise_dbhz` |

Величины с размерностью — **строки с единицами измерения** (`"1234.5 Hz"`,
`"-98.3 dB"`, `"437.050000 MHz"`, `"1.234 ppm"`), так их ожидает портал; при
изменении формата сломается отображение на стороне сайта. Счётчики
`n_spec_peaks`, `n_bursts`, `n_valid_rows` уходят **числами**, `saturated` —
**bool** (опора цели упёрлась в край полосы: сигнал шире водопада или приёмник
перегружен; порталу — считать долю таких проходов, Фаза 4), а `modulation`,
`deviation_method` и `method` — текстом как есть.

```{note}
Ключ `bw99_hz` в ответе портала читается из `bw_99_hz` словаря оценщика.
Одноимённый `bw99_hz` внутри самого оценщика — legacy: ему никто не присваивает
значения, и он всегда `None`.
```

Геометрия берётся из заголовка `.dat`, а не из оценщика, поэтому есть даже там,
где анализ не состоялся. Она нужна порталу: полоса водопада равна `out_samp_rate`
графа и зависит от режима (48 кГц у FM, 57.6 кГц у FSK 9600, 76.8 кГц у BPSK,
66.56 кГц у APT/SSTV, 200 кГц у PHASMA) при постоянном БПФ на 1024 точки, так
что `noise_db` — мощность в бине — между режимами несравним. `noise_dbhz` =
`noise_db − 10·lg(bin_hz)` — плотность шума, сопоставимая между режимами и
станциями с разной геометрией (Фаза 3.3 в [дорожной карте сети](../roadmap-network.md)).
Формула точна для белого шума при прямоугольном окне и масштабе `1/fft_size`
`waterfall_sink`; смещение режима Max Hold (`10·lg(H_n)` по `nfft_per_row`,
от 3.2 дБ при 4 БПФ на строку до 5.5 дБ при 19) не вычитается — режим sink в
заголовке не записан.

Практическая польза: `ppm_error` и `carrier_offset_hz` показывают уход опорного
генератора вашего приёмника. Систематическое смещение из наблюдений — готовое
значение для `FLOWGRAPH__PPM_ERROR`.

## Валидация

Оценщик проверяется на синтетических спектрограммах в `tests/test_deviation.py`.
Генератор `_synthetic_spectrum()` повторяет то, что пишет `waterfall_sink`:
мощность комплексного гауссова шума в бине распределена экспоненциально, Max
Hold берёт максимум по `nfft_per_row` БПФ, итог в дБ; тона — гауссовы лепестки
в линейной мощности. Отсюда проверяемое смещение полки Max Hold — `10·lg(H_n)`,
4.34 дБ при 8 БПФ на строку.

Каждый тест закрепляет одну ветку конвейера из шапки `deviation.py`: k-means по
пикам строк (тона ±Δf **через строку**), пара пиков усреднённого спектра (оба
тона в каждой строке, один сильнее), σ_RMS для одного лепестка, CW, `weak/noise`,
смещение несущей и ppm, изоляция помехи, насыщение, guard на малом водопаде —
и ключевое утверждение Фазы 3.3: один N0 при разной ширине бина даёт один
`noise_dbhz`.

Потолки, которые тесты закрепляют как есть, а не чинят:

* `interferer_rejected` значит «оценён сигнал не по центру», а не «помеха
  отброшена»: слабая далёкая помеха отбрасывается молча с флагом `False`,
  сильная — измеряется с флагом `True`;
* непрерывный сигнал всегда классифицируется как `CW Morse (bursty …)`: при всех
  горячих строках `_detect_burst_rows` находит меньше пяти, фолбэк по 75-му
  перцентилю даёт `bursty_fraction` 0.25, ветка `CW continuous` недостижима;
* критерий насыщения `bw99 > 0.85·samp_rate` недостижим из-за среза ±0.45
  (шапка обещает `/2`); `saturated` ловит только касание края опорой цели, а
  широкий центрированный сигнал уходит в `weak/noise` — робастный шум берёт
  медиану самого сигнала;
* legacy-ключи словаря оценщика (`bw99_hz`, `bw95_hz`, `w30_*`, `delta_f_*_hz`)
  никем не присваиваются.

## Работа с модулем

* Правка алгоритма — это `deviation.py`; правка отрисовки — `plot.py`. Общие
  численные примитивы в `dsp.py` трогайте в последнюю очередь: их использует
  оценщик в десятке мест.
* Аннотации типов здесь почти отсутствуют (в отличие от остального кода), и
  autodoc покажет голые сигнатуры. Это известное состояние.
* Приватные хелперы в [Справочник API](../api/index.md) не выводятся —
  документируются только `Waterfall`, `plot()` и `get_signal_metadata()`.
* Для воспроизводимой отладки сохраняйте `.dat`-файлы:
  `OBSERVATION__REMOVE_WATERFALL_RAW_FILES=False`.