BadBob / Playground

Modellen din.
Ut i virkeligheten.

Gjør en trent modell til noe du kan bruke. Små eksempler med åpen kildekode, tydelige steg og kode du kan gjøre til din egen.

Åpen kildekode · MIT · Modellen din forblir din

FRA MODELL TIL APP
Professor Bob smiler og ser over lesebrillene som sitter langt nede på nesen, ved siden av en tavle full av kompleks fysikk. I et utvisket hjørne har han skrevet: MODEL = mc² / 10 PRINT "BAD BOB" / 20 GOTO 10.
  1. 01Kamera
  2. 02Modell
  3. 03Prediksjon
  4. 04Appen din
Illustrasjon · fra beregning til resultat

01 / VELG DIN VEI

En liten begynnelse. Rom for å bygge videre.

Tilgjengelig

Swift

En innebygd kameraapp for Mac med Core ML-detektoren din.

Core ML · macOS
Tilgjengelig

Python

Et skriptspor for å undersøke modeller og bygge nyttige verktøy.

ONNX Runtime · OpenCV
Tilgjengelig

JavaScript

Nettlesereksempler med en støttet ONNX-modell.

Web · ONNX
Tilgjengelig

Rust

Et innebygd spor med tydelige krav til modell og kjøremiljø.

OpenCV · ONNX
Tilgjengelig

Go

Praktiske verktøy med et tydelig grensesnitt til modellkjøring.

GoCV · ONNX
Tilgjengelig

C++

Kamera og lokal inferens med OpenCV og en støttet ONNX-modell.

OpenCV · ONNX

DeviconGo Gopher — Renee FrenchCC BY 3.0

Husk
  1. Symptom
    Grensesnittet fryser når kameraet starter.
    Årsak
    Oppstart av økten blokkerer; async flytter ikke i seg selv arbeidet bort fra MainActor.
    Tiltak
    Kjør opptak og inferens på en egen seriell eksekutor. Oppdater grensesnittet på MainActor.
  2. Symptom
    Forhåndsvisningen henger etter, og minnebruken øker.
    Årsak
    Kameraet leverer bilder raskere enn inferensen behandler dem, slik at en ubegrenset kø vokser.
    Tiltak
    Forkast forsinkede bilder, behandle serielt og behold bare det nyeste ventende resultatet. Unngå en Task per bilde.
  3. Symptom
    Gamle bokser kommer tilbake etter stopp eller modellbytte.
    Årsak
    En tidligere oppgave kan bli ferdig sent; beholdte observatører kan holde ressurser i live.
    Tiltak
    Avbryt den gamle kjøringen, avvis utdaterte resultater, stopp opptaket og fjern observatører. Frigjør midlertidige modeller; mål gjentatte starter og stopp med Instruments.
BadBob / Playground
Core ML · Vision · MIT
02.01

Forbered prosjektet

Last ned kildekoden og kjør testene. Du trenger et kamera og en Core ML-objektdetektor som virker med Vision. Modellvekter følger ikke med.

Grunnlag

swift test
Kjører automatiske kontroller uten å åpne kameraet.
Terminalbash
unzip badbob-playground-swift.zip
cd badbob-playground-swift
swift test
02.02

Koble til modellen

Last inn modellen og opprett en Vision-forespørsel. Kontroller inndata før kameraet starter, og behold midlertidige kompileringer så lenge inferensen bruker dem.

Grunnlag

VisionDetector.init(modelURL:)
Laster eller kompilerer Core ML-modellen og kontrollerer bildeinndataene.
VisionDetector.predict(_:)
Klargjør bildet, kjører modellen og returnerer deteksjoner.

Eksemplet krever en Core ML-objektdetektor som returnerer objektobservasjoner i Vision. Andre modelltyper og ONNX-filer trenger en annen adapter.

Fordypning

Vision gir normaliserte koordinater fra nedre venstre hjørne. Omregn dem til visningen, behold proporsjonene og speil bilde og bokser sammen.

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

Legg til kameraet

Opptaket kjører på sin egen serielle eksekutor. Forsinkede bilder droppes, og bare det nyeste behandlede bildet venter på grensesnittet. Bilde og prediksjoner hører sammen.

Grunnlag

CameraService.start(runID:modelURL:)
Oppretter kameraøkten på sin serielle eksekverer og returnerer en strøm med høyst ett ventende bilde.
CameraService.stop(runID:)
Stopper bare den tilhørende kjøringen og frigjør økten, delegaten og observatørene.
Husk
  1. Symptom
    Grensesnittet fryser når kameraet starter.
    Årsak
    Oppstart av økten blokkerer; async flytter ikke i seg selv arbeidet bort fra MainActor.
    Tiltak
    Kjør opptak og inferens på en egen seriell eksekutor. Oppdater grensesnittet på MainActor.
  2. Symptom
    Forhåndsvisningen henger etter, og minnebruken øker.
    Årsak
    Kameraet leverer bilder raskere enn inferensen behandler dem, slik at en ubegrenset kø vokser.
    Tiltak
    Forkast forsinkede bilder, behandle serielt og behold bare det nyeste ventende resultatet. Unngå en Task per bilde.
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

Plasser prediksjonene

Vision gir normaliserte koordinater fra nedre venstre hjørne. Omregn dem til visningen, behold proporsjonene og speil bilde og bokser sammen.

Grunnlag

OverlayGeometry.project(...)
Projiserer Visions bokser til en visning med bevarte proporsjoner og speiler bilde og bokser sammen.
Husk

Se bildestørrelse, beskjæring, retning og koordinater som én avtale. Test kjente bokser før du stoler på markeringene.

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

Bygg. Kjør. Prøv modellen.

Bygg den lokale appen, velg detektoren og trykk Start camera. Juster konfidensgrensen og speilingen. Stopp opptaket når du er ferdig.

Grunnlag

CameraController.start()
Ber om kameratillatelse, starter opptaket og oppdaterer tilhørende bilder på MainActor.
CameraController.stop()
Avbryter den aktive grensesnittoppgaven og ber kameratjenesten stoppe samme kjøring.
Husk
  1. Symptom
    Gamle bokser kommer tilbake etter stopp eller modellbytte.
    Årsak
    En tidligere oppgave kan bli ferdig sent; beholdte observatører kan holde ressurser i live.
    Tiltak
    Avbryt den gamle kjøringen, avvis utdaterte resultater, stopp opptaket og fjern observatører. Frigjør midlertidige modeller; mål gjentatte starter og stopp med Instruments.
Terminalbash
./build-app.sh
open ".build/BadBob Playground.app"

02.06 / Gode arbeidsmåter

Små detaljer. Bedre eksempler.

  • Hold opptak og inferens borte fra grensesnitttråden. Begrens køen i stedet for å samle gamle bilder.
  • Se bildestørrelse, beskjæring, retning og koordinater som én avtale. Test kjente bokser før du stoler på markeringene.
  • Håndter avvist tillatelse, inkompatible modeller og avbrudd. Sammenlign kjente prediksjoner på Macen du skal bruke.