VNRequest — cos’è, come funzionano le richieste Vision in iOS

Cos’è VNRequest in Vision?

VNRequest è un elemento fondamentale dell’architettura Vision, che implementa il pattern Richiesta-Risposta per l’analisi di immagini e video. Ogni sottoclasse di VNRequest è responsabile di un compito specifico di computer vision: rilevamento volti, riconoscimento testo, classificazione contenuti.

L’architettura VNRequest separa “cosa analizzare” (la richiesta) da “come elaborare” (il gestore). Lo sviluppatore configura la richiesta (tipo di analisi, parametri aggiuntivi) e la passa al gestore insieme all’immagine. Il gestore esegue la richiesta e restituisce i risultati senza richiedere allo sviluppatore di comprendere gli algoritmi ML interni.

Tutte le sottoclassi di VNRequest seguono una struttura unificata: inizializzazione con completion handler opzionale, configurazione delle proprietà (regione di interesse, livello di precisione) e passaggio al gestore. Questo rende l’API prevedibile e facilmente estendibile — aggiungere un nuovo tipo di analisi significa creare una nuova sottoclasse di VNRequest.

import Vision

// 1. Creare richiesta
let request = VNDetectFaceRectanglesRequest { req, _ in
    // 3. Elaborare risultati
    guard let faces = req.results as? [VNFaceObservation]
    else { return }
    print("Found \\(faces.count) faces")
}

// 2. Eseguire tramite gestore
let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
try handler.perform([request])

Proprietà chiave di VNRequest: regionOfInterest (area di interesse sull’immagine per accelerare l’analisi), preferBackgroundProcessing (modalità in background), revision (versione dell’algoritmo) e cancellationSupport. Una corretta configurazione di queste proprietà consente di ottimizzare le prestazioni per un compito specifico.

Secondo Apple WWDC 2024, in 7 anni di esistenza di Vision, il numero di sottoclassi VNRequest disponibili è passato da 8 (iOS 11) a oltre 25 (iOS 18), coprendo tutti i principali compiti di computer vision sui dispositivi mobili.

Principali Tipi di VNRequest per l’Analisi

Vision include oltre 25 sottoclassi VNRequest divise in categorie: rilevamento, riconoscimento, tracciamento e classificazione. Ogni sottoclasse eredita da VNRequest e aggiunge proprietà specifiche del compito.

Rilevamento e Riconoscimento

VNDetectFaceRectanglesRequest — rilevamento volti nelle immagini. Restituisce VNFaceObservation con coordinate del bounding box e confidenza. VNDetectHumanRectanglesRequest — simile per persone. VNDetectHumanBodyPoseRequest — stima della posa umana (punti scheletrici).

Analisi del Testo

VNRecognizeTextRequest — riconoscimento testo con supporto per 13 lingue e due livelli di precisione. VNReadCodeRequest — per codici specializzati. VNDetectTextRectanglesRequest — ricerca di aree di testo senza riconoscimento (più veloce, ma solo rettangoli).

Classificazione e Analisi

VNClassifyImageRequest — classificazione immagini in 1.000 categorie ImageNet. VNGenerateImageFeaturePrintRequest — estrazione di vettori di caratteristiche per confronto immagini. VNDetectContoursRequest — rilevamento contorni oggetti.

VNImageRequestHandler e VNSequenceRequestHandler

VNImageRequestHandler — un gestore per immagini statiche. Accetta CGImage, CIImage o Data (JPEG/PNG) ed esegue una o più istanze VNRequest. Questo è il modo principale per utilizzare Vision per foto, screenshot e immagini caricate.

VNSequenceRequestHandler — un gestore per sequenze di immagini (fotogrammi video). Accetta lo stesso insieme di tipi di immagine ma è progettato per l’elaborazione fotogramma per fotogramma mantenendo lo stato tra i fotogrammi (necessario per il tracciamento oggetti).

// VNImageRequestHandler per immagine singola
let imageHandler = VNImageRequestHandler(
    cgImage: cgImage,
    orientation: orientation,
    options: [:])

// VNSequenceRequestHandler per video
let sequenceHandler = VNSequenceRequestHandler()
try sequenceHandler.perform([trackingRequest],
    on: cgImage)

Differenza importante: VNSequenceRequestHandler non supporta l’esecuzione parallela di più richieste — ogni chiamata perform() elabora un insieme di richieste per un fotogramma. Per l’elaborazione video multi-thread, creare istanze di gestore separate per thread diversi.

VNImageRequestHandler può essere eseguito su una coda in background. Apple raccomanda DispatchQueue.global(qos: .userInitiated) per scenari interattivi (l’utente attende i risultati) e .background per l’elaborazione batch (ad esempio, analizzare l’intera libreria fotografica).

VNObservation: Struttura dei Risultati

VNObservation — la classe base per tutti i risultati delle richieste Vision. Ogni sottoclasse di VNObservation contiene dati specifici del tipo di analisi: coordinate del bounding box, testo riconosciuto, confidenza, identificatore univoco (uuid) e timestamp (timeRange).

Sottoclassi chiave di VNObservation: VNFaceObservation (risultato rilevamento volto con bounding box e landmarks), VNRecognizedTextObservation (testo riconosciuto con candidati), VNBarcodeObservation (codice a barre decodificato con payload e symbology), VNClassificationObservation (categoria di classificazione con confidenza).

func handleTextResults(request: VNRequest) {
    guard let observations = request.results
        as? [VNRecognizedTextObservation]
    else { return }

    for observation in observations {
        let bbox = observation.boundingBox
        let text = observation.topCandidates(1).first ?? ""
        print("\\(text) at \\(bbox)")
    }
}

Proprietà confidence (da 0.0 a 1.0) è presente in tutte le istanze VNObservation e indica la confidenza del modello nel risultato. Apple raccomanda di scartare le osservazioni con confidence < 0.5 per la maggior parte dei compiti. Per applicazioni critiche (medicina, sicurezza), la soglia dovrebbe essere aumentata a 0.8–0.9.

VNObservation contiene anche timeRange (per richieste video) e uuid (ID univoco per l’abbinamento tra fotogrammi). Ciò consente di tracciare lo stesso oggetto (ad esempio, un volto) attraverso una sequenza di fotogrammi video.

Eseguire Più Richieste Contemporaneamente

Uno dei principali vantaggi di VNRequest è la capacità di eseguire più richieste diverse sulla stessa immagine in una singola chiamata handler.perform(). Vision ottimizza internamente l’ordine di esecuzione e riutilizza calcoli comuni (ad esempio, pre-elaborazione dell’immagine).

Ciò consente di ottenere un set completo di dati su un’immagine in un unico passaggio: rilevare simultaneamente volti, riconoscere testo, trovare codici a barre e classificare contenuti. Questo approccio è significativamente più efficiente rispetto alla chiamata sequenziale di ogni singola richiesta.

import Vision

// Richieste multiple in un singolo array
let faceRequest = VNDetectFaceRectanglesRequest()
let textRequest = VNRecognizeTextRequest()
let barcodeRequest = VNDetectBarcodesRequest()
let classifyRequest = VNClassifyImageRequest()

let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
try handler.perform([
    faceRequest,
    textRequest,
    barcodeRequest,
    classifyRequest
])

// Accedere ai risultati di ogni richiesta
print("Faces: \\(faceRequest.results?.count ?? 0)")
print("Text blocks: \\(textRequest.results?.count ?? 0)")

Limitazioni: non tutte le richieste possono essere combinate con altre. Ad esempio, VNGenerateImageFeaturePrintRequest deve essere eseguito separatamente. Apple raccomanda di raggruppare le richieste per tipo (rilevamento, riconoscimento, classificazione) e testare le combinazioni sui dispositivi di destinazione.

Prestazioni: combinare 3–4 richieste in un singolo perform() è 30–40% più veloce dell’esecuzione sequenziale perché Vision riutilizza calcoli ML condivisi e pre-elaborazione dell’immagine (ridimensionamento, correzione colore).

Richieste Personalizzate con VNCoreMLRequest

VNCoreMLRequest è un ponte tra Core ML e Vision, che consente di eseguire qualsiasi modello Core ML come richiesta Vision. Il modello viene incapsulato in VNCoreMLModel, passato a VNCoreMLRequest, e Vision gestisce automaticamente la pre-elaborazione dell’immagine (ridimensionamento, ritaglio alla dimensione di input del modello).

VNCoreMLRequest eredita da VNRequest, quindi supporta tutte le funzionalità standard: regionOfInterest, completion handler, richieste multiple. Ciò consente di combinare un modello ML personalizzato con i rilevatori integrati di Vision in un unico pipeline.

import Vision
import CoreML

// Incapsulare modello Core ML
guard let mlModel = try VNCoreMLModel(
    for: MyCustomClassifier().model)
else { return }

// Creare VNCoreMLRequest
let coreMLRequest = VNCoreMLRequest(model: mlModel) { request, _ in
    guard let results = request.results
        as? [VNClassificationObservation]
    else { return }

    for result in results.prefix(5) {
        print("\\(result.identifier): \\(result.confidence)"
    }
}
coreMLRequest.imageCropAndScaleOption = .centerCrop
coreMLRequest.regionOfInterest = faceBoundingBox

imageCropAndScaleOption determina come Vision ridimensiona l’immagine per l’input del modello: .centerCrop (ritaglio centrato), .scaleFill (stiramento) o .scaleFit (ridimensionamento mantenendo le proporzioni). La scelta dipende dal tipo di modello e dalla posizione dell’oggetto nell’immagine.

Esempio pratico: rilevamento volti tramite VNDetectFaceRectanglesRequest, quindi classificazione di ciascun volto tramite VNCoreMLRequest con un modello personalizzato (ad esempio, stima del sesso o dell’età). Combinando due richieste in un unico perform(), si ottiene un pipeline completo di analisi del volto in un unico passaggio.