ulab.utils — utilitários auxiliares do ulab

O submódulo ulab.utils fornece um pequeno conjunto de auxiliares que operam em objetos numpy.ndarray, mas residem fora da superfície padrão NumPy/SciPy. Os auxiliares estão otimizados para os padrões de streaming comuns em alvos embebidos – buffers de periféricos com mais de 16 bits, espectros de magnitude sem alocação.

Conversores de buffer

O numpy.frombuffer() padrão apenas trata dtypes que o próprio numpy define (uint8, int8, uint16, int16, float). Os auxiliares abaixo alargam essa cobertura a buffers de bytes int16 / uint16 / int32 / uint32 e devolvem um numpy.ndarray de float numa única passagem.

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

Converte um buffer de amostras int16 num numpy.ndarray de float numa única passagem.

Parâmetros:

  • buffer – um buffer do tipo bytes que contém as amostras.

  • count – número de elementos a ler. -1 lê todo o buffer desde offset até ao fim.

  • offset – número de bytes a ignorar no início do buffer.

  • out – um numpy.ndarray de float pré-alocado opcional para escrever o resultado. Quando fornecido, não é alocado nenhum novo array.

  • byteswap – inverte a ordem dos bytes de cada elemento antes de converter – a definição correta quando o buffer provém de um periférico que escreveu na ordem de bytes oposta à da CPU da câmara.

Retorno:

um numpy.ndarray de float de comprimento count (ou o número de amostras disponíveis 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 um buffer de amostras uint16 num numpy.ndarray de float numa única passagem.

Parâmetros:

  • buffer – um buffer do tipo bytes que contém as amostras.

  • count – número de elementos a ler. -1 lê todo o buffer desde offset até ao fim.

  • offset – número de bytes a ignorar no início do buffer.

  • out – um numpy.ndarray de float pré-alocado opcional para escrever o resultado. Quando fornecido, não é alocado nenhum novo array.

  • byteswap – inverte a ordem dos bytes de cada elemento antes de converter – a definição correta quando o buffer provém de um periférico que escreveu na ordem de bytes oposta à da CPU da câmara.

Retorno:

um numpy.ndarray de float de comprimento count (ou o número de amostras disponíveis 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 um buffer de amostras int32 num numpy.ndarray de float numa única passagem.

Parâmetros:

  • buffer – um buffer do tipo bytes que contém as amostras.

  • count – número de elementos a ler. -1 lê todo o buffer desde offset até ao fim.

  • offset – número de bytes a ignorar no início do buffer.

  • out – um numpy.ndarray de float pré-alocado opcional para escrever o resultado. Quando fornecido, não é alocado nenhum novo array.

  • byteswap – inverte a ordem dos bytes de cada elemento antes de converter – a definição correta quando o buffer provém de um periférico que escreveu na ordem de bytes oposta à da CPU da câmara.

Retorno:

um numpy.ndarray de float de comprimento count (ou o número de amostras disponíveis 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 um buffer de amostras uint32 num numpy.ndarray de float numa única passagem.

Parâmetros:

  • buffer – um buffer do tipo bytes que contém as amostras.

  • count – número de elementos a ler. -1 lê todo o buffer desde offset até ao fim.

  • offset – número de bytes a ignorar no início do buffer.

  • out – um numpy.ndarray de float pré-alocado opcional para escrever o resultado. Quando fornecido, não é alocado nenhum novo array.

  • byteswap – inverte a ordem dos bytes de cada elemento antes de converter – a definição correta quando o buffer provém de um periférico que escreveu na ordem de bytes oposta à da CPU da câmara.

Retorno:

um numpy.ndarray de float de comprimento count (ou o número de amostras disponíveis quando count é -1).

Espectrograma

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

Devolve a magnitude da transformada de Fourier discreta da entrada, conceitualmente equivalente a np.sqrt(real * real + imag * imag) após uma chamada a numpy.fft.fft() – sem alocar os buffers intermédios que a forma explícita exigiria.

Parâmetros:

  • r – a parte real da entrada como um numpy.ndarray de float 1-D. O seu comprimento deve ser uma potência de dois.

  • imag – parte imaginária opcional da entrada, com a mesma forma que r. Quando omitida, a entrada é tratada como puramente real.

  • scratchpad – buffer de trabalho opcional para a FFT. Quando fornecido, não é alocado nenhum array de trabalho temporário.

  • out – buffer de destino pré-alocado opcional para o espectro de magnitude. Quando fornecido, o resultado é escrito diretamente nele.

  • log – quando True, devolve o logaritmo natural da magnitude em vez da magnitude em si.

Retorno:

um numpy.ndarray de float com o mesmo comprimento que r, contendo a magnitude (ou o seu logaritmo) em cada bin de frequência.