BadBob / Playground

Sinun mallisi.
Käytännössä.

Tee koulutetusta mallista jotain hyödyllistä. Pieniä avoimen lähdekoodin esimerkkejä, selkeät vaiheet ja koodia, jota voit muokata omiin tarpeisiisi.

Avoin lähdekoodi · MIT · Mallisi pysyy sinun

MALLISTA SOVELLUKSEKSI
Professori Bob hymyilee ja katsoo nenälle valuneiden lukulasiensa yli. Vieressä on liitutaulu täynnä monimutkaista fysiikkaa. Pyyhittyyn kulmaan hän on kirjoittanut: MODEL = mc² / 10 PRINT "BAD BOB" / 20 GOTO 10.
  1. 01Kamera
  2. 02Malli
  3. 03Ennuste
  4. 04Sovelluksesi
Kuvitus · laskennasta tulokseen

01 / VALITSE POLKUSI

Pieni alku. Tilaa rakentaa lisää.

Saatavilla

Swift

Natiivi Mac-kamerasovellus omalla Core ML -tunnistimellasi.

Core ML · macOS
Saatavilla

Python

Komentosarjapolku mallien tutkimiseen ja hyödyllisten työkalujen rakentamiseen.

ONNX Runtime · OpenCV
Saatavilla

JavaScript

Selain-esimerkkejä tuetulla ONNX-mallilla.

Web · ONNX
Saatavilla

Rust

Natiivipolku, jossa mallin ja suoritusympäristön vaatimukset ovat selkeät.

OpenCV · ONNX
Saatavilla

Go

Käytännöllisiä työkaluja, joissa mallin suorittamisen rajapinta on selkeä.

GoCV · ONNX
Saatavilla

C++

Kamera ja paikallinen päättely OpenCV:llä sekä tuetulla ONNX-mallilla.

OpenCV · ONNX

DeviconGo Gopher — Renee FrenchCC BY 3.0

Muista
  1. Oire
    Käyttöliittymä jäätyy kameran käynnistyessä.
    Syy
    Istunnon käynnistys on estävä; async ei yksin siirrä työtä pois MainActorista.
    Ratkaisu
    Suorita kuvaus ja inferenssi omalla sarjallisella suorittajalla. Päivitä käyttöliittymä MainActorissa.
  2. Oire
    Esikatselu viivästyy ja muistinkulutus kasvaa.
    Syy
    Kamera tuottaa kuvia nopeammin kuin inferenssi käsittelee niitä, joten rajoittamaton jono kasvaa.
    Ratkaisu
    Hylkää myöhästyneet kuvat, käsittele sarjallisesti ja säilytä vain uusin odottava tulos. Vältä erillistä Task-tehtävää jokaiselle kuvalle.
  3. Oire
    Vanhat laatikot palaavat pysäytyksen tai mallinvaihdon jälkeen.
    Syy
    Aiempi tehtävä voi valmistua myöhässä; säilytetyt tarkkailijat voivat pitää resursseja varattuina.
    Ratkaisu
    Peru aiempi ajo, hylkää vanhentuneet tulokset, pysäytä kuvaus ja poista tarkkailijat. Vapauta väliaikaiset mallit; mittaa toistuvia käynnistyksiä ja pysäytyksiä Instrumentsilla.
BadBob / Playground
Core ML · Vision · MIT
02.01

Valmistele projekti

Lataa lähdekoodi ja suorita testit. Tarvitset kameran sekä Vision-yhteensopivan Core ML -kohteentunnistusmallin. Mallin painoja ei toimiteta mukana.

Perusteet

swift test
Suorittaa automaattiset tarkistukset avaamatta kameraa.
Terminalbash
unzip badbob-playground-swift.zip
cd badbob-playground-swift
swift test
02.02

Liitä mallisi

Lataa malli ja luo Vision-pyyntö. Tarkista syötteet ennen kameran käynnistämistä ja säilytä väliaikainen käännös koko päättelyn ajan.

Perusteet

VisionDetector.init(modelURL:)
Lataa tai kääntää Core ML -mallin ja tarkistaa sen kuvasisääntulon.
VisionDetector.predict(_:)
Valmistelee kuvan, suorittaa mallin ja palauttaa havainnot.

Esimerkki edellyttää Core ML -objektitunnistinta, joka palauttaa Visionin objektihavaintoja. Muut mallityypit ja ONNX-tiedostot tarvitsevat toisen sovittimen.

Syventävät tiedot

Vision antaa normalisoidut koordinaatit vasemmasta alakulmasta. Muunna ne näkymään, säilytä kuvasuhde ja peilaa kuva sekä laatikot yhdessä.

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

Lisää kamera

Kuvaus toimii omalla sarjallisella suorittajallaan. Myöhästyneet ruudut ohitetaan, ja vain uusin käsitelty ruutu odottaa käyttöliittymää. Kuva ja ennusteet pysyvät yhdessä.

Perusteet

CameraService.start(runID:modelURL:)
Luo kameraistunnon omalla sarjallisella suorittajallaan ja palauttaa virran, jossa odottaa enintään yksi kuva.
CameraService.stop(runID:)
Pysäyttää vain vastaavan ajon ja vapauttaa sen istunnon, delegaatin ja tarkkailijat.
Muista
  1. Oire
    Käyttöliittymä jäätyy kameran käynnistyessä.
    Syy
    Istunnon käynnistys on estävä; async ei yksin siirrä työtä pois MainActorista.
    Ratkaisu
    Suorita kuvaus ja inferenssi omalla sarjallisella suorittajalla. Päivitä käyttöliittymä MainActorissa.
  2. Oire
    Esikatselu viivästyy ja muistinkulutus kasvaa.
    Syy
    Kamera tuottaa kuvia nopeammin kuin inferenssi käsittelee niitä, joten rajoittamaton jono kasvaa.
    Ratkaisu
    Hylkää myöhästyneet kuvat, käsittele sarjallisesti ja säilytä vain uusin odottava tulos. Vältä erillistä Task-tehtävää jokaiselle kuvalle.
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

Sijoita ennusteet oikein

Vision antaa normalisoidut koordinaatit vasemmasta alakulmasta. Muunna ne näkymään, säilytä kuvasuhde ja peilaa kuva sekä laatikot yhdessä.

Perusteet

OverlayGeometry.project(...)
Muuntaa Visionin laatikot kuvasuhteen säilyttävään näkymään ja peilaa kuvan sekä laatikot yhdessä.
Muista

Käsittele kuvakokoa, rajausta, suuntaa ja koordinaatteja yhtenä sopimuksena. Testaa tunnetuilla laatikoilla ennen kuin luotat merkintöihin.

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

Käännä. Käynnistä. Kokeile.

Käännä paikallinen sovellus, valitse tunnistin ja paina Start camera. Säädä luottamuskynnystä ja peilausta. Lopeta kuvaus, kun olet valmis.

Perusteet

CameraController.start()
Pyytää kameraluvan, käynnistää kuvauksen ja päivittää vastaavat kuvat MainActorissa.
CameraController.stop()
Peruuttaa aktiivisen käyttöliittymätehtävän ja pyytää kamerapalvelua pysäyttämään saman ajon.
Muista
  1. Oire
    Vanhat laatikot palaavat pysäytyksen tai mallinvaihdon jälkeen.
    Syy
    Aiempi tehtävä voi valmistua myöhässä; säilytetyt tarkkailijat voivat pitää resursseja varattuina.
    Ratkaisu
    Peru aiempi ajo, hylkää vanhentuneet tulokset, pysäytä kuvaus ja poista tarkkailijat. Vapauta väliaikaiset mallit; mittaa toistuvia käynnistyksiä ja pysäytyksiä Instrumentsilla.
Terminalbash
./build-app.sh
open ".build/BadBob Playground.app"

02.06 / Hyvät käytännöt

Pienet yksityiskohdat. Paremmat esimerkit.

  • Pidä kuvaus ja päättely poissa käyttöliittymän säikeestä. Rajoita jonoa vanhojen ruutujen keräämisen sijaan.
  • Käsittele kuvakokoa, rajausta, suuntaa ja koordinaatteja yhtenä sopimuksena. Testaa tunnetuilla laatikoilla ennen kuin luotat merkintöihin.
  • Käsittele evätyt oikeudet, yhteensopimattomat mallit ja peruutukset. Vertaa tunnettuja ennusteita sillä Macilla, jota käytät.