ulab.utils --- ulab ユーティリティヘルパー

ulab.utils サブモジュールは、numpy.ndarray オブジェクトを操作するものの、標準的な NumPy / SciPy の範囲外に位置する小さなヘルパー群を提供します。これらのヘルパーは、組み込みターゲットで一般的なストリーミングパターン（16ビットを超える幅のペリフェラルバッファ、アロケーションを伴わない振幅スペクトル）向けに調整されています。

バッファコンバータ

標準の numpy.frombuffer() は numpy 自体が定義する dtype（uint8、int8、uint16、int16、float）のみを扱います。以下のヘルパーはその対応範囲を int16 / uint16 / int32 / uint32 のバイトバッファにまで拡張し、1パスで float 型 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 サンプルのバッファを1パスで float 型 numpy.ndarray に変換します。

パラメータ:

  • buffer -- サンプルを保持する bytes 様のバッファです。

  • count -- 読み取る要素数です。-1 は offset から末尾までバッファ全体を読み取ります。

  • offset -- バッファの先頭でスキップするバイト数です。

  • out -- 結果を書き込む、事前に確保された float 型 numpy.ndarray（省略可能）です。指定された場合、新しい配列は確保されません。

  • byteswap -- 変換前に各要素のバイト順を反転します。バッファがカメラの CPU とは逆のバイト順で書き込むペリフェラルから得られた場合に適した設定です。

戻り値:

長さ count の float 型 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 サンプルのバッファを1パスで float 型 numpy.ndarray に変換します。

パラメータ:

  • buffer -- サンプルを保持する bytes 様のバッファです。

  • count -- 読み取る要素数です。-1 は offset から末尾までバッファ全体を読み取ります。

  • offset -- バッファの先頭でスキップするバイト数です。

  • out -- 結果を書き込む、事前に確保された float 型 numpy.ndarray（省略可能）です。指定された場合、新しい配列は確保されません。

  • byteswap -- 変換前に各要素のバイト順を反転します。バッファがカメラの CPU とは逆のバイト順で書き込むペリフェラルから得られた場合に適した設定です。

戻り値:

長さ count の float 型 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 サンプルのバッファを1パスで float 型 numpy.ndarray に変換します。

パラメータ:

  • buffer -- サンプルを保持する bytes 様のバッファです。

  • count -- 読み取る要素数です。-1 は offset から末尾までバッファ全体を読み取ります。

  • offset -- バッファの先頭でスキップするバイト数です。

  • out -- 結果を書き込む、事前に確保された float 型 numpy.ndarray（省略可能）です。指定された場合、新しい配列は確保されません。

  • byteswap -- 変換前に各要素のバイト順を反転します。バッファがカメラの CPU とは逆のバイト順で書き込むペリフェラルから得られた場合に適した設定です。

戻り値:

長さ count の float 型 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 サンプルのバッファを1パスで float 型 numpy.ndarray に変換します。

パラメータ:

  • buffer -- サンプルを保持する bytes 様のバッファです。

  • count -- 読み取る要素数です。-1 は offset から末尾までバッファ全体を読み取ります。

  • offset -- バッファの先頭でスキップするバイト数です。

  • out -- 結果を書き込む、事前に確保された float 型 numpy.ndarray（省略可能）です。指定された場合、新しい配列は確保されません。

  • byteswap -- 変換前に各要素のバイト順を反転します。バッファがカメラの CPU とは逆のバイト順で書き込むペリフェラルから得られた場合に適した設定です。

戻り値:

長さ count の float 型 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 -- 入力の実部を1次元の float 型 numpy.ndarray として与えます。その長さは2のべき乗でなければなりません。

  • imag -- 入力の虚部（省略可能）で、r と同じ形状です。省略された場合、入力は純粋な実数として扱われます。

  • scratchpad -- FFT 用の作業バッファ（省略可能）です。指定された場合、一時的な作業配列は確保されません。

  • out -- 振幅スペクトル用の、事前に確保された出力先バッファ（省略可能）です。指定された場合、結果はそこに直接書き込まれます。

  • log -- True の場合、振幅そのものではなく振幅の自然対数を返します。

戻り値:

r と同じ長さの float 型 numpy.ndarray で、各周波数ビンにおける振幅（またはその対数）を保持します。