# Данные на диске

Программа хранит данные в трёх местах: наборы предобработки и наборы данных — в
`python_app/data/` (или в каталоге, выбранном в **Path**), своё рабочее состояние — в
`python_app/runtime/`, обмен между процессами — в разделяемой памяти `/dev/shm`.
Каталоги `python_app/data*` и `python_app/runtime` в git не попадают.

> **Внимание.** Наборы калибровки и референса в `python_app/data/` — незаменимые
> измерения. При обновлении программы их переносит `update.sh`; при ручном переносе
> копируйте этот каталог целиком.

## Где что лежит

| Путь | Что | Кто пишет |
| --- | --- | --- |
| `python_app/data/s21_calibration/<radar_key>/<имя>.npz`, `.json` | наборы калибровки | окно предобработки |
| `python_app/data/s21_reference/<radar_key>/<имя>.npz`, `.json` | наборы референса, в том числе `tmp_reference` | окно предобработки, временный референс |
| `python_app/data/s21_object_calibration/<radar_key>/<имя>.npz`, `.json` | калибровки по объекту | окно калибровки по объекту |
| `python_app/data/preview_png/<вид>/<имя>/<radar_key>/i<вход>_o<выход>.png` | картинки развёрток при съёме по вариантам радара | окно предобработки |
| `<Path>/<набор данных>/` | снимки и записи на диск; по умолчанию `python_app/data/snapshots` | **Save Last 1000**, **Save S21 JSON**, **Start + Record to Disk** |
| `python_app/runtime/` | рабочее состояние программы (ниже) | программа |
| `/dev/shm/<имя кольца>` | кольца разделяемой памяти | процессы конвейера |
| `/tmp/radar_system.lock` | блокировка единственного экземпляра | `start.sh` |
| `radar.rph_radar.tty_path`, например `/tmp/ttyADC_data` | ссылка на псевдотерминал коллектора E-502 | `rph_radar_collector` |
| `/etc/udev/rules.d/99-radar-librevna.rules` | доступ к LibreVNA по USB | `start.sh` |
| `/etc/systemd/system/radar.service`, `/etc/sudoers.d/radar` | служба и право её перезапускать | `deploy/install-daemon.sh` |

Все файлы JSON и наборы программа записывает через временный файл и замену, а важные
ещё и сбрасывает на диск (fsync). Оборванная запись оставляет прежний файл целым;
от неё может остаться временный файл вида `.<имя>.<32 знака>.tmp`, а от оборванного
сохранения набора данных — каталог `.<имя набора>.<32 знака>`; их можно удалить.

## Наборы предобработки

Набор лежит в каталоге своего вида и ключа радара (глава
[Файл конфигурации](configuration.md)) и состоит из двух файлов:

| Файл | Содержимое |
| --- | --- |
| `<имя>.npz` | архив NumPy без сжатия: для каждой пары `freq_i<вход>_o<выход>` (частоты, float32) и `s21_i<вход>_o<выход>` (S21, complex64), плюс `metadata_json` — описание набора |
| `<имя>.json` | то же описание в читаемом виде |

Описание: `collection_id`, `monotonic_ns`, `capture_start_ns`, `capture_end_ns`,
список `combos` (вход, выход, окно съёма, имена массивов) и `metadata`. У калибровки
по объекту в `metadata` записано, при каких условиях она снята: ключ радара,
геометрия, имя и хеш набора калибровки, настройки расчёта, координаты отражателя,
параметры антенн, диагностика фаз и пары без поправки (`unchanged_combos`).

Старые наборы без `metadata_json` читаются по файлу `.json`; лишние массивы (например,
S11) пропускаются.

Имя набора — любая строка, кроме пустой, `.`, `..` и строк с `/` или `\`. Существующее
имя программа не перезаписывает; исключение — `tmp_reference`, который заменяется при
каждом съёме. Перед записью проверяется, что пары не повторяются, массивы одной длины
и значения конечны.

## Наборы данных

Набор данных — каталог со снимком истории (**Save Last 1000**) или записью на диск
(**Start + Record to Disk**). Имя каталога — `<префикс>_<Name>`, например
`librevna_multi_0.001-6GHz_201pts_-10dBm_run_A`; символы кроме латиницы, цифр, `.`,
`_` и `-` заменяются на `_`. Префикс: модель, полоса в единицах большей границы,
число точек (у радиофотонного радара — `adc`) и мощность. Пустое имя —
`snapshot_<ГГГГММДД>_<ЧЧММСС>` по UTC. Существующий каталог программа не трогает.

```text
<набор данных>/
  config_profile.json          профиль, с которым сняты данные
  processing_settings.json     ревизии настроек обработки
  raw/                         сырые коллекции
    0000_id<номер>_ns<время>/
  preprocessed/                предобработанные коллекции
  results/                     результаты обработки
```

Коллекции внутри стадии нумеруются с нуля. Время в имени каталога — метка своей
стадии, поэтому у одной коллекции оно разное в `raw`, `preprocessed` и `results`.
Сопоставляйте стадии по паре `collection_id` и `capture_start_ns` из `meta.json`.

Каталог коллекции в `raw/` и `preprocessed/`:

| Файл | Содержимое |
| --- | --- |
| `i<вход>_o<выход>_freq.npy` | частоты, float32 |
| `i<вход>_o<выход>_s21.npy` | S21, complex64 |
| `meta.json` | `collection_id`, `monotonic_ns`, `capture_start_ns`, `capture_end_ns`, `trace_count`, список трасс с их окнами съёма и именами файлов |

Каталог коллекции в `results/` содержит `meta.json` (номер, время обработки,
`settings_revision`, окно съёма, использованная скорость `speed_m_s`, список
результатов) и массивы результатов. Результаты всей коллекции — файлы
`collection_<NNN>_<имя>_kind<вид>_<поле>.npy`, результаты пары — в подкаталоге
`block_<NNN>_i<вход>_o<выход>/`.

| Вид | Поля |
| --- | --- |
| 1 — трасса | `freq` float32, `trace` complex64 |
| 2 — число | `scalar` float32 |
| 3 — изображение | `x_axis`, `y_axis` float32, `image` float32 размером (строки по y, столбцы по x) |
| 4 — таблица | `table` float32 (строки, столбцы) |

| Режим | Что сохраняется |
| --- | --- |
| pass-through | для каждой пары `pass_through` (вид 1): частота и S21 |
| B-scan | для каждой пары `bscan` (вид 1): в поле `freq` — дальность в метрах, в `trace` — значение (мнимая часть 0) |
| GPR | `gpr_accumulator` (вид 3): карта, оси X и Z; `gpr_points` (вид 4): строки `[x_m, z_m, score]` |
| 3D SAR | `sar3d_front`, `sar3d_side`, `sar3d_top`, `sar3d_oblique` (вид 3); `sar3d_oblique_basis`; `sar3d_peak` `[уровень, X, Y, Z]`; `sar3d_background` `[отношение, 6, 8.5]`; `sar3d_objects` `[X, Y, Z, уровень]` и `sar3d_marks` `[класс, X0, X1, Y0, Y1, Z0, Z1]` или `sar3d_target_width` `[X, Y, Z]`; `sar3d_status` `[код, байты текста UTF-8]` |

Классы рамок 3D SAR: 0 — очень низко, 1 — на земле, 2 — над землёй, 3 — у края. Коды
состояния 3D SAR: 0 — посчитано, 1 — нет сигнала, 2 — ошибка, 3 — нет CUDA.

`processing_settings.json` — словарь «номер ревизии → настройки обработки» в формате
`processing_live.json`: по `settings_revision` из `meta.json` результата видно, с
какими настройками он посчитан. При ручном сохранении туда попадают все ревизии
текущего сеанса, при записи — только использованные. `config_profile.json` — полный
профиль; разделы радара, ключей, пар, предобработки и геометрии взяты из конфигурации,
с которой шёл сбор, даже если потом загрузили другой профиль.

### Запись на диск

**Start + Record to Disk** создаёт каталог сразу и пишет в него коллекции, снятые
после нажатия; счётчик считает результаты. Данные копятся порциями по 200 коллекций и
уходят в очередь записи на 8 порций; каждая коллекция появляется на диске целиком.
Если диск не успевает и очередь заполнилась, запись останавливается с
`Disk recording stopped because the writer could not keep up`; записанное остаётся.
Если сбор так и не начался и ничего не пришло, каталог удаляется.

### Экспорт S21 JSON

**Save S21 JSON** создаёт в `<Path>/<набор данных>/` по файлу на пару
`<имя набора>_i<вход>_o<выход>_s21_vna_bscan_history.json` и профиль
`vna_config_profile.json`. Основные поля файла:

| Поле | Что |
| --- | --- |
| `format` | `"vna-system-history-v1"` |
| `input_index`, `output_index`, `channel` | пара и канал (`"s21"`) |
| `primary_stage` | `"preprocessed"` |
| `sweep_history` | список коллекций: `timestamp`, `sweep_points` (сырая развёртка, пары `[re, im]`), `calibrated_points` (предобработанная), `reference_points` (всегда пусто), `vna_config` (начало, конец, число точек) |

`timestamp` — время конца съёма развёртки этой пары (если его нет — коллекции) в
секундах монотонных часов компьютера (отсчёт от его загрузки), а не дата и время. Сырая и
предобработанная развёртки
сопоставляются по паре номер — начало съёма; если пары нет, массив пуст.

### Как открыть данные в Python

```python
import json
from pathlib import Path

import numpy as np

# Набор предобработки
with np.load("python_app/data/s21_reference/<radar_key>/<имя>.npz", allow_pickle=False) as archive:
    meta = json.loads(str(archive["metadata_json"].item()))
    for combo in meta["combos"]:
        frequency, s21 = archive[combo["freq_key"]], archive[combo["s21_key"]]

# Предобработанные коллекции набора данных
from python_app.storage.npz.vna_history_json import collection_directories

for directory in collection_directories(Path("<набор данных>") / "preprocessed"):
    meta = json.loads((directory / "meta.json").read_text())
    for trace in meta["traces"]:
        frequency = np.load(directory / trace["freq_file"])
        s21 = np.load(directory / trace["s21_file"])

# Результаты (например, карта GPR)
for directory in collection_directories(Path("<набор данных>") / "results"):
    meta = json.loads((directory / "meta.json").read_text())
    for payload in meta["collection_payloads"]:
        if payload["name"] == "gpr_accumulator":
            image = np.load(directory / payload["image_file"])
```

`collection_directories` возвращает каталоги коллекций по порядку номеров. Загрузить
набор данных обратно в окно программы нельзя: он предназначен для обработки
отдельно.

## Рабочие файлы

Каталог `python_app/runtime/` программа создаёт и ведёт сама.

| Файл | Что | Можно удалить |
| --- | --- | --- |
| `gui_session_state.json` | путь последнего профиля: с него программа стартует | да; программа стартует с корневого профиля. Это и способ выйти из ситуации, когда запомненный профиль не даёт программе запуститься |
| `processing_live.json` | живые настройки процессора (глава [Файл конфигурации](configuration.md)) | да; программа запишет его заново |
| `run_config.json` | рабочая копия профиля последнего **Start** | при остановленном сборе |
| `s21_calibration_bundle.bin`, `s21_reference_bundle.bin`, `s21_object_calibration_bundle.bin` | выбранные наборы в формате для препроцессора, пересобираются при каждом **Start** | при остановленном сборе |
| `supervisor_children.pids` | номера процессов конвейера: если программа упала, следующий запуск завершает оставшиеся | когда процессы конвейера не работают |
| `logs/` | журналы (ниже) | при закрытой программе |

## Журналы

| Где | Что |
| --- | --- |
| `python_app/runtime/logs/radar.log` и `radar.log.1` … `radar.log.5` | журнал программы: то же, что в окне журнала, строки `дата время \| уровень \| источник \| сообщение`. Файл до 2 МиБ, хранятся пять предыдущих |
| `python_app/runtime/logs/acquisition.out.log`, `acquisition.err.log` | вывод процесса сбора, в том числе ожидание приборов и сообщения коллектора E-502 (`Collector: …`) |
| `python_app/runtime/logs/data_preprocessor.*.log`, `data_processor.*.log` | вывод препроцессора и процессора: отброшенные коллекции, отклонённый live-файл, сообщения 3D SAR (`sar3d: …`) и локатора (`locator: …`) |
| `*.prev` рядом | вывод прошлого запуска процесса или начало текущего, если файл превысил 8 МиБ |
| `journalctl -u radar.service` | при работе службой: вывод программы, включая строки `[start.sh] …` |

Уровень записей задаёт `logging.level` профиля или список **Level** в окне.
Подробности ошибки, показанной окном (например, трассировка вызовов), видны в окне
ошибки и в окне журнала, а в `radar.log` попадает само сообщение. Если процесс конвейера
завершился сам,
отчёт с последними 16 КиБ его вывода попадает в журнал программы. Раз в 50 замеров
программа пишет строку `metrics: <стадия> n=… avg=…ms min=…ms max=…ms` со временем
сбора, обработки и отрисовки.

## Разделяемая память

Кольца лежат в `/dev/shm` под именами из раздела `rings` профиля (без начальной `/`).
При ёмкости 50 и слоте 2 МиБ кольцо занимает около 100 МиБ виртуальной памяти, но
страницы выделяются только по мере записи. Кольца создаёт первый запустивший их
процесс с правами 0660 и при выходе не удаляет. `./start.sh --clean-shm` удаляет
кольца `/radar_raw`, `/radar_raw_tap`, `/radar_preprocessed`, `/radar_preprocessed_tap`,
`/radar_results` и те же имена с окончанием `_rph_radar`. Кольца с окончанием
`_simulator` он не трогает, а их используют корневой профиль, оба профиля симулятора и
оба примера с переключением стимула (`run_config_librevna_multi_per_point*.example.json`).
Их удаляйте вручную при закрытой программе: `rm /dev/shm/radar_*_simulator`.

> **Внимание.** Если программу хоть раз запустили от root (например, тесты через
> `sudo`), кольца станут принадлежать root, и обычный пользователь получит отказ в
> доступе. Удалите их при закрытой программе: `sudo rm -f /dev/shm/radar_*`.