BadBob / Playground
OpenCV · ONNX · MIT
03.01

Projekt vorbereiten

Installiere CMake und OpenCV 4.x. Baue den Quellcode und führe die Tests aus.

Grundlagen

cmake
Konfiguriert Abhängigkeiten und kompiliert das Projekt.
ctest
Führt automatische Prüfungen aus, ohne die Kamera zu öffnen.
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

Dein Modell verbinden

Prüfe Modell und Klassenbezeichnungen, bevor eine Kamera geöffnet wird.

Grundlagen

read_labels(path)
Liest Klassennamen in Modellreihenfolge; lehnt leere oder doppelte Bezeichnungen ab.
OpenCVDetector::detect(image)
Bereitet das Bild vor, führt das Modell aus und liefert Erkennungen zurück.
Gut zu wissen
Symptom
Boxen verrutschen oder das Modell lässt sich nicht laden.
Ursache
Vorverarbeitung, Ausgabeformat oder Klassenreihenfolge stimmt nicht überein.
Abhilfe
Dieser Adapter unterstützt nur den folgenden Vertrag. Core-ML-Dateien und andere ONNX-Ausgabeformate benötigen einen anderen Adapter.

Dieser Adapter unterstützt nur den folgenden Vertrag. Core-ML-Dateien und andere ONNX-Ausgabeformate benötigen einen anderen Adapter.

Vertiefung

Koordinaten beschreiben Boxmittelpunkte und Größen in den 640×640 Eingabepixeln. Die Bezeichnungen folgen exakt der Klassenreihenfolge des Modells.

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

Kamera einbinden

Aufnahme und Inferenz teilen einen seriellen Arbeitsthread. Die Oberfläche erhält nur das neueste fertig verarbeitete Bild mit seinen Erkennungen.

Grundlagen

Runner::run(...)
Verarbeitet Aufnahme und Inferenz in einem Arbeitsthread.
Runner::take()
Holt das neueste fertige Bild samt Erkennungen; Ergebnisse können sich nicht in einer Warteschlange ansammeln.
Gut zu wissen
Symptom
Die Vorschau hinkt hinterher und der Speicherbedarf wächst.
Ursache
Die Kamera liefert Bilder schneller, als die Inferenz sie verarbeitet. Dadurch wächst eine unbegrenzte Warteschlange.
Abhilfe
Aufnahme und Inferenz teilen einen seriellen Arbeitsthread. Die Oberfläche erhält nur das neueste fertig verarbeitete Bild mit seinen Erkennungen.
Vertiefung

Der Destruktor ~Runner() fordert einen Stopp an und wartet auf den Arbeitsthread. Ein laufender OpenCV-Aufruf muss zurückkehren, bevor die Bereinigung abgeschlossen werden kann.

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

Vorhersagen richtig platzieren

Rechne Letterbox-Skalierung und Auffüllung zurück und begrenze Boxen vor dem Zeichnen auf das Bild.

Grundlagen

letterbox(...) · unproject(...)
Bewahrt das Seitenverhältnis und rechnet Boxen auf das Originalbild zurück.
decode(...)
Prüft Vorhersagen und entfernt überlappende Boxen derselben Klasse.
Gut zu wissen

Behandle Bildgröße, Zuschnitt, Ausrichtung und Koordinaten als gemeinsamen Vertrag. Teste bekannte Rahmen, bevor du der Einblendung vertraust.

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

Bauen. Starten. Modell testen.

Wähle ausdrücklich eine Kamera oder verarbeite ein Bild offline. Q oder Escape beendet die Verarbeitung.

Grundlagen

parse(argc, argv)
Prüft Argumente und wählt genau eine Eingabe: Bild oder Kamera.
run_image(...) · run_camera(...)
Führt den gewählten Ablauf aus; im Kameramodus übernimmt Runner die Verarbeitung.
Gut zu wissen
Symptom
Das Beenden dauert länger als erwartet.
Ursache
Ein OpenCV-Aufnahme- oder Inferenzaufruf blockiert noch.
Abhilfe
Fordere das Beenden an, verwerfe neue Ergebnisse und warte auf den Arbeitsthread. Backend-Zeitlimits brauchen Plattformunterstützung; trenne niemals aktive Ressourcen ab.
Vertiefung

write_new_png() erstellt exklusiv eine neue Datei; vorhandene Dateien werden nie überschrieben.

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 / Bewährte Vorgehensweisen

Kleine Details. Bessere Beispiele.

  • Halte Aufnahme und Inferenz vom UI-Thread fern. Begrenze die Warteschlange, statt alte Frames anzusammeln.
  • Behandle Bildgröße, Zuschnitt, Ausrichtung und Koordinaten als gemeinsamen Vertrag. Teste bekannte Rahmen, bevor du der Einblendung vertraust.
  • Fordere das Beenden an, verwerfe neue Ergebnisse und warte auf den Arbeitsthread. Backend-Zeitlimits brauchen Plattformunterstützung; trenne niemals aktive Ressourcen ab.