ulab.utils --- ulab 实用辅助函数

ulab.utils 子模块提供了一小组辅助函数，它们作用于 numpy.ndarray 对象，但位于标准 NumPy / SciPy 接口之外。这些辅助函数针对嵌入式目标上常见的流式处理模式进行了优化——超过 16 位宽的外设缓冲区、免分配的幅度谱。

缓冲区转换器

标准的 numpy.frombuffer() 只能处理 numpy 自身定义的 dtype（uint8、int8、uint16、int16、float）。下面的辅助函数将这一覆盖范围扩展到 int16 / uint16 / int32 / uint32 字节缓冲区，并一次性返回一个浮点型 numpy.ndarray。

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

一次性将 int16 样本缓冲区转换为浮点型 numpy.ndarray。

参数:

  • buffer -- 存放样本的 bytes 类缓冲区。

  • count -- 要读取的元素数量。-1 表示从 offset 到末尾读取整个缓冲区。

  • offset -- 在缓冲区起始处要跳过的字节数。

  • out -- 可选的预分配浮点型 numpy.ndarray，用于写入结果。提供时不会分配新数组。

  • byteswap -- 在转换前反转每个元素的字节序——当缓冲区来自以与摄像头 CPU 相反的字节序写入的外设时，这是正确的设置。

返回:

长度为 count 的浮点型 numpy.ndarray（当 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

一次性将 uint16 样本缓冲区转换为浮点型 numpy.ndarray。

参数:

  • buffer -- 存放样本的字节类缓冲区。

  • count -- 要读取的元素数量。-1 表示从 offset 到末尾读取整个缓冲区。

  • offset -- 在缓冲区起始处要跳过的字节数。

  • out -- 可选的预分配浮点型 numpy.ndarray，用于写入结果。提供时不会分配新数组。

  • byteswap -- 在转换前反转每个元素的字节序——当缓冲区来自以与摄像头 CPU 相反的字节序写入的外设时，这是正确的设置。

返回:

长度为 count 的浮点型 numpy.ndarray（当 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

一次性将 int32 样本缓冲区转换为浮点型 numpy.ndarray。

参数:

  • buffer -- 存放样本的字节类缓冲区。

  • count -- 要读取的元素数量。-1 表示从 offset 到末尾读取整个缓冲区。

  • offset -- 在缓冲区起始处要跳过的字节数。

  • out -- 可选的预分配浮点型 numpy.ndarray，用于写入结果。提供时不会分配新数组。

  • byteswap -- 在转换前反转每个元素的字节序——当缓冲区来自以与摄像头 CPU 相反的字节序写入的外设时，这是正确的设置。

返回:

长度为 count 的浮点型 numpy.ndarray（当 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

一次性将 uint32 样本缓冲区转换为浮点型 numpy.ndarray。

参数:

  • buffer -- 存放样本的字节类缓冲区。

  • count -- 要读取的元素数量。-1 表示从 offset 到末尾读取整个缓冲区。

  • offset -- 在缓冲区起始处要跳过的字节数。

  • out -- 可选的预分配浮点型 numpy.ndarray，用于写入结果。提供时不会分配新数组。

  • byteswap -- 在转换前反转每个元素的字节序——当缓冲区来自以与摄像头 CPU 相反的字节序写入的外设时，这是正确的设置。

返回:

长度为 count 的浮点型 numpy.ndarray（当 count 为 -1 时，长度为可用的样本数量）。

频谱图

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

返回输入的离散傅里叶变换的幅度，概念上等价于在调用 numpy.fft.fft() 之后计算 np.sqrt(real * real + imag * imag)——但不会分配显式形式所需的中间缓冲区。

参数:

  • r -- 输入的实部，作为一维浮点型 numpy.ndarray。其长度必须为 2 的幂。

  • imag -- 可选的输入虚部，与 r 形状相同。省略时，输入被视为纯实数。

  • scratchpad -- 可选的 FFT 工作缓冲区。提供时不会分配临时工作数组。

  • out -- 可选的预分配目标缓冲区，用于存放幅度谱。提供时，结果将直接写入其中。

  • log -- 当为 True 时，返回幅度的自然对数而非幅度本身。

返回:

与 r 长度相同的浮点型 numpy.ndarray，存放每个频率分量（bin）处的幅度（或其对数）。