BadBob / Playground

你的模型。
走进真实世界。

让训练好的模型发挥作用。小巧的开源示例、清晰的步骤,以及可自由修改的代码。

开源 · MIT · 模型始终属于你

从模型到应用
Bob 教授面带微笑,老花镜低低地架在鼻梁上,身旁的黑板写满了复杂的物理内容。在擦净的一角,他写着:MODEL = mc² / 10 PRINT "BAD BOB" / 20 GOTO 10。
  1. 01摄像头
  2. 02模型
  3. 03预测结果
  4. 04你的应用
插画 · 从计算到结果

01 / 选择你的路径

从小处开始,逐步拓展。

已提供

Swift

使用你的 Core ML 检测器构建原生 Mac 摄像头应用。

Core ML · macOS
已提供

Python

通过脚本检查模型,构建实用工具。

ONNX Runtime · OpenCV
已提供

JavaScript

使用受支持的 ONNX 模型构建浏览器示例。

Web · ONNX
已提供

Rust

明确模型和运行环境要求的原生开发路径。

OpenCV · ONNX
已提供

Go

通过清晰的模型运行接口构建实用工具。

GoCV · ONNX
已提供

C++

使用 OpenCV 和受支持的 ONNX 模型进行摄像头采集与本地推理。

OpenCV · ONNX

DeviconGo Gopher — Renee FrenchCC BY 3.0

注意事项
  1. 症状
    启动摄像头时,界面卡住。
    原因
    会话启动会阻塞执行;仅使用 async 并不会把工作移出 MainActor。
    解决方法
    在专用串行执行器上运行采集和推理,在 MainActor 上更新界面。
  2. 症状
    预览延迟,内存占用不断增加。
    原因
    摄像头生成图像的速度快于推理处理速度,导致无界队列不断增长。
    解决方法
    丢弃延迟帧,串行处理,只保留最新的待显示结果。避免为每一帧创建一个 Task。
  3. 症状
    停止采集或切换模型后,旧检测框重新出现。
    原因
    先前的任务可能延迟完成;被保留的观察者可能让资源一直存活。
    解决方法
    取消旧任务,拒绝过期结果,停止采集并移除观察者。释放临时模型;用 Instruments 分析反复启动和停止的情况。
BadBob / Playground
Core ML · Vision · MIT
02.01

准备项目

下载源代码并运行测试。你需要摄像头,以及与 Vision 兼容的 Core ML 目标检测模型。示例不包含模型权重。

基础说明

swift test
运行自动检查,不打开摄像头。
Terminalbash
unzip badbob-playground-swift.zip
cd badbob-playground-swift
swift test
02.02

连接模型

加载模型并创建 Vision 请求。启动摄像头前检查输入,并在整个推理期间保留临时编译文件。

基础说明

VisionDetector.init(modelURL:)
加载或编译 Core ML 模型,并验证其图像输入。
VisionDetector.predict(_:)
预处理图像,运行模型并返回检测结果。

此示例需要能返回 Vision 对象观察结果的 Core ML 目标检测模型。其他模型类型和 ONNX 文件需要使用不同的适配器。

深入了解

Vision 返回以左下角为原点的归一化坐标。将其转换为视图坐标,保持画面宽高比,并同时镜像画面与检测框。

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

接入摄像头

采集在专用串行执行器上运行。丢弃延迟帧,只有最新处理的帧会等待界面显示。画面与预测结果始终对应。

基础说明

CameraService.start(runID:modelURL:)
在自己的串行执行器上创建采集会话,返回最多只保留一帧待处理图像的数据流。
CameraService.stop(runID:)
仅停止对应的运行,并释放其会话、代理和观察者。
注意事项
  1. 症状
    启动摄像头时,界面卡住。
    原因
    会话启动会阻塞执行;仅使用 async 并不会把工作移出 MainActor。
    解决方法
    在专用串行执行器上运行采集和推理,在 MainActor 上更新界面。
  2. 症状
    预览延迟,内存占用不断增加。
    原因
    摄像头生成图像的速度快于推理处理速度,导致无界队列不断增长。
    解决方法
    丢弃延迟帧,串行处理,只保留最新的待显示结果。避免为每一帧创建一个 Task。
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

正确定位预测结果

Vision 返回以左下角为原点的归一化坐标。将其转换为视图坐标,保持画面宽高比,并同时镜像画面与检测框。

基础说明

OverlayGeometry.project(...)
将 Vision 检测框投影到保持宽高比的视图中,同时镜像图像与检测框。
注意事项

将图像尺寸、裁剪、方向和坐标作为统一约定。先用已知检测框测试,再信任画面标注。

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

构建、运行、测试模型。

构建本地应用,选择检测模型并点击 Start camera。调整置信度阈值和镜像设置。完成后停止采集。

基础说明

CameraController.start()
请求摄像头权限,启动采集,并在 MainActor 上更新对应的图像帧。
CameraController.stop()
取消当前界面任务,并请求摄像头服务停止同一次运行。
注意事项
  1. 症状
    停止采集或切换模型后,旧检测框重新出现。
    原因
    先前的任务可能延迟完成;被保留的观察者可能让资源一直存活。
    解决方法
    取消旧任务,拒绝过期结果,停止采集并移除观察者。释放临时模型;用 Instruments 分析反复启动和停止的情况。
Terminalbash
./build-app.sh
open ".build/BadBob Playground.app"

02.06 / 最佳实践

做好细节,写好示例。

  • 让采集和推理远离界面线程。限制队列长度,不要堆积旧帧。
  • 将图像尺寸、裁剪、方向和坐标作为统一约定。先用已知检测框测试,再信任画面标注。
  • 妥善处理权限被拒、模型不兼容和取消操作。在实际使用的 Mac 上对比已知预测结果。