image — maschinelles Sehen#

Das Modul image ist das Herzstück des Stacks für maschinelles Sehen von OpenMV. Es stellt die Klasse Image bereit – den Pixelpuffer im Arbeitsspeicher, auf dem jede Zeichen-, Filter-, Transformations- und Merkmalsextraktionsroutine arbeitet – zusammen mit den unterstützenden Ergebnisobjekten, die diese Routinen zurückgeben (Blob, Line, Circle, Rect, QRCode, AprilTag, DataMatrix, BarCode, …) und den Hilfsklassen zu ihrer Konfiguration (Threshold, Histogram, Statistics, HaarCascade, Similarity, Percentile, Displacement, ImageIO).

Ein Bild erfassen#

Es gibt vier Möglichkeiten, ein Image in den RAM zu bekommen:

  • Live-Aufnahme vom Kamerasensor. Rufen Sie csi.CSI.snapshot() auf, um das nächste Einzelbild direkt in den Framebuffer zu erfassen; das zurückgegebene Image verweist auf diesen Puffer.

  • Aus einer Datei. Übergeben Sie einen Pfad an den Konstruktor von Image (image.Image("/sd/photo.jpg")); unterstützte Formate auf dem Datenträger sind BMP, PPM/PGM, JPEG, PNG und das OpenMV-Aufnahmeformat ImageIO.

  • Aus einem ndarray. Übergeben Sie ein float32-(h, w)- oder (h, w, 3)-ndarray an den Konstruktor von Image. Die Pixel werden von 0.0 -- 255.0 in ein GRAYSCALE- bzw. RGB565-Bild skaliert. Verwenden Sie dies, um eine Tensor-Ausgabe von ml (oder einer beliebigen ulab-Pipeline) wieder in ein zeichenbares Bild zu überführen.

  • Leerer Puffer. Konstruieren Sie ein Image mit einer bestimmten Größe und einem bestimmten Pixelformat (image.Image(320, 240, image.RGB565)), um von Grund auf darin zu zeichnen oder es als Zwischenfläche für Bildarithmetik zu verwenden.

Pixelformate#

Jedes Image besitzt eines der folgenden Pixelformate; die Wahl ist ein Kompromiss zwischen Speicher, Verarbeitungsaufwand und den darauf ausführbaren Algorithmen. Verwenden Sie BINARY, GRAYSCALE, RGB565, BAYER, YUV422, JPEG oder PNG als pixformat-Argument beim Konstruieren eines Bildes oder beim Konfigurieren des Kamerasensors:

  • BINARY (1 bpp) – ein Bit pro Pixel. Das kleinste Format; wird intern von Schwellenwert- und Morphologieroutinen verwendet, aber selten direkt vom Sensor erfasst.

  • GRAYSCALE (8 bpp) – ein Byte pro Pixel (der Y-Kanal von YUV422). Das schnellste Format für die meisten Algorithmen des maschinellen Sehens (AprilTag, Kantenerkennung, optischer Fluss).

  • RGB565 (16 bpp) – zwei Byte pro Pixel, 5 Bit Rot / 6 Bit Grün / 5 Bit Blau. Das Standard-Farbformat.

  • BAYER (8 bpp) – rohe Farbdaten im Bayer-Muster direkt vom Sensor. Nützlich für eigenes De-Mosaicing oder um mehr Pixel in weniger Speicher abzulegen, bevor sie bei Bedarf debayert werden.

  • YUV422 (16 bpp) – 4:2:2-chroma-unterabgetastete Farbe, zwei Byte pro Pixel. Nützlich, wenn Sie chroma-spezifische Algorithmen ohne die vollen RGB-Kosten benötigen.

  • JPEG / PNG – komprimierte Puffer. Am besten geeignet zum Speichern und zur Netzwerkübertragung. Operationen auf Pixelebene erfordern zuvor Image.to_grayscale() oder Image.to_rgb565().

Mit Ergebnissen arbeiten#

Die Erkennungs- bzw. Merkmalsextraktionsmethoden von Image geben Objekte zurück, über die Sie iterieren und die Sie kombinieren können – ein Aufruf von Image.find_blobs() gibt eine Liste von Blob zurück, ein Aufruf von Image.find_apriltags() gibt eine Liste von AprilTag zurück usw. Jede Ergebnisklasse stellt die geometrischen Eigenschaften der Erkennung bereit (Schwerpunkt, Begrenzungsrahmen, Fläche, Codewert usw.), sodass Sie direkt darauf reagieren oder sie an Zeichenmethoden zurückgeben können (Image.draw_rectangle(), Image.draw_string(), …).

Hilfsfunktionen für Farbräume#

Das Modul stellt außerdem kleine reine Funktionen bereit, um einzelne Pixelwerte zwischen den Farbräumen Binär / Graustufen / RGB / LAB / YUV umzuwandeln. Diese sind nützlich, wenn Sie Schwellenwerte oder Paletteneinträge in Python umwandeln müssen, bevor Sie sie an Bildoperationen übergeben – für die Umwandlung ganzer Bilder verwenden Sie die to_*-Methoden von Image, die viel schneller sind als der Aufruf dieser Hilfsfunktionen in einer Schleife.

Klassen#

Funktionen#

Hilfsfunktionen zur Farbraumkonvertierung#

Jede der folgenden X_to_Y-Funktionen führt eine einzelne Pixelwert-Umwandlung durch. Sie alle nehmen/geben Werte in den kanonischen OpenMV-Bereichen entgegen bzw. zurück:

  • Binär – int 0 – 1.

  • Graustufen – int 0 – 255.

  • RGB – (r, g, b)-Tupel aus 8-Bit-Ganzzahlen (jeweils 0 – 255).

  • LAB – (l, a, b)-Tupel mit L im Bereich 0 – 100 und A/B im Bereich -128 – 127.

  • YUV – (y, u, v)-Tupel mit Y im Bereich 0 – 255 und U/V im Bereich -128 – 127.

Für die Umwandlung ganzer Bilder verwenden Sie die to_*-Methoden von Image, die viel schneller sind als der Aufruf dieser Hilfsfunktionen in einer Schleife.

image.binary_to_grayscale(value: int) int#

Wandelt einen Binärwert in einen Graustufenwert um.

image.binary_to_rgb(value: int) Tuple[int, int, int]#

Wandelt einen Binärwert in ein RGB-Tupel um.

image.binary_to_lab(value: int) Tuple[int, int, int]#

Wandelt einen Binärwert in ein LAB-Tupel um.

image.binary_to_yuv(value: int) Tuple[int, int, int]#

Wandelt einen Binärwert in ein YUV-Tupel um.

image.grayscale_to_binary(value: int) int#

Wandelt einen Graustufenwert in einen Binärwert um.

image.grayscale_to_rgb(value: int) Tuple[int, int, int]#

Wandelt einen Graustufenwert in ein RGB-Tupel um.

image.grayscale_to_lab(value: int) Tuple[int, int, int]#

Wandelt einen Graustufenwert in ein LAB-Tupel um.

image.grayscale_to_yuv(value: int) Tuple[int, int, int]#

Wandelt einen Graustufenwert in ein YUV-Tupel um.

image.rgb_to_binary(value: Tuple[int, int, int]) int#

Wandelt ein RGB-Tupel in einen Binärwert um.

image.rgb_to_grayscale(value: Tuple[int, int, int]) int#

Wandelt ein RGB-Tupel in einen Graustufenwert um.

image.rgb_to_lab(value: Tuple[int, int, int]) Tuple[int, int, int]#

Wandelt ein RGB-Tupel in ein LAB-Tupel um.

image.rgb_to_yuv(value: Tuple[int, int, int]) Tuple[int, int, int]#

Wandelt ein RGB-Tupel in ein YUV-Tupel um.

image.lab_to_binary(value: Tuple[int, int, int]) int#

Wandelt ein LAB-Tupel in einen Binärwert um.

image.lab_to_grayscale(value: Tuple[int, int, int]) int#

Wandelt ein LAB-Tupel in einen Graustufenwert um.

image.lab_to_rgb(value: Tuple[int, int, int]) Tuple[int, int, int]#

Wandelt ein LAB-Tupel in ein RGB-Tupel um.

image.lab_to_yuv(value: Tuple[int, int, int]) Tuple[int, int, int]#

Wandelt ein LAB-Tupel in ein YUV-Tupel um.

image.yuv_to_binary(value: Tuple[int, int, int]) int#

Wandelt ein YUV-Tupel in einen Binärwert um.

image.yuv_to_grayscale(value: Tuple[int, int, int]) int#

Wandelt ein YUV-Tupel in einen Graustufenwert um.

image.yuv_to_rgb(value: Tuple[int, int, int]) Tuple[int, int, int]#

Wandelt ein YUV-Tupel in ein RGB-Tupel um.

image.yuv_to_lab(value: Tuple[int, int, int]) Tuple[int, int, int]#

Wandelt ein YUV-Tupel in ein LAB-Tupel um.

Merkmalsdeskriptoren#

image.HaarCascade(path: str, stages: int = -1) Cascade#

Lädt eine Haar-Kaskade und gibt ein Cascade-Handle zur Verwendung mit Image.find_features() zurück.

path kann entweder sein:

  • die wörtliche Zeichenkette "frontalface" oder "eye", um eine der beiden im Firmware-ROM eingebackenen Kaskaden zu laden, oder

  • ein Dateisystempfad zu einer benutzerdefinierten .cascade-Binärdatei, die von den OpenMV-Kaskaden-Konverter-Tools erzeugt wurde.

stages wählt aus, wie viele Kaskadenstufen zur Erkennungszeit ausgewertet werden. -1 verwendet jede in der Datei gespeicherte Stufe. Eine Verringerung dieses Werts beschleunigt die Erkennung auf Kosten von mehr Falscherkennungen.

image.load_descriptor(path: str) kp_desc | lbp_desc#

Lädt einen Deskriptor aus der Datei unter path und gibt ihn zurück. Das interne Typkennzeichen der Datei wählt aus, welche Deskriptorklasse rekonstruiert wird:

image.save_descriptor(descriptor: kp_desc | lbp_desc, path: str) None#

Serialisiert descriptor (einen ORB-Schlüsselpunkt- oder LBP-Deskriptor) in die Datei unter path im OpenMV-Deskriptordateiformat. Dieselbe Datei kann später über image.load_descriptor() erneut geladen werden.

image.match_descriptor(descriptor0, descriptor1, threshold: int = 85, filter_outliers: bool = False) int | kptmatch#

Vergleicht zwei Deskriptoren desselben Typs.

  • Bei zwei LBP-Deskriptoren – gibt einen ganzzahligen Hamming-Abstand zwischen ihnen zurück (niedriger bedeutet eine engere Übereinstimmung).

  • Bei zwei ORB-Schlüsselpunkt-Deskriptoren – gibt ein kptmatch zurück, das den Cluster übereinstimmender Schlüsselpunkte beschreibt, oder None, wenn keine Übereinstimmung threshold besteht.

threshold (0 – 100) legt fest, wie streng die ORB-Übereinstimmung beim Akzeptieren eines Schlüsselpunktpaars ist. Niedrigere Werte verschärfen die Übereinstimmung, indem schwache Nächste-Nachbarn-Übereinstimmungen abgewiesen werden.

filter_outliers aktiviert eine Ausreißerabweisung im RANSAC-Stil über die Menge der übereinstimmenden Schlüsselpunkte. Verwenden Sie es, wenn Sie eine einzelne starre Transformation zwischen den beiden Ansichten erwarten; deaktivieren Sie es, wenn die übereinstimmenden Schlüsselpunkte mehrere Objekte umfassen.

Hilfsfunktionen für Blob-Geometrie#

Diese Hilfsfunktionen nehmen ein Blob (wie von Image.find_blobs() zurückgegeben) und berechnen bei Bedarf zusätzliche geometrische Eigenschaften. Sie befinden sich auf Modulebene – nicht auf Blob – damit der einfache find_blobs()-Pfad nicht für sie bezahlt, sofern Sie sie nicht anfordern.

image.get_solidity(blob: blob) float#

Gibt die Solidität (blob.pixels / convex_hull_area) von blob zurück. Float, 0 – 1; 1.0 bedeutet, dass der Blob seine konvexe Hülle vollständig ausfüllt.

image.get_convexity(blob: blob) float#

Gibt die Konvexität (convex_hull_perimeter / blob.perimeter) von blob zurück. Float, 0 – 1; 1.0 ist ein perfekt konvexer Blob.

image.get_major_axis_line(blob: blob) line#

Gibt eine Line entlang der Hauptachse von blob zurück (die längere der beiden Hauptachsen des flächenminimalen gedrehten Rechtecks).

image.get_minor_axis_line(blob: blob) line#

Gibt eine Line entlang der Nebenachse von blob zurück (die kürzere der beiden Hauptachsen des flächenminimalen gedrehten Rechtecks).

image.get_enclosing_circle(blob: blob) circle#

Gibt einen Circle zurück, der blob umschließt.

image.get_enclosed_ellipse(blob: blob) Tuple[int, int, int, int, int]#

Gibt ein 5-Tupel (cx, cy, a, b, rotation) zurück, das die in das flächenminimale gedrehte Rechteck um blob einbeschriebene Ellipse beschreibt:

  • cx / cy – Ellipsenmittelpunkt in Pixeln (Ganzzahl).

  • a / b – Halbachsenlängen in Pixeln (Ganzzahl).

  • rotation – Ellipsendrehung in Grad (Ganzzahl).

Dies ist ein einfaches Tupel, kein attrtuple, sodass die Felder nur über den Index zugänglich sind.

Konstanten#

Pixelformate#

Übergeben Sie eine der folgenden Optionen als pixformat-Argument an den Konstruktor von Image oder an csi.CSI.pixformat().

image.BINARY: int#

1-Bit-pro-Pixel-Bitmap. Kleinstes Format – wird intern von Schwellenwertbildung und Morphologie verwendet, selten direkt von einem Sensor erfasst.

image.GRAYSCALE: int#

8-Bit-pro-Pixel-Graustufen (ein Byte pro Pixel). Das schnellste Format für die meisten Algorithmen des maschinellen Sehens (AprilTag, Kantenerkennung, optischer Fluss).

image.RGB565: int#

16-Bit-pro-Pixel-Farbe, gepackt als 5 Bit Rot / 6 Bit Grün / 5 Bit Blau. Das Standard-Farbformat.

image.BAYER: int#

8-Bit-pro-Pixel-Rohdaten im Bayer-Format direkt vom Sensor. Die meisten Bildverarbeitungsmethoden sind für Bayer-Bilder nicht verfügbar; verwenden Sie dies, wenn Sie bei Bedarf debayern oder mehr Pixel in weniger Speicher ablegen möchten.

image.YUV422: int#

4:2:2-chroma-unterabgetastete Farbe, zwei Byte pro Pixel, gepackt als Y1, U, Y2, V pro Pixelpaar. Nur einige Bildverarbeitungsmethoden funktionieren direkt auf YUV422.

image.JPEG: int#

Komprimierter JPEG-Puffer. Operationen auf Pixelebene erfordern zuvor Image.to_grayscale() oder Image.to_rgb565().

image.PNG: int#

Komprimierter PNG-Puffer. Operationen auf Pixelebene erfordern zuvor Image.to_grayscale() oder Image.to_rgb565().

Farbpaletten#

Übergeben Sie eine der folgenden Optionen an Image.to_rainbow(), Image.to_ironbow(), Image.draw_image() (color_palette=) oder an csi.CSI.color_palette(), um ein Graustufenbild einzufärben.

image.PALETTE_RAINBOW: int#

Glattes Regenbogen-Farbrad. Die Standardpalette von OpenMV für Wärmebilder.

image.PALETTE_IRONBOW: int#

Nichtlineare „Ironbow“-Palette, die das Aussehen des Wärmebild-Suchers FLIR Lepton nachahmt.

image.PALETTE_DEPTH: int#

Tiefenbild-Palette. Nur auf Builds mit Tiefensensor-Unterstützung verfügbar (die ToF-Pipeline – z. B. OpenMV Cam AE3 oder jede Kamera mit angeschlossenem ToF-Pmod).

image.PALETTE_EVT_DARK: int#

Palette zur Visualisierung von GENX320-Event-Kamera-Einzelbildern auf dunklem Hintergrund. Übergeben Sie sie an csi.CSI.color_palette, damit der GENX320-Treiber im Histogrammmodus eingefärbte RGB565-Einzelbilder ausgibt, oder an Image.draw_image() color_palette=, wenn ein Graustufen-Event-Bild eingefärbt wird.

Nur auf Builds mit GENX320-Unterstützung verfügbar (OpenMV Cam AE3 und das GENX320-Pmod).

image.PALETTE_EVT_LIGHT: int#

Palette zur Visualisierung von GENX320-Event-Kamera-Einzelbildern auf hellem Hintergrund. Gleiche Verteilung und Verfügbarkeit wie PALETTE_EVT_DARK.

Skalierungsmodi#

Übergeben Sie eine der folgenden Optionen als hint-Argument an Image.draw_image(), Image.scale() oder ähnliche Skalierungsmethoden.

image.AREA: int#

Flächenmittelnder Skalierer. Wird beim Herunterskalieren verwendet; beim Hochskalieren wird Nearest-Neighbor verwendet.

image.BILINEAR: int#

Bilinearer Skalierer. Tastet beim Herunterskalieren unter.

image.BICUBIC: int#

Bikubischer Skalierer. Höhere Qualität als BILINEAR, aber langsamer. Tastet beim Herunterskalieren unter.

Hinweise für Zeichnen / draw_image#

Verknüpfen Sie beliebige davon per Bit-OR und übergeben Sie sie als hint-Argument von Image.draw_image().

image.VFLIP: int#

Spiegelt die Quelle beim Zeichnen vertikal.

image.HMIRROR: int#

Spiegelt die Quelle beim Zeichnen horizontal.

image.TRANSPOSE: int#

Transponiert die Quelle (vertauscht x/y) beim Zeichnen.

image.CENTER: int#

Zentriert die Quelle auf dem Ziel. Etwaige explizite x/y-Versätze werden dann zu Versätzen vom Mittelpunkt statt von der oberen linken Ecke.

image.EXTRACT_RGB_CHANNEL_FIRST: int#

Beim Extrahieren eines RGB-Kanals über Image.draw_image() wird der Kanal vor dem Skalieren extrahiert. Ohne diesen Hinweis wird der Kanal nach dem Skalieren extrahiert.

image.APPLY_COLOR_PALETTE_FIRST: int#

Beim Anwenden einer Farbpalette über Image.draw_image() wird die Palette vor dem Skalieren angewendet. Ohne diesen Hinweis wird die Palette nach dem Skalieren angewendet.

image.SCALE_ASPECT_KEEP: int#

Skaliert die Quelle so, dass sie unter Beibehaltung des Seitenverhältnisses in das Ziel passt (Letterboxing bei abweichenden Verhältnissen).

image.SCALE_ASPECT_EXPAND: int#

Skaliert die Quelle so, dass sie das Ziel unter Beibehaltung des Seitenverhältnisses ausfüllt (Zuschnitt bei abweichenden Verhältnissen).

image.SCALE_ASPECT_IGNORE: int#

Skaliert die Quelle so, dass sie das Ziel ausfüllt, wobei das Seitenverhältnis ignoriert wird.

image.BLACK_BACKGROUND: int#

Teilt dem Alpha-Blending-Pfad mit, dass das Ziel garantiert schwarz ist, sodass das Zurücklesen des Zielpixels übersprungen werden kann. Beschleunigt Alpha-Effekte auf frisch geleerten Puffern.

image.ROTATE_90: int#

Abkürzung für VFLIP | TRANSPOSE (um 90 Grad im Uhrzeigersinn drehen).

image.ROTATE_180: int#

Abkürzung für HMIRROR | VFLIP (um 180 Grad drehen).

image.ROTATE_270: int#

Abkürzung für HMIRROR | TRANSPOSE (um 270 Grad im Uhrzeigersinn drehen).

JPEG-Unterabtastung#

Übergeben Sie eine der folgenden Optionen als subsampling-Argument an Image.to_jpeg(), Image.compress() oder Image.save() beim Schreiben eines JPEG.

image.JPEG_SUBSAMPLING_AUTO: int#

Wählt die Chroma-Unterabtastung automatisch anhand der JPEG-Qualitätseinstellung.

image.JPEG_SUBSAMPLING_444: int#

Erzwingt 4:4:4-Chroma-Unterabtastung (keine Chroma-Kompression).

image.JPEG_SUBSAMPLING_422: int#

Erzwingt 4:2:2-Chroma-Unterabtastung. Empfohlen beim Streamen von MJPEG an Drittanbieter-Videoplayer, die sich bei 4:2:0 fehlerhaft verhalten.

image.JPEG_SUBSAMPLING_420: int#

Erzwingt 4:2:0-Chroma-Unterabtastung.

Template-Matching#

Übergeben Sie eine der folgenden Optionen als search-Argument an Image.find_template().

image.SEARCH_EX: int#

Erschöpfende Suche – wertet jede Position im ROI aus. Am langsamsten, aber garantiert, die beste Übereinstimmung zu finden.

image.SEARCH_DS: int#

Diamantsuche – eine Grob-zu-Fein-Suche, die viel schneller als SEARCH_EX ist, aber bei stark selbstähnlichen Templates das globale Optimum verfehlen kann.

Kantenerkennung#

Übergeben Sie eine der folgenden Optionen als algorithm-Argument an Image.find_edges().

image.EDGE_CANNY: int#

Canny-Kantendetektor – Gradientenbetrag + Non-Max-Suppression + Hysterese. Höhere Qualität, langsamer.

image.EDGE_SIMPLE: int#

Schwellenwertbasierter Hochpassfilter-Kantendetektor. Schneller, erzeugt aber dickere, verrauschtere Kanten als EDGE_CANNY.

ORB-Eckendetektoren#

Übergeben Sie eine der folgenden Optionen als corner_detector-Argument an Image.find_keypoints().

image.CORNER_FAST: int#

FAST-Eckendetektor. Schneller als CORNER_AGAST, aber weniger genau.

image.CORNER_AGAST: int#

AGAST-Eckendetektor. Langsamer als CORNER_FAST, erzeugt aber stabilere Schlüsselpunkte.

AprilTag-Familien#

Verknüpfen Sie eine beliebige Kombination der folgenden Optionen per Bit-OR und übergeben Sie sie als families-Argument an Image.find_apriltags(). Jede Familie wird durch ihre eigene Build-Option in der Firmware freigeschaltet; nicht unterstützte Familien sind zur Laufzeit nicht vorhanden, statt immer null zu sein.

image.TAG16H5: int#

AprilTag-Familie 16h5 (30 eindeutige IDs, 0-Bit-Fehlerkorrektur).

image.TAG25H9: int#

AprilTag-Familie 25h9 (35 eindeutige IDs, bis zu 3-Bit-Fehlerkorrektur).

image.TAG36H10: int#

AprilTag-Familie 36h10 (2320 eindeutige IDs, bis zu 3-Bit-Fehlerkorrektur).

image.TAG36H11: int#

AprilTag-Familie 36h11 (587 eindeutige IDs, bis zu 4-Bit-Fehlerkorrektur). Die häufigste Familie.

image.TAGCIRCLE21H7: int#

AprilTag-Familie Circle21h7.

image.TAGCIRCLE49H12: int#

AprilTag-Familie Circle49h12.

image.TAGCUSTOM48H12: int#

AprilTag-Familie Custom48h12.

image.TAGSTANDARD41H12: int#

AprilTag-Familie Standard41h12.

image.TAGSTANDARD52H13: int#

AprilTag-Familie Standard52h13.

Barcode-Symbologien#

Die in BarCode.type gemeldeten Werte für von Image.find_barcodes() zurückgegebene Einträge.

image.EAN2: int#

EAN-2-Zusatzbarcode.

image.EAN5: int#

EAN-5-Zusatzbarcode.

image.EAN8: int#

EAN-8-Barcode.

image.UPCE: int#

UPC-E-Barcode.

image.ISBN10: int#

ISBN-10-Barcode.

image.UPCA: int#

UPC-A-Barcode.

image.EAN13: int#

EAN-13-Barcode.

image.ISBN13: int#

ISBN-13-Barcode.

image.I25: int#

Interleaved-2-of-5-Barcode.

image.DATABAR: int#

GS1-DataBar-Barcode.

image.DATABAR_EXP: int#

GS1-DataBar-Expanded-Barcode.

image.CODABAR: int#

Codabar-Barcode.

image.CODE39: int#

Code-39-Barcode.

image.PDF417: int#

PDF417-2D-Stapelbarcode. Die Konstante existiert der Vollständigkeit halber, aber der Barcode-Decoder implementiert PDF417 derzeit nicht – Image.find_barcodes() gibt keine Erkennungen dieses Typs zurück.

image.CODE93: int#

Code-93-Barcode.

image.CODE128: int#

Code-128-Barcode.