VNRequest — o que é, como funcionam as solicitações do Vision no iOS

O que é VNRequest no Vision?

VNRequest é um elemento fundamental da arquitetura Vision, implementando o padrão Solicitação-Resposta para análise de imagens e vídeos. Cada subclasse de VNRequest é responsável por uma tarefa específica de visão computacional: detecção facial, reconhecimento de texto, classificação de conteúdo.

A arquitetura VNRequest separa “o que analisar” (a solicitação) de “como processar” (o manipulador). O desenvolvedor configura a solicitação (tipo de análise, parâmetros adicionais) e a passa ao manipulador junto com a imagem. O manipulador executa a solicitação e retorna os resultados sem exigir que o desenvolvedor compreenda os algoritmos internos de ML.

Todas as subclasses de VNRequest seguem uma estrutura unificada: inicialização com um completion handler opcional, configuração de propriedades (região de interesse, nível de precisão) e passagem ao manipulador. Isso torna a API previsível e facilmente extensível — adicionar um novo tipo de análise significa criar uma nova subclasse de VNRequest.

import Vision

// 1. Criar solicitação
let request = VNDetectFaceRectanglesRequest { req, _ in
    // 3. Processar resultados
    guard let faces = req.results as? [VNFaceObservation]
    else { return }
    print("Found \\(faces.count) faces")
}

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

Propriedades chave do VNRequest: regionOfInterest (área de interesse na imagem para acelerar a análise), preferBackgroundProcessing (modo de fundo), revision (versão do algoritmo) e cancellationSupport. A configuração adequada dessas propriedades permite otimizar o desempenho para uma tarefa específica.

De acordo com Apple WWDC 2024, em 7 anos de existência do Vision, o número de subclasses disponíveis de VNRequest cresceu de 8 (iOS 11) para mais de 25 (iOS 18), cobrindo todas as principais tarefas de visão computacional em dispositivos móveis.

Principais Tipos de VNRequest para Análise

Vision inclui mais de 25 subclasses de VNRequest divididas em categorias: detecção, reconhecimento, rastreamento e classificação. Cada subclasse herda de VNRequest e adiciona propriedades específicas da tarefa.

Detecção e Reconhecimento

VNDetectFaceRectanglesRequest — detecção facial em imagens. Retorna VNFaceObservation com coordenadas do bounding box e confiança. VNDetectHumanRectanglesRequest — semelhante para pessoas. VNDetectHumanBodyPoseRequest — estimativa de postura humana (pontos esqueléticos).

Análise de Texto

VNRecognizeTextRequest — reconhecimento de texto com suporte a 13 idiomas e dois níveis de precisão. VNReadCodeRequest — para códigos especializados. VNDetectTextRectanglesRequest — busca de áreas de texto sem reconhecimento (mais rápido, mas apenas retângulos).

Classificação e Análise

VNClassifyImageRequest — classificação de imagens em 1.000 categorias do ImageNet. VNGenerateImageFeaturePrintRequest — extração de vetor de características para comparação de imagens. VNDetectContoursRequest — detecção de contornos de objetos.

VNImageRequestHandler e VNSequenceRequestHandler

VNImageRequestHandler — um manipulador para imagens estáticas. Aceita CGImage, CIImage ou Data (JPEG/PNG) e executa uma ou mais instâncias de VNRequest. Esta é a principal forma de usar o Vision para fotos, capturas de tela e imagens carregadas.

VNSequenceRequestHandler — um manipulador para sequências de imagens (quadros de vídeo). Aceita o mesmo conjunto de tipos de imagem, mas é projetado para processamento quadro a quadro mantendo o estado entre quadros (necessário para rastreamento de objetos).

// VNImageRequestHandler para imagem única
let imageHandler = VNImageRequestHandler(
    cgImage: cgImage,
    orientation: orientation,
    options: [:])

// VNSequenceRequestHandler para vídeo
let sequenceHandler = VNSequenceRequestHandler()
try sequenceHandler.perform([trackingRequest],
    on: cgImage)

Diferença importante: VNSequenceRequestHandler não suporta execução paralela de várias solicitações — cada chamada perform() processa um conjunto de solicitações para um quadro. Para processamento de vídeo multithread, crie instâncias de manipulador separadas para diferentes threads.

VNImageRequestHandler pode ser executado em uma fila em segundo plano. A Apple recomenda DispatchQueue.global(qos: .userInitiated) para cenários interativos (o usuário aguarda resultados) e .background para processamento em lote (por exemplo, analisar uma biblioteca de fotos completa).

VNObservation: Estrutura dos Resultados

VNObservation — a classe base para todos os resultados de solicitações do Vision. Cada subclasse de VNObservation contém dados específicos do tipo de análise: coordenadas do bounding box, texto reconhecido, confiança, identificador único (uuid) e carimbo de data/hora (timeRange).

Subclasses chave de VNObservation: VNFaceObservation (resultado de detecção facial com bounding box e landmarks), VNRecognizedTextObservation (texto reconhecido com candidatos), VNBarcodeObservation (código de barras decodificado com payload e symbology), VNClassificationObservation (categoria de classificação com confiança).

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

Propriedade confidence (de 0.0 a 1.0) está presente em todas as instâncias de VNObservation e indica a confiança do modelo no resultado. A Apple recomenda descartar observações com confidence < 0.5 para a maioria das tarefas. Para aplicativos críticos (medicina, segurança), o limite deve ser elevado para 0.8–0.9.

VNObservation também contém timeRange (para solicitações de vídeo) e uuid (ID único para correspondência entre quadros). Isso permite rastrear o mesmo objeto (por exemplo, um rosto) através de uma sequência de quadros de vídeo.

Executar Várias Solicitações Simultaneamente

Uma das principais vantagens do VNRequest é a capacidade de executar várias solicitações diferentes na mesma imagem em uma única chamada handler.perform(). O Vision otimiza internamente a ordem de execução e reutiliza cálculos comuns (por exemplo, pré-processamento de imagem).

Isso permite obter um conjunto completo de dados sobre uma imagem em uma única passagem: detectar rostos simultaneamente, reconhecer texto, encontrar códigos de barras e classificar conteúdo. Esta abordagem é significativamente mais eficiente do que chamar cada solicitação sequencialmente.

import Vision

// Várias solicitações em um único 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
])

// Acessar resultados de cada solicitação
print("Faces: \\(faceRequest.results?.count ?? 0)")
print("Text blocks: \\(textRequest.results?.count ?? 0)")

Limitações: nem todas as solicitações podem ser combinadas com outras. Por exemplo, VNGenerateImageFeaturePrintRequest deve ser executado separadamente. A Apple recomenda agrupar solicitações por tipo (detecção, reconhecimento, classificação) e testar combinações nos dispositivos de destino.

Desempenho: combinar 3–4 solicitações em um único perform() é 30–40% mais rápido que a execução sequencial porque o Vision reutiliza cálculos compartilhados de ML e pré-processamento de imagem (dimensionamento, correção de cor).

Solicitações Personalizadas com VNCoreMLRequest

VNCoreMLRequest é uma ponte entre Core ML e Vision, permitindo executar qualquer modelo Core ML como uma solicitação do Vision. O modelo é encapsulado em VNCoreMLModel, passado para VNCoreMLRequest, e o Vision lida automaticamente com o pré-processamento da imagem (dimensionamento, corte para o tamanho de entrada do modelo).

VNCoreMLRequest herda de VNRequest, portanto suporta todos os recursos padrão: regionOfInterest, completion handler, várias solicitações. Isso permite combinar um modelo ML personalizado com os detectores integrados do Vision em um único pipeline.

import Vision
import CoreML

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

// Criar 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 como o Vision dimensiona a imagem para a entrada do modelo: .centerCrop (corte centralizado), .scaleFill (esticamento) ou .scaleFit (dimensionamento mantendo a proporção). A escolha depende do tipo de modelo e da posição do objeto na imagem.

Exemplo prático: detecção facial através de VNDetectFaceRectanglesRequest, em seguida classificação de cada rosto através de VNCoreMLRequest com um modelo personalizado (por exemplo, estimativa de gênero ou idade). Combinando duas solicitações em um único perform(), você obtém um pipeline completo de análise facial em uma única passagem.