image — vision industrielle

Le module image est au cœur de la pile de vision industrielle d’OpenMV. Il expose la classe Image – le tampon de pixels en mémoire sur lequel opère chaque routine de dessin, de filtrage, de transformation et d’extraction de caractéristiques – ainsi que les objets de résultat renvoyés par ces routines (Blob, Line, Circle, Rect, QRCode, AprilTag, DataMatrix, BarCode, …) et les classes auxiliaires utilisées pour les configurer (Threshold, Histogram, Statistics, HaarCascade, Similarity, Percentile, Displacement, ImageIO).

Acquérir une image

Il existe quatre façons de charger une Image en RAM :

  • Capture en direct depuis le capteur de la caméra. Appelez csi.CSI.snapshot() pour capturer la trame suivante directement dans le tampon d’image ; l”Image renvoyée référence ce tampon.

  • Depuis un fichier. Passez un chemin au constructeur Image (image.Image("/sd/photo.jpg")) ; les formats sur disque pris en charge sont BMP, PPM/PGM, JPEG, PNG et le format d’enregistrement ImageIO d’OpenMV.

  • Depuis un ndarray. Passez un ndarray float32 (h, w) ou (h, w, 3) au constructeur Image. Les pixels sont mis à l’échelle de 0.0 -- 255.0 vers une image GRAYSCALE ou RGB565 respectivement. Utilisez ceci pour ramener la sortie tensorielle de ml (ou de tout pipeline ulab) dans une image que l’on peut dessiner.

  • Tampon vide. Construisez une Image avec une taille et un format de pixel donnés (image.Image(320, 240, image.RGB565)) pour y dessiner à partir de zéro, ou pour l’utiliser comme surface de travail pour des opérations arithmétiques sur les images.

Formats de pixel

Chaque Image possède l’un des formats de pixel suivants ; ce choix arbitre entre la mémoire, le coût de traitement et les algorithmes qui peuvent s’y exécuter. Utilisez BINARY, GRAYSCALE, RGB565, BAYER, YUV422, JPEG ou PNG comme argument pixformat lors de la construction d’une image ou de la configuration du capteur de la caméra :

  • BINARY (1 bpp) – un bit par pixel. Le format le plus compact ; utilisé en interne par les routines de seuillage et de morphologie mais rarement capturé directement depuis le capteur.

  • GRAYSCALE (8 bpp) – un octet par pixel (le canal Y de YUV422). Le format le plus rapide pour la plupart des algorithmes de vision par ordinateur (AprilTag, détection de contours, flux optique).

  • RGB565 (16 bpp) – deux octets par pixel, 5 bits de rouge / 6 bits de vert / 5 bits de bleu. Le format couleur par défaut.

  • BAYER (8 bpp) – données couleur brutes en mosaïque de Bayer directement issues du capteur. Utile pour un dématriçage personnalisé ou pour stocker plus de pixels dans moins de mémoire avant de débayeriser à la demande.

  • YUV422 (16 bpp) – couleur avec sous-échantillonnage chromatique 4:2:2, deux octets par pixel. Utile lorsque vous voulez des algorithmes spécifiques à la chrominance sans payer le coût complet du RGB.

  • JPEG / PNG – tampons compressés. Idéal pour le stockage et la transmission réseau. Les opérations au niveau du pixel nécessitent d’abord Image.to_grayscale() ou Image.to_rgb565().

Travailler avec les résultats

Les méthodes de détection / extraction de caractéristiques de Image renvoient des objets que vous pouvez parcourir et combiner – un appel à Image.find_blobs() renvoie une liste de Blob, un appel à Image.find_apriltags() renvoie une liste d”AprilTag, etc. Chaque classe de résultat expose les propriétés géométriques de la détection (centroïde, boîte englobante, surface, valeur de code, etc.) afin que vous puissiez agir directement dessus ou les repasser aux méthodes de dessin (Image.draw_rectangle(), Image.draw_string(), …).

Fonctions d’aide pour les espaces colorimétriques

Le module expose également de petites fonctions pures pour convertir des valeurs de pixel individuelles entre les espaces colorimétriques binaire / niveaux de gris / RGB / LAB / YUV. Elles sont utiles lorsque vous devez convertir des valeurs de seuil ou des entrées de palette en Python avant de les passer à des opérations sur image – pour une conversion d’image entière, utilisez les méthodes to_* de Image, qui sont bien plus rapides que d’appeler ces fonctions d’aide dans une boucle.

Classes

Fonctions

Fonctions d’aide pour la conversion d’espaces colorimétriques

Chacune des fonctions X_to_Y ci-dessous effectue une seule conversion de valeur de pixel. Elles prennent/renvoient toutes des valeurs dans les plages canoniques d’OpenMV :

  • binaire – int 0 – 1.

  • niveaux de gris – int 0 – 255.

  • RGB – tuple (r, g, b) d’entiers 8 bits (chacun 0 – 255).

  • LAB – tuple (l, a, b) avec L dans 0 – 100 et A/B dans -128 – 127.

  • YUV – tuple (y, u, v) avec Y dans 0 – 255 et U/V dans -128 – 127.

Pour une conversion d’image entière, utilisez les méthodes to_* de Image, qui sont bien plus rapides que d’appeler ces fonctions d’aide dans une boucle.

image.binary_to_grayscale(value: int) → int

Convertit une valeur binaire en valeur en niveaux de gris.

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

Convertit une valeur binaire en tuple RGB.

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

Convertit une valeur binaire en tuple LAB.

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

Convertit une valeur binaire en tuple YUV.

image.grayscale_to_binary(value: int) → int

Convertit une valeur en niveaux de gris en valeur binaire.

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

Convertit une valeur en niveaux de gris en tuple RGB.

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

Convertit une valeur en niveaux de gris en tuple LAB.

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

Convertit une valeur en niveaux de gris en tuple YUV.

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

Convertit un tuple RGB en valeur binaire.

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

Convertit un tuple RGB en valeur en niveaux de gris.

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

Convertit un tuple RGB en tuple LAB.

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

Convertit un tuple RGB en tuple YUV.

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

Convertit un tuple LAB en valeur binaire.

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

Convertit un tuple LAB en valeur en niveaux de gris.

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

Convertit un tuple LAB en tuple RGB.

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

Convertit un tuple LAB en tuple YUV.

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

Convertit un tuple YUV en valeur binaire.

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

Convertit un tuple YUV en valeur en niveaux de gris.

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

Convertit un tuple YUV en tuple RGB.

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

Convertit un tuple YUV en tuple LAB.

Descripteurs de caractéristiques

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

Charge un Haar Cascade et renvoie un handle Cascade à utiliser avec Image.find_features().

path peut être soit :

  • la chaîne littérale "frontalface" ou "eye" pour charger l’une des deux cascades intégrées dans la ROM du micrologiciel, ou

  • un chemin de système de fichiers vers un fichier binaire .cascade personnalisé produit par les outils de conversion de cascade d’OpenMV.

stages sélectionne le nombre d’étapes de cascade à évaluer au moment de la détection. -1 utilise toutes les étapes stockées dans le fichier. Réduire cette valeur accélère la détection au prix de davantage de faux positifs.

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

Charge un descripteur depuis le fichier situé à path et le renvoie. L’étiquette de type interne du fichier sélectionne la classe de descripteur à reconstruire :

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

Sérialise descriptor (un descripteur de point clé ORB ou LBP) vers le fichier situé à path au format de fichier de descripteur OpenMV. Le même fichier peut être rechargé ultérieurement via image.load_descriptor().

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

Met en correspondance deux descripteurs du même type.

  • Pour deux descripteurs LBP – renvoie une distance de Hamming entière entre eux (plus elle est faible, plus la correspondance est proche).

  • Pour deux descripteurs de point clé ORB – renvoie un kptmatch décrivant le cluster de points clés correspondants, ou None si aucune correspondance ne dépasse threshold.

threshold (0 – 100) définit la rigueur de la mise en correspondance ORB lors de l’acceptation d’une paire de points clés. Des valeurs plus basses resserrent la correspondance en rejetant les faibles correspondances par plus proche voisin.

filter_outliers active un rejet des valeurs aberrantes de style RANSAC sur l’ensemble des points clés correspondants. Utilisez-le lorsque vous attendez une transformation rigide unique entre les deux vues ; désactivez-le lorsque les points clés correspondants couvrent plusieurs objets.

Fonctions d’aide pour la géométrie des blobs

Ces fonctions d’aide prennent un Blob (tel que renvoyé par Image.find_blobs()) et calculent à la demande des propriétés géométriques supplémentaires. Elles résident au niveau du module – et non sur Blob – de sorte que le chemin de base find_blobs() n’en paie pas le coût à moins que vous ne le demandiez.

image.get_solidity(blob: blob) → float

Renvoie la solidité (blob.pixels / convex_hull_area) de blob. Flottant, 0 – 1 ; 1.0 signifie que le blob remplit entièrement son enveloppe convexe.

image.get_convexity(blob: blob) → float

Renvoie la convexité (convex_hull_perimeter / blob.perimeter) de blob. Flottant, 0 – 1 ; 1.0 correspond à un blob parfaitement convexe.

image.get_major_axis_line(blob: blob) → line

Renvoie une Line le long du grand axe de blob (le plus long des deux axes principaux du rectangle pivoté d’aire minimale).

image.get_minor_axis_line(blob: blob) → line

Renvoie une Line le long du petit axe de blob (le plus court des deux axes principaux du rectangle pivoté d’aire minimale).

image.get_enclosing_circle(blob: blob) → circle

Renvoie un Circle qui englobe blob.

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

Renvoie un 5-tuple (cx, cy, a, b, rotation) décrivant l’ellipse inscrite dans le rectangle pivoté d’aire minimale autour de blob :

  • cx / cy – centre de l’ellipse en pixels (entier).

  • a / b – longueurs des demi-axes en pixels (entier).

  • rotation – rotation de l’ellipse en degrés (entier).

Il s’agit d’un tuple ordinaire, pas d’un attrtuple, donc les champs ne sont accessibles que par index.

Constantes

Formats de pixel

Passez l’une des valeurs suivantes comme argument pixformat au constructeur Image ou à csi.CSI.pixformat().

image.BINARY: int

Bitmap à 1 bit par pixel. Le format le plus compact – utilisé en interne par le seuillage et la morphologie, rarement capturé directement depuis un capteur.

image.GRAYSCALE: int

Niveaux de gris à 8 bits par pixel (un octet par pixel). Le format le plus rapide pour la plupart des algorithmes de vision par ordinateur (AprilTag, détection de contours, flux optique).

image.RGB565: int

Couleur à 16 bits par pixel encodée en 5 bits de rouge / 6 bits de vert / 5 bits de bleu. Le format couleur par défaut.

image.BAYER: int

Données Bayer brutes à 8 bits par pixel directement issues du capteur. La plupart des méthodes de traitement d’image ne sont pas disponibles sur les images Bayer ; utilisez ce format lorsque vous voulez débayeriser à la demande ou stocker plus de pixels dans moins de mémoire.

image.YUV422: int

Couleur avec sous-échantillonnage chromatique 4:2:2, deux octets par pixel, encodée en Y1, U, Y2, V par paire de pixels. Seules certaines méthodes de traitement d’image fonctionnent directement sur YUV422.

image.JPEG: int

Tampon JPEG compressé. Les opérations au niveau du pixel nécessitent d’abord Image.to_grayscale() ou Image.to_rgb565().

image.PNG: int

Tampon PNG compressé. Les opérations au niveau du pixel nécessitent d’abord Image.to_grayscale() ou Image.to_rgb565().

Palettes de couleurs

Passez l’une des valeurs suivantes à Image.to_rainbow(), Image.to_ironbow(), Image.draw_image() (color_palette=) ou à csi.CSI.color_palette() pour coloriser une image en niveaux de gris.

image.PALETTE_RAINBOW: int

Roue chromatique arc-en-ciel lisse. La palette OpenMV par défaut pour l’imagerie thermique.

image.PALETTE_IRONBOW: int

Palette « ironbow » non linéaire qui imite l’apparence du viseur thermique FLIR Lepton.

image.PALETTE_DEPTH: int

Palette d’image de profondeur. Disponible uniquement sur les builds avec prise en charge du capteur de profondeur (le pipeline ToF – p. ex. OpenMV Cam AE3 ou toute caméra avec un Pmod ToF connecté).

image.PALETTE_EVT_DARK: int

Palette pour visualiser les trames de la caméra événementielle GENX320 sur fond sombre. Passez-la à csi.CSI.color_palette pour que le pilote GENX320 émette des trames RGB565 colorisées en mode histogramme, ou à Image.draw_image() color_palette= lors de la colorisation d’une image événementielle en niveaux de gris.

Disponible uniquement sur les builds avec prise en charge du GENX320 (OpenMV Cam AE3 et le Pmod GENX320).

image.PALETTE_EVT_LIGHT: int

Palette pour visualiser les trames de la caméra événementielle GENX320 sur fond clair. Même répartition et même disponibilité que PALETTE_EVT_DARK.

Modes de mise à l’échelle

Passez l’une des valeurs suivantes comme argument hint à Image.draw_image(), Image.scale(), ou à des méthodes de mise à l’échelle similaires.

image.AREA: int

Scaler par moyennage de zone. Utilisé lors de la réduction d’échelle ; le plus proche voisin est utilisé pour l’agrandissement.

image.BILINEAR: int

Scaler bilinéaire. Sous-échantillonne lors de la réduction d’échelle.

image.BICUBIC: int

Scaler bicubique. Meilleure qualité que BILINEAR mais plus lent. Sous-échantillonne lors de la réduction d’échelle.

Indices de dessin / draw_image

Combinez par OU binaire l’une de ces valeurs et passez-les comme argument hint de Image.draw_image().

image.VFLIP: int

Retourne verticalement la source pendant le dessin.

image.HMIRROR: int

Met en miroir horizontalement la source pendant le dessin.

image.TRANSPOSE: int

Transpose (échange x/y) la source pendant le dessin.

image.CENTER: int

Centre la source sur la destination. Tout décalage x/y explicite devient alors un décalage par rapport au centre au lieu du coin supérieur gauche.

image.EXTRACT_RGB_CHANNEL_FIRST: int

Lors de l’extraction d’un canal RGB via Image.draw_image(), extrait le canal avant la mise à l’échelle. Sans cet indice, le canal est extrait après la mise à l’échelle.

image.APPLY_COLOR_PALETTE_FIRST: int

Lors de l’application d’une palette de couleurs via Image.draw_image(), applique la palette avant la mise à l’échelle. Sans cet indice, la palette est appliquée après la mise à l’échelle.

image.SCALE_ASPECT_KEEP: int

Met la source à l’échelle pour qu’elle tienne à l’intérieur de la destination tout en conservant le rapport d’aspect (ajoute des bandes noires lorsque les rapports diffèrent).

image.SCALE_ASPECT_EXPAND: int

Met la source à l’échelle pour qu’elle remplisse la destination tout en conservant le rapport d’aspect (recadre lorsque les rapports diffèrent).

image.SCALE_ASPECT_IGNORE: int

Met la source à l’échelle pour qu’elle remplisse la destination, en ignorant le rapport d’aspect.

image.BLACK_BACKGROUND: int

Indique au chemin de mélange alpha que la destination est connue pour être noire afin qu’il puisse omettre la relecture du pixel de destination. Accélère les effets alpha sur les tampons fraîchement effacés.

image.ROTATE_90: int

Raccourci pour VFLIP | TRANSPOSE (rotation de 90 degrés dans le sens horaire).

image.ROTATE_180: int

Raccourci pour HMIRROR | VFLIP (rotation de 180 degrés).

image.ROTATE_270: int

Raccourci pour HMIRROR | TRANSPOSE (rotation de 270 degrés dans le sens horaire).

Sous-échantillonnage JPEG

Passez l’une des valeurs suivantes comme argument subsampling à Image.to_jpeg(), Image.compress(), ou Image.save() lors de l’écriture d’un JPEG.

image.JPEG_SUBSAMPLING_AUTO: int

Choisit automatiquement le sous-échantillonnage chromatique en fonction du réglage de qualité JPEG.

image.JPEG_SUBSAMPLING_444: int

Force un sous-échantillonnage chromatique 4:4:4 (aucune compression de la chrominance).

image.JPEG_SUBSAMPLING_422: int

Force un sous-échantillonnage chromatique 4:2:2. Recommandé lors de la diffusion de MJPEG vers des lecteurs vidéo tiers qui se comportent mal avec le 4:2:0.

image.JPEG_SUBSAMPLING_420: int

Force un sous-échantillonnage chromatique 4:2:0.

Mise en correspondance de modèle

Passez l’une des valeurs suivantes comme argument search à Image.find_template().

image.SEARCH_EX: int

Recherche exhaustive – évalue chaque position dans la ROI. La plus lente mais garantit de trouver la meilleure correspondance.

image.SEARCH_DS: int

Recherche en diamant – recherche du grossier au fin qui est bien plus rapide que SEARCH_EX mais peut manquer l’optimum global sur des modèles fortement auto-similaires.

Détection de contours

Passez l’une des valeurs suivantes comme argument algorithm à Image.find_edges().

image.EDGE_CANNY: int

Détecteur de contours de Canny – magnitude du gradient + suppression des non-maxima + hystérésis. Meilleure qualité, plus lent.

image.EDGE_SIMPLE: int

Détecteur de contours par filtre passe-haut seuillé. Plus rapide mais produit des contours plus épais et plus bruités que EDGE_CANNY.

Détecteurs de coins ORB

Passez l’une des valeurs suivantes comme argument corner_detector à Image.find_keypoints().

image.CORNER_FAST: int

Détecteur de coins FAST. Plus rapide que CORNER_AGAST mais moins précis.

image.CORNER_AGAST: int

Détecteur de coins AGAST. Plus lent que CORNER_FAST mais produit des points clés plus stables.

Familles AprilTag

Combinez par OU binaire n’importe quelle combinaison des valeurs suivantes et passez-les comme argument families à Image.find_apriltags(). Chaque famille est conditionnée par sa propre option de build dans le micrologiciel ; les familles non prises en charge sont absentes au moment de l’exécution plutôt que toujours nulles.

image.TAG16H5: int

Famille AprilTag 16h5 (30 ID uniques, correction d’erreur de 0 bit).

image.TAG25H9: int

Famille AprilTag 25h9 (35 ID uniques, correction d’erreur jusqu’à 3 bits).

image.TAG36H10: int

Famille AprilTag 36h10 (2320 ID uniques, correction d’erreur jusqu’à 3 bits).

image.TAG36H11: int

Famille AprilTag 36h11 (587 ID uniques, correction d’erreur jusqu’à 4 bits). La famille la plus courante.

image.TAGCIRCLE21H7: int

Famille AprilTag Circle21h7.

image.TAGCIRCLE49H12: int

Famille AprilTag Circle49h12.

image.TAGCUSTOM48H12: int

Famille AprilTag Custom48h12.

image.TAGSTANDARD41H12: int

Famille AprilTag Standard41h12.

image.TAGSTANDARD52H13: int

Famille AprilTag Standard52h13.

Symbologies de code-barres

Les valeurs rapportées dans BarCode.type pour les entrées renvoyées par Image.find_barcodes().

image.EAN2: int

Code-barres supplémentaire EAN-2.

image.EAN5: int

Code-barres supplémentaire EAN-5.

image.EAN8: int

Code-barres EAN-8.

image.UPCE: int

Code-barres UPC-E.

image.ISBN10: int

Code-barres ISBN-10.

image.UPCA: int

Code-barres UPC-A.

image.EAN13: int

Code-barres EAN-13.

image.ISBN13: int

Code-barres ISBN-13.

image.I25: int

Code-barres Interleaved 2-of-5.

image.DATABAR: int

Code-barres GS1 DataBar.

image.DATABAR_EXP: int

Code-barres GS1 DataBar Expanded.

image.CODABAR: int

Code-barres Codabar.

image.CODE39: int

Code-barres Code 39.

image.PDF417: int

Code-barres 2D empilé PDF417. La constante existe par souci d’exhaustivité, mais le décodeur de code-barres n’implémente pas actuellement le PDF417 – Image.find_barcodes() ne renverra pas de détections de ce type.

image.CODE93: int

Code-barres Code 93.

image.CODE128: int

Code-barres Code 128.