image — visione artificiale

Il modulo image è il cuore dello stack di visione artificiale di OpenMV. Espone la classe Image – il buffer di pixel in memoria su cui operano tutte le routine di disegno, filtraggio, trasformazione ed estrazione di caratteristiche – insieme agli oggetti risultato di supporto restituiti da tali routine (Blob, Line, Circle, Rect, QRCode, AprilTag, DataMatrix, BarCode, …) e alle classi di supporto usate per configurarle (Threshold, Histogram, Statistics, HaarCascade, Similarity, Percentile, Displacement, ImageIO).

Acquisire un’immagine

Ci sono quattro modi per portare un’immagine Image in RAM:

  • Acquisizione dal vivo dal sensore della camera. Chiama csi.CSI.snapshot() per acquisire il frame successivo direttamente nel frame buffer; l’immagine Image restituita fa riferimento a quel buffer.

  • Da un file. Passa un percorso al costruttore di Image (image.Image("/sd/photo.jpg")); i formati su disco supportati sono BMP, PPM/PGM, JPEG, PNG e il formato di registrazione ImageIO di OpenMV.

  • Da un ndarray. Passa un ndarray float32 (h, w) o (h, w, 3) al costruttore di Image. I pixel vengono scalati da 0.0 -- 255.0 rispettivamente in un’immagine GRAYSCALE o RGB565. Usalo per riportare l’output tensoriale di ml (o di qualsiasi pipeline ulab) in un’immagine disegnabile.

  • Buffer vuoto. Costruisci un’immagine Image con una dimensione e un formato di pixel dati (image.Image(320, 240, image.RGB565)) su cui disegnare da zero, oppure da usare come superficie di lavoro per l’aritmetica sulle immagini.

Formati di pixel

Ogni Image ha uno dei seguenti formati di pixel; la scelta è un compromesso tra memoria, costo di elaborazione e quali algoritmi possono essere eseguiti su di essa. Usa BINARY, GRAYSCALE, RGB565, BAYER, YUV422, JPEG o PNG come argomento pixformat durante la costruzione di un’immagine o la configurazione del sensore della camera:

  • BINARY (1 bpp) – un bit per pixel. Il formato più piccolo; usato internamente dalle routine di soglia e morfologia ma raramente acquisito direttamente dal sensore.

  • GRAYSCALE (8 bpp) – un byte per pixel (il canale Y di YUV422). Il formato più veloce per la maggior parte degli algoritmi di visione artificiale (AprilTag, rilevamento dei bordi, flusso ottico).

  • RGB565 (16 bpp) – due byte per pixel, rosso a 5 bit / verde a 6 bit / blu a 5 bit. Il formato colore predefinito.

  • BAYER (8 bpp) – dati colore raw in pattern Bayer direttamente dal sensore. Utile per il de-mosaicing personalizzato o per memorizzare più pixel in meno memoria prima del debayering su richiesta.

  • YUV422 (16 bpp) – colore con sottocampionamento di crominanza 4:2:2, due byte per pixel. Utile quando si desiderano algoritmi specifici per la crominanza senza pagare il costo completo dell’RGB.

  • JPEG / PNG – buffer compressi. Ideali per l’archiviazione e la trasmissione in rete. Le operazioni a livello di pixel richiedono prima Image.to_grayscale() o Image.to_rgb565().

Lavorare con i risultati

I metodi di rilevamento / estrazione di caratteristiche di Image restituiscono oggetti su cui puoi iterare e che puoi combinare – una chiamata a Image.find_blobs() restituisce un elenco di Blob, una chiamata a Image.find_apriltags() restituisce un elenco di AprilTag, ecc. Ogni classe di risultato espone le proprietà geometriche del rilevamento (centroide, bounding box, area, valore del codice, ecc.) così da poter agire direttamente su di esse o passarle nuovamente ai metodi di disegno (Image.draw_rectangle(), Image.draw_string(), …).

Funzioni di supporto per lo spazio colore

Il modulo espone anche piccole funzioni pure per convertire singoli valori di pixel tra gli spazi colore binario / scala di grigi / RGB / LAB / YUV. Sono utili quando devi convertire valori di soglia o voci di palette in Python prima di passarli alle operazioni sulle immagini – per la conversione dell’immagine completa usa i metodi to_* di Image, che sono molto più veloci del chiamare queste funzioni di supporto in un ciclo.

Classi

Funzioni

Funzioni di supporto per la conversione dello spazio colore

Ognuna delle funzioni X_to_Y qui sotto esegue una singola conversione del valore di un pixel. Tutte accettano/restituiscono valori negli intervalli canonici di OpenMV:

  • binario – int 0 – 1.

  • scala di grigi – int 0 – 255.

  • RGB – tupla (r, g, b) di interi a 8 bit (ciascuno 0 – 255).

  • LAB – tupla (l, a, b) con L in 0 – 100 e A/B in -128 – 127.

  • YUV – tupla (y, u, v) con Y in 0 – 255 e U/V in -128 – 127.

Per la conversione dell’immagine completa usa i metodi to_* di Image, che sono molto più veloci del chiamare queste funzioni di supporto in un ciclo.

image.binary_to_grayscale(value: int) → int

Converte un valore binario in un valore in scala di grigi.

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

Converte un valore binario in una tupla RGB.

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

Converte un valore binario in una tupla LAB.

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

Converte un valore binario in una tupla YUV.

image.grayscale_to_binary(value: int) → int

Converte un valore in scala di grigi in un valore binario.

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

Converte un valore in scala di grigi in una tupla RGB.

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

Converte un valore in scala di grigi in una tupla LAB.

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

Converte un valore in scala di grigi in una tupla YUV.

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

Converte una tupla RGB in un valore binario.

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

Converte una tupla RGB in un valore in scala di grigi.

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

Converte una tupla RGB in una tupla LAB.

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

Converte una tupla RGB in una tupla YUV.

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

Converte una tupla LAB in un valore binario.

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

Converte una tupla LAB in un valore in scala di grigi.

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

Converte una tupla LAB in una tupla RGB.

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

Converte una tupla LAB in una tupla YUV.

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

Converte una tupla YUV in un valore binario.

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

Converte una tupla YUV in un valore in scala di grigi.

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

Converte una tupla YUV in una tupla RGB.

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

Converte una tupla YUV in una tupla LAB.

Descrittori di caratteristiche

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

Carica una Haar Cascade e restituisce un handle Cascade da usare con Image.find_features().

path può essere:

  • la stringa letterale "frontalface" o "eye" per caricare una delle due cascade integrate nella ROM del firmware, oppure

  • un percorso del filesystem a un file binario .cascade personalizzato prodotto dagli strumenti di conversione cascade di OpenMV.

stages seleziona quanti stadi della cascade valutare al momento del rilevamento. -1 usa ogni stadio memorizzato nel file. Ridurre questo valore velocizza il rilevamento al costo di un maggior numero di falsi positivi.

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

Carica un descrittore dal file in path e lo restituisce. Il tag di tipo interno del file seleziona quale classe di descrittore viene ricostruita:

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

Serializza descriptor (un descrittore di keypoint ORB o LBP) nel file in path nel formato di file descrittore di OpenMV. Lo stesso file può essere ricaricato in seguito tramite image.load_descriptor().

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

Confronta due descrittori dello stesso tipo.

  • Per due descrittori LBP – restituisce una distanza di Hamming intera tra di essi (più bassa indica una corrispondenza più stretta).

  • Per due descrittori di keypoint ORB – restituisce un kptmatch che descrive il cluster di keypoint corrispondenti, oppure None se nessuna corrispondenza supera threshold.

threshold (0 – 100) imposta quanto è rigoroso il matching ORB nell’accettare una coppia di keypoint. Valori più bassi rendono il matching più stretto rifiutando le corrispondenze deboli al vicino più prossimo.

filter_outliers abilita il rifiuto degli outlier in stile RANSAC sull’insieme dei keypoint corrispondenti. Usalo quando ti aspetti una singola trasformazione rigida tra le due viste; disabilitalo quando i keypoint corrispondenti coprono più oggetti.

Funzioni di supporto per la geometria dei blob

Queste funzioni di supporto prendono un Blob (come restituito da Image.find_blobs()) e calcolano proprietà geometriche aggiuntive su richiesta. Risiedono a livello di modulo – non su Blob – così che il percorso base di find_blobs() non ne paghi il costo se non lo richiedi.

image.get_solidity(blob: blob) → float

Restituisce la solidità (blob.pixels / convex_hull_area) di blob. Float, 0 – 1; 1.0 significa che il blob riempie completamente il suo guscio convesso.

image.get_convexity(blob: blob) → float

Restituisce la convessità (convex_hull_perimeter / blob.perimeter) di blob. Float, 0 – 1; 1.0 indica un blob perfettamente convesso.

image.get_major_axis_line(blob: blob) → line

Restituisce una Line lungo l’asse maggiore di blob (il più lungo dei due assi principali del rettangolo ruotato di area minima).

image.get_minor_axis_line(blob: blob) → line

Restituisce una Line lungo l’asse minore di blob (il più corto dei due assi principali del rettangolo ruotato di area minima).

image.get_enclosing_circle(blob: blob) → circle

Restituisce un Circle che racchiude blob.

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

Restituisce una 5-tupla (cx, cy, a, b, rotation) che descrive l’ellisse inscritta nel rettangolo ruotato di area minima attorno a blob:

  • cx / cy – centro dell’ellisse in pixel (intero).

  • a / b – lunghezze dei semiassi in pixel (intero).

  • rotation – rotazione dell’ellisse in gradi (intero).

Questa è una tupla semplice, non una attrtuple, quindi i campi sono accessibili solo per indice.

Costanti

Formati di pixel

Passa uno qualsiasi dei seguenti come argomento pixformat al costruttore di Image o a csi.CSI.pixformat().

image.BINARY: int

Bitmap a 1 bit per pixel. Il formato più piccolo – usato internamente dalle routine di soglia e morfologia, raramente acquisito direttamente da un sensore.

image.GRAYSCALE: int

Scala di grigi a 8 bit per pixel (un byte per pixel). Il formato più veloce per la maggior parte degli algoritmi di visione artificiale (AprilTag, rilevamento dei bordi, flusso ottico).

image.RGB565: int

Colore a 16 bit per pixel impacchettato come 5 bit rosso / 6 bit verde / 5 bit blu. Il formato colore predefinito.

image.BAYER: int

Dati Bayer raw a 8 bit per pixel direttamente dal sensore. La maggior parte dei metodi di elaborazione delle immagini non è disponibile sulle immagini Bayer; usalo quando vuoi fare il debayer su richiesta o memorizzare più pixel in meno memoria.

image.YUV422: int

Colore con sottocampionamento di crominanza 4:2:2, due byte per pixel, impacchettato come Y1, U, Y2, V per coppia di pixel. Solo alcuni metodi di elaborazione delle immagini funzionano direttamente su YUV422.

image.JPEG: int

Buffer JPEG compresso. Le operazioni a livello di pixel richiedono prima Image.to_grayscale() o Image.to_rgb565().

image.PNG: int

Buffer PNG compresso. Le operazioni a livello di pixel richiedono prima Image.to_grayscale() o Image.to_rgb565().

Palette di colori

Passa uno qualsiasi dei seguenti a Image.to_rainbow(), Image.to_ironbow(), Image.draw_image() (color_palette=) o a csi.CSI.color_palette() per colorare un’immagine in scala di grigi.

image.PALETTE_RAINBOW: int

Ruota dei colori arcobaleno fluida. La palette OpenMV predefinita per le immagini termiche.

image.PALETTE_IRONBOW: int

Palette «ironbow» non lineare che imita l’aspetto del mirino termico FLIR Lepton.

image.PALETTE_DEPTH: int

Palette per immagini di profondità. Disponibile solo nelle build con supporto per sensori di profondità (la pipeline ToF – ad esempio OpenMV Cam AE3 o qualsiasi cam con un Pmod ToF collegato).

image.PALETTE_EVT_DARK: int

Palette per visualizzare i frame della event-camera GENX320 su sfondo scuro. Passala a csi.CSI.color_palette per far sì che il driver GENX320 emetta frame RGB565 colorati in modalità istogramma, oppure a Image.draw_image() color_palette= quando colori un’immagine di eventi in scala di grigi.

Disponibile solo nelle build con supporto GENX320 (OpenMV Cam AE3 e il Pmod GENX320).

image.PALETTE_EVT_LIGHT: int

Palette per visualizzare i frame della event-camera GENX320 su sfondo chiaro. Stesso dispatch e disponibilità di PALETTE_EVT_DARK.

Modalità di scalatura

Passa uno qualsiasi dei seguenti come argomento hint a Image.draw_image(), Image.scale() o a metodi di scalatura simili.

image.AREA: int

Scaler con media d’area. Usato durante il ridimensionamento verso il basso; per l’ingrandimento si usa Nearest-Neighbor.

image.BILINEAR: int

Scaler bilineare. Sottocampiona durante il ridimensionamento verso il basso.

image.BICUBIC: int

Scaler bicubico. Qualità superiore a BILINEAR ma più lento. Sottocampiona durante il ridimensionamento verso il basso.

Hint di disegno / draw_image

Combina uno qualsiasi di questi con un OR a livello di bit e passalo come argomento hint di Image.draw_image().

image.VFLIP: int

Capovolge verticalmente la sorgente durante il disegno.

image.HMIRROR: int

Specchia orizzontalmente la sorgente durante il disegno.

image.TRANSPOSE: int

Traspone (scambia x/y) la sorgente durante il disegno.

image.CENTER: int

Centra la sorgente sulla destinazione. Eventuali offset x/y espliciti diventano allora offset rispetto al centro anziché rispetto all’angolo in alto a sinistra.

image.EXTRACT_RGB_CHANNEL_FIRST: int

Quando si estrae un canale RGB tramite Image.draw_image(), estrae il canale prima della scalatura. Senza questo hint, il canale viene estratto dopo la scalatura.

image.APPLY_COLOR_PALETTE_FIRST: int

Quando si applica una palette di colori tramite Image.draw_image(), applica la palette prima della scalatura. Senza questo hint, la palette viene applicata dopo la scalatura.

image.SCALE_ASPECT_KEEP: int

Scala la sorgente per adattarla all’interno della destinazione mantenendo le proporzioni (aggiunge bande quando i rapporti differiscono).

image.SCALE_ASPECT_EXPAND: int

Scala la sorgente per riempire la destinazione mantenendo le proporzioni (ritaglia quando i rapporti differiscono).

image.SCALE_ASPECT_IGNORE: int

Scala la sorgente per riempire la destinazione, ignorando le proporzioni.

image.BLACK_BACKGROUND: int

Indica al percorso di alpha-blending che la destinazione è notoriamente nera così da poter saltare la rilettura del pixel di destinazione. Velocizza gli effetti alpha sui buffer appena azzerati.

image.ROTATE_90: int

Scorciatoia per VFLIP | TRANSPOSE (ruota di 90 gradi in senso orario).

image.ROTATE_180: int

Scorciatoia per HMIRROR | VFLIP (ruota di 180 gradi).

image.ROTATE_270: int

Scorciatoia per HMIRROR | TRANSPOSE (ruota di 270 gradi in senso orario).

Sottocampionamento JPEG

Passa uno qualsiasi dei seguenti come argomento subsampling a Image.to_jpeg(), Image.compress() o Image.save() quando scrivi un JPEG.

image.JPEG_SUBSAMPLING_AUTO: int

Sceglie automaticamente il sottocampionamento di crominanza in base all’impostazione della qualità JPEG.

image.JPEG_SUBSAMPLING_444: int

Forza il sottocampionamento di crominanza 4:4:4 (nessuna compressione della crominanza).

image.JPEG_SUBSAMPLING_422: int

Forza il sottocampionamento di crominanza 4:2:2. Consigliato quando si trasmette MJPEG a lettori video di terze parti che si comportano in modo anomalo con il 4:2:0.

image.JPEG_SUBSAMPLING_420: int

Forza il sottocampionamento di crominanza 4:2:0.

Template matching

Passa uno dei seguenti come argomento search a Image.find_template().

image.SEARCH_EX: int

Ricerca esaustiva – valuta ogni posizione nella ROI. La più lenta ma garantita per trovare la corrispondenza migliore.

image.SEARCH_DS: int

Ricerca a diamante – ricerca dal grossolano al fine, molto più veloce di SEARCH_EX ma può mancare l’ottimo globale su template fortemente autosimili.

Rilevamento dei bordi

Passa uno dei seguenti come argomento algorithm a Image.find_edges().

image.EDGE_CANNY: int

Rilevatore di bordi Canny – magnitudine del gradiente + soppressione dei non-massimi + isteresi. Qualità superiore, più lento.

image.EDGE_SIMPLE: int

Rilevatore di bordi a filtro passa-alto con soglia. Più veloce ma produce bordi più spessi e più rumorosi rispetto a EDGE_CANNY.

Rilevatori di angoli ORB

Passa uno dei seguenti come argomento corner_detector a Image.find_keypoints().

image.CORNER_FAST: int

Rilevatore di angoli FAST. Più veloce di CORNER_AGAST ma meno accurato.

image.CORNER_AGAST: int

Rilevatore di angoli AGAST. Più lento di CORNER_FAST ma produce keypoint più stabili.

Famiglie AprilTag

Combina con un OR a livello di bit qualsiasi combinazione dei seguenti e passala come argomento families a Image.find_apriltags(). Ogni famiglia è condizionata dalla propria opzione di build nel firmware; le famiglie non supportate sono assenti a runtime anziché sempre a zero.

image.TAG16H5: int

Famiglia AprilTag 16h5 (30 ID univoci, correzione di errore a 0 bit).

image.TAG25H9: int

Famiglia AprilTag 25h9 (35 ID univoci, correzione di errore fino a 3 bit).

image.TAG36H10: int

Famiglia AprilTag 36h10 (2320 ID univoci, correzione di errore fino a 3 bit).

image.TAG36H11: int

Famiglia AprilTag 36h11 (587 ID univoci, correzione di errore fino a 4 bit). La famiglia più comune.

image.TAGCIRCLE21H7: int

Famiglia AprilTag Circle21h7.

image.TAGCIRCLE49H12: int

Famiglia AprilTag Circle49h12.

image.TAGCUSTOM48H12: int

Famiglia AprilTag Custom48h12.

image.TAGSTANDARD41H12: int

Famiglia AprilTag Standard41h12.

image.TAGSTANDARD52H13: int

Famiglia AprilTag Standard52h13.

Simbologie di barcode

I valori riportati in BarCode.type per le voci restituite da Image.find_barcodes().

image.EAN2: int

Barcode supplementare EAN-2.

image.EAN5: int

Barcode supplementare EAN-5.

image.EAN8: int

Barcode EAN-8.

image.UPCE: int

Barcode UPC-E.

image.ISBN10: int

Barcode ISBN-10.

image.UPCA: int

Barcode UPC-A.

image.EAN13: int

Barcode EAN-13.

image.ISBN13: int

Barcode ISBN-13.

image.I25: int

Barcode Interleaved 2-of-5.

image.DATABAR: int

Barcode GS1 DataBar.

image.DATABAR_EXP: int

Barcode GS1 DataBar Expanded.

image.CODABAR: int

Barcode Codabar.

image.CODE39: int

Barcode Code 39.

image.PDF417: int

Barcode 2D stacked PDF417. La costante esiste per completezza, ma il decodificatore di barcode attualmente non implementa PDF417 – Image.find_barcodes() non restituirà rilevamenti di questo tipo.

image.CODE93: int

Barcode Code 93.

image.CODE128: int

Barcode Code 128.