`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 -- 保存樣本的類 bytes 緩衝區。
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 -- 保存樣本的類 bytes 緩衝區。
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 -- 保存樣本的類 bytes 緩衝區。
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，保存每個頻率區間（frequency bin）的幅度（或其對數）。

ulab.utils --- ulab 公用程式輔助函式¶

緩衝區轉換器¶

頻譜圖¶

`ulab.utils` --- ulab 公用程式輔助函式¶