BadBob / Playground
OpenCV · ONNX · MIT
03.01

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

CMake اور OpenCV 4.x انسٹال کریں۔ سورس کوڈ بلڈ کریں اور ٹیسٹ چلائیں۔

بنیادی باتیں

cmake
انحصارات ترتیب دیتا ہے اور پروجیکٹ کمپائل کرتا ہے۔
ctest
کیمرہ کھولے بغیر خودکار جانچ چلاتا ہے۔
Terminalbash
unzip badbob-playground-cpp.zip
cd badbob-playground-cpp
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel
ctest --test-dir build -C Release --output-on-failure
03.02

ماڈل جوڑیں

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

بنیادی باتیں

read_labels(path)
ماڈل کی کلاس ترتیب میں نام پڑھتا ہے؛ خالی یا دہرائے گئے لیبل مسترد کرتا ہے۔
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
opencv_detector.cppcpp
#include "badbob/opencv_detector.hpp"
#include <fstream>
#include <opencv2/imgproc.hpp>
#include <set>
#include <stdexcept>

namespace badbob {

std::vector<std::string> read_labels(const std::filesystem::path &path) {
    std::ifstream input(path);

    if (!input) {
        throw std::invalid_argument("Cannot open labels file");
    }

    std::vector<std::string> labels;
    std::set<std::string> unique;
    std::string line;

    while (std::getline(input, line)) {
        const auto first = line.find_first_not_of(" \t\r"), last = line.find_last_not_of(" \t\r");

        if (first == std::string::npos) {
            throw std::invalid_argument("Labels must have no empty lines");
        }

        line = line.substr(first, last - first + 1);

        if (line.size() > 120 || line.find_first_of("\n\t") != std::string::npos ||
            !unique.insert(line).second) {
            throw std::invalid_argument(
                "Labels must be unique, single-line names of at most 120 bytes");
        }

        labels.push_back(line);

        if (labels.size() > 1024) {
            throw std::invalid_argument("At most 1024 classes are supported");
        }
    }

    if (input.bad() || labels.empty()) {
        throw std::invalid_argument("Cannot read nonempty labels file");
    }

    return labels;
}

OpenCVDetector::OpenCVDetector(const std::filesystem::path &model, std::size_t classes)
    : classes_(classes) {
    if (model.extension() != ".onnx" || !std::filesystem::is_regular_file(model) || classes == 0 ||
        classes > 1024) {
        throw std::invalid_argument("Provide an existing .onnx detector and 1–1024 labels");
    }

    network_ = cv::dnn::readNetFromONNX(model.string());
    network_.setPreferableBackend(cv::dnn::DNN_BACKEND_OPENCV);
    network_.setPreferableTarget(cv::dnn::DNN_TARGET_CPU);
    outputs_ = network_.getUnconnectedOutLayersNames();

    if (outputs_.size() != 1) {
        throw std::invalid_argument("Expected exactly one detector output");
    }

    // Fail before camera acquisition if the model cannot consume this exact input
    // contract.
    (void)detect(cv::Mat(640, 640, CV_8UC3, cv::Scalar(114, 114, 114)));
}

std::vector<Detection> OpenCVDetector::detect(const cv::Mat &image) {
    if (image.empty() || image.type() != CV_8UC3) {
        throw std::invalid_argument("Expected a nonempty 8-bit BGR image");
    }

    const auto t = letterbox({image.cols, image.rows});
    cv::Mat resized;
    cv::resize(image, resized, {t.resized.width, t.resized.height});
    cv::Mat padded(t.edge, t.edge, CV_8UC3, cv::Scalar(114, 114, 114));
    resized.copyTo(padded(cv::Rect(t.left, t.top, t.resized.width, t.resized.height)));
    // RGB, NCHW float32, no crop. These values are part of the model contract.
    const auto blob =
        cv::dnn::blobFromImage(padded, 1.0 / 255.0, {640, 640}, {}, true, false, CV_32F);
    network_.setInput(blob);
    cv::Mat output = network_.forward(outputs_.front());

    if (output.dims != 3 || output.type() != CV_32F || output.size[0] != 1 ||
        output.size[1] != static_cast<int>(4 + classes_) || output.size[2] <= 0) {
        throw std::invalid_argument("Expected float32[1,4+C,N], XYWH plus class "
                                    "probabilities; no objectness or embedded NMS");
    }

    if (!output.isContinuous()) {
        output = output.clone();
    }

    return decode({output.ptr<float>(), output.total()}, classes_,
                  static_cast<std::size_t>(output.size[2]), t);
}

} // namespace badbob
03.03

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

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

بنیادی باتیں

Runner::run(...)
ایک ہی ورکر تھریڈ پر کیمرے کی تصاویر اور انفرنس سنبھالتا ہے۔
Runner::take()
تازہ ترین مکمل تصویر اور اس کی شناختیں حاصل کرتا ہے؛ نتائج قطار میں جمع نہیں ہو سکتے۔
یاد رکھیں
علامت
پیش منظر پیچھے رہ جاتا ہے اور میموری کا استعمال بڑھتا ہے۔
وجہ
کیمرہ استدلال کی کارروائی سے زیادہ تیزی سے فریم دیتا ہے، اس لیے لامحدود قطار بڑھتی جاتی ہے۔
حل
کیپچر اور انفرنس ایک ہی ترتیبی ورکر تھریڈ پر چلتے ہیں۔ انٹرفیس کو صرف تازہ ترین مکمل تصویر اور اس کی شناختیں ملتی ہیں۔
مزید تفصیل

ڈسٹرکٹر ~Runner() رکنے کی درخواست کرتا ہے اور ورکر تھریڈ کا انتظار کرتا ہے۔ صفائی مکمل ہونے سے پہلے جاری OpenCV کال کا واپس آنا ضروری ہے۔

runner.cppcpp
#include "badbob/runner.hpp"
#include <exception>
#include <stdexcept>
#include <utility>

namespace badbob {

Runner::Runner(SourceFactory source, DetectorFactory detector)
    : worker_(&Runner::run, this, std::move(source), std::move(detector)) {}

Runner::~Runner() {
    stopped_.store(true);

    // A backend read/forward may still be blocking. Never detach a live owner.
    if (worker_.joinable()) {
        worker_.join();
    }
}

void Runner::run(SourceFactory source, DetectorFactory detector) noexcept {
    try {
        auto model = detector();

        if (!model) {
            throw std::runtime_error("Missing detector adapter");
        }

        if (stopped_.load()) {
            return;
        }

        auto frames = source();

        if (!frames) {
            throw std::runtime_error("Missing capture adapter");
        }

        while (!stopped_.load()) {
            auto image = frames->next();

            if (stopped_.load()) {
                break;
            }

            if (image.empty()) {
                throw std::runtime_error("Camera returned an empty frame");
            }

            auto detections = model->detect(image);

            if (stopped_.load()) {
                break;
            }

            result_.publish({std::move(image), std::move(detections), {}});
        }
    } catch (const std::exception &error) {
        if (!stopped_.load()) {
            result_.publish({{}, {}, error.what()});
        }
    } catch (...) {
        if (!stopped_.load()) {
            result_.publish({{}, {}, "Unknown capture/inference failure"});
        }
    }
}

} // namespace badbob
03.04

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

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

بنیادی باتیں

letterbox(...) · unproject(...)
تناسب برقرار رکھتا ہے اور باکس کو اصل تصویر کے کوآرڈینیٹس میں واپس بدلتا ہے۔
decode(...)
پیش گوئیوں کی جانچ کرتا ہے اور ایک ہی کلاس کے اوورلیپ ہوتے باکس ہٹاتا ہے۔
یاد رکھیں

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

detection.cppcpp
#include "badbob/detection.hpp"
#include <algorithm>
#include <cmath>
#include <limits>
#include <stdexcept>

namespace badbob {
namespace {

void validate(const Letterbox &t) {
    if (t.original.width <= 0 || t.original.height <= 0 || t.resized.width <= 0 ||
        t.resized.height <= 0 || t.edge <= 0 || t.resized.width > t.edge ||
        t.resized.height > t.edge || t.left < 0 || t.top < 0 || t.left > t.edge - t.resized.width ||
        t.top > t.edge - t.resized.height) {
        throw std::invalid_argument("Invalid letterbox geometry");
    }
}

double intersection_over_union(Box a, Box b) {
    const double w = std::max(0.0, std::min(a.x + a.width, b.x + b.width) - std::max(a.x, b.x));
    const double h = std::max(0.0, std::min(a.y + a.height, b.y + b.height) - std::max(a.y, b.y));
    const double intersection = w * h;
    const double area = a.width * a.height + b.width * b.height - intersection;

    return area > 0 ? intersection / area : 0;
}

} // namespace

Letterbox letterbox(Size size, int edge) {
    if (size.width <= 0 || size.height <= 0 || edge <= 0 || edge > 4096) {
        throw std::invalid_argument(
            "Image and input dimensions must be positive; input edge <=4096");
    }

    const double ratio = std::min(double(edge) / size.width, double(edge) / size.height);
    const Size resized{std::max(1, int(std::lround(size.width * ratio))),
                       std::max(1, int(std::lround(size.height * ratio)))};

    return {size, resized, (edge - resized.width) / 2, (edge - resized.height) / 2, edge};
}

Box unproject(Box b, const Letterbox &t) {
    validate(t);

    if (!std::isfinite(b.x) || !std::isfinite(b.y) || !std::isfinite(b.width) ||
        !std::isfinite(b.height) || !std::isfinite(b.x + b.width) ||
        !std::isfinite(b.y + b.height) || b.width < 0 || b.height < 0) {
        throw std::invalid_argument("Box coordinates must be finite with nonnegative dimensions");
    }

    const auto x = [&](double v) {
        return std::clamp((v - t.left) / t.resized.width, 0.0, 1.0) * t.original.width;
    };
    const auto y = [&](double v) {
        return std::clamp((v - t.top) / t.resized.height, 0.0, 1.0) * t.original.height;
    };
    const double left = x(b.x), top = y(b.y);

    return {left, top, x(b.x + b.width) - left, y(b.y + b.height) - top};
}

std::vector<Detection> decode(std::span<const float> data, std::size_t classes, std::size_t count,
                              const Letterbox &t, float confidence, float overlap) {
    validate(t);

    if (classes == 0 || classes > 1024 || count == 0 || count > 100000 ||
        data.size() != (4 + classes) * count || !std::isfinite(confidence) ||
        !std::isfinite(overlap) || confidence < 0 || confidence > 1 || overlap < 0 || overlap > 1) {
        throw std::invalid_argument("Expected [1,4+C,N] probabilities, C<=1024, "
                                    "N<=100000 and thresholds in [0,1]");
    }

    std::vector<Detection> candidates;

    for (std::size_t i = 0; i < count; ++i) {
        const double cx = data[i], cy = data[count + i], w = data[2 * count + i],
                     h = data[3 * count + i];

        if (!std::isfinite(cx) || !std::isfinite(cy) || !std::isfinite(w) || !std::isfinite(h) ||
            w < 0 || h < 0) {
            throw std::invalid_argument("Unsupported detector coordinates");
        }

        float score = 0;
        std::size_t label = 0;

        for (std::size_t c = 0; c < classes; ++c) {
            const float probability = data[(4 + c) * count + i];

            if (!std::isfinite(probability) || probability < 0 || probability > 1) {
                throw std::invalid_argument(
                    "Expected probabilities in [0,1], not logits/objectness");
            }

            if (probability > score) {
                score = probability;
                label = c;
            }
        }

        if (score < confidence) {
            continue;
        }

        const auto box = unproject({cx - w / 2, cy - h / 2, w, h}, t);

        if (box.width > 0 && box.height > 0) {
            candidates.push_back({box, label, score});
        }
    }

    std::stable_sort(candidates.begin(), candidates.end(), [](const auto &a, const auto &b) {
        return a.score > b.score;
    });
    // Bound quadratic suppression work; keep the highest-scoring candidates
    // first.
    if (candidates.size() > 3000) {
        candidates.resize(3000);
    }

    std::vector<Detection> selected;

    for (const auto &candidate : candidates) {
        const bool suppressed =
            std::any_of(selected.begin(), selected.end(), [&](const auto &previous) {
                return previous.label == candidate.label &&
                       intersection_over_union(previous.box, candidate.box) > overlap;
            });

        if (!suppressed) {
            selected.push_back(candidate);
        }

        if (selected.size() == 300) {
            break;
        }
    }

    return selected;
}

} // namespace badbob
03.05

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

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

بنیادی باتیں

parse(argc, argv)
آرگیومنٹس کی جانچ کرتا ہے اور صرف ایک ان پٹ چنتا ہے: تصویر یا کیمرہ۔
run_image(...) · run_camera(...)
منتخب طریقہ چلاتا ہے؛ کیمرہ موڈ پروسیسنگ Runner کو سونپتا ہے۔
یاد رکھیں
علامت
رکنے میں توقع سے زیادہ وقت لگتا ہے۔
وجہ
OpenCV کی کیپچر یا انفرنس کال اب بھی عمل روک رہی ہے۔
حل
رکنے کی درخواست کریں، نئے نتائج مسترد کریں اور ورکر ختم ہونے کا انتظار کریں۔ بیک اینڈ ٹائم آؤٹ کے لیے پلیٹ فارم سپورٹ چاہیے؛ فعال وسائل والے تھریڈ کو الگ نہ کریں۔
مزید تفصیل

write_new_png() خصوصی طور پر نئی فائل بناتا ہے؛ موجودہ فائل کو کبھی اوور رائٹ نہیں کرتا۔

Terminalbash
./build/badbob-camera --model detector.onnx --labels labels.txt --image frame.png --output result.png
./build/badbob-camera --model detector.onnx --labels labels.txt --camera 0

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

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

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