image — machine vision

De image-module is het hart van de OpenMV machine-vision-stack. Hij stelt de Image-klasse beschikbaar – de pixelbuffer in het geheugen waarop elke teken-, filter-, transformatie- en kenmerkextractieroutine werkt – samen met de bijbehorende resultaatobjecten die door die routines worden geretourneerd (Blob, Line, Circle, Rect, QRCode, AprilTag, DataMatrix, BarCode, …) en de hulpklassen die worden gebruikt om ze te configureren (Threshold, Histogram, Statistics, HaarCascade, Similarity, Percentile, Displacement, ImageIO).

Een afbeelding verkrijgen

Er zijn vier manieren om een Image in het RAM te krijgen:

  • Live opname van de camerasensor. Roep csi.CSI.snapshot() aan om het volgende frame rechtstreeks in de framebuffer vast te leggen; de geretourneerde Image verwijst naar die buffer.

  • Vanuit een bestand. Geef een pad door aan de Image-constructor (image.Image("/sd/photo.jpg")); ondersteunde formaten op schijf zijn BMP, PPM/PGM, JPEG, PNG en het OpenMV ImageIO-opnameformaat.

  • Vanuit een ndarray. Geef een float32 (h, w)- of (h, w, 3)-ndarray door aan de Image-constructor. De pixels worden van 0.0 -- 255.0 geschaald naar respectievelijk een GRAYSCALE- of RGB565-afbeelding. Gebruik dit om tensoruitvoer van ml (of een willekeurige ulab-pijplijn) terug te brengen naar een tekenbare afbeelding.

  • Lege buffer. Construeer een Image met een opgegeven grootte en pixelformaat (image.Image(320, 240, image.RGB565)) om vanaf nul in te tekenen, of om te gebruiken als kladoppervlak voor beeldrekenkunde.

Pixelformaten

Elke Image heeft een van de volgende pixelformaten; de keuze maakt een afweging tussen geheugen, verwerkingskosten en welke algoritmen erop kunnen draaien. Gebruik BINARY, GRAYSCALE, RGB565, BAYER, YUV422, JPEG of PNG als pixformat-argument bij het construeren van een afbeelding of het configureren van de camerasensor:

  • BINARY (1 bpp) – één bit per pixel. Het kleinste formaat; intern gebruikt door drempelwaarde- en morfologieroutines, maar zelden rechtstreeks van de sensor vastgelegd.

  • GRAYSCALE (8 bpp) – één byte per pixel (het Y-kanaal van YUV422). Het snelste formaat voor de meeste computer-vision-algoritmen (AprilTag, randdetectie, optical flow).

  • RGB565 (16 bpp) – twee bytes per pixel, 5-bits rood / 6-bits groen / 5-bits blauw. Het standaard kleurformaat.

  • BAYER (8 bpp) – ruwe Bayer-patroon-kleurgegevens rechtstreeks van de sensor. Handig voor aangepaste de-mosaicing of om meer pixels in minder geheugen op te slaan voordat er op aanvraag wordt gedebayerd.

  • YUV422 (16 bpp) – 4:2:2 chroma-subgesamplede kleur, twee bytes per pixel. Handig wanneer je chroma-specifieke algoritmen wilt zonder de volledige RGB-kosten te betalen.

  • JPEG / PNG – gecomprimeerde buffers. Het beste voor opslag en netwerkverzending. Bewerkingen op pixelniveau vereisen eerst Image.to_grayscale() of Image.to_rgb565().

Werken met resultaten

De detectie-/kenmerkextractiemethoden op Image retourneren objecten waarover je kunt itereren en die je kunt combineren – een Image.find_blobs()-aanroep retourneert een lijst van Blob, een Image.find_apriltags()-aanroep retourneert een lijst van AprilTag, enz. Elke resultaatklasse stelt de geometrische eigenschappen van de detectie beschikbaar (zwaartepunt, begrenzingsvak, oppervlakte, codewaarde, enz.) zodat je er rechtstreeks op kunt reageren of ze kunt terugdoorgeven aan tekenmethoden (Image.draw_rectangle(), Image.draw_string(), …).

Hulpfuncties voor kleurruimten

De module stelt ook kleine zuivere functies beschikbaar voor het converteren van afzonderlijke pixelwaarden tussen de binaire / grijswaarden / RGB / LAB / YUV kleurruimten. Deze zijn handig wanneer je drempelwaarden of palet-items in Python moet converteren voordat je ze doorgeeft aan beeldbewerkingen – voor conversie van een volledige afbeelding gebruik je de Image to_*-methoden, die veel sneller zijn dan deze hulpfuncties in een lus aan te roepen.

Klassen

Functies

Hulpfuncties voor kleurruimteconversie

Elk van de onderstaande X_to_Y-functies voert een enkele pixelwaardeconversie uit. Ze nemen/retourneren allemaal waarden in de canonieke OpenMV-bereiken:

  • binary – int 0 – 1.

  • grayscale – int 0 – 255.

  • RGB – (r, g, b)-tuple van 8-bits gehele getallen (elk 0 – 255).

  • LAB – (l, a, b)-tuple met L in 0 – 100 en A/B in -128 – 127.

  • YUV – (y, u, v)-tuple met Y in 0 – 255 en U/V in -128 – 127.

Voor conversie van een volledige afbeelding gebruik je de Image to_*-methoden, die veel sneller zijn dan deze hulpfuncties in een lus aan te roepen.

image.binary_to_grayscale(value: int) → int

Converteer een binaire waarde naar een grijswaarde.

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

Converteer een binaire waarde naar een RGB-tuple.

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

Converteer een binaire waarde naar een LAB-tuple.

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

Converteer een binaire waarde naar een YUV-tuple.

image.grayscale_to_binary(value: int) → int

Converteer een grijswaarde naar een binaire waarde.

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

Converteer een grijswaarde naar een RGB-tuple.

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

Converteer een grijswaarde naar een LAB-tuple.

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

Converteer een grijswaarde naar een YUV-tuple.

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

Converteer een RGB-tuple naar een binaire waarde.

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

Converteer een RGB-tuple naar een grijswaarde.

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

Converteer een RGB-tuple naar een LAB-tuple.

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

Converteer een RGB-tuple naar een YUV-tuple.

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

Converteer een LAB-tuple naar een binaire waarde.

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

Converteer een LAB-tuple naar een grijswaarde.

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

Converteer een LAB-tuple naar een RGB-tuple.

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

Converteer een LAB-tuple naar een YUV-tuple.

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

Converteer een YUV-tuple naar een binaire waarde.

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

Converteer een YUV-tuple naar een grijswaarde.

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

Converteer een YUV-tuple naar een RGB-tuple.

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

Converteer een YUV-tuple naar een LAB-tuple.

Kenmerkdescriptoren

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

Laad een Haar Cascade en retourneer een Cascade-handle voor gebruik met Image.find_features().

path kan een van beide zijn:

  • de letterlijke string "frontalface" of "eye" om een van de twee in de firmware-ROM ingebakken cascades te laden, of

  • een bestandssysteempad naar een aangepast .cascade-binair bestand geproduceerd door de OpenMV cascade-converter-tools.

stages selecteert hoeveel cascade-stadia er tijdens detectie worden geëvalueerd. -1 gebruikt elk in het bestand opgeslagen stadium. Het verlagen van deze waarde versnelt detectie ten koste van meer fout-positieven.

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

Laad een descriptor uit het bestand op path en retourneer deze. De interne typetag van het bestand selecteert welke descriptorklasse wordt gereconstrueerd:

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

Serialiseer descriptor (een ORB-sleutelpunt- of LBP-descriptor) naar het bestand op path in het OpenMV-descriptorbestandsformaat. Hetzelfde bestand kan later opnieuw worden geladen via image.load_descriptor().

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

Vergelijk twee descriptoren van hetzelfde type.

  • Voor twee LBP-descriptoren – retourneert een gehele Hamming-afstand tussen beide (lager is een nauwere overeenkomst).

  • Voor twee ORB-sleutelpuntdescriptoren – retourneert een kptmatch die het cluster van overeenkomende sleutelpunten beschrijft, of None als geen enkele overeenkomst door threshold komt.

threshold (0 – 100) stelt in hoe streng ORB-matching is bij het accepteren van een sleutelpuntpaar. Lagere waarden maken de matching strakker door zwakke nearest-neighbour-overeenkomsten af te wijzen.

filter_outliers schakelt RANSAC-achtige uitschieterverwijdering in over de verzameling overeenkomende sleutelpunten. Gebruik het wanneer je een enkele starre transformatie tussen de twee weergaven verwacht; schakel het uit wanneer de overeenkomende sleutelpunten meerdere objecten beslaan.

Hulpfuncties voor blobgeometrie

Deze hulpfuncties nemen een Blob (zoals geretourneerd door Image.find_blobs()) en berekenen op aanvraag aanvullende geometrische eigenschappen. Ze bevinden zich op modulescope – niet op Blob – zodat het basale find_blobs()-pad er niet voor betaalt tenzij je erom vraagt.

image.get_solidity(blob: blob) → float

Retourneert de soliditeit (blob.pixels / convex_hull_area) van blob. Float, 0 – 1; 1.0 betekent dat de blob zijn convexe omhulling volledig vult.

image.get_convexity(blob: blob) → float

Retourneert de convexiteit (convex_hull_perimeter / blob.perimeter) van blob. Float, 0 – 1; 1.0 is een perfect convexe blob.

image.get_major_axis_line(blob: blob) → line

Retourneert een Line langs de hoofdas van blob (de langste van de twee hoofdassen van de roterende rechthoek met minimale oppervlakte).

image.get_minor_axis_line(blob: blob) → line

Retourneert een Line langs de nevenas van blob (de kortste van de twee hoofdassen van de roterende rechthoek met minimale oppervlakte).

image.get_enclosing_circle(blob: blob) → circle

Retourneert een Circle die blob omsluit.

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

Retourneert een 5-tuple (cx, cy, a, b, rotation) die de ellips beschrijft die is ingeschreven in de roterende rechthoek met minimale oppervlakte rond blob:

  • cx / cy – middelpunt van de ellips in pixels (geheel getal).

  • a / b – halve-aslengten in pixels (geheel getal).

  • rotation – rotatie van de ellips in graden (geheel getal).

Dit is een gewone tuple, geen attrtuple, dus de velden zijn alleen toegankelijk via index.

Constanten

Pixelformaten

Geef een van de volgende waarden door als pixformat-argument aan de Image-constructor of aan csi.CSI.pixformat().

image.BINARY: int

Bitmap met 1 bit per pixel. Het kleinste formaat – intern gebruikt door drempelwaarde en morfologie, zelden rechtstreeks van een sensor vastgelegd.

image.GRAYSCALE: int

Grijswaarden met 8 bits per pixel (één byte per pixel). Het snelste formaat voor de meeste computer-vision-algoritmen (AprilTag, randdetectie, optical flow).

image.RGB565: int

Kleur met 16 bits per pixel, gepakt als 5 bits rood / 6 bits groen / 5 bits blauw. Het standaard kleurformaat.

image.BAYER: int

Ruwe Bayer-gegevens met 8 bits per pixel rechtstreeks van de sensor. De meeste beeldverwerkingsmethoden zijn niet beschikbaar op Bayer-afbeeldingen; gebruik dit wanneer je op aanvraag wilt debayeren of meer pixels in minder geheugen wilt opslaan.

image.YUV422: int

4:2:2 chroma-subgesamplede kleur, twee bytes per pixel, gepakt als Y1, U, Y2, V per pixelpaar. Slechts sommige beeldverwerkingsmethoden werken rechtstreeks op YUV422.

image.JPEG: int

Gecomprimeerde JPEG-buffer. Bewerkingen op pixelniveau vereisen eerst Image.to_grayscale() of Image.to_rgb565().

image.PNG: int

Gecomprimeerde PNG-buffer. Bewerkingen op pixelniveau vereisen eerst Image.to_grayscale() of Image.to_rgb565().

Kleurenpaletten

Geef een van de volgende waarden door aan Image.to_rainbow(), Image.to_ironbow(), Image.draw_image() (color_palette=) of aan csi.CSI.color_palette() om een grijswaardenafbeelding in te kleuren.

image.PALETTE_RAINBOW: int

Vloeiend regenboogkleurenwiel. Het standaard OpenMV-palet voor thermische beelden.

image.PALETTE_IRONBOW: int

Niet-lineair “ironbow”-palet dat het uiterlijk van de FLIR Lepton thermische zoeker nabootst.

image.PALETTE_DEPTH: int

Dieptebeeldpalet. Alleen beschikbaar op builds met diepte-sensorondersteuning (de ToF-pijplijn – bijv. de OpenMV Cam AE3 of een willekeurige cam met een aangesloten ToF Pmod).

image.PALETTE_EVT_DARK: int

Palet voor het visualiseren van GENX320-eventcameraframes op een donkere achtergrond. Geef het door aan csi.CSI.color_palette om de GENX320-driver ingekleurde RGB565-frames in histogrammodus te laten uitvoeren, of aan Image.draw_image() color_palette= bij het inkleuren van een grijswaarden-eventafbeelding.

Alleen beschikbaar op builds met GENX320-ondersteuning (de OpenMV Cam AE3 en de GENX320 Pmod).

image.PALETTE_EVT_LIGHT: int

Palet voor het visualiseren van GENX320-eventcameraframes op een lichte achtergrond. Dezelfde dispatch en beschikbaarheid als PALETTE_EVT_DARK.

Schaalmodi

Geef een van de volgende waarden door als hint-argument aan Image.draw_image(), Image.scale() of vergelijkbare schaalmethoden.

image.AREA: int

Oppervlakte-middelende schaler. Gebruikt bij verkleinen; Nearest-Neighbor wordt gebruikt bij vergroten.

image.BILINEAR: int

Bilineaire schaler. Subsampelt bij verkleinen.

image.BICUBIC: int

Bicubische schaler. Hogere kwaliteit dan BILINEAR maar trager. Subsampelt bij verkleinen.

Hints voor tekenen / draw_image

Combineer een willekeurige set hiervan met bit-OR en geef ze door als het hint-argument van Image.draw_image().

image.VFLIP: int

Spiegel de bron verticaal tijdens het tekenen.

image.HMIRROR: int

Spiegel de bron horizontaal tijdens het tekenen.

image.TRANSPOSE: int

Transponeer (verwissel x/y) de bron tijdens het tekenen.

image.CENTER: int

Centreer de bron op de bestemming. Eventuele expliciete x/y-offsets worden dan offsets vanaf het midden in plaats van vanaf de linkerbovenhoek.

image.EXTRACT_RGB_CHANNEL_FIRST: int

Bij het extraheren van een RGB-kanaal via Image.draw_image(), extraheer het kanaal vóór het schalen. Zonder deze hint wordt het kanaal na het schalen geëxtraheerd.

image.APPLY_COLOR_PALETTE_FIRST: int

Bij het toepassen van een kleurenpalet via Image.draw_image(), pas het palet vóór het schalen toe. Zonder deze hint wordt het palet na het schalen toegepast.

image.SCALE_ASPECT_KEEP: int

Schaal de bron om binnen de bestemming te passen met behoud van de beeldverhouding (letterboxt wanneer de verhoudingen verschillen).

image.SCALE_ASPECT_EXPAND: int

Schaal de bron om de bestemming te vullen met behoud van de beeldverhouding (snijdt bij wanneer de verhoudingen verschillen).

image.SCALE_ASPECT_IGNORE: int

Schaal de bron om de bestemming te vullen, waarbij de beeldverhouding wordt genegeerd.

image.BLACK_BACKGROUND: int

Vertel het alpha-blending-pad dat de bestemming bekend-zwart is zodat het de terugleesoperatie van de bestemmingspixel kan overslaan. Versnelt alpha-effecten op zojuist gewiste buffers.

image.ROTATE_90: int

Snelkoppeling voor VFLIP | TRANSPOSE (90 graden met de klok mee draaien).

image.ROTATE_180: int

Snelkoppeling voor HMIRROR | VFLIP (180 graden draaien).

image.ROTATE_270: int

Snelkoppeling voor HMIRROR | TRANSPOSE (270 graden met de klok mee draaien).

JPEG-subsampling

Geef een van de volgende waarden door als subsampling-argument aan Image.to_jpeg(), Image.compress() of Image.save() bij het wegschrijven van een JPEG.

image.JPEG_SUBSAMPLING_AUTO: int

Kies chroma-subsampling automatisch op basis van de JPEG-kwaliteitsinstelling.

image.JPEG_SUBSAMPLING_444: int

Forceer 4:4:4 chroma-subsampling (geen chroma-compressie).

image.JPEG_SUBSAMPLING_422: int

Forceer 4:2:2 chroma-subsampling. Aanbevolen bij het streamen van MJPEG naar videospelers van derden die niet goed omgaan met 4:2:0.

image.JPEG_SUBSAMPLING_420: int

Forceer 4:2:0 chroma-subsampling.

Template matching

Geef een van de volgende waarden door als search-argument aan Image.find_template().

image.SEARCH_EX: int

Uitputtende zoekactie – evalueert elke positie in de ROI. Traagst, maar gegarandeerd om de beste overeenkomst te vinden.

image.SEARCH_DS: int

Diamantzoekactie – grof-naar-fijn zoekactie die veel sneller is dan SEARCH_EX maar het globale optimum kan missen bij sterk zelfgelijkende templates.

Randdetectie

Geef een van de volgende waarden door als algorithm-argument aan Image.find_edges().

image.EDGE_CANNY: int

Canny-randdetector – gradiëntmagnitude + non-max-suppressie + hysterese. Hogere kwaliteit, trager.

image.EDGE_SIMPLE: int

Drempelwaarde-hoogdoorlaatfilter-randdetector. Sneller maar produceert dikkere, ruisigere randen dan EDGE_CANNY.

ORB-hoekdetectoren

Geef een van de volgende waarden door als corner_detector-argument aan Image.find_keypoints().

image.CORNER_FAST: int

FAST-hoekdetector. Sneller dan CORNER_AGAST maar minder nauwkeurig.

image.CORNER_AGAST: int

AGAST-hoekdetector. Trager dan CORNER_FAST maar produceert stabielere sleutelpunten.

AprilTag-families

Combineer een willekeurige combinatie van de volgende waarden met bit-OR en geef ze door als het families-argument aan Image.find_apriltags(). Elke familie wordt afgeschermd door zijn eigen build-optie in de firmware; niet-ondersteunde families zijn tijdens runtime afwezig in plaats van altijd-nul.

image.TAG16H5: int

AprilTag 16h5-familie (30 unieke ID’s, 0-bits foutcorrectie).

image.TAG25H9: int

AprilTag 25h9-familie (35 unieke ID’s, tot 3-bits foutcorrectie).

image.TAG36H10: int

AprilTag 36h10-familie (2320 unieke ID’s, tot 3-bits foutcorrectie).

image.TAG36H11: int

AprilTag 36h11-familie (587 unieke ID’s, tot 4-bits foutcorrectie). De meest voorkomende familie.

image.TAGCIRCLE21H7: int

AprilTag Circle21h7-familie.

image.TAGCIRCLE49H12: int

AprilTag Circle49h12-familie.

image.TAGCUSTOM48H12: int

AprilTag Custom48h12-familie.

image.TAGSTANDARD41H12: int

AprilTag Standard41h12-familie.

image.TAGSTANDARD52H13: int

AprilTag Standard52h13-familie.

Barcode-symbologieën

De waarden die worden gerapporteerd in BarCode.type voor items die worden geretourneerd door Image.find_barcodes().

image.EAN2: int

EAN-2 supplementaire barcode.

image.EAN5: int

EAN-5 supplementaire barcode.

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-gestapelde barcode. De constante bestaat voor de volledigheid, maar de barcodedecoder implementeert PDF417 momenteel niet – Image.find_barcodes() zal geen detecties van dit type retourneren.

image.CODE93: int

Code 93-barcode.

image.CODE128: int

Code 128-barcode.