BadBob / Playground

Din model.
Ud i virkeligheden.

Gør en trænet model til noget, du kan bruge. Små eksempler med åben kildekode, tydelige trin og kode, du kan gøre til din egen.

Åben kildekode · MIT · Din model er stadig din

FRA MODEL TIL APP
Professor Bob smiler og kigger over sine læsebriller, der sidder langt nede på næsen, ved siden af en tavle fyldt med kompleks fysik. I et udvisket hjørne har han skrevet: MODEL = mc² / 10 PRINT "BAD BOB" / 20 GOTO 10.
  1. 01Kamera
  2. 02Model
  3. 03Forudsigelse
  4. 04Din app
Illustration · fra beregning til resultat

01 / VÆLG DIN VEJ

En lille begyndelse. Plads til at bygge videre.

Tilgængelig

Swift

En indbygget kameraapp til Mac med din Core ML-detektor.

Core ML · macOS
Tilgængelig

Python

Et scriptspor til at undersøge modeller og bygge praktiske værktøjer.

ONNX Runtime · OpenCV
Tilgængelig

JavaScript

Browsereksempler med en understøttet ONNX-model.

Web · ONNX
Tilgængelig

Rust

Et indbygget spor med tydelige krav til model og kørselsmiljø.

OpenCV · ONNX
Tilgængelig

Go

Praktiske værktøjer med en klar grænseflade til modelkørsel.

GoCV · ONNX
Tilgængelig

C++

Kamera og lokal inferens med OpenCV og en understøttet ONNX-model.

OpenCV · ONNX

DeviconGo Gopher — Renee FrenchCC BY 3.0

Husk
  1. Symptom
    Brugerfladen fryser, når kameraet starter.
    Årsag
    Sessionsstart blokerer; async flytter ikke i sig selv arbejdet væk fra MainActor.
    Løsning
    Kør optagelse og inferens på en separat seriel executor. Opdater brugerfladen på MainActor.
  2. Symptom
    Forhåndsvisningen halter, og hukommelsesforbruget stiger.
    Årsag
    Kameraet leverer billeder hurtigere, end inferensen behandler dem, så en ubegrænset kø vokser.
    Løsning
    Kassér forsinkede billeder, behandl serielt, og behold kun det nyeste ventende resultat. Undgå en Task pr. billede.
  3. Symptom
    Gamle bokse vender tilbage efter stop eller modelskift.
    Årsag
    En tidligere opgave kan afsluttes sent; bevarede observatører kan holde ressourcer i live.
    Løsning
    Annuller den gamle kørsel, afvis forældede resultater, stop optagelsen, og fjern observatører. Frigiv midlertidige modeller; mål gentagne starter og stop med Instruments.
BadBob / Playground
Core ML · Vision · MIT
02.01

Forbered projektet

Hent kildekoden, og kør testene. Du skal bruge et kamera og en Core ML-objektdetektor, der virker med Vision. Modelvægte medfølger ikke.

Grundlag

swift test
Kører automatiske kontroller uden at åbne kameraet.
Terminalbash
unzip badbob-playground-swift.zip
cd badbob-playground-swift
swift test
02.02

Tilslut din model

Indlæs modellen, og opret en Vision-anmodning. Kontrollér input, før kameraet starter, og behold midlertidige kompileringer, så længe inferensen bruger dem.

Grundlag

VisionDetector.init(modelURL:)
Indlæser eller kompilerer Core ML-modellen og kontrollerer dens billedinput.
VisionDetector.predict(_:)
Forbereder billedet, kører modellen og returnerer detektioner.

Eksemplet kræver en Core ML-objektdetektor, der returnerer objektobservationer i Vision. Andre modeltyper og ONNX-filer kræver en anden adapter.

Fordybelse

Vision giver normaliserede koordinater fra nederste venstre hjørne. Omregn dem til visningen, bevar proportionerne, og spejl billede og bokse 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

Tilføj kameraet

Optagelsen kører på sin egen serielle eksekutor. Forsinkede billeder droppes, og kun det seneste behandlede billede venter på grænsefladen. Billede og forudsigelser følges ad.

Grundlag

CameraService.start(runID:modelURL:)
Opretter kamerasessionen på sin serielle eksekverer og returnerer en strøm med højst ét ventende billede.
CameraService.stop(runID:)
Stopper kun den matchende kørsel og frigiver dens session, delegat og observatører.
Husk
  1. Symptom
    Brugerfladen fryser, når kameraet starter.
    Årsag
    Sessionsstart blokerer; async flytter ikke i sig selv arbejdet væk fra MainActor.
    Løsning
    Kør optagelse og inferens på en separat seriel executor. Opdater brugerfladen på MainActor.
  2. Symptom
    Forhåndsvisningen halter, og hukommelsesforbruget stiger.
    Årsag
    Kameraet leverer billeder hurtigere, end inferensen behandler dem, så en ubegrænset kø vokser.
    Løsning
    Kassér forsinkede billeder, behandl serielt, og behold kun det nyeste ventende resultat. Undgå en Task pr. billede.
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

Placér forudsigelserne

Vision giver normaliserede koordinater fra nederste venstre hjørne. Omregn dem til visningen, bevar proportionerne, og spejl billede og bokse sammen.

Grundlag

OverlayGeometry.project(...)
Projicerer Visions bokse til en visning med bevarede proportioner og spejler billede og bokse sammen.
Husk

Se billedstørrelse, beskæring, retning og koordinater som én aftale. Test kendte bokse, før du stoler på markeringerne.

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

Byg. Kør. Prøv din model.

Byg den lokale app, vælg din detektor, og tryk på Start camera. Justér konfidensgrænsen og spejlingen. Stop optagelsen, når du er færdig.

Grundlag

CameraController.start()
Beder om kameratilladelse, starter optagelsen og opdaterer matchende billeder på MainActor.
CameraController.stop()
Annullerer den aktive grænsefladeopgave og beder kameratjenesten stoppe samme kørsel.
Husk
  1. Symptom
    Gamle bokse vender tilbage efter stop eller modelskift.
    Årsag
    En tidligere opgave kan afsluttes sent; bevarede observatører kan holde ressourcer i live.
    Løsning
    Annuller den gamle kørsel, afvis forældede resultater, stop optagelsen, og fjern observatører. Frigiv midlertidige modeller; mål gentagne starter og stop med Instruments.
Terminalbash
./build-app.sh
open ".build/BadBob Playground.app"

02.06 / Gode arbejdsgange

Små detaljer. Bedre eksempler.

  • Hold optagelse og inferens væk fra grænsefladens tråd. Begræns køen i stedet for at samle gamle billeder.
  • Se billedstørrelse, beskæring, retning og koordinater som én aftale. Test kendte bokse, før du stoler på markeringerne.
  • Håndtér afvist tilladelse, inkompatible modeller og afbrydelser. Sammenlign kendte forudsigelser på den Mac, du skal bruge.