VNRequest — apa itu, arsitektur permintaan Vision di iOS

Apa itu VNRequest di Vision?

VNRequest — adalah elemen fundamental arsitektur Vision yang mengimplementasikan pola Request-Response untuk analisis gambar dan video. Setiap subkelas VNRequest bertanggung jawab untuk tugas visi komputer tertentu: mencari wajah, mengenali teks, mengklasifikasikan konten.

Arsitektur VNRequest memisahkan “apa yang akan dianalisis” (permintaan) dari “bagaimana memproses” (handler). Pengembang mengonfigurasi permintaan (jenis analisis, parameter tambahan) dan mengirimkannya ke handler bersama dengan gambar. Handler menjalankan permintaan dan mengembalikan hasil, tanpa memerlukan pengembang untuk memahami algoritma ML internal.

Semua subkelas VNRequest mengikuti struktur seragam: inisialisasi dengan completion handler opsional, konfigurasi properti (wilayah analisis, tingkat akurasi) dan pengiriman ke handler. Ini membuat API dapat diprediksi dan mudah diperluas — menambahkan jenis analisis baru berarti membuat subkelas VNRequest baru.

import Vision

// 1. Buat permintaan
let request = VNDetectFaceRectanglesRequest { req, _ in
    // 3. Proses hasil
    guard let faces = req.results as? [VNFaceObservation]
    else { return }
    print("Found \\(faces.count) faces")
}

// 2. Jalankan melalui handler
let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
try handler.perform([request])

Properti kunci VNRequest: regionOfInterest (wilayah minat pada gambar untuk mempercepat analisis), preferBackgroundProcessing (mode latar belakang), revision (versi algoritma) dan cancellationSupport. Konfigurasi yang tepat dari properti ini memungkinkan Anda mengoptimalkan kinerja untuk tugas tertentu.

Menurut Apple WWDC 2024, selama 7 tahun keberadaan Vision, jumlah subkelas VNRequest yang tersedia telah meningkat dari 8 (iOS 11) menjadi lebih dari 25 (iOS 18), mencakup semua tugas utama visi komputer pada perangkat seluler.

Jenis utama VNRequest untuk analisis

Vision mencakup lebih dari 25 subkelas VNRequest, dibagi ke dalam kategori: deteksi, pengenalan, pelacakan, dan klasifikasi. Setiap subkelas mewarisi VNRequest dan menambahkan properti spesifik tugas.

Deteksi dan pengenalan

VNDetectFaceRectanglesRequest — mencari wajah pada gambar. Mengembalikan VNFaceObservation dengan koordinat bounding box dan confidence. VNDetectHumanRectanglesRequest — serupa untuk manusia. VNDetectHumanBodyPoseRequest — menentukan pose manusia (titik kerangka).

Analisis teks

VNRecognizeTextRequest — pengenalan teks dengan dukungan 13 bahasa dan dua tingkat akurasi. VNReadCodeRequest — untuk kode khusus. VNDetectTextRectanglesRequest — mencari area teks tanpa pengenalan (lebih cepat, tetapi hanya persegi panjang).

Klasifikasi dan analisis

VNClassifyImageRequest — klasifikasi gambar berdasarkan 1000 kategori ImageNet. VNGenerateImageFeaturePrintRequest — ekstraksi feature vector untuk membandingkan gambar. VNDetectContoursRequest — deteksi kontur objek.

VNImageRequestHandler dan VNSequenceRequestHandler

VNImageRequestHandler — handler untuk gambar statis. Menerima CGImage, CIImage atau Data (JPEG/PNG) dan menjalankan satu atau beberapa VNRequest. Ini adalah cara utama menggunakan Vision untuk foto, tangkapan layar, dan gambar yang diunggah.

VNSequenceRequestHandler — handler untuk urutan gambar (bingkai video). Menerima set jenis gambar yang sama, tetapi ditujukan untuk pemrosesan bingkai demi bingkai dengan mempertahankan status antar bingkai (diperlukan untuk pelacakan objek).

// VNImageRequestHandler untuk satu gambar
let imageHandler = VNImageRequestHandler(
    cgImage: cgImage,
    orientation: orientation,
    options: [:])

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

Perbedaan penting: VNSequenceRequestHandler tidak mendukung eksekusi paralel beberapa permintaan — setiap panggilan perform() memproses satu set permintaan untuk satu bingkai. Untuk pemrosesan video multi-thread, buat instance handler terpisah untuk thread yang berbeda.

VNImageRequestHandler dapat dijalankan pada antrian latar belakang. Apple merekomendasikan DispatchQueue.global(qos: .userInitiated) untuk skenario interaktif (pengguna menunggu hasil) dan .background untuk pemrosesan batch (misalnya, analisis seluruh perpustakaan foto).

VNObservation: struktur hasil

VNObservation — kelas dasar untuk semua hasil permintaan Vision. Setiap subkelas VNObservation berisi data spesifik untuk jenis analisis: koordinat bounding box, teks yang dikenali, kepercayaan (confidence), pengidentifikasi unik (uuid), dan stempel waktu (timeRange).

Subkelas kunci VNObservation: VNFaceObservation (hasil deteksi wajah dengan bounding box dan landmarks), VNRecognizedTextObservation (teks yang dikenali dengan candidates), VNBarcodeObservation (kode batang yang didekode dengan payload dan symbology), VNClassificationObservation (kategori klasifikasi dengan 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)")
    }
}

Properti confidence (dari 0,0 hingga 1,0) ada di semua VNObservation dan menunjukkan kepercayaan model terhadap hasil. Apple merekomendasikan untuk membuang observasi dengan confidence < 0,5 untuk sebagian besar tugas. Untuk aplikasi kritis (medis, keamanan) tingkatkan ambang batas menjadi 0,8–0,9.

VNObservation juga berisi timeRange (untuk permintaan video) dan uuid (ID unik untuk pencocokan antar bingkai). Ini memungkinkan pelacakan objek yang sama (misalnya, wajah) melalui urutan bingkai video.

Menjalankan beberapa permintaan secara bersamaan

Salah satu keunggulan utama VNRequest — kemampuan untuk menjalankan beberapa permintaan berbeda untuk satu gambar dalam satu panggilan handler.perform(). Vision secara internal mengoptimalkan urutan eksekusi dan menggunakan kembali perhitungan bersama (misalnya, prapemrosesan gambar).

Ini memungkinkan memperoleh set data lengkap tentang gambar dalam satu kali proses: secara bersamaan mendeteksi wajah, mengenali teks, menemukan kode batang, dan mengklasifikasikan konten. Pendekatan ini jauh lebih efisien daripada memanggil setiap permintaan secara berurutan.

import Vision

// Beberapa permintaan dalam satu 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
])

// Akses hasil dari setiap permintaan
print("Faces: \\(faceRequest.results?.count ?? 0)")
print("Text blocks: \\(textRequest.results?.count ?? 0)")

Keterbatasan: tidak semua permintaan dapat digabungkan dengan yang lain. Misalnya, VNGenerateImageFeaturePrintRequest harus dijalankan secara terpisah. Apple merekomendasikan pengelompokan permintaan berdasarkan jenis (deteksi, pengenalan, klasifikasi) dan menguji kombinasi pada perangkat target.

Kinerja: menggabungkan 3–4 permintaan dalam satu perform() 30–40% lebih cepat daripada eksekusi berurutan, karena Vision menggunakan kembali perhitungan ML bersama dan prapemrosesan gambar (penskalaan, koreksi warna).

Permintaan kustom dengan VNCoreMLRequest

VNCoreMLRequest — adalah jembatan antara Core ML dan Vision, yang memungkinkan menjalankan model Core ML apa pun sebagai permintaan Vision. Model dibungkus dalam VNCoreMLModel, diteruskan ke VNCoreMLRequest, dan Vision secara otomatis memproses prapemrosesan gambar (penskalaan, pemotongan sesuai ukuran input model).

VNCoreMLRequest mewarisi VNRequest, sehingga mendukung semua fungsionalitas standar: regionOfInterest, completion handler, beberapa permintaan. Ini memungkinkan menggabungkan model ML kustom dengan detektor bawaan Vision dalam satu pipeline.

import Vision
import CoreML

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

// Buat 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 menentukan bagaimana Vision menskalakan gambar ke input model: .centerCrop (pemotongan dari tengah), .scaleFill (peregangan) atau .scaleFit (penskalaan dengan mempertahankan proporsi). Pilihan tergantung pada jenis model dan posisi objek pada gambar.

Contoh praktis: deteksi wajah melalui VNDetectFaceRectanglesRequest, kemudian klasifikasi setiap wajah melalui VNCoreMLRequest dengan model kustom (misalnya, menentukan jenis kelamin atau usia). Dengan menggabungkan dua permintaan dalam satu perform(), Anda mendapatkan pipeline analisis wajah lengkap dalam satu kali proses.