BadBob / Playground

Tu modelo.
En el mundo real.

Convierte un modelo entrenado en algo útil. Pequeños ejemplos de código abierto, pasos claros y código que puedes adaptar a tu idea.

Código abierto · MIT · Tu modelo sigue siendo tuyo

DEL MODELO A LA APP
El profesor Bob sonríe y mira por encima de sus gafas de lectura, bajadas sobre la nariz, junto a una pizarra llena de física compleja. En una esquina borrada ha escrito: MODEL = mc² / 10 PRINT "BAD BOB" / 20 GOTO 10.
  1. 01Cámara
  2. 02Modelo
  3. 03Predicción
  4. 04Tu app
Ilustración · del cálculo al resultado

01 / ELIGE TU CAMINO

Un pequeño comienzo. Espacio para crecer.

Disponible

Swift

Una app de cámara nativa para Mac con tu detector Core ML.

Core ML · macOS
Disponible

Python

Una ruta de scripts para inspeccionar modelos y crear herramientas prácticas.

ONNX Runtime · OpenCV
Disponible

JavaScript

Ejemplos de navegador con un modelo ONNX compatible.

Web · ONNX
Disponible

Rust

Una ruta nativa con requisitos claros de modelo y entorno.

OpenCV · ONNX
Disponible

Go

Herramientas prácticas con una interfaz clara hacia la ejecución del modelo.

GoCV · ONNX
Disponible

C++

Cámara e inferencia local con OpenCV y un modelo ONNX compatible.

OpenCV · ONNX

DeviconGo Gopher — Renee FrenchCC BY 3.0

Ten en cuenta
  1. Síntoma
    La interfaz se congela al iniciar la cámara.
    Causa
    El inicio de la sesión bloquea; async por sí solo no saca el trabajo de MainActor.
    Solución
    Ejecuta la captura y la inferencia en un ejecutor serie dedicado. Actualiza la interfaz en MainActor.
  2. Síntoma
    La vista previa se retrasa y aumenta el uso de memoria.
    Causa
    La cámara produce imágenes más rápido de lo que la inferencia las procesa, por lo que crece una cola sin límite.
    Solución
    Descarta imágenes tardías, procesa en serie y conserva solo el resultado pendiente más reciente. Evita una Task por imagen.
  3. Síntoma
    Reaparecen cuadros antiguos tras detener la cámara o cambiar de modelo.
    Causa
    Una tarea anterior puede terminar tarde; los observadores retenidos pueden mantener recursos activos.
    Solución
    Cancela la ejecución anterior, rechaza resultados obsoletos, detén la captura y elimina observadores. Libera modelos temporales; analiza inicios y paradas repetidos con Instruments.
BadBob / Playground
Core ML · Vision · MIT
02.01

Prepara el proyecto

Descarga el código y ejecuta sus pruebas. Necesitas una cámara y un detector de objetos Core ML compatible con Vision. No se incluyen pesos del modelo.

Fundamentos

swift test
Ejecuta comprobaciones automáticas sin abrir la cámara.
Terminalbash
unzip badbob-playground-swift.zip
cd badbob-playground-swift
swift test
02.02

Conecta tu modelo

Carga el modelo y crea una solicitud de Vision. Revisa las entradas antes de iniciar la cámara y conserva las compilaciones temporales durante toda la inferencia.

Fundamentos

VisionDetector.init(modelURL:)
Carga o compila el modelo Core ML y valida su entrada de imagen.
VisionDetector.predict(_:)
Prepara la imagen, ejecuta el modelo y devuelve las detecciones.

Este ejemplo requiere un detector de objetos Core ML que devuelva observaciones de objetos de Vision. Otros tipos de modelos y los archivos ONNX necesitan otro adaptador.

En profundidad

Vision devuelve coordenadas normalizadas desde la esquina inferior izquierda. Conviértelas a la vista, conserva la proporción y refleja imagen y cuadros juntos.

Core ML · Visionyaml
model:
  runtime: Core ML + Vision
  formats: [.mlmodel, .mlpackage, .mlmodelc]
  image_inputs: 1
  results: VNRecognizedObjectObservation
preprocessing:
  crop_and_scale: scaleFill
  orientation: up
coordinates:
  range: [0, 1]
  origin: bottom_left
preview:
  scaling: aspect_fit
  mirroring: paired
VisionDetector.swiftswift
import CoreML
import Foundation
import Vision

/// Owned by one frame processor and used only on its serial capture queue.
final class VisionDetector {
    private let request: VNCoreMLRequest
    private let compiledURL: URL?
    private let scopedURL: URL?

    init(modelURL: URL) throws {
        guard modelURL.isFileURL,
            ["mlmodel", "mlpackage", "mlmodelc"].contains(modelURL.pathExtension.lowercased())
        else {
            throw CaptureFailure.unsupportedModel
        }

        let scoped = modelURL.startAccessingSecurityScopedResource()
        var ownedCompilation: URL?

        do {
            let loadURL: URL

            if modelURL.pathExtension.lowercased() == "mlmodelc" {
                loadURL = modelURL
            } else {
                loadURL = try MLModel.compileModel(at: modelURL)
                ownedCompilation = loadURL
            }

            let model = try MLModel(contentsOf: loadURL)
            guard
                model.modelDescription.inputDescriptionsByName.values.filter({ $0.type == .image })
                    .count == 1
            else {
                throw CaptureFailure.unsupportedModel
            }

            request = VNCoreMLRequest(model: try VNCoreMLModel(for: model))
            request.imageCropAndScaleOption = .scaleFill
            compiledURL = ownedCompilation
            scopedURL = scoped ? modelURL : nil
        } catch {
            if scoped {
                modelURL.stopAccessingSecurityScopedResource()
            }

            if let ownedCompilation {
                try? FileManager.default.removeItem(at: ownedCompilation)
            }

            throw error
        }
    }

    deinit {
        // Predictions have ended; remove only our own temporary compilation.
        if let compiledURL {
            try? FileManager.default.removeItem(at: compiledURL)
        }

        scopedURL?.stopAccessingSecurityScopedResource()
    }

    func predict(_ buffer: CVPixelBuffer) throws -> [Detection] {
        try VNImageRequestHandler(cvPixelBuffer: buffer, orientation: .up).perform([request])

        guard let objects = request.results as? [VNRecognizedObjectObservation] else {
            throw CaptureFailure.unsupportedModel
        }

        return objects.enumerated().compactMap { index, observation in

            guard let label = observation.labels.first, label.confidence.isFinite else {
                return nil
            }

            return Detection(
                id: index, label: label.identifier, confidence: label.confidence,
                bounds: observation.boundingBox)
        }
    }
}
02.03

Incorpora la cámara

La captura usa su propio ejecutor en serie. Se descartan los fotogramas tardíos y solo el último procesado espera a la interfaz. Imagen y predicciones permanecen juntas.

Fundamentos

CameraService.start(runID:modelURL:)
Crea la sesión de captura en su ejecutor serie y devuelve un flujo con un máximo de una imagen pendiente.
CameraService.stop(runID:)
Detiene solo la ejecución correspondiente y libera su sesión, delegado y observadores.
Ten en cuenta
  1. Síntoma
    La interfaz se congela al iniciar la cámara.
    Causa
    El inicio de la sesión bloquea; async por sí solo no saca el trabajo de MainActor.
    Solución
    Ejecuta la captura y la inferencia en un ejecutor serie dedicado. Actualiza la interfaz en MainActor.
  2. Síntoma
    La vista previa se retrasa y aumenta el uso de memoria.
    Causa
    La cámara produce imágenes más rápido de lo que la inferencia las procesa, por lo que crece una cola sin límite.
    Solución
    Descarta imágenes tardías, procesa en serie y conserva solo el resultado pendiente más reciente. Evita una Task por imagen.
CameraService.swiftswift
import AVFoundation
import CoreImage
import Dispatch
import Foundation

/// A custom executor keeps blocking AVFoundation work off the main actor.
public actor CameraService: CameraCapturing {
    private nonisolated let queue = DispatchSerialQueue(label: "ai.badbob.playground.camera")
    public nonisolated var unownedExecutor: UnownedSerialExecutor {
        queue.asUnownedSerialExecutor()
    }

    private var session: AVCaptureSession?
    private var output: AVCaptureVideoDataOutput?
    private var processor: FrameProcessor?
    private var monitor: CaptureSessionMonitor?
    private var activeRunID: UUID?

    public init() {}

    public func start(runID: UUID, modelURL: URL) async throws -> FrameStream {
        stopActiveRun()
        let detector = try loadDetector(modelURL: modelURL)

        try Task.checkCancellation()

        guard let camera = AVCaptureDevice.default(for: .video) else {
            throw CaptureFailure.noCamera
        }

        let candidate = AVCaptureSession()
        let frames = AVCaptureVideoDataOutput()
        let (stream, continuation) = FrameStream.makeStream(bufferingPolicy: .bufferingNewest(1))
        let delegate = FrameProcessor(detector: detector, continuation: continuation)
        try configureSession(candidate, output: frames, processor: delegate, camera: camera)

        try Task.checkCancellation()
        session = candidate
        output = frames
        processor = delegate
        activeRunID = runID
        monitor = CaptureSessionMonitor(session: candidate, continuation: continuation)
        continuation.onTermination = { [weak self] _ in
            Task { await self?.stop(runID: runID) }
        }

        candidate.startRunning()

        guard candidate.isRunning else {
            stopActiveRun()
            throw CaptureFailure.configuration
        }

        return stream
    }

    private func loadDetector(modelURL: URL) throws -> VisionDetector {
        do {
            return try VisionDetector(modelURL: modelURL)
        } catch let error as CaptureFailure {
            throw error
        } catch {
            throw CaptureFailure.model(error.localizedDescription)
        }
    }

    private func configureSession(
        _ candidate: AVCaptureSession,
        output frames: AVCaptureVideoDataOutput,
        processor delegate: FrameProcessor,
        camera: AVCaptureDevice
    ) throws {
        candidate.beginConfiguration()

        do {
            let input = try AVCaptureDeviceInput(device: camera)

            guard candidate.canAddInput(input), candidate.canAddOutput(frames) else {
                throw CaptureFailure.configuration
            }

            candidate.addInput(input)
            candidate.addOutput(frames)

            if candidate.canSetSessionPreset(.hd1280x720) {
                candidate.sessionPreset = .hd1280x720
            }

            frames.alwaysDiscardsLateVideoFrames = true
            frames.videoSettings = [
                kCVPixelBufferPixelFormatTypeKey as String: kCVPixelFormatType_32BGRA
            ]
            // The delegate, Vision request and frame renderer share this one serial queue.
            frames.setSampleBufferDelegate(delegate, queue: queue)

            if let connection = frames.connection(with: .video),
                connection.isVideoMirroringSupported
            {
                connection.automaticallyAdjustsVideoMirroring = false
                connection.isVideoMirrored = false
            }

            candidate.commitConfiguration()
        } catch {
            candidate.commitConfiguration()
            frames.setSampleBufferDelegate(nil, queue: nil)
            delegate.finish()
            throw error
        }
    }

    public func stop(runID: UUID) {
        // A cancelled old task must not stop a more recent capture run.
        guard activeRunID == runID else {
            return
        }

        stopActiveRun()
    }

    private func stopActiveRun() {
        // Remove observers first so our deliberate stop cannot become a failure.
        monitor?.invalidate()
        monitor = nil
        session?.stopRunning()
        output?.setSampleBufferDelegate(nil, queue: nil)
        processor?.finish()
        processor = nil
        output = nil
        session = nil
        activeRunID = nil
    }
}

/// AVFoundation invokes this delegate only on CameraService's serial queue.
/// No sample buffer or mutable Vision object crosses into a Task or the UI.
private final class FrameProcessor: NSObject, AVCaptureVideoDataOutputSampleBufferDelegate {
    private let detector: VisionDetector
    private let continuation: FrameStream.Continuation
    private let renderer = CIContext(options: [.cacheIntermediates: false])
    private var finished = false

    init(detector: VisionDetector, continuation: FrameStream.Continuation) {
        self.detector = detector
        self.continuation = continuation
    }

    func finish() {
        guard !finished else {
            return
        }

        finished = true
        continuation.finish()
    }

    func captureOutput(
        _ output: AVCaptureOutput, didOutput sampleBuffer: CMSampleBuffer,
        from connection: AVCaptureConnection
    ) {
        guard !finished, let buffer = CMSampleBufferGetImageBuffer(sampleBuffer) else {
            return
        }

        autoreleasepool {
            do {
                let detections = try detector.predict(buffer)
                let image = CIImage(cvPixelBuffer: buffer)

                guard let pixels = renderer.createCGImage(image, from: image.extent) else {
                    throw CaptureFailure.imageCreation
                }

                continuation.yield(DetectionFrame(image: pixels, detections: detections))
            } catch {
                finished = true
                continuation.finish(throwing: error)
            }
        }
    }
}
02.04

Coloca las predicciones

Vision devuelve coordenadas normalizadas desde la esquina inferior izquierda. Conviértelas a la vista, conserva la proporción y refleja imagen y cuadros juntos.

Fundamentos

OverlayGeometry.project(...)
Proyecta los cuadros de Vision en una vista que conserva la proporción y refleja juntos imagen y cuadros.
Ten en cuenta

Trata tamaño, recorte, orientación y coordenadas como un contrato común. Prueba cuadros conocidos antes de confiar en la superposición.

OverlayGeometry.swiftswift
import CoreGraphics

/// Convert Vision's normalized, bottom-left coordinates to an aspect-fit view.
public enum OverlayGeometry {
    public static func project(
        _ bounds: CGRect, imageSize: CGSize, viewport: CGSize, mirrored: Bool
    ) -> CGRect? {
        guard
            [imageSize.width, imageSize.height, viewport.width, viewport.height].allSatisfy({
                $0.isFinite && $0 > 0
            }),
            [bounds.origin.x, bounds.origin.y, bounds.width, bounds.height].allSatisfy(\.isFinite),
            bounds.width > 0, bounds.height > 0
        else { return nil }
        let clipped = bounds.intersection(CGRect(x: 0, y: 0, width: 1, height: 1))

        guard !clipped.isNull, !clipped.isEmpty else {
            return nil
        }

        let scale = min(viewport.width / imageSize.width, viewport.height / imageSize.height)
        let width = imageSize.width * scale
        let height = imageSize.height * scale

        return CGRect(
            x: (viewport.width - width) / 2 + (mirrored ? 1 - clipped.maxX : clipped.minX) * width,
            y: (viewport.height - height) / 2 + (1 - clipped.maxY) * height,
            width: clipped.width * width, height: clipped.height * height
        )
    }
}
02.05

Compila. Ejecuta. Prueba.

Compila la app local, elige tu detector y pulsa Start camera. Ajusta el umbral de confianza y el reflejo. Detén la captura al terminar.

Fundamentos

CameraController.start()
Solicita permiso de cámara, inicia la captura y actualiza las imágenes correspondientes en MainActor.
CameraController.stop()
Cancela la tarea de interfaz activa y pide al servicio de cámara que detenga esa misma ejecución.
Ten en cuenta
  1. Síntoma
    Reaparecen cuadros antiguos tras detener la cámara o cambiar de modelo.
    Causa
    Una tarea anterior puede terminar tarde; los observadores retenidos pueden mantener recursos activos.
    Solución
    Cancela la ejecución anterior, rechaza resultados obsoletos, detén la captura y elimina observadores. Libera modelos temporales; analiza inicios y paradas repetidos con Instruments.
Terminalbash
./build-app.sh
open ".build/BadBob Playground.app"

02.06 / Buenas prácticas

Pequeños detalles. Mejores ejemplos.

  • Mantén captura e inferencia fuera del hilo de la interfaz. Limita la cola en lugar de acumular fotogramas antiguos.
  • Trata tamaño, recorte, orientación y coordenadas como un contrato común. Prueba cuadros conocidos antes de confiar en la superposición.
  • Gestiona permisos denegados, modelos incompatibles y cancelaciones. Compara predicciones conocidas en el Mac que utilizarás.