BadBob / Playground

Din modell.
Ut i verkligheten.

Gör en tränad modell till något du kan använda. Små exempel med öppen källkod, tydliga steg och kod du kan göra till din egen.

Öppen källkod · MIT · Din modell förblir din

FRÅN MODELL TILL APP
Professor Bob ler och tittar över sina nedhasade läsglasögon bredvid en svart tavla full av avancerad fysik. I ett utsuddat hörn har han skrivit: MODEL = mc² / 10 PRINT "BAD BOB" / 20 GOTO 10.
  1. 01Kamera
  2. 02Modell
  3. 03Prediktion
  4. 04Din app
Illustration · från beräkning till resultat

01 / VÄLJ DIN VÄG

En liten början. Plats att bygga vidare.

Tillgängligt

Swift

En kameraapp för Mac med din Core ML-detektor.

Core ML · macOS
Tillgängligt

Python

Ett skriptspår för att granska modeller och bygga praktiska verktyg.

ONNX Runtime · OpenCV
Tillgängligt

JavaScript

Webbläsarexempel med en ONNX-modell som stöds.

Web · ONNX
Tillgängligt

Rust

Ett inbyggt spår med tydliga krav på modell och körmiljö.

OpenCV · ONNX
Tillgängligt

Go

Praktiska verktyg med ett tydligt gränssnitt till modellkörningen.

GoCV · ONNX
Tillgängligt

C++

Kamera och lokal inferens med OpenCV och en ONNX-modell som stöds.

OpenCV · ONNX

DeviconGo Gopher — Renee FrenchCC BY 3.0

Tänk på
  1. Symtom
    Gränssnittet fryser när kameran startar.
    Orsak
    Sessionsstarten blockerar; async flyttar inte i sig arbetet från MainActor.
    Åtgärd
    Kör kamerafångst och inferens på en egen seriell exekverare. Uppdatera gränssnittet på MainActor.
  2. Symtom
    Förhandsvisningen släpar efter och minnesåtgången ökar.
    Orsak
    Kameran levererar bilder snabbare än inferensen hinner bearbeta dem, så en obegränsad kö växer.
    Åtgärd
    Kasta sena bilder, bearbeta seriellt och behåll bara det senaste väntande resultatet. Undvik en Task per bildruta.
  3. Symtom
    Gamla rutor återkommer efter stopp eller modellbyte.
    Orsak
    En tidigare uppgift kan bli klar för sent; kvarhållna observatörer kan hålla resurser vid liv.
    Åtgärd
    Avbryt den gamla körningen, avvisa inaktuella resultat, stoppa kameran och ta bort observatörer. Frigör tillfälliga modeller; mät upprepade starter och stopp med Instruments.
BadBob / Playground
Core ML · Vision · MIT
02.01

Förbered projektet

Ladda ner källkoden och kör testerna. Du behöver en kamera och en Core ML-objektdetektor som fungerar med Vision. Inga modellvikter ingår.

Grunder

swift test
Kör automatiska kontroller utan att öppna kameran.
Terminalbash
unzip badbob-playground-swift.zip
cd badbob-playground-swift
swift test
02.02

Koppla in din modell

Ladda modellen och skapa en Vision-förfrågan. Kontrollera indata innan kameran startar och behåll eventuell tillfällig kompilering så länge inferensen används.

Grunder

VisionDetector.init(modelURL:)
Laddar eller kompilerar Core ML-modellen och kontrollerar dess bildindata.
VisionDetector.predict(_:)
Förbereder bilden, kör modellen och lämnar tillbaka detektioner.

Exemplet kräver en Core ML-objektdetektor som ger objektobservationer i Vision. Andra modelltyper och ONNX-filer behöver en annan adapter.

Fördjupning

Vision ger normaliserade koordinater från nedre vänstra hörnet. Omvandla dem till vyn, behåll bildens proportioner och spegla bild och rutor tillsammans.

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

Ta in kamerabilden

Fångsten körs på en egen seriell exekverare. Sena bildrutor släpps och bara den senaste bearbetade rutan väntar på gränssnittet. Bild och prediktioner hör ihop.

Grunder

CameraService.start(runID:modelURL:)
Skapar kamerasessionen på sin seriella exekverare och lämnar en ström med högst en väntande bildruta.
CameraService.stop(runID:)
Stoppar bara den matchande körningen och frigör dess session, delegat och observatörer.
Tänk på
  1. Symtom
    Gränssnittet fryser när kameran startar.
    Orsak
    Sessionsstarten blockerar; async flyttar inte i sig arbetet från MainActor.
    Åtgärd
    Kör kamerafångst och inferens på en egen seriell exekverare. Uppdatera gränssnittet på MainActor.
  2. Symtom
    Förhandsvisningen släpar efter och minnesåtgången ökar.
    Orsak
    Kameran levererar bilder snabbare än inferensen hinner bearbeta dem, så en obegränsad kö växer.
    Åtgärd
    Kasta sena bilder, bearbeta seriellt och behåll bara det senaste väntande resultatet. Undvik en Task per bildruta.
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

Placera prediktionerna rätt

Vision ger normaliserade koordinater från nedre vänstra hörnet. Omvandla dem till vyn, behåll bildens proportioner och spegla bild och rutor tillsammans.

Grunder

OverlayGeometry.project(...)
Projicerar Visions rutor till en vy med bevarade bildproportioner och speglar bild och rutor tillsammans.
Tänk på

Se bildstorlek, beskärning, orientering och koordinater som ett gemensamt kontrakt. Testa kända rutor innan du litar på markeringarna.

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. Kör. Prova din modell.

Bygg den lokala appen, välj din detektor och tryck på Start camera. Justera konfidensgränsen och speglingen. Stoppa fångsten när du är klar.

Grunder

CameraController.start()
Ber om kamerabehörighet, startar fångsten och uppdaterar matchande bildrutor på MainActor.
CameraController.stop()
Avbryter den aktiva gränssnittsuppgiften och ber kameratjänsten stoppa samma körning.
Tänk på
  1. Symtom
    Gamla rutor återkommer efter stopp eller modellbyte.
    Orsak
    En tidigare uppgift kan bli klar för sent; kvarhållna observatörer kan hålla resurser vid liv.
    Åtgärd
    Avbryt den gamla körningen, avvisa inaktuella resultat, stoppa kameran och ta bort observatörer. Frigör tillfälliga modeller; mät upprepade starter och stopp med Instruments.
Terminalbash
./build-app.sh
open ".build/BadBob Playground.app"

02.06 / Bra arbetssätt

Små detaljer. Bättre exempel.

  • Håll fångst och inferens borta från gränssnittstråden. Begränsa kön i stället för att samla gamla bildrutor.
  • Se bildstorlek, beskärning, orientering och koordinater som ett gemensamt kontrakt. Testa kända rutor innan du litar på markeringarna.
  • Hantera nekad behörighet, inkompatibla modeller och avbrott. Jämför några kända prediktioner på den Mac du ska använda.