BadBob / Playground
OpenCV · ONNX · MIT

06 / Rust

Rust۔ ماڈل سے کیمرے تک۔

لائیو نشانات اور محدود فریم پروسیسنگ کے ساتھ اپنا ONNX ڈیٹیکٹر مقامی طور پر چلائیں۔

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

06.01

پروجیکٹ تیار کریں

درج شدہ انحصارات نصب کریں اور ٹیسٹ چلائیں۔ کیمرہ کھولنے سے پہلے کوئی مقامی تصویر آزمائیں۔

بنیادی باتیں

cargo test --locked
کیمرہ کھولے بغیر خودکار جانچ چلاتا ہے۔
Terminalbash
unzip badbob-playground-rust.zip
cd badbob-playground-rust
cargo build --locked
cargo test --locked
cargo fmt --check
06.02

ماڈل جوڑیں

کیمرا کھولنے سے پہلے ماڈل اور لیبل کی تصدیق کریں۔

بنیادی باتیں

parse_labels(text)
ماڈل کی کلاس ترتیب میں نام پڑھتا ہے؛ خالی یا دہرائے گئے لیبل مسترد کرتا ہے۔
OpenCvDetector::load(path, classes)
ONNX ماڈل لوڈ کرتا ہے اور اس کے ان پٹ، آؤٹ پٹ اور لیبلوں کی تعداد کی توثیق کرتا ہے۔
prepare_input(image)
تناسب برقرار رکھتے ہوئے 640×640 کا RGB ان پٹ بناتا ہے اور باقی جگہ بھرتا ہے۔
OpenCvDetector::detect(image)
تصویر تیار کرتا ہے، ماڈل چلاتا ہے اور شناخت کے نتائج واپس کرتا ہے۔
یاد رکھیں
علامت
باکس اپنی جگہ سے ہٹتے ہیں یا ماڈل لوڈ نہیں ہوتا۔
وجہ
پری پروسیسنگ، آؤٹ پٹ کی ساخت یا لیبل کی ترتیب مطابقت نہیں رکھتی۔
حل
یہ اڈاپٹر صرف نیچے دیے گئے معاہدے کو سپورٹ کرتا ہے۔ Core ML فائلوں اور دوسرے ONNX آؤٹ پٹ فارمیٹس کے لیے الگ اڈاپٹر درکار ہے۔

یہ اڈاپٹر صرف نیچے دیے گئے معاہدے کو سپورٹ کرتا ہے۔ Core ML فائلوں اور دوسرے ONNX آؤٹ پٹ فارمیٹس کے لیے الگ اڈاپٹر درکار ہے۔

مزید تفصیل

کوآرڈینیٹس 640×640 ان پٹ پکسلز میں باکس کے مرکز اور جسامت کو ظاہر کرتے ہیں۔ لیبل کی ترتیب ماڈل کی کلاس ترتیب کے عین مطابق ہونی چاہیے۔

ONNXyaml
input:
  color: RGB
  dtype: float32
  shape: [1, 3, 640, 640]
  letterbox: 114
  scale: 1/255
output:
  dtype: float32
  shape: [1, 4+C, N]
  boxes: [cx, cy, width, height]
  class_scores: probabilities
  objectness: false
  embedded_nms: false
src/opencv_adapter.rsrust
use crate::{
    Result,
    geometry::{Detection, decode, letterbox},
    runtime::{Detector, FrameSource},
};
use opencv::{
    core::{self, Mat, Rect, Scalar, Size, Vector},
    dnn, imgproc,
    prelude::*,
    videoio,
};
use std::path::Path;

pub struct OpenCvDetector {
    network: dnn::Net,
    classes: usize,
    output_name: String,
}

impl OpenCvDetector {
    pub fn load(path: &Path, classes: usize) -> Result<Self> {
        if path.extension().and_then(|s| s.to_str()) != Some("onnx")
            || !path.is_file()
            || !(1..=1024).contains(&classes)
        {
            return Err("Provide an existing .onnx file and 1-1024 labels".into());
        }
        let mut network =
            dnn::read_net_from_onnx(path.to_str().ok_or("Model path must be UTF-8")?)?;
        network.set_preferable_backend(dnn::DNN_BACKEND_OPENCV)?;
        network.set_preferable_target(dnn::DNN_TARGET_CPU)?;
        let outputs = network.get_unconnected_out_layers_names()?;
        if outputs.len() != 1 {
            return Err("Expected exactly one detector output".into());
        }
        let mut detector = Self {
            network,
            classes,
            output_name: outputs.get(0)?,
        };
        // Validate the actual forward contract before the camera factory runs.
        let sample = Mat::new_rows_cols_with_default(640, 640, core::CV_8UC3, Scalar::all(114.))?;
        detector.detect(&sample)?;
        Ok(detector)
    }
}

impl Detector for OpenCvDetector {
    fn detect(&mut self, image: &Mat) -> Result<Vec<Detection>> {
        let (blob, t) = prepare_input(image)?;
        self.network.set_input(&blob, "", 1., Scalar::default())?;
        let output = self.network.forward_single(&self.output_name)?;
        let shape = output.mat_size();
        let count = validate_output_shape(&shape, output.typ(), self.classes)?;
        let contiguous = output.try_clone()?;
        decode(contiguous.data_typed::<f32>()?, self.classes, count, t)
    }
}

pub struct OpenCvCamera(videoio::VideoCapture);

impl OpenCvCamera {
    pub fn open(index: i32) -> Result<Self> {
        let capture = videoio::VideoCapture::new(index, videoio::CAP_ANY)?;
        if !capture.is_opened()? {
            return Err("Cannot open camera; check index, permissions and backend".into());
        }
        Ok(Self(capture))
    }
}

impl FrameSource for OpenCvCamera {
    fn next_frame(&mut self) -> Result<Mat> {
        let mut image = Mat::default();
        if !self.0.read(&mut image)? || image.empty() {
            return Err("Camera read failed or returned an empty image".into());
        }
        Ok(image)
    }
}

pub fn annotate(image: &mut Mat, detections: &[Detection], labels: &[String]) -> Result<()> {
    for detection in detections {
        let b = detection.bounds;
        let left = (b.x.floor() as i32).clamp(0, image.cols() - 1);
        let top = (b.y.floor() as i32).clamp(0, image.rows() - 1);
        let right = (b.x + b.width).ceil() as i32;
        let bottom = (b.y + b.height).ceil() as i32;
        let bounds = Rect::new(
            left,
            top,
            (right.min(image.cols()) - left).max(1),
            (bottom.min(image.rows()) - top).max(1),
        );
        imgproc::rectangle(
            image,
            bounds,
            Scalar::new(74., 220., 250., 0.),
            2,
            imgproc::LINE_8,
            0,
        )?;
        let text = format!("{} {:.2}", labels[detection.label], detection.score);
        imgproc::put_text(
            image,
            &text,
            core::Point::new(left, (top - 6).max(16)),
            imgproc::FONT_HERSHEY_SIMPLEX,
            0.5,
            Scalar::new(74., 220., 250., 0.),
            1,
            imgproc::LINE_AA,
            false,
        )?;
    }
    Ok(())
}

pub fn encode_png(image: &Mat) -> Result<Vec<u8>> {
    let mut bytes = Vector::<u8>::new();
    if !opencv::imgcodecs::imencode(".png", image, &mut bytes, &Vector::<i32>::new())? {
        return Err("Cannot encode PNG".into());
    }
    Ok(bytes.to_vec())
}

pub fn prepare_input(image: &Mat) -> Result<(Mat, crate::geometry::Letterbox)> {
    if image.empty() || image.typ() != core::CV_8UC3 {
        return Err("Expected a nonempty 8-bit BGR image".into());
    }
    let t = letterbox(image.cols(), image.rows())?;
    let mut resized = Mat::default();
    imgproc::resize(
        image,
        &mut resized,
        Size::new(t.width, t.height),
        0.,
        0.,
        imgproc::INTER_LINEAR,
    )?;
    let mut padded = Mat::new_rows_cols_with_default(640, 640, core::CV_8UC3, Scalar::all(114.))?;
    let mut region = Mat::roi_mut(&mut padded, Rect::new(t.left, t.top, t.width, t.height))?;
    resized.copy_to(&mut region)?;
    let blob = dnn::blob_from_image(
        &padded,
        1. / 255.,
        Size::new(640, 640),
        Scalar::default(),
        true,
        false,
        core::CV_32F,
    )?;
    Ok((blob, t))
}

pub fn validate_output_shape(shape: &[i32], datatype: i32, classes: usize) -> Result<usize> {
    if !(1..=1024).contains(&classes)
        || shape.len() != 3
        || datatype != core::CV_32F
        || shape[0] != 1
        || shape[1] != (4 + classes) as i32
        || !(1..=100_000).contains(&shape[2])
    {
        return Err("Expected float32[1,4+C,N], N<=100000, XYWH + class probabilities; no objectness/embedded NMS".into());
    }
    Ok(shape[2] as usize)
}
06.03

کیمرا شامل کریں

کیپچر اور انفرنس ایک ہی ترتیبی ورکر تھریڈ پر چلتے ہیں۔ انٹرفیس کو صرف تازہ ترین مکمل تصویر اور اس کی شناختیں ملتی ہیں۔

بنیادی باتیں

run_worker(source, detector, stopped, results)
ایک ہی ورکر تھریڈ پر کیمرے کی تصاویر اور انفرنس سنبھالتا ہے۔
Latest::take()
تازہ ترین مکمل تصویر اور اس کی شناختیں حاصل کرتا ہے؛ نتائج قطار میں جمع نہیں ہو سکتے۔
Worker::stop() · Worker::join()
نئے نتائج قبول کرنا بند کرتا ہے اور جاری کام مکمل ہونے کے بعد وسائل آزاد کرتا ہے۔
یاد رکھیں
علامت
پیش منظر پیچھے رہ جاتا ہے اور میموری کا استعمال بڑھتا ہے۔
وجہ
کیمرہ استدلال کی کارروائی سے زیادہ تیزی سے فریم دیتا ہے، اس لیے لامحدود قطار بڑھتی جاتی ہے۔
حل
کیپچر اور انفرنس ایک ہی ترتیبی ورکر تھریڈ پر چلتے ہیں۔ انٹرفیس کو صرف تازہ ترین مکمل تصویر اور اس کی شناختیں ملتی ہیں۔
مزید تفصیل

رکنے کی درخواست کریں، تاخیر سے آنے والے نتائج مسترد کریں اور وسائل آزاد کرنے سے پہلے جاری کام مکمل ہونے کا انتظار کریں۔ بنیادی نظام کی کارروائی منسوخ کرنا پلیٹ فارم کی معاونت پر منحصر ہے۔

src/runtime.rsrust
use crate::{Result, geometry::Detection};
use opencv::{core::Mat, prelude::*};
use std::sync::{
    Arc, Mutex,
    atomic::{AtomicBool, Ordering},
};
use std::thread::{self, JoinHandle};

pub trait FrameSource: Send {
    fn next_frame(&mut self) -> Result<Mat>;
}

pub trait Detector: Send {
    fn detect(&mut self, image: &Mat) -> Result<Vec<Detection>>;
}

pub struct FrameResult {
    pub image: Mat,
    pub detections: Vec<Detection>,
}

struct Slot<T> {
    value: Option<T>,
    closed: bool,
}

pub struct Latest<T>(Mutex<Slot<T>>);

impl<T> Default for Latest<T> {
    fn default() -> Self {
        Self(Mutex::new(Slot {
            value: None,
            closed: false,
        }))
    }
}

impl<T> Latest<T> {
    pub fn publish(&self, value: T) {
        let mut slot = self.0.lock().unwrap_or_else(|e| e.into_inner());
        if !slot.closed {
            slot.value = Some(value);
        }
    }

    pub fn take(&self) -> Option<T> {
        self.0
            .lock()
            .unwrap_or_else(|e| e.into_inner())
            .value
            .take()
    }

    pub fn close(&self) {
        let mut slot = self.0.lock().unwrap_or_else(|e| e.into_inner());
        slot.closed = true;
        slot.value = None;
    }
}

pub struct Worker {
    stop_requested: Arc<AtomicBool>,
    done: Arc<AtomicBool>,
    results: Arc<Latest<Result<FrameResult>>>,
    thread: Option<JoinHandle<()>>,
}

impl Worker {
    pub fn start<S, D>(source: S, detector: D) -> Self
    where
        S: FnOnce() -> Result<Box<dyn FrameSource>> + Send + 'static,
        D: FnOnce() -> Result<Box<dyn Detector>> + Send + 'static,
    {
        let stop_requested = Arc::new(AtomicBool::new(false));
        let done = Arc::new(AtomicBool::new(false));
        let results = Arc::new(Latest::default());
        let stopped = stop_requested.clone();
        let finished = done.clone();
        let slot = results.clone();
        let thread = thread::spawn(move || {
            let _completion = Completion(finished);
            if let Err(error) = run_worker(source, detector, &stopped, &slot)
                && !stopped.load(Ordering::Acquire)
            {
                slot.publish(Err(error));
            }
        });
        Self {
            stop_requested,
            done,
            results,
            thread: Some(thread),
        }
    }

    pub fn take(&self) -> Option<Result<FrameResult>> {
        self.results.take()
    }

    pub fn is_done(&self) -> bool {
        self.done.load(Ordering::Acquire)
    }

    pub fn stop(&self) {
        self.stop_requested.store(true, Ordering::Release);
        self.results.close();
    }

    pub fn join(&mut self) -> Result<()> {
        if let Some(thread) = self.thread.take() {
            thread
                .join()
                .map_err(|_| "Capture/inference worker panicked")?;
        }
        Ok(())
    }
}

impl Drop for Worker {
    fn drop(&mut self) {
        self.stop();
        let _ = self.join();
    }
}

fn run_worker<S, D>(
    source: S,
    detector: D,
    stopped: &AtomicBool,
    results: &Latest<Result<FrameResult>>,
) -> Result<()>
where
    S: FnOnce() -> Result<Box<dyn FrameSource>>,
    D: FnOnce() -> Result<Box<dyn Detector>>,
{
    let mut model = detector()?;
    if stopped.load(Ordering::Acquire) {
        return Ok(());
    }
    let mut frames = source()?;
    while !stopped.load(Ordering::Acquire) {
        let image = frames.next_frame()?;
        if stopped.load(Ordering::Acquire) {
            break;
        }
        if image.empty() {
            return Err("Camera returned an empty frame".into());
        }
        let detections = model.detect(&image)?;
        if stopped.load(Ordering::Acquire) {
            break;
        }
        results.publish(Ok(FrameResult { image, detections }));
    }
    Ok(())
}

struct Completion(Arc<AtomicBool>);

impl Drop for Completion {
    fn drop(&mut self) {
        self.0.store(true, Ordering::Release);
    }
}
06.04

پیش گوئیاں درست جگہ رکھیں

letterbox کی اسکیلنگ اور پیڈنگ واپس ختم کریں، پھر باکس بنانے سے پہلے انہیں تصویر کی حدود تک محدود کریں۔

بنیادی باتیں

letterbox(width, height) · unproject(box, transform)
تناسب برقرار رکھتا ہے اور باکس کو اصل تصویر کے کوآرڈینیٹس میں واپس بدلتا ہے۔
decode(data, classes, count, transform)
پیش گوئیوں کی جانچ کرتا ہے اور ایک ہی کلاس کے اوورلیپ ہوتے باکس ہٹاتا ہے۔
یاد رکھیں

تصویر کے سائز، کراپ، سمت اور کوآرڈینیٹس کو ایک مشترک اصول سمجھیں۔ نشانات پر اعتماد سے پہلے معلوم باکسز سے جانچیں۔

src/geometry.rsrust
use crate::Result;

#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Box2 {
    pub x: f64,
    pub y: f64,
    pub width: f64,
    pub height: f64,
}

#[derive(Clone, Debug)]
pub struct Detection {
    pub bounds: Box2,
    pub label: usize,
    pub score: f32,
}

#[derive(Clone, Copy, Debug)]
pub struct Letterbox {
    pub original_width: i32,
    pub original_height: i32,
    pub width: i32,
    pub height: i32,
    pub left: i32,
    pub top: i32,
}

pub fn letterbox(width: i32, height: i32) -> Result<Letterbox> {
    if width <= 0 || height <= 0 {
        return Err("Image dimensions must be positive".into());
    }

    let ratio = (640. / f64::from(width)).min(640. / f64::from(height));
    let resized_width = (f64::from(width) * ratio).round().max(1.) as i32;
    let resized_height = (f64::from(height) * ratio).round().max(1.) as i32;
    Ok(Letterbox {
        original_width: width,
        original_height: height,
        width: resized_width,
        height: resized_height,
        left: (640 - resized_width) / 2,
        top: (640 - resized_height) / 2,
    })
}

pub fn unproject(b: Box2, t: Letterbox) -> Result<Box2> {
    if t.original_width <= 0
        || t.original_height <= 0
        || t.width <= 0
        || t.height <= 0
        || t.width > 640
        || t.height > 640
        || t.left < 0
        || t.top < 0
        || t.left > 640 - t.width
        || t.top > 640 - t.height
    {
        return Err("Invalid letterbox geometry".into());
    }
    if ![b.x, b.y, b.width, b.height, b.x + b.width, b.y + b.height]
        .iter()
        .all(|x| x.is_finite())
        || b.width < 0.
        || b.height < 0.
    {
        return Err("Box geometry must be finite and nonnegative".into());
    }

    let x = |v: f64| {
        ((v - f64::from(t.left)) / f64::from(t.width)).clamp(0., 1.) * f64::from(t.original_width)
    };
    let y = |v: f64| {
        ((v - f64::from(t.top)) / f64::from(t.height)).clamp(0., 1.) * f64::from(t.original_height)
    };
    let left = x(b.x);
    let top = y(b.y);
    Ok(Box2 {
        x: left,
        y: top,
        width: x(b.x + b.width) - left,
        height: y(b.y + b.height) - top,
    })
}

fn intersection_over_union(a: Box2, b: Box2) -> f64 {
    let width = (a.x + a.width).min(b.x + b.width) - a.x.max(b.x);
    let height = (a.y + a.height).min(b.y + b.height) - a.y.max(b.y);
    let intersection = width.max(0.) * height.max(0.);
    let area = a.width * a.height + b.width * b.height - intersection;
    if area > 0. { intersection / area } else { 0. }
}

pub fn decode(data: &[f32], classes: usize, count: usize, t: Letterbox) -> Result<Vec<Detection>> {
    if !(1..=1024).contains(&classes)
        || !(1..=100_000).contains(&count)
        || data.len() != (4 + classes) * count
    {
        return Err("Expected float32[1,4+C,N], C<=1024, N<=100000".into());
    }

    let mut candidates = Vec::new();
    for i in 0..count {
        let cx = f64::from(data[i]);
        let cy = f64::from(data[count + i]);
        let width = f64::from(data[2 * count + i]);
        let height = f64::from(data[3 * count + i]);
        // Validate even candidates below the confidence threshold.
        let bounds = unproject(
            Box2 {
                x: cx - width / 2.,
                y: cy - height / 2.,
                width,
                height,
            },
            t,
        )?;
        let mut score = 0.;
        let mut label = 0;
        for c in 0..classes {
            let probability = data[(4 + c) * count + i];
            if !probability.is_finite() || !(0.0..=1.0).contains(&probability) {
                return Err("Expected probabilities in [0,1], not logits/objectness".into());
            }
            if probability > score {
                score = probability;
                label = c;
            }
        }
        if score >= 0.25 && bounds.width > 0. && bounds.height > 0. {
            candidates.push(Detection {
                bounds,
                label,
                score,
            });
        }
    }

    candidates.sort_by(|a, b| b.score.total_cmp(&a.score));
    candidates.truncate(3000);
    let mut selected: Vec<Detection> = Vec::new();
    for candidate in candidates {
        let suppressed = selected.iter().any(|previous| {
            previous.label == candidate.label
                && intersection_over_union(previous.bounds, candidate.bounds) > 0.45
        });
        if suppressed {
            continue;
        }
        selected.push(candidate);
        if selected.len() == 300 {
            break;
        }
    }
    Ok(selected)
}
06.05

بنائیں۔ چلائیں۔ آزمائیں۔

کیمرا واضح طور پر منتخب کریں یا تصویر آف لائن پراسیس کریں۔ روکنے کے لیے Q یا Escape دبائیں۔

بنیادی باتیں

parse_options()
آرگیومنٹس کی جانچ کرتا ہے اور صرف ایک ان پٹ چنتا ہے: تصویر یا کیمرہ۔
run()
منتخب ماخذ کی توثیق کرتا ہے اور تصویر یا کیمرے کی کارروائی متعلقہ حصے کے سپرد کرتا ہے۔
یاد رکھیں
علامت
رکنے میں توقع سے زیادہ وقت لگتا ہے۔
وجہ
تصویر حاصل کرنے یا استدلال کی کوئی نیٹو کال ابھی چل رہی ہے۔
حل
رکنے کی درخواست کریں، تاخیر سے آنے والے نتائج مسترد کریں اور وسائل آزاد کرنے سے پہلے جاری کام مکمل ہونے کا انتظار کریں۔ بنیادی نظام کی کارروائی منسوخ کرنا پلیٹ فارم کی معاونت پر منحصر ہے۔
Terminalbash
cargo run --locked -- --model detector.onnx --labels labels.txt --image frame.png --output result.png

cargo run --locked -- --model detector.onnx --labels labels.txt --camera 0

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

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

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