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-failure03.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: falseopencv_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 badbob03.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 badbob03.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 badbob03.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 003.06 / 最佳实践
做好细节,写好示例。
- 让采集和推理远离界面线程。限制队列长度,不要堆积旧帧。
- 将图像尺寸、裁剪、方向和坐标作为统一约定。先用已知检测框测试,再信任画面标注。
- 请求停止、拒绝新结果,并等待工作线程结束。后端超时需要平台支持;切勿分离仍在使用资源的线程。