BadBob / Playground

آپ کا ماڈل۔
حقیقی دنیا میں۔

تربیت یافتہ ماڈل کو کارآمد چیز بنائیں۔ چھوٹی اوپن سورس مثالیں، واضح مراحل اور ایسا کوڈ جسے آپ اپنی سوچ کے مطابق ڈھال سکیں۔

اوپن سورس · MIT · آپ کا ماڈل آپ ہی کا رہتا ہے

ماڈل سے ایپ تک
پروفیسر بوب ناک پر نیچے سرکے ہوئے پڑھنے کے چشمے کے اوپر سے دیکھتے ہوئے مسکرا رہے ہیں۔ پاس کا تختۂ سیاہ پیچیدہ طبیعیات سے بھرا ہے۔ ایک صاف کیے گئے کونے میں انہوں نے لکھا ہے: 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 سے باہر نہیں جاتا۔
    حل
    کیپچر اور استدلال کو الگ ترتیب وار executor پر چلائیں۔ UI کو MainActor پر اپ ڈیٹ کریں۔
  2. علامت
    پیش منظر پیچھے رہ جاتا ہے اور میموری کا استعمال بڑھتا ہے۔
    وجہ
    کیمرہ استدلال کی کارروائی سے زیادہ تیزی سے فریم دیتا ہے، اس لیے لامحدود قطار بڑھتی جاتی ہے۔
    حل
    دیر سے آنے والے فریم چھوڑ دیں، ترتیب وار کارروائی کریں اور صرف تازہ ترین زیرِ انتظار نتیجہ رکھیں۔ ہر فریم کے لیے الگ Task نہ بنائیں۔
  3. علامت
    روکنے یا ماڈل بدلنے کے بعد پرانے خانے دوبارہ دکھائی دیتے ہیں۔
    وجہ
    پچھلا کام دیر سے مکمل ہو سکتا ہے؛ محفوظ رہنے والے observers وسائل کو فعال رکھ سکتے ہیں۔
    حل
    پرانا عمل منسوخ کریں، پرانے نتائج رد کریں، کیپچر روکیں اور observers ہٹائیں۔ عارضی ماڈل آزاد کریں؛ بار بار آغاز اور بندش کو Instruments سے ناپیں۔
BadBob / Playground
Core ML · Vision · MIT

02 / Swift Core ML + Vision

کچھ ایسا بنائیں جو دیکھ سکے۔

مکمل Swift مثال: ماڈل چنیں، کیمرا شروع کریں اور تصویر سے ملتی پیش گوئیاں دکھائیں۔ مراحل ترتیب سے پڑھیں یا پورا سورس کوڈ دیکھیں۔

یہ مثالیں محدود ماحول میں اشیا اور جانوروں پر مرکوز ہیں۔ ان میں لوگوں کی نگرانی، شناخت یا رویے کا تجزیہ شامل نہیں۔

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(_:)
تصویر تیار کرتا ہے، ماڈل چلاتا ہے اور شناخت کے نتائج واپس کرتا ہے۔

اس مثال کے لیے ایسا 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 سے باہر نہیں جاتا۔
    حل
    کیپچر اور استدلال کو الگ ترتیب وار executor پر چلائیں۔ UI کو 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()
فعال UI ٹاسک منسوخ کرتا ہے اور کیمرہ سروس سے اسی رن کو روکنے کی درخواست کرتا ہے۔
یاد رکھیں
  1. علامت
    روکنے یا ماڈل بدلنے کے بعد پرانے خانے دوبارہ دکھائی دیتے ہیں۔
    وجہ
    پچھلا کام دیر سے مکمل ہو سکتا ہے؛ محفوظ رہنے والے observers وسائل کو فعال رکھ سکتے ہیں۔
    حل
    پرانا عمل منسوخ کریں، پرانے نتائج رد کریں، کیپچر روکیں اور observers ہٹائیں۔ عارضی ماڈل آزاد کریں؛ بار بار آغاز اور بندش کو Instruments سے ناپیں۔
Terminalbash
./build-app.sh
open ".build/BadBob Playground.app"

02.06 / بہترین طریقے

چھوٹی باریکیاں۔ بہتر مثالیں۔

  • کیپچر اور استدلال کو UI تھریڈ سے باہر رکھیں۔ پرانے فریم جمع کرنے کے بجائے قطار کی حد مقرر کریں۔
  • تصویر کے سائز، کراپ، سمت اور کوآرڈینیٹس کو ایک مشترک اصول سمجھیں۔ نشانات پر اعتماد سے پہلے معلوم باکسز سے جانچیں۔
  • اجازت نہ ملنے، غیرمطابق ماڈلز اور منسوخی کو سنبھالیں۔ استعمال ہونے والے Mac پر معلوم پیش گوئیوں کا موازنہ کریں۔