BadBob / Playground

Jouw model.
In de echte wereld.

Maak iets bruikbaars van een getraind model. Kleine opensourcevoorbeelden, duidelijke stappen en code die je zelf kunt aanpassen.

Open source · MIT · Jouw model blijft van jou

VAN MODEL NAAR APP
Professor Bob glimlacht en kijkt over zijn laag op de neus gezakte leesbril, naast een schoolbord vol complexe natuurkunde. In een uitgeveegde hoek heeft hij geschreven: MODEL = mc² / 10 PRINT "BAD BOB" / 20 GOTO 10.
  1. 01Camera
  2. 02Model
  3. 03Voorspelling
  4. 04Jouw app
Illustratie · van berekening naar resultaat

01 / KIES JE ROUTE

Een klein begin. Ruimte om verder te bouwen.

Beschikbaar

Swift

Een native camera-app voor Mac met jouw Core ML-detector.

Core ML · macOS
Beschikbaar

Python

Een scripttraject om modellen te onderzoeken en handige tools te bouwen.

ONNX Runtime · OpenCV
Beschikbaar

JavaScript

Browservoorbeelden met een ondersteund ONNX-model.

Web · ONNX
Beschikbaar

Rust

Een native traject met duidelijke eisen aan model en runtime.

OpenCV · ONNX
Beschikbaar

Go

Praktische tools met een duidelijke interface voor het uitvoeren van modellen.

GoCV · ONNX
Beschikbaar

C++

Camera en lokale inferentie met OpenCV en een ondersteund ONNX-model.

OpenCV · ONNX

DeviconGo Gopher — Renee FrenchCC BY 3.0

Goed om te weten
  1. Symptoom
    De interface bevriest wanneer de camera start.
    Oorzaak
    Het starten van de sessie blokkeert; async alleen verplaatst het werk niet van MainActor.
    Oplossing
    Voer opname en inferentie uit op een eigen seriële executor. Werk de interface bij op MainActor.
  2. Symptoom
    De voorvertoning loopt achter en het geheugengebruik groeit.
    Oorzaak
    De camera levert beelden sneller aan dan de inferentie ze verwerkt, waardoor een onbeperkte wachtrij groeit.
    Oplossing
    Sla late beelden over, verwerk serieel en bewaar alleen het nieuwste wachtende resultaat. Vermijd een Task per beeld.
  3. Symptoom
    Oude kaders verschijnen opnieuw na stoppen of wisselen van model.
    Oorzaak
    Een eerdere taak kan laat eindigen; vastgehouden observers kunnen resources in gebruik houden.
    Oplossing
    Annuleer de oude uitvoering, verwerp verouderde resultaten, stop de opname en verwijder observers. Geef tijdelijke modellen vrij; analyseer herhaald starten en stoppen met Instruments.
BadBob / Playground
Core ML · Vision · MIT
02.01

Bereid je project voor

Download de broncode en voer de tests uit. Je hebt een camera en een Vision-compatibele Core ML-objectdetector nodig. Modelgewichten zijn niet inbegrepen.

De basis

swift test
Voert automatische controles uit zonder de camera te openen.
Terminalbash
unzip badbob-playground-swift.zip
cd badbob-playground-swift
swift test
02.02

Koppel je model

Laad je model en maak een Vision-verzoek. Controleer de invoer voordat de camera start en bewaar tijdelijke compilaties zolang de inferentie ze gebruikt.

De basis

VisionDetector.init(modelURL:)
Laadt of compileert het Core ML-model en controleert de afbeeldingsinvoer.
VisionDetector.predict(_:)
Bereidt de afbeelding voor, voert het model uit en geeft detecties terug.

Dit voorbeeld vereist een Core ML-objectdetector die Vision-objectwaarnemingen teruggeeft. Andere modeltypen en ONNX-bestanden hebben een andere adapter nodig.

Verdieping

Vision geeft genormaliseerde coördinaten vanaf linksonder. Zet ze om naar de weergave, behoud de beeldverhouding en spiegel beeld en kaders samen.

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

Voeg de camera toe

De opname draait op een eigen seriële executor. Late frames worden overgeslagen; alleen het nieuwste verwerkte frame wacht op de interface. Beeld en voorspellingen blijven samen.

De basis

CameraService.start(runID:modelURL:)
Maakt de opnamesessie op de eigen seriële executor en geeft een stream met hoogstens één wachtend beeld terug.
CameraService.stop(runID:)
Stopt alleen de bijbehorende uitvoering en geeft de sessie, delegate en waarnemers vrij.
Goed om te weten
  1. Symptoom
    De interface bevriest wanneer de camera start.
    Oorzaak
    Het starten van de sessie blokkeert; async alleen verplaatst het werk niet van MainActor.
    Oplossing
    Voer opname en inferentie uit op een eigen seriële executor. Werk de interface bij op MainActor.
  2. Symptoom
    De voorvertoning loopt achter en het geheugengebruik groeit.
    Oorzaak
    De camera levert beelden sneller aan dan de inferentie ze verwerkt, waardoor een onbeperkte wachtrij groeit.
    Oplossing
    Sla late beelden over, verwerk serieel en bewaar alleen het nieuwste wachtende resultaat. Vermijd een Task per beeld.
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

Plaats de voorspellingen

Vision geeft genormaliseerde coördinaten vanaf linksonder. Zet ze om naar de weergave, behoud de beeldverhouding en spiegel beeld en kaders samen.

De basis

OverlayGeometry.project(...)
Projecteert Vision-kaders naar een beeldverhoudingbehoudende weergave en spiegelt beeld en kaders samen.
Goed om te weten

Behandel beeldformaat, uitsnede, oriëntatie en coördinaten als één contract. Test bekende kaders voordat je op de markeringen vertrouwt.

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

Bouw. Start. Probeer je model.

Bouw de lokale app, kies je detector en druk op Start camera. Pas de betrouwbaarheidsdrempel en spiegeling aan. Stop de opname als je klaar bent.

De basis

CameraController.start()
Vraagt cameratoestemming, start de opname en werkt bijbehorende beelden bij op MainActor.
CameraController.stop()
Annuleert de actieve UI-taak en vraagt de cameraservice om dezelfde uitvoering te stoppen.
Goed om te weten
  1. Symptoom
    Oude kaders verschijnen opnieuw na stoppen of wisselen van model.
    Oorzaak
    Een eerdere taak kan laat eindigen; vastgehouden observers kunnen resources in gebruik houden.
    Oplossing
    Annuleer de oude uitvoering, verwerp verouderde resultaten, stop de opname en verwijder observers. Geef tijdelijke modellen vrij; analyseer herhaald starten en stoppen met Instruments.
Terminalbash
./build-app.sh
open ".build/BadBob Playground.app"

02.06 / Goede werkwijzen

Kleine details. Betere voorbeelden.

  • Houd opname en inferentie buiten de UI-thread. Begrens de wachtrij in plaats van oude frames op te stapelen.
  • Behandel beeldformaat, uitsnede, oriëntatie en coördinaten als één contract. Test bekende kaders voordat je op de markeringen vertrouwt.
  • Verwerk geweigerde toestemming, ongeschikte modellen en annulering. Vergelijk bekende voorspellingen op de Mac die je gaat gebruiken.