ulab.utils — pomocnicze narzędzia ulab

Podmoduł ulab.utils udostępnia niewielki zestaw funkcji pomocniczych, które operują na obiektach numpy.ndarray, lecz znajdują się poza standardowym zakresem NumPy / SciPy. Funkcje pomocnicze są dostrojone do wzorców strumieniowych typowych dla urządzeń wbudowanych – buforów peryferyjnych szerszych niż 16 bitów oraz widm amplitudowych bez alokacji.

Konwertery buforów

Standardowa numpy.frombuffer() obsługuje wyłącznie dtypy, które numpy sam definiuje (uint8, int8, uint16, int16, float). Poniższe funkcje pomocnicze rozszerzają to pokrycie na bufory bajtowe int16 / uint16 / int32 / uint32 i zwracają numpy.ndarray typu float w jednym przebiegu.

ulab.utils.from_int16_buffer(buffer: bytes, *, count: int = -1, offset: int = 0, out: numpy.ndarray | None = None, byteswap: bool = False) → numpy.ndarray

Konwertuje bufor próbek int16 na numpy.ndarray typu float w jednym przebiegu.

Parametry:

  • buffer – bufor przypominający bytes zawierający próbki.

  • count – liczba elementów do odczytania. -1 odczytuje cały bufor od offset do końca.

  • offset – liczba bajtów do pominięcia na początku bufora.

  • out – opcjonalna, wstępnie zaalokowana numpy.ndarray typu float, do której zostanie zapisany wynik. Gdy jest podana, nie jest alokowana nowa tablica.

  • byteswap – odwraca kolejność bajtów każdego elementu przed konwersją – właściwe ustawienie, gdy bufor pochodzi z urządzenia peryferyjnego, które zapisało dane w odwrotnej kolejności bajtów niż CPU kamery.

Zwraca:

numpy.ndarray typu float o długości count (lub o dostępnej liczbie próbek, gdy count wynosi -1).

ulab.utils.from_uint16_buffer(buffer: bytes, *, count: int = -1, offset: int = 0, out: numpy.ndarray | None = None, byteswap: bool = False) → numpy.ndarray

Konwertuje bufor próbek uint16 na numpy.ndarray typu float w jednym przebiegu.

Parametry:

  • buffer – bufor przypominający bytes zawierający próbki.

  • count – liczba elementów do odczytania. -1 odczytuje cały bufor od offset do końca.

  • offset – liczba bajtów do pominięcia na początku bufora.

  • out – opcjonalna, wstępnie zaalokowana numpy.ndarray typu float, do której zostanie zapisany wynik. Gdy jest podana, nie jest alokowana nowa tablica.

  • byteswap – odwraca kolejność bajtów każdego elementu przed konwersją – właściwe ustawienie, gdy bufor pochodzi z urządzenia peryferyjnego, które zapisało dane w odwrotnej kolejności bajtów niż CPU kamery.

Zwraca:

numpy.ndarray typu float o długości count (lub o dostępnej liczbie próbek, gdy count wynosi -1).

ulab.utils.from_int32_buffer(buffer: bytes, *, count: int = -1, offset: int = 0, out: numpy.ndarray | None = None, byteswap: bool = False) → numpy.ndarray

Konwertuje bufor próbek int32 na numpy.ndarray typu float w jednym przebiegu.

Parametry:

  • buffer – bufor przypominający bytes zawierający próbki.

  • count – liczba elementów do odczytania. -1 odczytuje cały bufor od offset do końca.

  • offset – liczba bajtów do pominięcia na początku bufora.

  • out – opcjonalna, wstępnie zaalokowana numpy.ndarray typu float, do której zostanie zapisany wynik. Gdy jest podana, nie jest alokowana nowa tablica.

  • byteswap – odwraca kolejność bajtów każdego elementu przed konwersją – właściwe ustawienie, gdy bufor pochodzi z urządzenia peryferyjnego, które zapisało dane w odwrotnej kolejności bajtów niż CPU kamery.

Zwraca:

numpy.ndarray typu float o długości count (lub o dostępnej liczbie próbek, gdy count wynosi -1).

ulab.utils.from_uint32_buffer(buffer: bytes, *, count: int = -1, offset: int = 0, out: numpy.ndarray | None = None, byteswap: bool = False) → numpy.ndarray

Konwertuje bufor próbek uint32 na numpy.ndarray typu float w jednym przebiegu.

Parametry:

  • buffer – bufor przypominający bytes zawierający próbki.

  • count – liczba elementów do odczytania. -1 odczytuje cały bufor od offset do końca.

  • offset – liczba bajtów do pominięcia na początku bufora.

  • out – opcjonalna, wstępnie zaalokowana numpy.ndarray typu float, do której zostanie zapisany wynik. Gdy jest podana, nie jest alokowana nowa tablica.

  • byteswap – odwraca kolejność bajtów każdego elementu przed konwersją – właściwe ustawienie, gdy bufor pochodzi z urządzenia peryferyjnego, które zapisało dane w odwrotnej kolejności bajtów niż CPU kamery.

Zwraca:

numpy.ndarray typu float o długości count (lub o dostępnej liczbie próbek, gdy count wynosi -1).

Spektrogram

ulab.utils.spectrogram(r: numpy.ndarray, imag: numpy.ndarray | None = None, *, scratchpad: numpy.ndarray | None = None, out: numpy.ndarray | None = None, log: bool = False) → numpy.ndarray

Zwraca amplitudę dyskretnej transformaty Fouriera wejścia, pojęciowo równoważną np.sqrt(real * real + imag * imag) po wywołaniu numpy.fft.fft() – bez alokowania buforów pośrednich, które wymagałaby postać jawna.

Parametry:

  • r – część rzeczywista wejścia jako 1-wymiarowa numpy.ndarray typu float. Jej długość musi być potęgą dwójki.

  • imag – opcjonalna część urojona wejścia, o tym samym kształcie co r. W przypadku pominięcia wejście traktowane jest jako czysto rzeczywiste.

  • scratchpad – opcjonalny bufor roboczy dla FFT. Gdy jest podany, nie jest alokowana tymczasowa tablica robocza.

  • out – opcjonalny, wstępnie zaalokowany bufor docelowy dla widma amplitudowego. Gdy jest podany, wynik jest zapisywany bezpośrednio do niego.

  • log – gdy True, zwraca logarytm naturalny amplitudy zamiast samej amplitudy.

Zwraca:

numpy.ndarray typu float o tej samej długości co r, zawierająca amplitudę (lub jej logarytm) w każdym prążku częstotliwości.