BadBob / Playground
OpenCV · ONNX · MIT

03 / C++

C++। मॉडल से कैमरे तक।

लाइव एनोटेशन और सीमित फ़्रेम प्रोसेसिंग के साथ अपना ONNX डिटेक्टर स्थानीय रूप से चलाएँ।

ये उदाहरण नियंत्रित परिवेश में वस्तुओं और जानवरों पर केंद्रित हैं। इनमें लोगों की निगरानी, पहचान या व्यवहार का विश्लेषण शामिल नहीं है।

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 थ्रेड से बाहर रखें। पुराने फ़्रेम जमा करने के बजाय कतार सीमित रखें।
  • चित्र का आकार, क्रॉप, दिशा और निर्देशांक एक साझा नियम मानें। चिह्नों पर भरोसा करने से पहले ज्ञात बॉक्स से जाँचें।
  • रुकने का अनुरोध करें, नए परिणाम अस्वीकार करें और वर्कर के समाप्त होने का इंतज़ार करें। बैकएंड टाइमआउट के लिए प्लेटफ़ॉर्म सपोर्ट चाहिए; सक्रिय संसाधनों वाले थ्रेड को अलग न करें।