BadBob / Playground

O teu modelo.
No mundo real.

Transforma um modelo treinado em algo útil. Pequenos exemplos de código aberto, passos claros e código que podes adaptar à tua ideia.

Código aberto · MIT · O modelo continua a ser teu

DO MODELO À APLICAÇÃO
O Professor Bob sorri e olha por cima dos óculos de leitura, descidos no nariz, ao lado de um quadro cheio de física complexa. Num canto apagado, escreveu: MODEL = mc² / 10 PRINT "BAD BOB" / 20 GOTO 10.
  1. 01Câmara
  2. 02Modelo
  3. 03Previsão
  4. 04A tua aplicação
Ilustração · do cálculo ao resultado

01 / ESCOLHE O TEU CAMINHO

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

Disponível

Swift

Uma aplicação de câmara nativa para Mac com o teu detetor Core ML.

Core ML · macOS
Disponível

Python

Um percurso com scripts para explorar modelos e criar ferramentas úteis.

ONNX Runtime · OpenCV
Disponível

JavaScript

Exemplos no navegador com um modelo ONNX compatível.

Web · ONNX
Disponível

Rust

Um percurso 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âmara e inferência local com OpenCV e um modelo ONNX compatível.

OpenCV · ONNX

DeviconGo Gopher — Renee FrenchCC BY 3.0

A ter em conta
  1. Sintoma
    A interface bloqueia quando a câmara inicia.
    Causa
    O arranque da sessão é bloqueante; async, por si só, não retira o trabalho de MainActor.
    Solução
    Executa a captura e a inferência num executor série dedicado. Atualiza a interface em MainActor.
  2. Sintoma
    A pré-visualização atrasa-se e o uso de memória aumenta.
    Causa
    A câmara produz imagens mais depressa do que a inferência as processa, criando uma fila sem limite.
    Solução
    Descarta imagens atrasadas, processa em série e mantém apenas o resultado pendente mais recente. Evita uma Task por imagem.
  3. Sintoma
    As caixas antigas reaparecem após parar ou mudar de modelo.
    Causa
    Uma tarefa anterior pode terminar tarde; observadores retidos podem manter recursos ativos.
    Solução
    Cancela a execução anterior, rejeita resultados desatualizados, para a captura e remove observadores. Liberta modelos temporários; analisa arranques e paragens repetidos com Instruments.
BadBob / Playground
Core ML · Vision · MIT
02.01

Prepara o projeto

Transfere o código e executa os testes. Precisas de uma câmara e de um detetor 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âmara.
Terminalbash
unzip badbob-playground-swift.zip
cd badbob-playground-swift
swift test
02.02

Liga o teu modelo

Carrega o modelo e cria um pedido Vision. Verifica as entradas antes de iniciares a câmara e mantém qualquer compilação temporária durante toda a inferência.

Fundamentos

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

Este exemplo requer um detetor de objetos Core ML que devolva observações de objetos Vision. Outros tipos de modelo e ficheiros ONNX precisam de outro adaptador.

Aprofundamento

Vision devolve coordenadas normalizadas a partir do canto inferior esquerdo. Converte-as para a vista, mantém as proporções e espelha imagem e caixas em conjunto.

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

Adiciona a câmara

A captura usa um executor série próprio. Os fotogramas atrasados são descartados e só o mais recente processado espera pela interface. Imagem e previsões mantêm-se juntas.

Fundamentos

CameraService.start(runID:modelURL:)
Cria a sessão de captura no seu executor série e devolve um fluxo com, no máximo, uma imagem em espera.
CameraService.stop(runID:)
Para apenas a execução correspondente e liberta a sessão, o delegado e os observadores.
A ter em conta
  1. Sintoma
    A interface bloqueia quando a câmara inicia.
    Causa
    O arranque da sessão é bloqueante; async, por si só, não retira o trabalho de MainActor.
    Solução
    Executa a captura e a inferência num executor série dedicado. Atualiza a interface em MainActor.
  2. Sintoma
    A pré-visualização atrasa-se e o uso de memória aumenta.
    Causa
    A câmara produz imagens mais depressa do que a inferência as processa, criando uma fila sem limite.
    Solução
    Descarta imagens atrasadas, processa em série e mantém apenas o resultado pendente mais recente. Evita 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

Posiciona as previsões

Vision devolve coordenadas normalizadas a partir do canto inferior esquerdo. Converte-as para a vista, mantém as proporções e espelha imagem e caixas em conjunto.

Fundamentos

OverlayGeometry.project(...)
Projeta as caixas Vision numa vista que mantém as proporções e espelha a imagem e as caixas em conjunto.
A ter em conta

Trata tamanho, recorte, orientação e coordenadas como um contrato comum. Testa caixas conhecidas antes de confiares 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

Compila. Executa. Experimenta.

Compila a aplicação local, escolhe o detetor e prime Start camera. Ajusta o limiar de confiança e o espelhamento. Para a captura quando terminares.

Fundamentos

CameraController.start()
Pede permissão para a câmara, 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âmara que pare essa mesma execução.
A ter em conta
  1. Sintoma
    As caixas antigas reaparecem após parar ou mudar de modelo.
    Causa
    Uma tarefa anterior pode terminar tarde; observadores retidos podem manter recursos ativos.
    Solução
    Cancela a execução anterior, rejeita resultados desatualizados, para a captura e remove observadores. Liberta modelos temporários; analisa arranques e paragens repetidos com Instruments.
Terminalbash
./build-app.sh
open ".build/BadBob Playground.app"

02.06 / Boas práticas

Pequenos detalhes. Melhores exemplos.

  • Mantém a captura e a inferência fora da thread da interface. Limita a fila em vez de acumulares fotogramas antigos.
  • Trata tamanho, recorte, orientação e coordenadas como um contrato comum. Testa caixas conhecidas antes de confiares na sobreposição.
  • Gere permissões recusadas, modelos incompatíveis e cancelamentos. Compara previsões conhecidas no Mac que vais usar.