ulab.utils — ulab-Hilfsfunktionen

Das Submodul ulab.utils stellt eine kleine Auswahl an Hilfsfunktionen bereit, die auf numpy.ndarray-Objekten operieren, aber außerhalb der Standard-Oberfläche von NumPy / SciPy liegen. Die Hilfsfunktionen sind auf die für eingebettete Systeme typischen Streaming-Muster abgestimmt – Peripherie-Puffer mit mehr als 16 Bit, allokationsfreie Magnitudenspektren.

Puffer-Konverter

Das Standard-numpy.frombuffer() verarbeitet nur dtypes, die numpy selbst definiert (uint8, int8, uint16, int16, float). Die folgenden Hilfsfunktionen erweitern diese Abdeckung auf int16- / uint16- / int32- / uint32-Byte-Puffer und geben in einem Durchgang ein float-numpy.ndarray zurück.

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

Konvertiert einen Puffer mit int16-Stichproben in einem Durchgang in ein float-numpy.ndarray.

Parameter:

  • buffer – ein bytes-artiger Puffer, der die Stichproben enthält.

  • count – Anzahl der zu lesenden Elemente. -1 liest den gesamten Puffer von offset bis zum Ende.

  • offset – Anzahl der am Anfang des Puffers zu überspringenden Bytes.

  • out – optionales vorab allokiertes float-numpy.ndarray, in das das Ergebnis geschrieben wird. Wenn angegeben, wird kein neues Array allokiert.

  • byteswap – kehrt die Byte-Reihenfolge jedes Elements vor der Konvertierung um – die richtige Einstellung, wenn der Puffer von einem Peripheriegerät stammt, das in umgekehrter Byte-Reihenfolge zur CPU der Kamera geschrieben hat.

Rückgabe:

ein float-numpy.ndarray der Länge count (oder der verfügbaren Anzahl von Stichproben, wenn count gleich -1 ist).

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

Konvertiert einen Puffer mit uint16-Stichproben in einem Durchgang in ein float-numpy.ndarray.

Parameter:

  • buffer – ein bytes-artiger Puffer, der die Stichproben enthält.

  • count – Anzahl der zu lesenden Elemente. -1 liest den gesamten Puffer von offset bis zum Ende.

  • offset – Anzahl der am Anfang des Puffers zu überspringenden Bytes.

  • out – optionales vorab allokiertes float-numpy.ndarray, in das das Ergebnis geschrieben wird. Wenn angegeben, wird kein neues Array allokiert.

  • byteswap – kehrt die Byte-Reihenfolge jedes Elements vor der Konvertierung um – die richtige Einstellung, wenn der Puffer von einem Peripheriegerät stammt, das in umgekehrter Byte-Reihenfolge zur CPU der Kamera geschrieben hat.

Rückgabe:

ein float-numpy.ndarray der Länge count (oder der verfügbaren Anzahl von Stichproben, wenn count gleich -1 ist).

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

Konvertiert einen Puffer mit int32-Stichproben in einem Durchgang in ein float-numpy.ndarray.

Parameter:

  • buffer – ein bytes-artiger Puffer, der die Stichproben enthält.

  • count – Anzahl der zu lesenden Elemente. -1 liest den gesamten Puffer von offset bis zum Ende.

  • offset – Anzahl der am Anfang des Puffers zu überspringenden Bytes.

  • out – optionales vorab allokiertes float-numpy.ndarray, in das das Ergebnis geschrieben wird. Wenn angegeben, wird kein neues Array allokiert.

  • byteswap – kehrt die Byte-Reihenfolge jedes Elements vor der Konvertierung um – die richtige Einstellung, wenn der Puffer von einem Peripheriegerät stammt, das in umgekehrter Byte-Reihenfolge zur CPU der Kamera geschrieben hat.

Rückgabe:

ein float-numpy.ndarray der Länge count (oder der verfügbaren Anzahl von Stichproben, wenn count gleich -1 ist).

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

Konvertiert einen Puffer mit uint32-Stichproben in einem Durchgang in ein float-numpy.ndarray.

Parameter:

  • buffer – ein bytes-artiger Puffer, der die Stichproben enthält.

  • count – Anzahl der zu lesenden Elemente. -1 liest den gesamten Puffer von offset bis zum Ende.

  • offset – Anzahl der am Anfang des Puffers zu überspringenden Bytes.

  • out – optionales vorab allokiertes float-numpy.ndarray, in das das Ergebnis geschrieben wird. Wenn angegeben, wird kein neues Array allokiert.

  • byteswap – kehrt die Byte-Reihenfolge jedes Elements vor der Konvertierung um – die richtige Einstellung, wenn der Puffer von einem Peripheriegerät stammt, das in umgekehrter Byte-Reihenfolge zur CPU der Kamera geschrieben hat.

Rückgabe:

ein float-numpy.ndarray der Länge count (oder der verfügbaren Anzahl von Stichproben, wenn count gleich -1 ist).

Spektrogramm

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

Gibt die Magnitude der diskreten Fourier-Transformation der Eingabe zurück, konzeptionell äquivalent zu np.sqrt(real * real + imag * imag) nach einem Aufruf von numpy.fft.fft() – ohne die Zwischenpuffer zu allokieren, die die explizite Form benötigen würde.

Parameter:

  • r – der Realteil der Eingabe als 1-D-float-numpy.ndarray. Seine Länge muss eine Zweierpotenz sein.

  • imag – optionaler Imaginärteil der Eingabe, gleiche Form wie r. Wird er weggelassen, wird die Eingabe als rein reell behandelt.

  • scratchpad – optionaler Arbeitspuffer für die FFT. Wenn angegeben, wird kein temporäres Arbeits-Array allokiert.

  • out – optionaler vorab allokierter Zielpuffer für das Magnitudenspektrum. Wenn angegeben, wird das Ergebnis direkt darin gespeichert.

  • log – wenn True, wird der natürliche Logarithmus der Magnitude statt der Magnitude selbst zurückgegeben.

Rückgabe:

ein float-numpy.ndarray derselben Länge wie r, das die Magnitude (oder deren Logarithmus) an jedem Frequenzbin enthält.