BadBob / Playground

نموذجك.
في العالم الحقيقي.

حوّل نموذجًا مدرّبًا إلى شيء مفيد. أمثلة صغيرة مفتوحة المصدر، وخطوات واضحة، وشيفرة يمكنك تكييفها مع فكرتك.

مفتوح المصدر · MIT · نموذجك يبقى ملكك

من النموذج إلى التطبيق
يبتسم البروفيسور بوب وهو ينظر من فوق نظارة القراءة المنخفضة على أنفه، بجوار سبورة تغطيها مسائل فيزيائية معقدة. في زاوية ممسوحة كتب: MODEL = mc² / 10 PRINT "BAD BOB" / 20 GOTO 10.
  1. 01الكاميرا
  2. 02النموذج
  3. 03التنبؤ
  4. 04تطبيقك
رسم توضيحي · من الحساب إلى النتيجة

01 / اختر مسارك

بداية صغيرة. ومساحة للتطوير.

متاح

Swift

تطبيق كاميرا أصلي على Mac باستخدام كاشف Core ML الخاص بك.

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 / Swift Core ML + Vision

ابنِ شيئًا يرى.

مثال Swift كامل: اختر نموذجك، وشغّل الكاميرا، وارسم التنبؤات المطابقة للصورة. اتبع الخطوات أو استكشف الشيفرة كاملة.

تركّز الأمثلة على الأشياء والحيوانات في بيئات محددة. ولا تتناول مراقبة الأشخاص أو تحديد هوياتهم أو تحليل سلوكهم.

02.01

حضّر المشروع

نزّل الشيفرة وشغّل اختباراتها. تحتاج إلى كاميرا وكاشف كائنات Core ML متوافق مع Vision. أوزان النموذج غير مرفقة.

الأساسيات

swift test
يشغّل الفحوص الآلية دون فتح الكاميرا.
Terminalbash
unzip badbob-playground-swift.zip
cd badbob-playground-swift
swift test
02.02

اربط نموذجك

حمّل النموذج وأنشئ طلب Vision. تحقّق من المدخلات قبل تشغيل الكاميرا، واحتفظ بأي تجميع مؤقت طوال فترة استخدامه في الاستدلال.

الأساسيات

VisionDetector.init(modelURL:)
يحمّل نموذج Core ML أو يترجمه ويتحقق من مدخل الصورة.
VisionDetector.predict(_:)
يجهّز الصورة ويشغّل النموذج ويعيد نتائج الكشف.

يتطلب هذا المثال كاشف أجسام Core ML يعيد ملاحظات أجسام Vision. تحتاج أنواع النماذج الأخرى وملفات 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 الذي ستستخدمه.