BadBob / Playground

Model Anda.
Di dunia nyata.

Ubah model terlatih menjadi sesuatu yang berguna. Contoh sumber terbuka yang ringkas, langkah yang jelas, dan kode yang dapat Anda sesuaikan dengan ide sendiri.

Sumber terbuka · MIT · Model tetap milik Anda

DARI MODEL KE APLIKASI
Profesor Bob tersenyum sambil mengintip dari atas kacamata bacanya yang turun di hidung, di samping papan tulis penuh fisika rumit. Di sudut yang telah dihapus, ia menulis: MODEL = mc² / 10 PRINT "BAD BOB" / 20 GOTO 10.
  1. 01Kamera
  2. 02Model
  3. 03Prediksi
  4. 04Aplikasi Anda
Ilustrasi · dari perhitungan ke hasil

01 / PILIH JALUR ANDA

Awal yang kecil. Ruang untuk berkembang.

Tersedia

Swift

Aplikasi kamera native Mac dengan detektor Core ML Anda.

Core ML · macOS
Tersedia

Python

Jalur skrip untuk memeriksa model dan membuat alat praktis.

ONNX Runtime · OpenCV
Tersedia

JavaScript

Contoh browser dengan model ONNX yang didukung.

Web · ONNX
Tersedia

Rust

Jalur native dengan persyaratan model dan runtime yang jelas.

OpenCV · ONNX
Tersedia

Go

Alat praktis dengan antarmuka yang jelas untuk menjalankan model.

GoCV · ONNX
Tersedia

C++

Kamera dan inferensi lokal dengan OpenCV serta model ONNX yang didukung.

OpenCV · ONNX

DeviconGo Gopher — Renee FrenchCC BY 3.0

Perlu diingat
  1. Gejala
    Antarmuka membeku saat kamera dimulai.
    Penyebab
    Memulai sesi memblokir eksekusi; async saja tidak memindahkan pekerjaan dari MainActor.
    Penanganan
    Jalankan pengambilan gambar dan inferensi pada executor serial khusus. Perbarui UI pada MainActor.
  2. Gejala
    Pratinjau tertinggal dan penggunaan memori meningkat.
    Penyebab
    Kamera menghasilkan frame lebih cepat daripada inferensi memprosesnya, sehingga antrean tanpa batas terus bertambah.
    Penanganan
    Buang frame yang terlambat, proses secara serial dan simpan hanya hasil tertunda terbaru. Hindari satu Task untuk setiap frame.
  3. Gejala
    Kotak lama muncul lagi setelah berhenti atau mengganti model.
    Penyebab
    Tugas sebelumnya bisa selesai terlambat; observer yang masih disimpan dapat mempertahankan sumber daya.
    Penanganan
    Batalkan proses lama, tolak hasil usang, hentikan pengambilan gambar dan hapus observer. Lepaskan model sementara; ukur siklus mulai dan berhenti berulang dengan Instruments.
BadBob / Playground
Core ML · Vision · MIT
02.01

Siapkan proyek

Unduh kode sumber dan jalankan pengujiannya. Anda memerlukan kamera dan detektor objek Core ML yang kompatibel dengan Vision. Bobot model tidak disertakan.

Dasar

swift test
Menjalankan pemeriksaan otomatis tanpa membuka kamera.
Terminalbash
unzip badbob-playground-swift.zip
cd badbob-playground-swift
swift test
02.02

Hubungkan model

Muat model dan buat permintaan Vision. Periksa input sebelum memulai kamera, dan simpan kompilasi sementara selama inferensi menggunakannya.

Dasar

VisionDetector.init(modelURL:)
Memuat atau mengompilasi model Core ML dan memvalidasi masukan gambarnya.
VisionDetector.predict(_:)
Menyiapkan gambar, menjalankan model, dan mengembalikan deteksi.

Contoh ini membutuhkan detektor objek Core ML yang mengembalikan pengamatan objek Vision. Jenis model lain dan berkas ONNX memerlukan adaptor berbeda.

Lebih mendalam

Vision menghasilkan koordinat ternormalisasi dari kiri bawah. Ubah ke koordinat tampilan, pertahankan rasio gambar, dan cerminkan gambar serta kotak bersama-sama.

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

Tambahkan kamera

Pengambilan gambar berjalan pada executor serial khusus. Frame terlambat dibuang, dan hanya frame terbaru yang diproses menunggu antarmuka. Gambar dan prediksi tetap berpasangan.

Dasar

CameraService.start(runID:modelURL:)
Membuat sesi pengambilan pada eksekutor serialnya dan mengembalikan aliran dengan maksimal satu frame tertunda.
CameraService.stop(runID:)
Menghentikan hanya proses yang sesuai dan melepaskan sesi, delegat, serta pengamatnya.
Perlu diingat
  1. Gejala
    Antarmuka membeku saat kamera dimulai.
    Penyebab
    Memulai sesi memblokir eksekusi; async saja tidak memindahkan pekerjaan dari MainActor.
    Penanganan
    Jalankan pengambilan gambar dan inferensi pada executor serial khusus. Perbarui UI pada MainActor.
  2. Gejala
    Pratinjau tertinggal dan penggunaan memori meningkat.
    Penyebab
    Kamera menghasilkan frame lebih cepat daripada inferensi memprosesnya, sehingga antrean tanpa batas terus bertambah.
    Penanganan
    Buang frame yang terlambat, proses secara serial dan simpan hanya hasil tertunda terbaru. Hindari satu Task untuk setiap frame.
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

Tempatkan prediksi

Vision menghasilkan koordinat ternormalisasi dari kiri bawah. Ubah ke koordinat tampilan, pertahankan rasio gambar, dan cerminkan gambar serta kotak bersama-sama.

Dasar

OverlayGeometry.project(...)
Memproyeksikan kotak Vision ke tampilan yang mempertahankan rasio aspek dan mencerminkan gambar serta kotak bersamaan.
Perlu diingat

Perlakukan ukuran gambar, pemotongan, orientasi, dan koordinat sebagai satu kesepakatan. Uji dengan kotak yang diketahui sebelum memercayai penanda.

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

Bangun. Jalankan. Coba model.

Bangun aplikasi lokal, pilih detektor, lalu tekan Start camera. Sesuaikan ambang keyakinan dan pencerminan. Hentikan pengambilan gambar setelah selesai.

Dasar

CameraController.start()
Meminta izin kamera, memulai pengambilan, dan memperbarui frame yang sesuai pada MainActor.
CameraController.stop()
Membatalkan tugas UI aktif dan meminta layanan kamera menghentikan proses yang sama.
Perlu diingat
  1. Gejala
    Kotak lama muncul lagi setelah berhenti atau mengganti model.
    Penyebab
    Tugas sebelumnya bisa selesai terlambat; observer yang masih disimpan dapat mempertahankan sumber daya.
    Penanganan
    Batalkan proses lama, tolak hasil usang, hentikan pengambilan gambar dan hapus observer. Lepaskan model sementara; ukur siklus mulai dan berhenti berulang dengan Instruments.
Terminalbash
./build-app.sh
open ".build/BadBob Playground.app"

02.06 / Praktik terbaik

Detail kecil. Contoh yang lebih baik.

  • Jalankan pengambilan gambar dan inferensi di luar thread antarmuka. Batasi antrean alih-alih menumpuk frame lama.
  • Perlakukan ukuran gambar, pemotongan, orientasi, dan koordinat sebagai satu kesepakatan. Uji dengan kotak yang diketahui sebelum memercayai penanda.
  • Tangani izin yang ditolak, model tidak kompatibel, dan pembatalan. Bandingkan prediksi yang diketahui pada Mac yang akan Anda gunakan.