ulab.utils — ayudantes de utilidad de ulab

El submódulo ulab.utils proporciona un pequeño conjunto de ayudantes que operan sobre objetos numpy.ndarray pero que residen fuera de la superficie estándar de NumPy / SciPy. Los ayudantes están optimizados para los patrones de transmisión comunes en objetivos embebidos – búferes de periféricos de más de 16 bits, espectros de magnitud sin asignación de memoria.

Conversores de búfer

El estándar numpy.frombuffer() solo maneja los dtypes que el propio numpy define (uint8, int8, uint16, int16, float). Los ayudantes que se muestran a continuación amplían esa cobertura a los búferes de bytes int16 / uint16 / int32 / uint32 y devuelven un numpy.ndarray de float en una sola pasada.

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

Convierte un búfer de muestras int16 en un numpy.ndarray de float en una sola pasada.

Parámetros:

  • buffer – un búfer de tipo bytes que contiene las muestras.

  • count – número de elementos a leer. -1 lee todo el búfer desde offset hasta el final.

  • offset – número de bytes que se omiten al inicio del búfer.

  • out – un numpy.ndarray de float preasignado y opcional donde escribir el resultado. Cuando se proporciona, no se asigna ninguna matriz nueva.

  • byteswap – invierte el orden de los bytes de cada elemento antes de la conversión – la configuración adecuada cuando el búfer proviene de un periférico que escribió en un orden de bytes opuesto al de la CPU de la cámara.

Devuelve:

un numpy.ndarray de float de longitud count (o el número de muestras disponibles cuando count es -1).

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

Convierte un búfer de muestras uint16 en un numpy.ndarray de float en una sola pasada.

Parámetros:

  • buffer – un búfer de tipo bytes que contiene las muestras.

  • count – número de elementos a leer. -1 lee todo el búfer desde offset hasta el final.

  • offset – número de bytes que se omiten al inicio del búfer.

  • out – un numpy.ndarray de float preasignado y opcional donde escribir el resultado. Cuando se proporciona, no se asigna ninguna matriz nueva.

  • byteswap – invierte el orden de los bytes de cada elemento antes de la conversión – la configuración adecuada cuando el búfer proviene de un periférico que escribió en un orden de bytes opuesto al de la CPU de la cámara.

Devuelve:

un numpy.ndarray de float de longitud count (o el número de muestras disponibles cuando count es -1).

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

Convierte un búfer de muestras int32 en un numpy.ndarray de float en una sola pasada.

Parámetros:

  • buffer – un búfer de tipo bytes que contiene las muestras.

  • count – número de elementos a leer. -1 lee todo el búfer desde offset hasta el final.

  • offset – número de bytes que se omiten al inicio del búfer.

  • out – un numpy.ndarray de float preasignado y opcional donde escribir el resultado. Cuando se proporciona, no se asigna ninguna matriz nueva.

  • byteswap – invierte el orden de los bytes de cada elemento antes de la conversión – la configuración adecuada cuando el búfer proviene de un periférico que escribió en un orden de bytes opuesto al de la CPU de la cámara.

Devuelve:

un numpy.ndarray de float de longitud count (o el número de muestras disponibles cuando count es -1).

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

Convierte un búfer de muestras uint32 en un numpy.ndarray de float en una sola pasada.

Parámetros:

  • buffer – un búfer de tipo bytes que contiene las muestras.

  • count – número de elementos a leer. -1 lee todo el búfer desde offset hasta el final.

  • offset – número de bytes que se omiten al inicio del búfer.

  • out – un numpy.ndarray de float preasignado y opcional donde escribir el resultado. Cuando se proporciona, no se asigna ninguna matriz nueva.

  • byteswap – invierte el orden de los bytes de cada elemento antes de la conversión – la configuración adecuada cuando el búfer proviene de un periférico que escribió en un orden de bytes opuesto al de la CPU de la cámara.

Devuelve:

un numpy.ndarray de float de longitud count (o el número de muestras disponibles cuando count es -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

Devuelve la magnitud de la transformada discreta de Fourier de la entrada, conceptualmente equivalente a np.sqrt(real * real + imag * imag) tras una llamada a numpy.fft.fft() – sin asignar los búferes intermedios que requeriría la forma explícita.

Parámetros:

  • r – la parte real de la entrada como un numpy.ndarray de float 1-D. Su longitud debe ser una potencia de dos.

  • imag – parte imaginaria opcional de la entrada, con la misma forma que r. Cuando se omite, la entrada se trata como puramente real.

  • scratchpad – búfer de trabajo opcional para la FFT. Cuando se proporciona, no se asigna ninguna matriz de trabajo temporal.

  • out – búfer de destino opcional y preasignado para el espectro de magnitud. Cuando se proporciona, el resultado se escribe directamente en él.

  • log – cuando es True, devuelve el logaritmo natural de la magnitud en lugar de la propia magnitud.

Devuelve:

un numpy.ndarray de float de la misma longitud que r que contiene la magnitud (o su logaritmo) en cada banda de frecuencia.