VNRequest — ce este, arhitectura cererilor Vision în iOS

Ce este VNRequest în Vision?

VNRequest — este elementul fundamental al arhitecturii Vision, care implementează modelul Request-Response pentru analiza imaginilor și video. Fiecare subclasă VNRequest este responsabilă pentru o sarcină specifică de viziune computerizată: găsirea fețelor, recunoașterea textului, clasificarea conținutului.

Arhitectura VNRequest separă ce să analizăm (cererea) de cum să procesăm (handler-ul). Dezvoltatorul configurează cererea (tipul de analiză, parametrii suplimentari) și o transmite handler-ului împreună cu imaginea. Handler-ul execută cererea și returnează rezultatele fără a necesita de la dezvoltator înțelegerea algoritmilor interni ML.

Toate subclasele VNRequest urmează o structură unitară: inițializare cu completion handler opțional, configurarea proprietăților (regiunea de analiză, nivelul de precizie) și transmiterea la handler. Acest lucru face API-ul predictibil și ușor extensibil — adăugarea unui nou tip de analiză înseamnă crearea unei noi subclase VNRequest.

import Vision

// 1. Creează cererea
let request = VNDetectFaceRectanglesRequest { req, _ in
    // 3. Procesează rezultatele
    guard let faces = req.results as? [VNFaceObservation]
    else { return }
    print("Found \\(faces.count) faces")
}

// 2. Execută prin handler
let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
try handler.perform([request])

Proprietățile cheie ale VNRequest: regionOfInterest (zona de interes pe imagine pentru accelerarea analizei), preferBackgroundProcessing (modul fundal), revision (versiunea algoritmului) și cancellationSupport. Configurarea corectă a acestor proprietăți permite optimizarea performanței pentru o sarcină specifică.

Conform Apple WWDC 2024, în cei 7 ani de existență Vision, numărul subclaselor disponibile VNRequest a crescut de la 8 (iOS 11) la peste 25 (iOS 18), acoperind toate sarcinile principale de viziune computerizată pe dispozitivele mobile.

Tipurile principale de VNRequest pentru analiză

Vision include peste 25 de subclase VNRequest, împărțite pe categorii: detectare, recunoaștere, urmărire și clasificare. Fiecare subclasă moștenește VNRequest și adaugă proprietăți specifice sarcinii.

Detectare și recunoaștere

VNDetectFaceRectanglesRequest — căutarea fețelor în imagine. Returnează VNFaceObservation cu coordonatele bounding box și confidence. VNDetectHumanRectanglesRequest — similar pentru oameni. VNDetectHumanBodyPoseRequest — determinarea posturii umane (puncte scheletice).

Analiza textului

VNRecognizeTextRequest — recunoașterea textului cu suport pentru 13 limbi și două niveluri de precizie. VNReadCodeRequest — pentru coduri specializate. VNDetectTextRectanglesRequest — căutarea zonelor de text fără recunoaștere (mai rapid, dar doar dreptunghiuri).

Clasificare și analiză

VNClassifyImageRequest — clasificarea imaginii după 1000 de categorii ImageNet. VNGenerateImageFeaturePrintRequest — extragerea vectorului de caracteristici pentru compararea imaginilor. VNDetectContoursRequest — detectarea contururilor obiectelor.

VNImageRequestHandler și VNSequenceRequestHandler

VNImageRequestHandler — handler pentru imagini statice. Acceptă CGImage, CIImage sau Data (JPEG/PNG) și execută una sau mai multe VNRequest. Aceasta este metoda principală de utilizare a Vision pentru fotografii, capturi de ecran și imagini încărcate.

VNSequenceRequestHandler — handler pentru secvențe de imagini (cadre video). Acceptă același set de tipuri de imagini, dar este destinat procesării cadru cu cadru cu păstrarea stării între cadre (necesar pentru urmărirea obiectelor).

// VNImageRequestHandler pentru o singură imagine
let imageHandler = VNImageRequestHandler(
    cgImage: cgImage,
    orientation: orientation,
    options: [:])

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

Diferența importantă: VNSequenceRequestHandler nu suportă executarea paralelă a mai multor cereri — fiecare apel perform() procesează un set de cereri pentru un cadru. Pentru procesarea video multi-thread, creați instanțe separate ale handler-ului pentru diferite fire de execuție.

VNImageRequestHandler poate fi executat în coada de fundal. Apple recomandă DispatchQueue.global(qos: .userInitiated) pentru scenarii interactive (utilizatorul așteaptă rezultatul) și .background pentru procesarea loturilor (de exemplu, analiza înntregii biblioteci foto).

VNObservation: structura rezultatelor

VNObservation — clasa de bază pentru toate rezultatele cererilor Vision. Fiecare subclasă VNObservation conține date specifice tipului de analiză: coordonatele bounding box, textul recunoscut, încrederea (confidence), identificatorul unic (uuid) și marca temporală (timeRange).

Subclasele cheie VNObservation: VNFaceObservation (rezultatul detectării feței cu bounding box și landmarks), VNRecognizedTextObservation (text recunoscut cu candidates), VNBarcodeObservation (cod de bare decodat cu payload și symbology), VNClassificationObservation (categoria de clasificare cu confidence).

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)")
    }
}

Proprietatea confidence (de la 0.0 la 1.0) este prezentă în toate VNObservation și arată încrederea modelului în rezultat. Apple recomandă respingerea observațiilor cu confidence < 0.5 pentru majoritatea sarcinilor. Pentru aplicații critice (medicină, securitate) pragul trebuie ridicat la 0.8–0.9.

VNObservation conține, de asemenea, timeRange (pentru cereri video) și uuid (ID unic pentru potrivirea între cadre). Acest lucru permite urmărirea aceluiași obiect (de exemplu, o față) printr-o secvență de cadre video.

Executarea mai multor cereri simultan

Unul dintre avantajele cheie ale VNRequest — posibilitatea de a executa mai multe cereri diferite pentru aceeași imagine înntr-un singur apel handler.perform(). Vision optimizează intern ordinea executării și reutilizează calculele comune (de exemplu, preprocesarea imaginii).

Acest lucru permite obținerea unui set complet de date despre imagine înntr-o singură trecere: detectarea simultană a fețelor, recunoașterea textului, găsirea codurilor de bare și clasificarea conținutului. Această abordare este semnificativ mai eficientă decât apelarea secvențială a fiecărei cereri în parte.

import Vision

// Mai multe cereri înntr-un singur tablou
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
])

// Accesează rezultatele din fiecare cerere
print("Faces: \\(faceRequest.results?.count ?? 0)")
print("Text blocks: \\(textRequest.results?.count ?? 0)")

Limitări: nu toate cererile pot fi combinate cu altele. De exemplu, VNGenerateImageFeaturePrintRequest trebuie executat separat. Apple recomandă gruparea cererilor după tip (detectare, recunoaștere, clasificare) și testarea combinațiilor pe dispozitivele țintă.

Performanță: combinarea a 3–4 cereri înntr-un perform() este cu 30–40% mai rapidă decât executarea secvențială, deoarece Vision reutilizează calculele ML comune și preprocesarea imaginii (scalare, corecția culorilor).

Cereri personalizate cu VNCoreMLRequest

VNCoreMLRequest — este o punte între Core ML și Vision, care permite rularea oricărui model Core ML ca cerere Vision. Modelul este înfășurat în VNCoreMLModel, transmis către VNCoreMLRequest, iar Vision procesează automat preprocesarea imaginii (scalare, decupare la dimensiunea de intrare a modelului).

VNCoreMLRequest moștenește VNRequest, deci suportă toate funcționalitățile standard: regionOfInterest, completion handler, cereri multiple. Acest lucru permite combinarea modelului ML personalizat cu detectoarele încorporate Vision înntr-un singur pipeline.

import Vision
import CoreML

// Înfășurează modelul Core ML
guard let mlModel = try VNCoreMLModel(
    for: MyCustomClassifier().model)
else { return }

// Creează 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 determină modul în care Vision scalează imaginea la intrarea modelului: .centerCrop (decupare din centru), .scaleFill (întindere) sau .scaleFit (scalare cu păstrarea proporțiilor). Alegerea depinde de tipul modelului și de poziția obiectului în imagine.

Exemplu practic: detectarea fețelor prin VNDetectFaceRectanglesRequest, apoi clasificarea fiecărei fețe prin VNCoreMLRequest cu un model personalizat (de exemplu, determinarea sexului sau vârstei). Combinând două cereri înntr-un perform(), obțineți un pipeline complet de analiză a feței înntr-o singură trecere.