Waterfall Viewer

Просмотрщик и анализатор waterfall-спектрограмм гамма-спектрометра: длительная запись (суточный лог, десятки тысяч спектров) разворачивается в 3D-поверхность и 2D-карту Время × Энергия, где короткий всплеск активности или дрейф фона виден сразу — без перебора сотен спектров вручную. Любой момент записи раскрывается в обычный спектр, любая энергетическая линия — в график её хода во времени.

Поддерживаемые форматы: AtomSpectra (.aswf, нативный бинарный waterfall прибора, версии v1–v5 — включая температуру детектора, GPS и per-row CRC32), RadiaCode (.rcspg, JSON — проверено на RadiaCode-110) и ANSI N42.42-2011 (.n42/.xml). Калибровка энергии берётся из самого файла (полином из заголовка .aswf / coefficients / CoefficientValues).

Описание и документация

Что	Где
Обзор программы и всего семейства инструментов (витрина с иллюстрациями)	vibeengineering-llc.github.io/demo-web-pages/atomspectra-waterfall-family
Встроенная справка — 15 разделов по всем функциям	в приложении: меню Справка → Справка
Установка с нуля (без опыта Python)	INSTALL.md
Формат данных .aswf (спецификация v1–v5)	ASWF_FORMAT.md
Известные проблемы и совместимость	KNOWN_ISSUES.md
Готовые сборки (Windows exe)	Releases

Источник данных-прибора: atomspectra-waterfall-esp32 (WiFi-шлюз спектрометра). Архитектурные идеи — по мотивам InterSpec (Sandia).

Возможности

Просмотр спектрограммы

• 3D-поверхность Время × Энергия × Отсчёты (OpenGL, вращение ЛКМ, зум колесом, панорама СКМ), секущие плоскости по времени / энергии / отсчётам.
• 2D-карта Время × Энергия с прямоугольной выборкой (ROI) и палитрами (Jet и др.).
• Z-шкала отображения — переключатель контраста (линейная / √ / log10) для 2D-карты и 3D-рельефа; регулировки усиления, гаммы, отсечки, освещения, сглаживания.

Анализ

• Срезы (по времени) — спектр выбранного временного среза.
• Сечения (по каналу/полосе) — временной ряд интенсивности в выбранной полосе энергий (энергоокно с пресетами линий, напр. Cs-137 662 кэВ), кривая суммарного cps.
• Выборки (ROI) — спектр окна времени + временной ряд полосы + суммарные отсчёты в прямоугольнике.
• Библиотека нуклидов — выбор нуклида/семейства (21 нуклид, данные LSRM СпектраЛайн) подсвечивает энергии гамма-линий вертикальными маркерами; фильтр по интенсивности.
• Аналитика — поиск и идентификация пиков, FWHM(E), фон/MDA, анализ цепочек распада.

Данные прибора (вкладка «Прибор»)

• Графики мощности дозы (мкЗв/ч) и температуры детектора (°C) по времени, с переключением единиц времени (с / мин / ч).
• GPS-трек — точки маршрута, окрашенные по скорости счёта; экспорт в CSV всех рядов.
• Наложение линии температуры на 2D-карту (отключаемо).

Целостность и надёжность

• Отчёт о целостности при открытии файла: число срезов/каналов, суммарные отсчёты, длительность, проверка per-row CRC32 (ASWF v4/v5), версия формата, наличие данных прибора; сохраняется в .txt.
• Масштаб без верхнего предела — суточные записи (десятки тысяч срезов) грузятся потоково (lxml.iterparse, ограниченная память), 3D и 2D рендерятся через LOD-прорежку (Spectrogram.downsample).

Скачать готовый дистрибутив

Готовый exe для Windows — на странице Releases.
Скачайте waterfall-viewer-vX.Y.Z-windows-x64.zip, распакуйте и запустите waterfall-viewer/waterfall-viewer.exe.
Python устанавливать не нужно.

Установка из исходников

Подробная установка с нуля (без опыта Python) — в INSTALL.md. Известные проблемы и совместимость — в KNOWN_ISSUES.md.

Вариант A — venv (изолированно, рекомендуется):

cd "путь\к\waterfall-viewer"
python -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt

Вариант B — глобально (без venv):

py -3.14 -m pip install -r requirements.txt

Проще всего — просто запустить run.bat: при первом запуске он сам доустановит недостающие зависимости в пользовательский site-packages (pip install --user, без прав администратора) и затем откроет приложение. Первый запуск из-за установки занимает ~минуту (в окне будет Installing dependencies on first run...). Ручная установка (Вариант A/B выше) нужна только если хочется изолированный .venv либо автоустановка недоступна (нет сети).

run.bat сам выберет интерпретатор: при наличии .venv запустит из него, иначе — глобальный Python 3.14.

Запуск

run.bat                              REM пустое окно, файл открыть через меню
run.bat "C:\путь\waterfall (7).n42"  REM сразу открыть файл

или напрямую:

.venv\Scripts\python.exe -m awf "C:\путь\к\файлу.n42"

Управление

Действие	Как
Открыть файл	Меню Файл → Открыть… (Ctrl+O)
Отчёт о целостности	Показывается при открытии; повторно — Файл → Отчёт целостности…
Вращать 3D	Левая кнопка мыши + перемещение
Зум 3D	Колесо мыши
Панорама 3D	Средняя кнопка мыши
Выборка (ROI)	Вкладка 2D Карта → тянуть жёлтый прямоугольник; срезы справа обновляются
Z-шкала	Тулбар Вид → Z-шкала (линейная / √ / log10) — меняет контраст 2D и 3D
Нуклиды	Док Нуклиды (слева) → галочки на нуклидах; энергии линий подсвечиваются на графике спектра
Данные прибора	Вкладка Прибор — доза, температура, GPS, экспорт CSV
Единицы времени	Тулбар Время: (с / мин / ч) — синхронно на всех графиках
Температура на 2D	Тулбар Темп. (2D) — наложение линии температуры на карту

Архитектура

awf/
  model/spectrogram.py   — численное ядро: Calibration (полиномиальная), Spectrogram
                           (срезы, сечения, ROI-суммы, LOD-downsample, дозы/температура/GPS). Без Qt.
  io/aswf_loader.py       — загрузчик AtomSpectra (.aswf v1–v5): магия ASWF + JSON-заголовок +
                           self-describing row_fields; RLE, baseline, per-row CRC32, температура.
  io/n42_loader.py       — потоковый загрузчик N42 (CountedZeroes-декодер; iterparse для суточных файлов).
  io/rcspg_loader.py     — загрузчик RadiaCode (.rcspg, JSON): pulses->counts, calib из coefficients.
  io/nuclide_lib.py      — библиотека нуклидов: парсер LSRM .lib (win-1251 XML) + наш JSON.
  data/nuclides.json     — встроенная библиотека (21 нуклид, энергии/интенсивности гамма-линий).
  analysis/              — поиск/идентификация пиков (curve_fit), деконволюция, цепочки распада, MDA.
  ui/view3d.py           — Waterfall3DView (GLViewWidget + GLSurfacePlotItem).
  ui/panels.py           — HeatmapPanel (2D + ROI + оверлей температуры), SlicePanel (спектр + ряд + маркеры).
  ui/device_data_panel.py— вкладка «Прибор» (доза/температура/GPS + CSV).
  ui/integrity_dialog.py — диалог отчёта о целостности (CRC32).
  ui/nuclide_panel.py    — NuclidePanel (выбор нуклидов/семейств, фильтр интенсивности).
  ui/zscale.py           — общий apply_z_scale (linear/sqrt/log10) для 2D и 3D.
  ui/main_window.py      — MainWindow + фоновая загрузка (QThread).
  __main__.py            — точка входа (python -m awf).

Численное ядро отделено от UI: его можно тестировать и использовать без графики.

Тесты

Слой данных покрыт автотестами (опорные значения — независимый оракул из байтов реального файла):

.venv\Scripts\python.exe -m pytest -q

(797 тестов: ISO-длительности, CountedZeroes, полиномиальная калибровка, загрузчики N42/ASWF v1–v5/RCSPG, per-row CRC32, температура/GPS/доза, библиотека нуклидов, поиск и идентификация пиков, анализ цепочек распада, сегментация, i18n и др.)

Графические модули проверяются smoke-скриптами в scripts/ (строят виджеты на реальном образце без GUI-взаимодействия).

Стек

Python 3.12 / 3.14 · numpy · scipy · lxml · PySide6 (Qt) · pyqtgraph + PyOpenGL.

Лицензия

MIT © 2026 Verter73.