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.