VNRequest — qué es, cómo funcionan las solicitudes de Vision en iOS

¿Qué es VNRequest en Vision?

VNRequest es un elemento fundamental de la arquitectura Vision que implementa el patrón Solicitud-Respuesta para el análisis de imágenes y vídeo. Cada subclase de VNRequest se encarga de una tarea específica de visión por computadora: detección de rostros, reconocimiento de texto, clasificación de contenido.

La arquitectura de VNRequest separa “qué analizar” (la solicitud) de “cómo procesar” (el manejador). El desarrollador configura la solicitud (tipo de análisis, parámetros adicionales) y la pasa al manejador junto con la imagen. El manejador ejecuta la solicitud y devuelve los resultados sin requerir que el desarrollador comprenda los algoritmos internos de ML.

Todas las subclases de VNRequest siguen una estructura unificada: inicialización con un completion handler opcional, configuración de propiedades (región de interés, nivel de precisión) y paso al manejador. Esto hace que la API sea predecible y fácilmente extensible — agregar un nuevo tipo de análisis significa crear una nueva subclase de VNRequest.

import Vision

// 1. Crear solicitud
let request = VNDetectFaceRectanglesRequest { req, _ in
    // 3. Procesar resultados
    guard let faces = req.results as? [VNFaceObservation]
    else { return }
    print("Found \\(faces.count) faces")
}

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

Propiedades clave de VNRequest: regionOfInterest (área de interés en la imagen para acelerar el análisis), preferBackgroundProcessing (modo fondo), revision (versión del algoritmo) y cancellationSupport. La configuración adecuada de estas propiedades permite optimizar el rendimiento para una tarea específica.

Según Apple WWDC 2024, en 7 años de existencia de Vision, el número de subclases disponibles de VNRequest pasó de 8 (iOS 11) a más de 25 (iOS 18), cubriendo todas las tareas principales de visión por computadora en dispositivos móviles.

Principales Tipos de VNRequest para Análisis

Vision incluye más de 25 subclases de VNRequest divididas en categorías: detección, reconocimiento, seguimiento y clasificación. Cada subclase hereda de VNRequest y añade propiedades específicas de la tarea.

Detección y Reconocimiento

VNDetectFaceRectanglesRequest — detección de rostros en imágenes. Devuelve VNFaceObservation con coordenadas del bounding box y confianza. VNDetectHumanRectanglesRequest — similar para personas. VNDetectHumanBodyPoseRequest — estimación de la postura humana (puntos esqueléticos).

Análisis de Texto

VNRecognizeTextRequest — reconocimiento de texto con soporte para 13 idiomas y dos niveles de precisión. VNReadCodeRequest — para códigos especializados. VNDetectTextRectanglesRequest — búsqueda de áreas de texto sin reconocimiento (más rápido, pero solo rectángulos).

Clasificación y Análisis

VNClassifyImageRequest — clasificación de imágenes en 1.000 categorías de ImageNet. VNGenerateImageFeaturePrintRequest — extracción de vectores de características para comparación de imágenes. VNDetectContoursRequest — detección de contornos de objetos.

VNImageRequestHandler y VNSequenceRequestHandler

VNImageRequestHandler — un manejador para imágenes estáticas. Acepta CGImage, CIImage o Data (JPEG/PNG) y ejecuta una o más instancias de VNRequest. Esta es la forma principal de usar Vision para fotos, capturas de pantalla e imágenes cargadas.

VNSequenceRequestHandler — un manejador para secuencias de imágenes (fotogramas de vídeo). Acepta el mismo conjunto de tipos de imagen pero está diseñado para procesamiento fotograma a fotograma manteniendo el estado entre fotogramas (necesario para el seguimiento de objetos).

// VNImageRequestHandler para una sola imagen
let imageHandler = VNImageRequestHandler(
    cgImage: cgImage,
    orientation: orientation,
    options: [:])

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

Diferencia importante: VNSequenceRequestHandler no soporta la ejecución paralela de múltiples solicitudes — cada llamada a perform() procesa un conjunto de solicitudes para un fotograma. Para procesamiento de vídeo multiproceso, cree instancias de manejador separadas para diferentes hilos.

VNImageRequestHandler puede ejecutarse en una cola en segundo plano. Apple recomienda DispatchQueue.global(qos: .userInitiated) para escenarios interactivos (el usuario espera resultados) y .background para procesamiento por lotes (por ejemplo, analizar una biblioteca de fotos completa).

VNObservation: Estructura de los Resultados

VNObservation — la clase base para todos los resultados de solicitudes de Vision. Cada subclase de VNObservation contiene datos específicos del tipo de análisis: coordenadas del bounding box, texto reconocido, confianza, identificador único (uuid) y marca de tiempo (timeRange).

Subclases clave de VNObservation: VNFaceObservation (resultado de detección facial con bounding box y landmarks), VNRecognizedTextObservation (texto reconocido con candidatos), VNBarcodeObservation (código de barras decodificado con payload y symbology), VNClassificationObservation (categoría de clasificación con confianza).

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

Propiedad confidence (de 0.0 a 1.0) está presente en todas las instancias de VNObservation e indica la confianza del modelo en el resultado. Apple recomienda descartar observaciones con confidence < 0.5 para la mayoría de las tareas. Para aplicaciones críticas (medicina, seguridad), el umbral debe elevarse a 0.8–0.9.

VNObservation también contiene timeRange (para solicitudes de vídeo) y uuid (ID único para coincidencia entre fotogramas). Esto permite rastrear el mismo objeto (por ejemplo, un rostro) a través de una secuencia de fotogramas de vídeo.

Ejecutar Múltiples Solicitudes Simultáneamente

Una de las ventajas clave de VNRequest es la capacidad de ejecutar múltiples solicitudes diferentes en la misma imagen en una sola llamada a handler.perform(). Vision optimiza internamente el orden de ejecución y reutiliza cálculos comunes (por ejemplo, el preprocesamiento de la imagen).

Esto permite obtener un conjunto completo de datos sobre una imagen en una sola pasada: detectar rostros simultáneamente, reconocer texto, encontrar códigos de barras y clasificar contenido. Este enfoque es significativamente más eficiente que llamar a cada solicitud secuencialmente.

import Vision

// Múltiples solicitudes en un solo 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
])

// Acceder a los resultados de cada solicitud
print("Faces: \\(faceRequest.results?.count ?? 0)")
print("Text blocks: \\(textRequest.results?.count ?? 0)")

Limitaciones: no todas las solicitudes se pueden combinar con otras. Por ejemplo, VNGenerateImageFeaturePrintRequest debe ejecutarse por separado. Apple recomienda agrupar las solicitudes por tipo (detección, reconocimiento, clasificación) y probar las combinaciones en los dispositivos de destino.

Rendimiento: combinar 3–4 solicitudes en un solo perform() es 30–40% más rápido que la ejecución secuencial porque Vision reutiliza cálculos compartidos de ML y preprocesamiento de imagen (escalado, corrección de color).

Solicitudes Personalizadas con VNCoreMLRequest

VNCoreMLRequest es un puente entre Core ML y Vision que permite ejecutar cualquier modelo de Core ML como una solicitud de Vision. El modelo se envuelve en VNCoreMLModel, se pasa a VNCoreMLRequest, y Vision maneja automáticamente el preprocesamiento de la imagen (escalado, recorte al tamaño de entrada del modelo).

VNCoreMLRequest hereda de VNRequest, por lo que soporta todas las funciones estándar: regionOfInterest, completion handler, múltiples solicitudes. Esto permite combinar un modelo ML personalizado con los detectores integrados de Vision en un solo pipeline.

import Vision
import CoreML

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

// Crear 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 cómo Vision escala la imagen a la entrada del modelo: .centerCrop (recorte centrado), .scaleFill (estiramiento) o .scaleFit (escalado manteniendo la relación de aspecto). La elección depende del tipo de modelo y la posición del objeto en la imagen.

Ejemplo práctico: detección de rostros mediante VNDetectFaceRectanglesRequest, luego clasificación de cada rostro mediante VNCoreMLRequest con un modelo personalizado (por ejemplo, estimación de género o edad). Combinando dos solicitudes en un solo perform(), se obtiene un pipeline completo de análisis facial en una sola pasada.