Waterfall Viewer

Просмотрщик и анализатор waterfall-спектрограмм гамма-спектрометра. 3D-просмотр с вращением и зумом, 2D-карта Время×Энергия, срезы / сечения / прямоугольные выборки.

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

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

Возможности v1

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

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

Готовый exe для Windows — на странице Releases.
Скачайте waterfall-viewer-vX.Y.Z-win64.zip, распакуйте и запустите 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
Нуклиды	Док Нуклиды (слева) → галочки на нуклидах; энергии линий подсвечиваются на графике спектра

Архитектура

awf/
  model/spectrogram.py   — численное ядро: Calibration (полиномиальная), Spectrogram
                           (срезы, сечения, ROI-суммы, LOD-downsample). Без зависимости от Qt.
  io/n42_loader.py       — потоковый загрузчик N42 (CountedZeroes-декодер: векторный + скалярный
                           эталон; iterparse с освобождением памяти для суточных файлов).
  io/aswf_loader.py      — загрузчик AtomSpectra (.aswf): магия ASWF + uint32 len + JSON-заголовок +
                           матрица uint16 LE (channels на строку); calib/interval/t0 из заголовка.
  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 нуклид, энергии/интенсивности гамма-линий).
  ui/view3d.py           — Waterfall3DView (GLViewWidget + GLSurfacePlotItem).
  ui/panels.py           — HeatmapPanel (2D + ROI), SlicePanel (спектр + временной ряд + маркеры нуклидов).
  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

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

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

Стек

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

Дорожная карта (v2)

Дальнейшие улучшения поиска и идентификации пиков, калибровка по реперам, экспорт результатов.

Лицензия

MIT © 2026 Verter73.