Як розгорнути значення енкодерів або кути, які обертаються у певній числовій точці

# Простий приклад (самодостатній)
import numpy as np
from UliEngineering.SignalProcessing.WrappedValues import unwrap

# Кути в градусах, згорнуті на 360
wrapped = np.array([350, 355,   1,   3])   # стрибок 355 -> 1 (згортання)
un = unwrap(wrapped, wrap_value=360)

print(un)  # -> [350. 355. 361. 363.]  (безперервно зростаючий кут)

# Онлайн-використання зі скалярами та блоками
import numpy as np
from UliEngineering.SignalProcessing.WrappedValues import OnlineUnwrapper

u = OnlineUnwrapper(wrap_value=100)   # лічильники, що згортаються на 100

# Подавати скаляри
print(u(10))   # -> 10
print(u(95))   # -> 95
print(u(2))    # -> 102  (згортання вперед обробляється онлайн)

# Або подати блок (одновимірний масив)
chunk = np.array([98, 3, 5])  # продовжується з попереднього стану
print(u(chunk))  # -> array([ 98., 103., 105.])

#!/usr/bin/env python3
# SPDX-License-Identifier: CC0-1.0
"""Приклад: побудова графіка згорнутих та розгорнутих фазових сигналів.

Ліцензія: CC0 1.0 Universal — присвячення суспільному надбанню (див. examples/LICENSE-CC0-1.0.txt)

Запуск як скрипт:
    python examples/unwrap_plot.py        # показує графік
    python examples/unwrap_plot.py --save out.png  # зберігає у файл

Цей скрипт створює синтетичний безперервний фазовий сигнал, згортає його до [0,2*pi),
а потім відновлює за допомогою пакетної функції `unwrap()` та станомісткого
`OnlineUnwrapper`, щоб продемонструвати, що вони узгоджуються.
"""
import argparse

import numpy as np
import matplotlib.pyplot as plt
plt.style.use("ggplot")

from UliEngineering.SignalProcessing.WrappedValues import unwrap, OnlineUnwrapper

def make_data(n=1000, wrap_value=2 * np.pi, seed=0):
    """Створити безперервний фазовий сигнал, який *змінює напрямок* посередині.

    Перша половина має додатну кутову швидкість, а друга половина — від'ємну
    кутову швидкість, тому фаза змінює напрямок. Повернений ряд `wrapped`
    знаходиться в [0, wrap_value).
    """
    np.random.seed(seed)
    t = np.linspace(0.0, 10.0, n)
    mid = n // 2
    # кутові швидкості (рад за одиницю часу)
    omega1 = 1.2 * 2 * np.pi
    omega2 = -0.8 * 2 * np.pi

    true_phase = np.empty(n, dtype=float)
    # перша половина: додатний нахил + мале коливання
    true_phase[:mid] = omega1 * t[:mid] + 0.8 * np.sin(2 * np.pi * 0.3 * t[:mid])
    # друга половина: почати з останнього значення першої половини, щоб зробити безперервним
    # а потім інтегрувати від'ємну кутову швидкість
    start_phase = true_phase[mid - 1]
    true_phase[mid:] = (
        start_phase
        + omega2 * (t[mid:] - t[mid - 1])
        + 0.8 * np.sin(2 * np.pi * 0.3 * t[mid:])
    )

    # згорнути до [0, wrap_value)
    wrapped = np.mod(true_phase, wrap_value)
    return t, true_phase, wrapped


def plot_example(save_path=None):
    wrap_value = 2 * np.pi
    t, true_phase, wrapped = make_data(n=1200, wrap_value=wrap_value)

    # Пакетне розгортання
    static_unwrapped = unwrap(wrapped, wrap_value=wrap_value)

    # Онлайн-розгортання (потоковий стиль)
    u = OnlineUnwrapper(wrap_value=wrap_value)
    online_unwrapped = np.array([u(x) for x in wrapped])

    # Швидка перевірка коректності
    maxdiff = np.max(np.abs(static_unwrapped - online_unwrapped))
    print(f"максимальна різниця між unwrap() та OnlineUnwrapper: {maxdiff:.3e}")

    fig, axs = plt.subplots(2, 1, figsize=(10, 6), sharex=True)

    # позначити зміну напрямку на графіках
    mid_idx = len(t) // 2
    axs[0].axvline(t[mid_idx], color="#444444", ls=":", lw=0.8)
    axs[1].axvline(t[mid_idx], color="#444444", ls=":", lw=0.8, label="зміна напрямку")

    axs[0].plot(t, wrapped, color="#1f77b4", lw=1)
    axs[0].set_title("Згорнутий сигнал (0 .. 2π)")
    axs[0].set_ylabel("фаза (рад)")
    axs[0].grid(True)

    axs[1].plot(t, static_unwrapped, color="#2ca02c", lw=1, label="unwrap()")
    axs[1].plot(t, online_unwrapped, color="#ff7f0e", lw=1, ls="--", label="OnlineUnwrapper")
    axs[1].plot(t, true_phase, color="#7f7f7f", lw=0.8, ls=":", label="істинна фаза")
    axs[1].set_title("Розгорнутий сигнал (безперервна фаза)")
    axs[1].set_xlabel("час")
    axs[1].set_ylabel("фаза (рад)")
    axs[1].legend()
    axs[1].grid(True)

    plt.tight_layout()
    if save_path:
        fig.savefig(save_path, dpi=150)
        print(f"Графік збережено у {save_path}")
    else:
        plt.show()


if __name__ == "__main__":
    p = argparse.ArgumentParser(description="Побудова графіка згорнутих та розгорнутих фазових сигналів.")
    p.add_argument("--save", dest="save", help="Зберегти графік за цим шляхом замість показу")
    args = p.parse_args()
    plot_example(save_path=args.save)