ulab.utils — helper di utilità di ulab

Il sottomodulo ulab.utils fornisce un piccolo insieme di helper che operano su oggetti numpy.ndarray ma che vivono al di fuori della superficie standard di NumPy / SciPy. Gli helper sono ottimizzati per i pattern di streaming comuni sui target embedded – buffer di periferiche più larghi di 16 bit, spettri di magnitudine senza allocazioni.

Convertitori di buffer

La funzione standard numpy.frombuffer() gestisce solo i dtype che numpy stesso definisce (uint8, int8, uint16, int16, float). Gli helper qui sotto estendono questa copertura ai buffer di byte int16 / uint16 / int32 / uint32 e restituiscono un numpy.ndarray di float in un solo passaggio.

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

Converte un buffer di campioni int16 in un numpy.ndarray di float in un solo passaggio.

Parametri:

  • buffer – un buffer di tipo bytes che contiene i campioni.

  • count – numero di elementi da leggere. -1 legge l’intero buffer da offset fino alla fine.

  • offset – numero di byte da saltare all’inizio del buffer.

  • out – un numpy.ndarray di float opzionale, pre-allocato, in cui scrivere il risultato. Quando viene fornito, non viene allocato alcun nuovo array.

  • byteswap – inverte l’ordine dei byte di ogni elemento prima della conversione – l’impostazione corretta quando il buffer proviene da una periferica che ha scritto con un ordine dei byte opposto a quello della CPU della camera.

Ritorna:

un numpy.ndarray di float di lunghezza count (oppure il numero di campioni disponibili quando count è -1).

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

Converte un buffer di campioni uint16 in un numpy.ndarray di float in un solo passaggio.

Parametri:

  • buffer – un buffer di tipo bytes che contiene i campioni.

  • count – numero di elementi da leggere. -1 legge l’intero buffer da offset fino alla fine.

  • offset – numero di byte da saltare all’inizio del buffer.

  • out – un numpy.ndarray di float opzionale, pre-allocato, in cui scrivere il risultato. Quando viene fornito, non viene allocato alcun nuovo array.

  • byteswap – inverte l’ordine dei byte di ogni elemento prima della conversione – l’impostazione corretta quando il buffer proviene da una periferica che ha scritto con un ordine dei byte opposto a quello della CPU della camera.

Ritorna:

un numpy.ndarray di float di lunghezza count (oppure il numero di campioni disponibili quando count è -1).

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

Converte un buffer di campioni int32 in un numpy.ndarray di float in un solo passaggio.

Parametri:

  • buffer – un buffer di tipo bytes che contiene i campioni.

  • count – numero di elementi da leggere. -1 legge l’intero buffer da offset fino alla fine.

  • offset – numero di byte da saltare all’inizio del buffer.

  • out – un numpy.ndarray di float opzionale, pre-allocato, in cui scrivere il risultato. Quando viene fornito, non viene allocato alcun nuovo array.

  • byteswap – inverte l’ordine dei byte di ogni elemento prima della conversione – l’impostazione corretta quando il buffer proviene da una periferica che ha scritto con un ordine dei byte opposto a quello della CPU della camera.

Ritorna:

un numpy.ndarray di float di lunghezza count (oppure il numero di campioni disponibili quando count è -1).

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

Converte un buffer di campioni uint32 in un numpy.ndarray di float in un solo passaggio.

Parametri:

  • buffer – un buffer di tipo bytes che contiene i campioni.

  • count – numero di elementi da leggere. -1 legge l’intero buffer da offset fino alla fine.

  • offset – numero di byte da saltare all’inizio del buffer.

  • out – un numpy.ndarray di float opzionale, pre-allocato, in cui scrivere il risultato. Quando viene fornito, non viene allocato alcun nuovo array.

  • byteswap – inverte l’ordine dei byte di ogni elemento prima della conversione – l’impostazione corretta quando il buffer proviene da una periferica che ha scritto con un ordine dei byte opposto a quello della CPU della camera.

Ritorna:

un numpy.ndarray di float di lunghezza count (oppure il numero di campioni disponibili quando count è -1).

Spettrogramma

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

Restituisce la magnitudine della trasformata di Fourier discreta dell’input, concettualmente equivalente a np.sqrt(real * real + imag * imag) dopo una chiamata a numpy.fft.fft() – senza allocare i buffer intermedi che la forma esplicita richiederebbe.

Parametri:

  • r – la parte reale dell’input come numpy.ndarray di float 1-D. La sua lunghezza deve essere una potenza di due.

  • imag – parte immaginaria dell’input opzionale, della stessa forma di r. Quando omessa, l’input viene trattato come puramente reale.

  • scratchpad – buffer di lavoro opzionale per la FFT. Quando viene fornito, non viene allocato alcun array di lavoro temporaneo.

  • out – buffer di destinazione opzionale, pre-allocato, per lo spettro di magnitudine. Quando viene fornito, il risultato vi viene scritto direttamente.

  • log – quando True, restituisce il logaritmo naturale della magnitudine invece della magnitudine stessa.

Ritorna:

un numpy.ndarray di float della stessa lunghezza di r che contiene la magnitudine (o il suo logaritmo) in ciascun bin di frequenza.