ulab.utils — auxiliares utilitários do ulab

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

Conversores de buffer

O numpy.frombuffer() padrão só lida com dtypes que o próprio numpy define (uint8, int8, uint16, int16, float). Os auxiliares abaixo estendem essa cobertura a buffers de bytes int16 / uint16 / int32 / uint32 e retornam um numpy.ndarray de floats em uma ú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 em um numpy.ndarray de floats em uma única passagem.

Parâmetros:

  • buffer – um buffer do tipo bytes contendo as amostras.

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

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

  • out – um numpy.ndarray de floats pré-alocado, opcional, no qual escrever o resultado. Quando fornecido, nenhum novo array é alocado.

  • byteswap – inverte a ordem dos bytes de cada elemento antes da conversão – a configuração correta quando o buffer veio de um periférico que escreveu na ordem de bytes oposta à da CPU da câmera.

Retorna:

um numpy.ndarray de floats 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 em um numpy.ndarray de floats em uma única passagem.

Parâmetros:

  • buffer – um buffer do tipo bytes contendo as amostras.

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

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

  • out – um numpy.ndarray de floats pré-alocado, opcional, no qual escrever o resultado. Quando fornecido, nenhum novo array é alocado.

  • byteswap – inverte a ordem dos bytes de cada elemento antes da conversão – a configuração correta quando o buffer veio de um periférico que escreveu na ordem de bytes oposta à da CPU da câmera.

Retorna:

um numpy.ndarray de floats 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 em um numpy.ndarray de floats em uma única passagem.

Parâmetros:

  • buffer – um buffer do tipo bytes contendo as amostras.

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

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

  • out – um numpy.ndarray de floats pré-alocado, opcional, no qual escrever o resultado. Quando fornecido, nenhum novo array é alocado.

  • byteswap – inverte a ordem dos bytes de cada elemento antes da conversão – a configuração correta quando o buffer veio de um periférico que escreveu na ordem de bytes oposta à da CPU da câmera.

Retorna:

um numpy.ndarray de floats 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 em um numpy.ndarray de floats em uma única passagem.

Parâmetros:

  • buffer – um buffer do tipo bytes contendo as amostras.

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

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

  • out – um numpy.ndarray de floats pré-alocado, opcional, no qual escrever o resultado. Quando fornecido, nenhum novo array é alocado.

  • byteswap – inverte a ordem dos bytes de cada elemento antes da conversão – a configuração correta quando o buffer veio de um periférico que escreveu na ordem de bytes oposta à da CPU da câmera.

Retorna:

um numpy.ndarray de floats 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

Retorna 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 intermediários que a forma explícita alocaria.

Parâmetros:

  • r – a parte real da entrada como um numpy.ndarray de floats unidimensional. Seu comprimento deve ser uma potência de dois.

  • imag – parte imaginária opcional da entrada, do mesmo formato que r. Quando omitida, a entrada é tratada como puramente real.

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

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

  • log – quando True, retorna o logaritmo natural da magnitude em vez da própria magnitude.

Retorna:

um numpy.ndarray de floats do mesmo comprimento que r contendo a magnitude (ou seu logaritmo) em cada bin de frequência.