BadBob / Playground

Votre modèle.
Dans le monde réel.

Transformez un modèle entraîné en outil concret. De petits exemples open source, des étapes claires et du code à adapter à vos idées.

Open source · MIT · Votre modèle reste le vôtre

DU MODÈLE À L’APPLICATION
Le professeur Bob sourit en regardant par-dessus ses lunettes de lecture baissées sur le nez, à côté d’un tableau couvert de physique complexe. Dans un coin effacé, il a écrit : MODEL = mc² / 10 PRINT "BAD BOB" / 20 GOTO 10.
  1. 01Caméra
  2. 02Modèle
  3. 03Prédiction
  4. 04Votre app
Illustration · du calcul au résultat

01 / CHOISISSEZ VOTRE PARCOURS

Un petit début. De quoi aller plus loin.

Disponible

Swift

Une app caméra native pour Mac avec votre détecteur Core ML.

Core ML · macOS
Disponible

Python

Un parcours en scripts pour examiner les modèles et créer des outils utiles.

ONNX Runtime · OpenCV
Disponible

JavaScript

Des exemples navigateur avec un modèle ONNX compatible.

Web · ONNX
Disponible

Rust

Un parcours natif avec des exigences explicites de modèle et d’exécution.

OpenCV · ONNX
Disponible

Go

Des outils pratiques avec une interface claire vers l’exécution du modèle.

GoCV · ONNX
Disponible

C++

Caméra et inférence locale avec OpenCV et un modèle ONNX compatible.

OpenCV · ONNX

DeviconGo Gopher — Renee FrenchCC BY 3.0

À garder en tête
  1. Symptôme
    L’interface se fige au démarrage de la caméra.
    Cause
    Le démarrage de la session est bloquant ; async seul ne déplace pas le travail hors de MainActor.
    Solution
    Exécutez la capture et l’inférence sur un exécuteur série dédié. Mettez l’interface à jour sur MainActor.
  2. Symptôme
    L’aperçu prend du retard et la mémoire utilisée augmente.
    Cause
    La caméra produit des images plus vite que l’inférence ne les traite, ce qui fait grossir une file sans limite.
    Solution
    Écartez les images en retard, traitez en série et ne gardez que le résultat en attente le plus récent. Évitez une Task par image.
  3. Symptôme
    D’anciens cadres réapparaissent après un arrêt ou un changement de modèle.
    Cause
    Une tâche précédente peut se terminer tard ; des observateurs conservés peuvent maintenir des ressources en mémoire.
    Solution
    Annulez l’ancienne exécution, rejetez les résultats périmés, arrêtez la capture et retirez les observateurs. Libérez les modèles temporaires ; analysez les démarrages et arrêts répétés avec Instruments.
BadBob / Playground
Core ML · Vision · MIT

02 / Swift Core ML + Vision

Créez quelque chose qui voit.

Un exemple Swift complet : choisissez votre modèle, démarrez la caméra et dessinez les prédictions correspondantes. Suivez les étapes ou explorez tout le code source.

Ces exemples portent sur des objets et des animaux dans un cadre maîtrisé. Ils ne traitent pas de surveillance de personnes, d’identification ni d’analyse des comportements.

02.01

Préparer le projet

Téléchargez le code source et lancez ses tests. Il vous faut une caméra et un détecteur d’objets Core ML compatible avec Vision. Aucun poids de modèle n’est fourni.

Les bases

swift test
Exécute les vérifications automatiques sans ouvrir la caméra.
Terminalbash
unzip badbob-playground-swift.zip
cd badbob-playground-swift
swift test
02.02

Connecter votre modèle

Chargez le modèle et créez une requête Vision. Vérifiez les entrées avant de démarrer la caméra et conservez toute compilation temporaire pendant l’inférence.

Les bases

VisionDetector.init(modelURL:)
Charge ou compile le modèle Core ML et valide son entrée image.
VisionDetector.predict(_:)
Prépare l’image, exécute le modèle et renvoie les détections.

Cet exemple nécessite un détecteur d’objets Core ML qui renvoie des observations d’objets Vision. Les autres types de modèles et les fichiers ONNX nécessitent un autre adaptateur.

Pour approfondir

Vision fournit des coordonnées normalisées depuis le bas à gauche. Convertissez-les vers votre vue, conservez les proportions et inversez ensemble l’image et les cadres.

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

Ajouter la caméra

La capture utilise son propre exécuteur série. Les images en retard sont abandonnées ; seule la dernière image traitée attend l’interface. Pixels et prédictions restent associés.

Les bases

CameraService.start(runID:modelURL:)
Crée la session de capture sur son exécuteur sériel et renvoie un flux contenant au plus une image en attente.
CameraService.stop(runID:)
Arrête uniquement l’exécution correspondante et libère sa session, son délégué et ses observateurs.
À garder en tête
  1. Symptôme
    L’interface se fige au démarrage de la caméra.
    Cause
    Le démarrage de la session est bloquant ; async seul ne déplace pas le travail hors de MainActor.
    Solution
    Exécutez la capture et l’inférence sur un exécuteur série dédié. Mettez l’interface à jour sur MainActor.
  2. Symptôme
    L’aperçu prend du retard et la mémoire utilisée augmente.
    Cause
    La caméra produit des images plus vite que l’inférence ne les traite, ce qui fait grossir une file sans limite.
    Solution
    Écartez les images en retard, traitez en série et ne gardez que le résultat en attente le plus récent. Évitez une Task par image.
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

Placer les prédictions

Vision fournit des coordonnées normalisées depuis le bas à gauche. Convertissez-les vers votre vue, conservez les proportions et inversez ensemble l’image et les cadres.

Les bases

OverlayGeometry.project(...)
Projette les boîtes Vision dans une vue conservant les proportions et reflète ensemble l’image et les boîtes.
À garder en tête

Traitez taille, recadrage, orientation et coordonnées comme un contrat commun. Testez des cadres connus avant de vous fier à l’affichage.

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

Compiler. Lancer. Essayer.

Compilez l’app locale, choisissez votre détecteur et cliquez sur Start camera. Ajustez le seuil de confiance et le miroir. Arrêtez la capture quand vous avez terminé.

Les bases

CameraController.start()
Demande l’accès à la caméra, démarre la capture et met à jour les images correspondantes sur MainActor.
CameraController.stop()
Annule la tâche d’interface active et demande au service caméra d’arrêter cette même exécution.
À garder en tête
  1. Symptôme
    D’anciens cadres réapparaissent après un arrêt ou un changement de modèle.
    Cause
    Une tâche précédente peut se terminer tard ; des observateurs conservés peuvent maintenir des ressources en mémoire.
    Solution
    Annulez l’ancienne exécution, rejetez les résultats périmés, arrêtez la capture et retirez les observateurs. Libérez les modèles temporaires ; analysez les démarrages et arrêts répétés avec Instruments.
Terminalbash
./build-app.sh
open ".build/BadBob Playground.app"

02.06 / Bonnes pratiques

Petits détails. Meilleurs exemples.

  • Gardez capture et inférence hors du thread de l’interface. Limitez la file au lieu d’accumuler d’anciennes images.
  • Traitez taille, recadrage, orientation et coordonnées comme un contrat commun. Testez des cadres connus avant de vous fier à l’affichage.
  • Gérez le refus d’accès, les modèles incompatibles et l’annulation. Comparez quelques prédictions connues sur le Mac utilisé.