BadBob / Playground

Seu modelo.
No mundo real.

Transforme um modelo treinado em algo útil. Pequenos exemplos de código aberto, etapas claras e código que você pode adaptar à sua ideia.

Código aberto · MIT · Seu modelo continua seu

DO MODELO AO APLICATIVO
O Professor Bob sorri e olha por cima dos óculos de leitura, baixos no nariz, ao lado de um quadro cheio de física complexa. Em um canto apagado, ele escreveu: MODEL = mc² / 10 PRINT "BAD BOB" / 20 GOTO 10.
  1. 01Câmera
  2. 02Modelo
  3. 03Previsão
  4. 04Seu aplicativo
Ilustração · do cálculo ao resultado

01 / ESCOLHA SEU CAMINHO

Um pequeno começo. Espaço para crescer.

Disponível

Swift

Um aplicativo de câmera nativo para Mac com seu detector Core ML.

Core ML · macOS
Disponível

Python

Um caminho com scripts para explorar modelos e criar ferramentas práticas.

ONNX Runtime · OpenCV
Disponível

JavaScript

Exemplos no navegador com um modelo ONNX compatível.

Web · ONNX
Disponível

Rust

Um caminho nativo com requisitos claros de modelo e execução.

OpenCV · ONNX
Disponível

Go

Ferramentas práticas com uma interface clara para executar modelos.

GoCV · ONNX
Disponível

C++

Câmera e inferência local com OpenCV e um modelo ONNX compatível.

OpenCV · ONNX

DeviconGo Gopher — Renee FrenchCC BY 3.0

Vale lembrar
  1. Sintoma
    A interface trava quando a câmera inicia.
    Causa
    A inicialização da sessão é bloqueante; async, por si só, não tira o trabalho de MainActor.
    Solução
    Execute a captura e a inferência em um executor serial dedicado. Atualize a interface em MainActor.
  2. Sintoma
    A prévia fica atrasada e o uso de memória aumenta.
    Causa
    A câmera produz imagens mais rápido do que a inferência consegue processar, criando uma fila sem limite.
    Solução
    Descarte imagens atrasadas, processe em série e mantenha apenas o resultado pendente mais recente. Evite uma Task por imagem.
  3. Sintoma
    As caixas antigas reaparecem após parar ou trocar de modelo.
    Causa
    Uma tarefa anterior pode terminar tarde; observadores retidos podem manter recursos ativos.
    Solução
    Cancele a execução anterior, rejeite resultados desatualizados, pare a captura e remova observadores. Libere modelos temporários; analise inícios e paradas repetidos com Instruments.
BadBob / Playground
Core ML · Vision · MIT
02.01

Prepare o projeto

Baixe o código e execute os testes. Você precisa de uma câmera e de um detector de objetos Core ML compatível com Vision. Os pesos do modelo não estão incluídos.

Fundamentos

swift test
Executa verificações automáticas sem abrir a câmera.
Terminalbash
unzip badbob-playground-swift.zip
cd badbob-playground-swift
swift test
02.02

Conecte seu modelo

Carregue o modelo e crie uma solicitação Vision. Verifique as entradas antes de iniciar a câmera e mantenha qualquer compilação temporária durante toda a inferência.

Fundamentos

VisionDetector.init(modelURL:)
Carrega ou compila o modelo Core ML e valida sua entrada de imagem.
VisionDetector.predict(_:)
Prepara a imagem, executa o modelo e retorna as detecções.

Este exemplo requer um detector de objetos Core ML que retorne observações de objetos Vision. Outros tipos de modelo e arquivos ONNX precisam de outro adaptador.

Aprofundamento

Vision retorna coordenadas normalizadas a partir do canto inferior esquerdo. Converta-as para a visualização, mantenha as proporções e espelhe imagem e caixas juntas.

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

Adicione a câmera

A captura usa seu próprio executor serial. Quadros atrasados são descartados, e só o último quadro processado espera pela interface. Imagem e previsões permanecem juntas.

Fundamentos

CameraService.start(runID:modelURL:)
Cria a sessão de captura no seu executor serial e retorna um fluxo com, no máximo, uma imagem pendente.
CameraService.stop(runID:)
Para apenas a execução correspondente e libera sua sessão, delegado e observadores.
Vale lembrar
  1. Sintoma
    A interface trava quando a câmera inicia.
    Causa
    A inicialização da sessão é bloqueante; async, por si só, não tira o trabalho de MainActor.
    Solução
    Execute a captura e a inferência em um executor serial dedicado. Atualize a interface em MainActor.
  2. Sintoma
    A prévia fica atrasada e o uso de memória aumenta.
    Causa
    A câmera produz imagens mais rápido do que a inferência consegue processar, criando uma fila sem limite.
    Solução
    Descarte imagens atrasadas, processe em série e mantenha apenas o resultado pendente mais recente. Evite uma Task por imagem.
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

Posicione as previsões

Vision retorna coordenadas normalizadas a partir do canto inferior esquerdo. Converta-as para a visualização, mantenha as proporções e espelhe imagem e caixas juntas.

Fundamentos

OverlayGeometry.project(...)
Projeta as caixas Vision em uma visualização que mantém as proporções e espelha a imagem e as caixas em conjunto.
Vale lembrar

Trate tamanho, recorte, orientação e coordenadas como um contrato comum. Teste caixas conhecidas antes de confiar na sobreposição.

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

Compile. Execute. Experimente.

Compile o aplicativo local, escolha o detector e pressione Start camera. Ajuste o limite de confiança e o espelhamento. Pare a captura quando terminar.

Fundamentos

CameraController.start()
Solicita permissão para a câmera, inicia a captura e atualiza as imagens correspondentes no MainActor.
CameraController.stop()
Cancela a tarefa ativa da interface e pede ao serviço de câmera que pare essa mesma execução.
Vale lembrar
  1. Sintoma
    As caixas antigas reaparecem após parar ou trocar de modelo.
    Causa
    Uma tarefa anterior pode terminar tarde; observadores retidos podem manter recursos ativos.
    Solução
    Cancele a execução anterior, rejeite resultados desatualizados, pare a captura e remova observadores. Libere modelos temporários; analise inícios e paradas repetidos com Instruments.
Terminalbash
./build-app.sh
open ".build/BadBob Playground.app"

02.06 / Boas práticas

Pequenos detalhes. Melhores exemplos.

  • Mantenha captura e inferência fora da thread da interface. Limite a fila em vez de acumular quadros antigos.
  • Trate tamanho, recorte, orientação e coordenadas como um contrato comum. Teste caixas conhecidas antes de confiar na sobreposição.
  • Trate permissões negadas, modelos incompatíveis e cancelamentos. Compare previsões conhecidas no Mac que você vai usar.