new project structure

rfg_adc_plotter/visualization/matplotlib_backend.py

@@ -0,0 +1,513 @@
+"""
+Визуализация данных с использованием matplotlib.
+"""
+
+import sys
+import threading
+import time
+from queue import Empty, Queue
+from typing import Optional, Tuple
+
+import numpy as np
+
+try:
+    import matplotlib
+    import matplotlib.pyplot as plt
+    from matplotlib.animation import FuncAnimation
+    from matplotlib.widgets import Slider
+except Exception as e:
+    raise RuntimeError(f"Нужны matplotlib и ее зависимости: {e}")
+
+from ..config import FFT_LEN, WF_WIDTH, SweepInfo, SweepPacket
+from ..data_acquisition.sweep_reader import SweepReader
+from ..signal_processing.phase_analysis import apply_temporal_unwrap, phase_to_distance
+from ..utils.formatting import format_status_kv, parse_spec_clip
+
+
+def run_matplotlib(args):
+    """Запуск визуализации с использованием matplotlib."""
+    # Очередь завершённых свипов и поток чтения
+    q: Queue[SweepPacket] = Queue(maxsize=1000)
+    stop_event = threading.Event()
+    reader = SweepReader(args.port, args.baud, q, stop_event, fancy=bool(args.fancy))
+    reader.start()
+
+    # Графика (3 ряда x 2 колонки = 6 графиков)
+    fig, axs = plt.subplots(3, 2, figsize=(12, 12))
+    (ax_line, ax_img), (ax_fft, ax_spec), (ax_phase, ax_phase_wf) = axs
+    fig.canvas.manager.set_window_title(args.title) if hasattr(fig.canvas.manager, "set_window_title") else None
+    # Увеличим расстояния и оставим место справа под ползунки оси Y B-scan
+    fig.subplots_adjust(wspace=0.25, hspace=0.35, left=0.07, right=0.90, top=0.95, bottom=0.05)
+
+    # Состояние для отображения
+    current_sweep: Optional[np.ndarray] = None
+    current_info: Optional[SweepInfo] = None
+    x_shared: Optional[np.ndarray] = None
+    width: Optional[int] = None
+    max_sweeps = int(max(10, args.max_sweeps))
+    ring = None  # type: Optional[np.ndarray]
+    ring_time = None  # type: Optional[np.ndarray]
+    head = 0
+    # Авто-уровни цветовой шкалы водопада сырых данных пересчитываются по видимой области.
+    # FFT состояние
+    fft_bins = FFT_LEN // 2 + 1
+    ring_fft = None  # type: Optional[np.ndarray]
+    y_min_fft, y_max_fft = None, None
+    freq_shared: Optional[np.ndarray] = None
+    # Phase состояние
+    ring_phase = None  # type: Optional[np.ndarray]
+    prev_phase_per_bin: Optional[np.ndarray] = None
+    phase_offset_per_bin: Optional[np.ndarray] = None
+    y_min_phase, y_max_phase = None, None
+    # Параметры контраста водопада спектров
+    spec_clip = parse_spec_clip(getattr(args, "spec_clip", None))
+    # Ползунки управления Y для B-scan и контрастом
+    ymin_slider = None
+    ymax_slider = None
+    contrast_slider = None
+
+    # Статусная строка (внизу окна)
+    status_text = fig.text(
+        0.01,
+        0.01,
+        "",
+        ha="left",
+        va="bottom",
+        fontsize=8,
+        family="monospace",
+    )
+
+    # Линейный график последнего свипа
+    line_obj, = ax_line.plot([], [], lw=1)
+    ax_line.set_title("Сырые данные", pad=1)
+    ax_line.set_xlabel("F")
+    ax_line.set_ylabel("")
+
+    # Линейный график спектра текущего свипа
+    fft_line_obj, = ax_fft.plot([], [], lw=1)
+    ax_fft.set_title("FFT", pad=1)
+    ax_fft.set_xlabel("X")
+    ax_fft.set_ylabel("Амплитуда, дБ")
+
+    # Диапазон по Y для последнего свипа: авто по умолчанию (поддерживает отрицательные значения)
+    fixed_ylim: Optional[Tuple[float, float]] = None
+    # CLI переопределение при необходимости
+    if args.ylim:
+        try:
+            y0, y1 = args.ylim.split(",")
+            fixed_ylim = (float(y0), float(y1))
+        except Exception:
+            sys.stderr.write("[warn] Некорректный формат --ylim, игнорирую. Ожидалось min,max\n")
+    if fixed_ylim is not None:
+        ax_line.set_ylim(fixed_ylim)
+
+    # Водопад (будет инициализирован при первом свипе)
+    img_obj = ax_img.imshow(
+        np.zeros((1, 1), dtype=np.float32),
+        aspect="auto",
+        interpolation="nearest",
+        origin="lower",
+        cmap=args.cmap,
+    )
+    ax_img.set_title("Сырые данные", pad=12)
+    ax_img.set_xlabel("")
+    ax_img.set_ylabel("частота")
+    # Не показываем численные значения по времени на водопаде сырых данных
+    try:
+        ax_img.tick_params(axis="x", labelbottom=False)
+    except Exception:
+        pass
+
+    # Водопад спектров
+    img_fft_obj = ax_spec.imshow(
+        np.zeros((1, 1), dtype=np.float32),
+        aspect="auto",
+        interpolation="nearest",
+        origin="lower",
+        cmap=args.cmap,
+    )
+    ax_spec.set_title("B-scan (дБ)", pad=12)
+    ax_spec.set_xlabel("")
+    ax_spec.set_ylabel("расстояние")
+    # Не показываем численные значения по времени на B-scan
+    try:
+        ax_spec.tick_params(axis="x", labelbottom=False)
+    except Exception:
+        pass
+
+    # График фазы текущего свипа
+    phase_line_obj, = ax_phase.plot([], [], lw=1)
+    ax_phase.set_title("Фаза спектра (развернутая)", pad=1)
+    ax_phase.set_xlabel("Бин")
+    ax_phase.set_ylabel("Фаза, радианы")
+
+    # Добавим второй Y axis для расстояния
+    ax_phase_dist = ax_phase.twinx()
+    ax_phase_dist.set_ylabel("Расстояние, м", color='green')
+
+    # Водопад фазы
+    img_phase_obj = ax_phase_wf.imshow(
+        np.zeros((1, 1), dtype=np.float32),
+        aspect="auto",
+        interpolation="nearest",
+        origin="lower",
+        cmap=args.cmap,
+    )
+    ax_phase_wf.set_title("Водопад фазы", pad=12)
+    ax_phase_wf.set_xlabel("")
+    ax_phase_wf.set_ylabel("Бин")
+    # Не показываем численные значения по времени
+    try:
+        ax_phase_wf.tick_params(axis="x", labelbottom=False)
+    except Exception:
+        pass
+    # Слайдеры для управления осью Y B-scan (мин/макс) и контрастом
+    try:
+        ax_smin = fig.add_axes([0.92, 0.55, 0.02, 0.35])
+        ax_smax = fig.add_axes([0.95, 0.55, 0.02, 0.35])
+        ax_sctr = fig.add_axes([0.98, 0.55, 0.02, 0.35])
+        ymin_slider = Slider(ax_smin, "Y min", 0, max(1, fft_bins - 1), valinit=0, valstep=1, orientation="vertical")
+        ymax_slider = Slider(ax_smax, "Y max", 0, max(1, fft_bins - 1), valinit=max(1, fft_bins - 1), valstep=1, orientation="vertical")
+        contrast_slider = Slider(ax_sctr, "Int max", 0, 100, valinit=100, valstep=1, orientation="vertical")
+
+        def _on_ylim_change(_val):
+            try:
+                y0 = int(min(ymin_slider.val, ymax_slider.val))
+                y1 = int(max(ymin_slider.val, ymax_slider.val))
+                ax_spec.set_ylim(y0, y1)
+                fig.canvas.draw_idle()
+            except Exception:
+                pass
+
+        ymin_slider.on_changed(_on_ylim_change)
+        ymax_slider.on_changed(_on_ylim_change)
+        # Контраст влияет на верхнюю границу цветовой шкалы (процент от авто-диапазона)
+        contrast_slider.on_changed(lambda _v: fig.canvas.draw_idle())
+    except Exception:
+        pass
+
+    # Для контроля частоты обновления
+    max_fps = max(1.0, float(args.max_fps))
+    interval_ms = int(1000.0 / max_fps)
+    frames_since_ylim_update = 0
+
+    def ensure_buffer(_w: int):
+        nonlocal ring, width, head, x_shared, ring_fft, freq_shared, ring_time
+        nonlocal ring_phase, prev_phase_per_bin, phase_offset_per_bin
+        if ring is not None:
+            return
+        width = WF_WIDTH
+        x_shared = np.arange(width, dtype=np.int32)
+        ring = np.full((max_sweeps, width), np.nan, dtype=np.float32)
+        ring_time = np.full((max_sweeps,), np.nan, dtype=np.float64)
+        head = 0
+        # Обновляем изображение под новые размеры: время по X (горизонталь), X по Y
+        img_obj.set_data(np.zeros((width, max_sweeps), dtype=np.float32))
+        img_obj.set_extent((0, max_sweeps - 1, 0, width - 1 if width > 0 else 1))
+        ax_img.set_xlim(0, max_sweeps - 1)
+        ax_img.set_ylim(0, max(1, width - 1))
+        # FFT буферы: время по X, бин по Y
+        ring_fft = np.full((max_sweeps, fft_bins), np.nan, dtype=np.float32)
+        img_fft_obj.set_data(np.zeros((fft_bins, max_sweeps), dtype=np.float32))
+        img_fft_obj.set_extent((0, max_sweeps - 1, 0, fft_bins - 1))
+        ax_spec.set_xlim(0, max_sweeps - 1)
+        ax_spec.set_ylim(0, max(1, fft_bins - 1))
+        freq_shared = np.arange(fft_bins, dtype=np.int32)
+        # Phase буферы: время по X, бин по Y
+        ring_phase = np.full((max_sweeps, fft_bins), np.nan, dtype=np.float32)
+        prev_phase_per_bin = np.zeros(fft_bins, dtype=np.float32)
+        phase_offset_per_bin = np.zeros(fft_bins, dtype=np.float32)
+        img_phase_obj.set_data(np.zeros((fft_bins, max_sweeps), dtype=np.float32))
+        img_phase_obj.set_extent((0, max_sweeps - 1, 0, fft_bins - 1))
+        ax_phase_wf.set_xlim(0, max_sweeps - 1)
+        ax_phase_wf.set_ylim(0, max(1, fft_bins - 1))
+
+    def _visible_levels_matplotlib(data: np.ndarray, axis) -> Optional[Tuple[float, float]]:
+        """(vmin, vmax) по текущей видимой области imshow (без накопления по времени)."""
+        if data.size == 0:
+            return None
+        ny, nx = data.shape[0], data.shape[1]
+        try:
+            x0, x1 = axis.get_xlim()
+            y0, y1 = axis.get_ylim()
+        except Exception:
+            x0, x1 = 0.0, float(nx - 1)
+            y0, y1 = 0.0, float(ny - 1)
+        xmin, xmax = sorted((float(x0), float(x1)))
+        ymin, ymax = sorted((float(y0), float(y1)))
+        ix0 = max(0, min(nx - 1, int(np.floor(xmin))))
+        ix1 = max(0, min(nx - 1, int(np.ceil(xmax))))
+        iy0 = max(0, min(ny - 1, int(np.floor(ymin))))
+        iy1 = max(0, min(ny - 1, int(np.ceil(ymax))))
+        if ix1 < ix0:
+            ix1 = ix0
+        if iy1 < iy0:
+            iy1 = iy0
+        sub = data[iy0 : iy1 + 1, ix0 : ix1 + 1]
+        finite = np.isfinite(sub)
+        if not finite.any():
+            return None
+        vals = sub[finite]
+        vmin = float(np.min(vals))
+        vmax = float(np.max(vals))
+        if not (np.isfinite(vmin) and np.isfinite(vmax)) or vmin == vmax:
+            return None
+        return (vmin, vmax)
+
+    def push_sweep(s: np.ndarray):
+        nonlocal ring, head, ring_fft, y_min_fft, y_max_fft, ring_time
+        nonlocal ring_phase, prev_phase_per_bin, phase_offset_per_bin, y_min_phase, y_max_phase
+        if s is None or s.size == 0 or ring is None:
+            return
+        # Нормализуем длину до фиксированной ширины
+        w = ring.shape[1]
+        row = np.full((w,), np.nan, dtype=np.float32)
+        take = min(w, s.size)
+        row[:take] = s[:take]
+        ring[head, :] = row
+        if ring_time is not None:
+            ring_time[head] = time.time()
+        head = (head + 1) % ring.shape[0]
+        # FFT строка (дБ) и фаза
+        if ring_fft is not None:
+            bins = ring_fft.shape[1]
+            # Подготовка входа FFT_LEN, замена NaN на 0
+            take_fft = min(int(s.size), FFT_LEN)
+            if take_fft <= 0:
+                fft_row = np.full((bins,), np.nan, dtype=np.float32)
+                phase_row = np.full((bins,), np.nan, dtype=np.float32)
+            else:
+                fft_in = np.zeros((FFT_LEN,), dtype=np.float32)
+                seg = s[:take_fft]
+                if isinstance(seg, np.ndarray):
+                    seg = np.nan_to_num(seg, nan=0.0).astype(np.float32, copy=False)
+                else:
+                    seg = np.asarray(seg, dtype=np.float32)
+                    seg = np.nan_to_num(seg, nan=0.0)
+                # Окно Хэннинга
+                win = np.hanning(take_fft).astype(np.float32)
+                fft_in[:take_fft] = seg * win
+                spec = np.fft.rfft(fft_in)
+                mag = np.abs(spec).astype(np.float32)
+                fft_row = 20.0 * np.log10(mag + 1e-9)
+                if fft_row.shape[0] != bins:
+                    # rfft длиной FFT_LEN даёт bins == FFT_LEN//2+1
+                    fft_row = fft_row[:bins]
+
+                # Расчет фазы
+                phase = np.angle(spec).astype(np.float32)
+                if phase.shape[0] > bins:
+                    phase = phase[:bins]
+                # Unwrapping по частоте (внутри свипа)
+                phase_unwrapped_freq = np.unwrap(phase)
+                # Unwrapping по времени (между свипами)
+                phase_unwrapped_time, prev_phase_per_bin, phase_offset_per_bin = apply_temporal_unwrap(
+                    phase_unwrapped_freq, prev_phase_per_bin, phase_offset_per_bin
+                )
+                phase_row = phase_unwrapped_time
+
+            ring_fft[(head - 1) % ring_fft.shape[0], :] = fft_row
+            # Экстремумы для цветовой шкалы
+            fr_min = np.nanmin(fft_row)
+            fr_max = np.nanmax(fft_row)
+            fr_max = np.nanpercentile(fft_row, 90)
+            if y_min_fft is None or (not np.isnan(fr_min) and fr_min < y_min_fft):
+                y_min_fft = float(fr_min)
+            if y_max_fft is None or (not np.isnan(fr_max) and fr_max > y_max_fft):
+                y_max_fft = float(fr_max)
+
+            # Сохраняем фазу в буфер
+            if ring_phase is not None:
+                ring_phase[(head - 1) % ring_phase.shape[0], :] = phase_row
+                # Экстремумы для цветовой шкалы фазы
+                ph_min = np.nanmin(phase_row)
+                ph_max = np.nanmax(phase_row)
+                if y_min_phase is None or (not np.isnan(ph_min) and ph_min < y_min_phase):
+                    y_min_phase = float(ph_min)
+                if y_max_phase is None or (not np.isnan(ph_max) and ph_max > y_max_phase):
+                    y_max_phase = float(ph_max)
+
+    def drain_queue():
+        nonlocal current_sweep, current_info
+        drained = 0
+        while True:
+            try:
+                s, info = q.get_nowait()
+            except Empty:
+                break
+            drained += 1
+            current_sweep = s
+            current_info = info
+            ensure_buffer(s.size)
+            push_sweep(s)
+        return drained
+
+    def make_display_ring():
+        # Возвращаем буфер с правильным порядком по времени (старые→новые) и осью времени по X
+        if ring is None:
+            return np.zeros((1, 1), dtype=np.float32)
+        base = ring if head == 0 else np.roll(ring, -head, axis=0)
+        return base.T  # (width, time)
+
+    def make_display_times():
+        if ring_time is None:
+            return None
+        base_t = ring_time if head == 0 else np.roll(ring_time, -head)
+        return base_t
+
+    def make_display_ring_fft():
+        if ring_fft is None:
+            return np.zeros((1, 1), dtype=np.float32)
+        base = ring_fft if head == 0 else np.roll(ring_fft, -head, axis=0)
+        return base.T  # (bins, time)
+
+    def make_display_ring_phase():
+        if ring_phase is None:
+            return np.zeros((1, 1), dtype=np.float32)
+        base = ring_phase if head == 0 else np.roll(ring_phase, -head, axis=0)
+        return base.T  # (bins, time)
+
+    def update(_frame):
+        nonlocal frames_since_ylim_update
+        changed = drain_queue() > 0
+
+        # Обновление линии последнего свипа
+        if current_sweep is not None:
+            if x_shared is not None and current_sweep.size <= x_shared.size:
+                xs = x_shared[: current_sweep.size]
+            else:
+                xs = np.arange(current_sweep.size, dtype=np.int32)
+            line_obj.set_data(xs, current_sweep)
+            # Лимиты по X постоянные под текущую ширину
+            ax_line.set_xlim(0, max(1, current_sweep.size - 1))
+            # Адаптивные Y-лимиты (если не задан --ylim)
+            if fixed_ylim is None:
+                y0 = float(np.nanmin(current_sweep))
+                y1 = float(np.nanmax(current_sweep))
+                if np.isfinite(y0) and np.isfinite(y1):
+                    if y0 == y1:
+                        pad = max(1.0, abs(y0) * 0.05)
+                        y0 -= pad
+                        y1 += pad
+                    else:
+                        pad = 0.05 * (y1 - y0)
+                        y0 -= pad
+                        y1 += pad
+                    ax_line.set_ylim(y0, y1)
+
+            # Обновление спектра и фазы текущего свипа
+            take_fft = min(int(current_sweep.size), FFT_LEN)
+            if take_fft > 0 and freq_shared is not None:
+                fft_in = np.zeros((FFT_LEN,), dtype=np.float32)
+                seg = np.nan_to_num(current_sweep[:take_fft], nan=0.0).astype(np.float32, copy=False)
+                win = np.hanning(take_fft).astype(np.float32)
+                fft_in[:take_fft] = seg * win
+                spec = np.fft.rfft(fft_in)
+                mag = np.abs(spec).astype(np.float32)
+                fft_vals = 20.0 * np.log10(mag + 1e-9)
+                xs_fft = freq_shared
+                if fft_vals.size > xs_fft.size:
+                    fft_vals = fft_vals[: xs_fft.size]
+                fft_line_obj.set_data(xs_fft[: fft_vals.size], fft_vals)
+                # Авто-диапазон по Y для спектра
+                if np.isfinite(np.nanmin(fft_vals)) and np.isfinite(np.nanmax(fft_vals)):
+                    ax_fft.set_xlim(0, max(1, xs_fft.size - 1))
+                    ax_fft.set_ylim(float(np.nanmin(fft_vals)), float(np.nanmax(fft_vals)))
+
+                # Расчет и отображение фазы текущего свипа
+                phase = np.angle(spec).astype(np.float32)
+                if phase.size > xs_fft.size:
+                    phase = phase[: xs_fft.size]
+                # Unwrapping по частоте
+                phase_unwrapped = np.unwrap(phase)
+                phase_line_obj.set_data(xs_fft[: phase_unwrapped.size], phase_unwrapped)
+                # Авто-диапазон по Y для фазы
+                if np.isfinite(np.nanmin(phase_unwrapped)) and np.isfinite(np.nanmax(phase_unwrapped)):
+                    ax_phase.set_xlim(0, max(1, xs_fft.size - 1))
+                    phase_min = float(np.nanmin(phase_unwrapped))
+                    phase_max = float(np.nanmax(phase_unwrapped))
+                    ax_phase.set_ylim(phase_min, phase_max)
+                    # Обновляем вторую ось Y с расстоянием
+                    try:
+                        dist_min = phase_to_distance(np.array([phase_min]))[0]
+                        dist_max = phase_to_distance(np.array([phase_max]))[0]
+                        ax_phase_dist.set_ylim(dist_min, dist_max)
+                    except Exception:
+                        pass
+
+        # Обновление водопада
+        if changed and ring is not None:
+            disp = make_display_ring()
+            # Новые данные справа: без реверса
+            img_obj.set_data(disp)
+            # Подписи времени не обновляем динамически (оставляем авто-тики)
+            # Авто-уровни: по видимой области (не накапливаем за всё время)
+            levels = _visible_levels_matplotlib(disp, ax_img)
+            if levels is not None:
+                img_obj.set_clim(vmin=levels[0], vmax=levels[1])
+
+        # Обновление водопада спектров
+        if changed and ring_fft is not None:
+            disp_fft = make_display_ring_fft()
+            # Новые данные справа: без реверса
+            img_fft_obj.set_data(disp_fft)
+            # Подписи времени не обновляем динамически (оставляем авто-тики)
+            # Автодиапазон по среднему спектру за видимый интервал (как в хорошей версии)
+            try:
+                # disp_fft имеет форму (bins, time); берём среднее по времени
+                mean_spec = np.nanmean(disp_fft, axis=1)
+                vmin_v = float(np.nanmin(mean_spec))
+                vmax_v = float(np.nanmax(mean_spec))
+            except Exception:
+                vmin_v = vmax_v = None
+            # Если средние не дают валидный диапазон — используем процентильную обрезку (если задана)
+            if (vmin_v is None or not np.isfinite(vmin_v)) or (vmax_v is None or not np.isfinite(vmax_v)) or vmin_v == vmax_v:
+                if spec_clip is not None:
+                    try:
+                        vmin_v = float(np.nanpercentile(disp_fft, spec_clip[0]))
+                        vmax_v = float(np.nanpercentile(disp_fft, spec_clip[1]))
+                    except Exception:
+                        vmin_v = vmax_v = None
+            # Фолбэк к отслеживаемым минимум/максимумам
+            if (vmin_v is None or not np.isfinite(vmin_v)) or (vmax_v is None or not np.isfinite(vmax_v)) or vmin_v == vmax_v:
+                if y_min_fft is not None and y_max_fft is not None and np.isfinite(y_min_fft) and np.isfinite(y_max_fft) and y_min_fft != y_max_fft:
+                    vmin_v, vmax_v = y_min_fft, y_max_fft
+            if vmin_v is not None and vmax_v is not None and vmin_v != vmax_v:
+                # Применим скалирование контрастом (верхняя граница)
+                try:
+                    c = float(contrast_slider.val) / 100.0 if contrast_slider is not None else 1.0
+                except Exception:
+                    c = 1.0
+                vmax_eff = vmin_v + c * (vmax_v - vmin_v)
+                img_fft_obj.set_clim(vmin=vmin_v, vmax=vmax_eff)
+
+        # Обновление водопада фазы
+        if changed and ring_phase is not None:
+            disp_phase = make_display_ring_phase()
+            img_phase_obj.set_data(disp_phase)
+            # Автодиапазон для фазы
+            try:
+                mean_phase = np.nanmean(disp_phase, axis=1)
+                vmin_p = float(np.nanmin(mean_phase))
+                vmax_p = float(np.nanmax(mean_phase))
+            except Exception:
+                vmin_p = vmax_p = None
+            # Фолбэк к отслеживаемым минимум/максимумам
+            if (vmin_p is None or not np.isfinite(vmin_p)) or (vmax_p is None or not np.isfinite(vmax_p)) or vmin_p == vmax_p:
+                if y_min_phase is not None and y_max_phase is not None and np.isfinite(y_min_phase) and np.isfinite(y_max_phase) and y_min_phase != y_max_phase:
+                    vmin_p, vmax_p = y_min_phase, y_max_phase
+            if vmin_p is not None and vmax_p is not None and vmin_p != vmax_p:
+                img_phase_obj.set_clim(vmin=vmin_p, vmax=vmax_p)
+
+        if changed and current_info:
+            status_text.set_text(format_status_kv(current_info))
+
+        # Возвращаем обновлённые артисты
+        return (line_obj, img_obj, fft_line_obj, img_fft_obj, phase_line_obj, img_phase_obj, status_text)
+
+    ani = FuncAnimation(fig, update, interval=interval_ms, blit=False)
+
+    plt.show()
+    # Нормальное завершение при закрытии окна
+    stop_event.set()
+    reader.join(timeout=1.0)

rfg_adc_plotter/visualization/pyqtgraph_backend.py

@@ -0,0 +1,434 @@
+"""
+Визуализация данных с использованием pyqtgraph (быстрый бэкенд).
+"""
+
+import sys
+import threading
+import time
+from queue import Empty, Queue
+from typing import Optional, Tuple
+
+import numpy as np
+
+try:
+    import pyqtgraph as pg
+    from PyQt5 import QtCore, QtWidgets  # noqa: F401
+except Exception:
+    # Возможно установлена PySide6
+    try:
+        import pyqtgraph as pg
+        from PySide6 import QtCore, QtWidgets  # noqa: F401
+    except Exception as e:
+        raise RuntimeError(
+            "pyqtgraph/PyQt5(Pyside6) не найдены. Установите: pip install pyqtgraph PyQt5"
+        ) from e
+
+from ..config import FFT_LEN, WF_WIDTH, SweepInfo, SweepPacket
+from ..data_acquisition.sweep_reader import SweepReader
+from ..signal_processing.phase_analysis import apply_temporal_unwrap, phase_to_distance
+from ..utils.formatting import format_status_kv, parse_spec_clip
+
+
+def run_pyqtgraph(args):
+    """Быстрый GUI на PyQtGraph. Требует pyqtgraph и PyQt5/PySide6."""
+    # Очередь завершённых свипов и поток чтения
+    q: Queue[SweepPacket] = Queue(maxsize=1000)
+    stop_event = threading.Event()
+    reader = SweepReader(args.port, args.baud, q, stop_event, fancy=bool(args.fancy))
+    reader.start()
+
+    # Настройки скорости
+    max_sweeps = int(max(10, args.max_sweeps))
+    max_fps = max(1.0, float(args.max_fps))
+    interval_ms = int(1000.0 / max_fps)
+
+    # PyQtGraph настройки
+    pg.setConfigOptions(useOpenGL=True, antialias=False)
+    app = pg.mkQApp(args.title)
+    win = pg.GraphicsLayoutWidget(show=True, title=args.title)
+    win.resize(1200, 900)
+
+    # Плот последнего свипа (слева-сверху)
+    p_line = win.addPlot(row=0, col=0, title="Сырые данные")
+    p_line.showGrid(x=True, y=True, alpha=0.3)
+    curve = p_line.plot(pen=pg.mkPen((80, 120, 255), width=1))
+    p_line.setLabel("bottom", "X")
+    p_line.setLabel("left", "Y")
+
+    # Водопад (справа-сверху)
+    p_img = win.addPlot(row=0, col=1, title="Сырые данные водопад")
+    p_img.invertY(False)
+    p_img.showGrid(x=False, y=False)
+    p_img.setLabel("bottom", "Время, с (новое справа)")
+    try:
+        p_img.getAxis("bottom").setStyle(showValues=False)
+    except Exception:
+        pass
+    p_img.setLabel("left", "X (0 снизу)")
+    img = pg.ImageItem()
+    p_img.addItem(img)
+
+    # FFT (слева-средний ряд)
+    p_fft = win.addPlot(row=1, col=0, title="FFT")
+    p_fft.showGrid(x=True, y=True, alpha=0.3)
+    curve_fft = p_fft.plot(pen=pg.mkPen((255, 120, 80), width=1))
+    p_fft.setLabel("bottom", "Бин")
+    p_fft.setLabel("left", "Амплитуда, дБ")
+
+    # Водопад спектров (справа-средний ряд)
+    p_spec = win.addPlot(row=1, col=1, title="B-scan (дБ)")
+    p_spec.invertY(True)
+    p_spec.showGrid(x=False, y=False)
+    p_spec.setLabel("bottom", "Время, с (новое справа)")
+    try:
+        p_spec.getAxis("bottom").setStyle(showValues=False)
+    except Exception:
+        pass
+    p_spec.setLabel("left", "Бин (0 снизу)")
+    img_fft = pg.ImageItem()
+    p_spec.addItem(img_fft)
+
+    # График фазы (слева-снизу)
+    p_phase = win.addPlot(row=2, col=0, title="Фаза спектра (развернутая)")
+    p_phase.showGrid(x=True, y=True, alpha=0.3)
+    curve_phase = p_phase.plot(pen=pg.mkPen((120, 255, 80), width=1))
+    p_phase.setLabel("bottom", "Бин")
+    p_phase.setLabel("left", "Фаза, радианы")
+    # Добавим вторую ось Y для расстояния
+    p_phase_dist_axis = pg.ViewBox()
+    p_phase.showAxis("right")
+    p_phase.scene().addItem(p_phase_dist_axis)
+    p_phase.getAxis("right").linkToView(p_phase_dist_axis)
+    p_phase_dist_axis.setXLink(p_phase)
+    p_phase.setLabel("right", "Расстояние, м")
+
+    def updateViews():
+        try:
+            p_phase_dist_axis.setGeometry(p_phase.vb.sceneBoundingRect())
+            p_phase_dist_axis.linkedViewChanged(p_phase.vb, p_phase_dist_axis.XAxis)
+        except Exception:
+            pass
+
+    updateViews()
+    p_phase.vb.sigResized.connect(updateViews)
+
+    # Водопад фазы (справа-снизу)
+    p_phase_wf = win.addPlot(row=2, col=1, title="Водопад фазы")
+    p_phase_wf.invertY(True)
+    p_phase_wf.showGrid(x=False, y=False)
+    p_phase_wf.setLabel("bottom", "Время, с (новое справа)")
+    try:
+        p_phase_wf.getAxis("bottom").setStyle(showValues=False)
+    except Exception:
+        pass
+    p_phase_wf.setLabel("left", "Бин (0 снизу)")
+    img_phase = pg.ImageItem()
+    p_phase_wf.addItem(img_phase)
+
+    # Статусная строка (внизу окна)
+    status = pg.LabelItem(justify="left")
+    win.addItem(status, row=3, col=0, colspan=2)
+
+    # Состояние
+    ring: Optional[np.ndarray] = None
+    head = 0
+    width: Optional[int] = None
+    x_shared: Optional[np.ndarray] = None
+    current_sweep: Optional[np.ndarray] = None
+    current_info: Optional[SweepInfo] = None
+    # Авто-уровни цветовой шкалы водопада сырых данных пересчитываются по видимой области.
+    # Для спектров
+    fft_bins = FFT_LEN // 2 + 1
+    ring_fft: Optional[np.ndarray] = None
+    freq_shared: Optional[np.ndarray] = None
+    y_min_fft, y_max_fft = None, None
+    # Phase состояние
+    ring_phase: Optional[np.ndarray] = None
+    prev_phase_per_bin: Optional[np.ndarray] = None
+    phase_offset_per_bin: Optional[np.ndarray] = None
+    y_min_phase, y_max_phase = None, None
+    # Параметры контраста водопада спектров (процентильная обрезка)
+    spec_clip = parse_spec_clip(getattr(args, "spec_clip", None))
+    # Диапазон по Y: авто по умолчанию (поддерживает отрицательные значения)
+    fixed_ylim: Optional[Tuple[float, float]] = None
+    if args.ylim:
+        try:
+            y0, y1 = args.ylim.split(",")
+            fixed_ylim = (float(y0), float(y1))
+        except Exception:
+            pass
+    if fixed_ylim is not None:
+        p_line.setYRange(fixed_ylim[0], fixed_ylim[1], padding=0)
+
+    def ensure_buffer(_w: int):
+        nonlocal ring, head, width, x_shared, ring_fft, freq_shared
+        nonlocal ring_phase, prev_phase_per_bin, phase_offset_per_bin
+        if ring is not None:
+            return
+        width = WF_WIDTH
+        x_shared = np.arange(width, dtype=np.int32)
+        ring = np.full((max_sweeps, width), np.nan, dtype=np.float32)
+        head = 0
+        # Водопад: время по оси X, X по оси Y
+        img.setImage(ring.T, autoLevels=False)
+        p_img.setRange(xRange=(0, max_sweeps - 1), yRange=(0, max(1, width - 1)), padding=0)
+        p_line.setXRange(0, max(1, width - 1), padding=0)
+        # FFT: время по оси X, бин по оси Y
+        ring_fft = np.full((max_sweeps, fft_bins), np.nan, dtype=np.float32)
+        img_fft.setImage(ring_fft.T, autoLevels=False)
+        p_spec.setRange(xRange=(0, max_sweeps - 1), yRange=(0, max(1, fft_bins - 1)), padding=0)
+        p_fft.setXRange(0, max(1, fft_bins - 1), padding=0)
+        freq_shared = np.arange(fft_bins, dtype=np.int32)
+        # Phase: время по оси X, бин по оси Y
+        ring_phase = np.full((max_sweeps, fft_bins), np.nan, dtype=np.float32)
+        prev_phase_per_bin = np.zeros(fft_bins, dtype=np.float32)
+        phase_offset_per_bin = np.zeros(fft_bins, dtype=np.float32)
+        img_phase.setImage(ring_phase.T, autoLevels=False)
+        p_phase_wf.setRange(xRange=(0, max_sweeps - 1), yRange=(0, max(1, fft_bins - 1)), padding=0)
+        p_phase.setXRange(0, max(1, fft_bins - 1), padding=0)
+
+    def _visible_levels_pyqtgraph(data: np.ndarray) -> Optional[Tuple[float, float]]:
+        """(vmin, vmax) по текущей видимой области ImageItem (без накопления по времени)."""
+        if data.size == 0:
+            return None
+        ny, nx = data.shape[0], data.shape[1]
+        try:
+            (x0, x1), (y0, y1) = p_img.viewRange()
+        except Exception:
+            x0, x1 = 0.0, float(nx - 1)
+            y0, y1 = 0.0, float(ny - 1)
+        xmin, xmax = sorted((float(x0), float(x1)))
+        ymin, ymax = sorted((float(y0), float(y1)))
+        ix0 = max(0, min(nx - 1, int(np.floor(xmin))))
+        ix1 = max(0, min(nx - 1, int(np.ceil(xmax))))
+        iy0 = max(0, min(ny - 1, int(np.floor(ymin))))
+        iy1 = max(0, min(ny - 1, int(np.ceil(ymax))))
+        if ix1 < ix0:
+            ix1 = ix0
+        if iy1 < iy0:
+            iy1 = iy0
+        sub = data[iy0 : iy1 + 1, ix0 : ix1 + 1]
+        finite = np.isfinite(sub)
+        if not finite.any():
+            return None
+        vals = sub[finite]
+        vmin = float(np.min(vals))
+        vmax = float(np.max(vals))
+        if not (np.isfinite(vmin) and np.isfinite(vmax)) or vmin == vmax:
+            return None
+        return (vmin, vmax)
+
+    def push_sweep(s: np.ndarray):
+        nonlocal ring, head, ring_fft, y_min_fft, y_max_fft
+        nonlocal ring_phase, prev_phase_per_bin, phase_offset_per_bin, y_min_phase, y_max_phase
+        if s is None or s.size == 0 or ring is None:
+            return
+        w = ring.shape[1]
+        row = np.full((w,), np.nan, dtype=np.float32)
+        take = min(w, s.size)
+        row[:take] = s[:take]
+        ring[head, :] = row
+        head = (head + 1) % ring.shape[0]
+        # FFT строка (дБ) и фаза
+        if ring_fft is not None:
+            bins = ring_fft.shape[1]
+            take_fft = min(int(s.size), FFT_LEN)
+            if take_fft > 0:
+                fft_in = np.zeros((FFT_LEN,), dtype=np.float32)
+                seg = np.nan_to_num(s[:take_fft], nan=0.0).astype(np.float32, copy=False)
+                win = np.hanning(take_fft).astype(np.float32)
+                fft_in[:take_fft] = seg * win
+                spec = np.fft.rfft(fft_in)
+                mag = np.abs(spec).astype(np.float32)
+                fft_row = 20.0 * np.log10(mag + 1e-9)
+                if fft_row.shape[0] != bins:
+                    fft_row = fft_row[:bins]
+
+                # Расчет фазы
+                phase = np.angle(spec).astype(np.float32)
+                if phase.shape[0] > bins:
+                    phase = phase[:bins]
+                # Unwrapping по частоте (внутри свипа)
+                phase_unwrapped_freq = np.unwrap(phase)
+                # Unwrapping по времени (между свипами)
+                phase_unwrapped_time, prev_phase_per_bin, phase_offset_per_bin = apply_temporal_unwrap(
+                    phase_unwrapped_freq, prev_phase_per_bin, phase_offset_per_bin
+                )
+                phase_row = phase_unwrapped_time
+            else:
+                fft_row = np.full((bins,), np.nan, dtype=np.float32)
+                phase_row = np.full((bins,), np.nan, dtype=np.float32)
+
+            ring_fft[(head - 1) % ring_fft.shape[0], :] = fft_row
+            fr_min = np.nanmin(fft_row)
+            fr_max = np.nanmax(fft_row)
+            if y_min_fft is None or (not np.isnan(fr_min) and fr_min < y_min_fft):
+                y_min_fft = float(fr_min)
+            if y_max_fft is None or (not np.isnan(fr_max) and fr_max > y_max_fft):
+                y_max_fft = float(fr_max)
+
+            # Сохраняем фазу в буфер
+            if ring_phase is not None:
+                ring_phase[(head - 1) % ring_phase.shape[0], :] = phase_row
+                # Экстремумы для цветовой шкалы фазы
+                ph_min = np.nanmin(phase_row)
+                ph_max = np.nanmax(phase_row)
+                if y_min_phase is None or (not np.isnan(ph_min) and ph_min < y_min_phase):
+                    y_min_phase = float(ph_min)
+                if y_max_phase is None or (not np.isnan(ph_max) and ph_max > y_max_phase):
+                    y_max_phase = float(ph_max)
+
+    def drain_queue():
+        nonlocal current_sweep, current_info
+        drained = 0
+        while True:
+            try:
+                s, info = q.get_nowait()
+            except Empty:
+                break
+            drained += 1
+            current_sweep = s
+            current_info = info
+            ensure_buffer(s.size)
+            push_sweep(s)
+        return drained
+
+    # Попытка применить LUT из колормэпа (если доступен)
+    try:
+        cm_mod = getattr(pg, "colormap", None)
+        if cm_mod is not None:
+            cm = cm_mod.get(args.cmap)
+            img.setLookupTable(cm.getLookupTable(0.0, 1.0, 256))
+    except Exception:
+        pass
+
+    def update():
+        changed = drain_queue() > 0
+        if current_sweep is not None and x_shared is not None:
+            if current_sweep.size <= x_shared.size:
+                xs = x_shared[: current_sweep.size]
+            else:
+                xs = np.arange(current_sweep.size)
+            curve.setData(xs, current_sweep, autoDownsample=True)
+            if fixed_ylim is None:
+                y0 = float(np.nanmin(current_sweep))
+                y1 = float(np.nanmax(current_sweep))
+                if np.isfinite(y0) and np.isfinite(y1):
+                    margin = 0.05 * max(1.0, (y1 - y0))
+                    p_line.setYRange(y0 - margin, y1 + margin, padding=0)
+
+            # Обновим спектр и фазу
+            take_fft = min(int(current_sweep.size), FFT_LEN)
+            if take_fft > 0 and freq_shared is not None:
+                fft_in = np.zeros((FFT_LEN,), dtype=np.float32)
+                seg = np.nan_to_num(current_sweep[:take_fft], nan=0.0).astype(np.float32, copy=False)
+                win = np.hanning(take_fft).astype(np.float32)
+                fft_in[:take_fft] = seg * win
+                spec = np.fft.rfft(fft_in)
+                mag = np.abs(spec).astype(np.float32)
+                fft_vals = 20.0 * np.log10(mag + 1e-9)
+                xs_fft = freq_shared
+                if fft_vals.size > xs_fft.size:
+                    fft_vals = fft_vals[: xs_fft.size]
+                curve_fft.setData(xs_fft[: fft_vals.size], fft_vals)
+                p_fft.setYRange(float(np.nanmin(fft_vals)), float(np.nanmax(fft_vals)), padding=0)
+
+                # Расчет и отображение фазы текущего свипа
+                phase = np.angle(spec).astype(np.float32)
+                if phase.size > xs_fft.size:
+                    phase = phase[: xs_fft.size]
+                # Unwrapping по частоте
+                phase_unwrapped = np.unwrap(phase)
+                curve_phase.setData(xs_fft[: phase_unwrapped.size], phase_unwrapped)
+                phase_min = float(np.nanmin(phase_unwrapped))
+                phase_max = float(np.nanmax(phase_unwrapped))
+                p_phase.setYRange(phase_min, phase_max, padding=0)
+                # Обновляем вторую ось Y с расстоянием
+                try:
+                    dist_min = phase_to_distance(np.array([phase_min]))[0]
+                    dist_max = phase_to_distance(np.array([phase_max]))[0]
+                    p_phase_dist_axis.setYRange(dist_min, dist_max, padding=0)
+                except Exception:
+                    pass
+
+        if changed and ring is not None:
+            disp = ring if head == 0 else np.roll(ring, -head, axis=0)
+            disp = disp.T[:, ::-1]  # (width, time with newest at left)
+            levels = _visible_levels_pyqtgraph(disp)
+            if levels is not None:
+                img.setImage(disp, autoLevels=False, levels=levels)
+            else:
+                img.setImage(disp, autoLevels=False)
+
+        if changed and current_info:
+            try:
+                status.setText(format_status_kv(current_info))
+            except Exception:
+                pass
+
+        if changed and ring_fft is not None:
+            disp_fft = ring_fft if head == 0 else np.roll(ring_fft, -head, axis=0)
+            disp_fft = disp_fft.T[:, ::-1]
+            # Автодиапазон по среднему спектру за видимый интервал (как в хорошей версии)
+            levels = None
+            try:
+                mean_spec = np.nanmean(disp_fft, axis=1)
+                vmin_v = float(np.nanmin(mean_spec))
+                vmax_v = float(np.nanmax(mean_spec))
+                if np.isfinite(vmin_v) and np.isfinite(vmax_v) and vmin_v != vmax_v:
+                    levels = (vmin_v, vmax_v)
+            except Exception:
+                levels = None
+            # Процентильная обрезка как запасной вариант
+            if levels is None and spec_clip is not None:
+                try:
+                    vmin_v = float(np.nanpercentile(disp_fft, spec_clip[0]))
+                    vmax_v = float(np.nanpercentile(disp_fft, spec_clip[1]))
+                    if np.isfinite(vmin_v) and np.isfinite(vmax_v) and vmin_v != vmax_v:
+                        levels = (vmin_v, vmax_v)
+                except Exception:
+                    levels = None
+            # Ещё один фолбэк — глобальные накопленные мин/макс
+            if levels is None and y_min_fft is not None and y_max_fft is not None and np.isfinite(y_min_fft) and np.isfinite(y_max_fft) and y_min_fft != y_max_fft:
+                levels = (y_min_fft, y_max_fft)
+            if levels is not None:
+                img_fft.setImage(disp_fft, autoLevels=False, levels=levels)
+            else:
+                img_fft.setImage(disp_fft, autoLevels=False)
+
+        # Обновление водопада фазы
+        if changed and ring_phase is not None:
+            disp_phase = ring_phase if head == 0 else np.roll(ring_phase, -head, axis=0)
+            disp_phase = disp_phase.T[:, ::-1]
+            # Автодиапазон для фазы
+            levels_phase = None
+            try:
+                mean_phase = np.nanmean(disp_phase, axis=1)
+                vmin_p = float(np.nanmin(mean_phase))
+                vmax_p = float(np.nanmax(mean_phase))
+                if np.isfinite(vmin_p) and np.isfinite(vmax_p) and vmin_p != vmax_p:
+                    levels_phase = (vmin_p, vmax_p)
+            except Exception:
+                levels_phase = None
+            # Фолбэк к отслеживаемым минимум/максимумам
+            if levels_phase is None and y_min_phase is not None and y_max_phase is not None and np.isfinite(y_min_phase) and np.isfinite(y_max_phase) and y_min_phase != y_max_phase:
+                levels_phase = (y_min_phase, y_max_phase)
+            if levels_phase is not None:
+                img_phase.setImage(disp_phase, autoLevels=False, levels=levels_phase)
+            else:
+                img_phase.setImage(disp_phase, autoLevels=False)
+
+    timer = pg.QtCore.QTimer()
+    timer.timeout.connect(update)
+    timer.start(interval_ms)
+
+    def on_quit():
+        stop_event.set()
+        reader.join(timeout=1.0)
+
+    app.aboutToQuit.connect(on_quit)
+    win.show()
+    exec_fn = getattr(app, "exec_", None) or getattr(app, "exec", None)
+    exec_fn()
+    # На случай если aboutToQuit не сработал
+    on_quit()