BadBob / Playground

Il tuo modello.
Nel mondo reale.

Trasforma un modello addestrato in qualcosa di utile. Piccoli esempi open source, passaggi chiari e codice da adattare alle tue idee.

Open source · MIT · Il modello resta tuo

DAL MODELLO ALL’APP
Il professor Bob sorride e guarda sopra gli occhiali da lettura abbassati sul naso, accanto a una lavagna piena di fisica complessa. In un angolo cancellato ha scritto: MODEL = mc² / 10 PRINT "BAD BOB" / 20 GOTO 10.
  1. 01Fotocamera
  2. 02Modello
  3. 03Previsione
  4. 04La tua app
Illustrazione · dal calcolo al risultato

01 / SCEGLI IL PERCORSO

Un piccolo inizio. Spazio per crescere.

Disponibile

Swift

Un’app fotocamera nativa per Mac con il tuo rilevatore Core ML.

Core ML · macOS
Disponibile

Python

Un percorso con script per esaminare modelli e creare strumenti pratici.

ONNX Runtime · OpenCV
Disponibile

JavaScript

Esempi nel browser con un modello ONNX compatibile.

Web · ONNX
Disponibile

Rust

Un percorso nativo con requisiti chiari per modello e ambiente.

OpenCV · ONNX
Disponibile

Go

Strumenti pratici con un’interfaccia chiara verso l’esecuzione del modello.

GoCV · ONNX
Disponibile

C++

Fotocamera e inferenza locale con OpenCV e un modello ONNX compatibile.

OpenCV · ONNX

DeviconGo Gopher — Renee FrenchCC BY 3.0

Da ricordare
  1. Sintomo
    L’interfaccia si blocca quando si avvia la fotocamera.
    Causa
    L’avvio della sessione è bloccante; async da solo non sposta il lavoro fuori da MainActor.
    Rimedio
    Esegui acquisizione e inferenza su un executor seriale dedicato. Aggiorna l’interfaccia su MainActor.
  2. Sintomo
    L’anteprima resta indietro e l’uso della memoria aumenta.
    Causa
    La fotocamera produce immagini più velocemente di quanto l’inferenza le elabori, creando una coda senza limite.
    Rimedio
    Scarta i fotogrammi in ritardo, elabora in serie e conserva solo il risultato in attesa più recente. Evita una Task per fotogramma.
  3. Sintomo
    I vecchi riquadri ricompaiono dopo uno stop o un cambio di modello.
    Causa
    Un’attività precedente può finire in ritardo; gli osservatori trattenuti possono mantenere attive le risorse.
    Rimedio
    Annulla l’esecuzione precedente, scarta i risultati obsoleti, ferma l’acquisizione e rimuovi gli osservatori. Rilascia i modelli temporanei; analizza avvii e arresti ripetuti con Instruments.
BadBob / Playground
Core ML · Vision · MIT
02.01

Prepara il progetto

Scarica il codice ed esegui i test. Servono una fotocamera e un rilevatore di oggetti Core ML compatibile con Vision. I pesi del modello non sono inclusi.

Le basi

swift test
Esegue i controlli automatici senza aprire la fotocamera.
Terminalbash
unzip badbob-playground-swift.zip
cd badbob-playground-swift
swift test
02.02

Collega il modello

Carica il modello e crea una richiesta Vision. Controlla gli input prima di avviare la fotocamera e conserva le compilazioni temporanee per tutta l’inferenza.

Le basi

VisionDetector.init(modelURL:)
Carica o compila il modello Core ML e ne convalida l’ingresso immagine.
VisionDetector.predict(_:)
Prepara l’immagine, esegue il modello e restituisce i rilevamenti.

L’esempio richiede un rilevatore di oggetti Core ML che restituisca osservazioni di oggetti Vision. Altri tipi di modello e i file ONNX richiedono un altro adattatore.

Approfondimento

Vision restituisce coordinate normalizzate dall’angolo in basso a sinistra. Convertile nella vista, conserva le proporzioni e specchia insieme immagine e riquadri.

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

Aggiungi la fotocamera

La cattura usa un executor seriale dedicato. I fotogrammi in ritardo vengono scartati; solo l’ultimo elaborato attende l’interfaccia. Immagine e previsioni restano insieme.

Le basi

CameraService.start(runID:modelURL:)
Crea la sessione di acquisizione sul proprio esecutore seriale e restituisce un flusso con al massimo un fotogramma in attesa.
CameraService.stop(runID:)
Arresta solo l’esecuzione corrispondente e ne rilascia sessione, delegato e osservatori.
Da ricordare
  1. Sintomo
    L’interfaccia si blocca quando si avvia la fotocamera.
    Causa
    L’avvio della sessione è bloccante; async da solo non sposta il lavoro fuori da MainActor.
    Rimedio
    Esegui acquisizione e inferenza su un executor seriale dedicato. Aggiorna l’interfaccia su MainActor.
  2. Sintomo
    L’anteprima resta indietro e l’uso della memoria aumenta.
    Causa
    La fotocamera produce immagini più velocemente di quanto l’inferenza le elabori, creando una coda senza limite.
    Rimedio
    Scarta i fotogrammi in ritardo, elabora in serie e conserva solo il risultato in attesa più recente. Evita una Task per fotogramma.
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

Posiziona le previsioni

Vision restituisce coordinate normalizzate dall’angolo in basso a sinistra. Convertile nella vista, conserva le proporzioni e specchia insieme immagine e riquadri.

Le basi

OverlayGeometry.project(...)
Proietta i riquadri Vision in una vista che conserva le proporzioni e specchia insieme immagine e riquadri.
Da ricordare

Tratta dimensioni, ritaglio, orientamento e coordinate come un contratto unico. Verifica riquadri noti prima di fidarti della sovrapposizione.

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

Compila. Avvia. Prova.

Compila l’app locale, scegli il rilevatore e premi Start camera. Regola la soglia di confidenza e la specchiatura. Ferma la cattura quando hai finito.

Le basi

CameraController.start()
Richiede il permesso della fotocamera, avvia l’acquisizione e aggiorna i fotogrammi corrispondenti su MainActor.
CameraController.stop()
Annulla il task attivo dell’interfaccia e chiede al servizio fotocamera di arrestare la stessa esecuzione.
Da ricordare
  1. Sintomo
    I vecchi riquadri ricompaiono dopo uno stop o un cambio di modello.
    Causa
    Un’attività precedente può finire in ritardo; gli osservatori trattenuti possono mantenere attive le risorse.
    Rimedio
    Annulla l’esecuzione precedente, scarta i risultati obsoleti, ferma l’acquisizione e rimuovi gli osservatori. Rilascia i modelli temporanei; analizza avvii e arresti ripetuti con Instruments.
Terminalbash
./build-app.sh
open ".build/BadBob Playground.app"

02.06 / Buone pratiche

Piccoli dettagli. Esempi migliori.

  • Tieni cattura e inferenza fuori dal thread dell’interfaccia. Limita la coda invece di accumulare vecchi fotogrammi.
  • Tratta dimensioni, ritaglio, orientamento e coordinate come un contratto unico. Verifica riquadri noti prima di fidarti della sovrapposizione.
  • Gestisci permessi negati, modelli incompatibili e annullamenti. Confronta previsioni note sul Mac che userai.