3.3 深度学习箱体识别与实例分割模块(DlSeg SDK)
头文件:include/CubeBraidSDK/DL_SDK/DlSegSdk.h
命名空间:dlseg_sdk;Python 封装:scripts/DL_SDK/dlseg_sdk.py。
DlSegSDK 加载 ONNX 实例分割模型,对输入图像中的箱体进行识别,输出目标类别、置信度、边框和掩膜。一次推理同时返回带识别框、标签及掩膜的可视化图,以及供后续图像处理使用的全局纯净掩膜。识别类别由所加载的模型决定。
3.3.1 模型与运行环境
模型与类别文件
官方 v1.4 发布页 提供 unload.onnx 箱体分割模型和 Windows 依赖包。仓库中的示例使用以下工作目录结构:
scripts/DL_SDK/
├── dlseg_sdk.py
├── dlseg_sdk_img_demo.py
├── dlseg_sdk_cam_demo.py
└── data/
├── models/
│ ├── unload.onnx
│ └── classes.txt
└── img/
├── demo.png
└── output_masks/
unload.onnx 需从发布页下载;classes.txt 按模型的类别 ID 顺序逐行填写类别名称。模型和类别文件不随 Git 源码目录自动生成。net_width、net_height 应与模型导出时的输入尺寸一致。
运行依赖
C++:C++14、OpenCV 开发文件,以及配套的 DlSegSDK 动态库与导入库。
Python:
numpy、opencv-python,通过仓库中的dlseg_sdk.py加载原生动态库。原生推理运行时:ONNX Runtime;使用 CUDA 时还需与发行库匹配的 NVIDIA 驱动、CUDA 和 cuDNN 运行时。
Windows 使用
bin/DlSegSDK.dll和lib/win/DlSegSDK.lib;Linux 使用lib/linux/libDlSegSDK.so。当前lib/linux_arm未提供该模块。
Python 封装默认从 SDK 根目录的 build/SDK_Demos 加载动态库。运行前须将 DlSegSDK 及其配套依赖部署到该目录,或通过 DlSegSDK(lib_path=...) 指定库文件,并配置对应的动态库搜索路径。顶层 CMake 构建不会自动完成这些运行库和模型的部署。
use_cuda = false``(Python 为 ``0)选择 CPU;true``(``1)选择 CUDA,设备由 cuda_id 指定。初始化或推理失败时应读取错误信息,再检查模型路径和运行时依赖。
模型导出
scripts/DL_SDK/pt_to_onnx/pt_to_onnx.py 使用 Ultralytics 将实例分割权重导出为 ONNX。仅在需要转换自有模型时安装 ultralytics;原生 SDK 推理不通过该 Python 包执行。
from ultralytics import YOLO
model = YOLO("best_11.pt")
model.export(format="onnx")
3.3.2 初始化配置与状态码
SdkConfig 的字段及默认值如下,Python initialize 使用同名参数:
字段 |
默认值 |
用途 |
|---|---|---|
|
空字符串 |
ONNX 模型文件路径。 |
|
空字符串 |
类别名称文本文件路径,每行一个名称。 |
|
|
是否使用 CUDA,以及 GPU 设备编号。 |
|
|
初始化时执行模型预热。 |
|
|
模型输入宽高,单位为像素。 |
|
|
类别置信度阈值。 |
|
|
非极大值抑制阈值。 |
|
|
掩膜二值化阈值。 |
|
|
推理批大小。 |
仓库图片示例使用 class_threshold=0.94、mask_threshold=0.25,摄像头示例使用 class_threshold=0.25、mask_threshold=0.25;这些是示例配置,不是接口默认值。
StatusCode 定义如下:
值 |
枚举 |
含义 |
|---|---|---|
0 |
|
执行成功。 |
1 |
|
模型加载失败。 |
2 |
|
模型推理失败。 |
3 |
|
参数无效。 |
4 |
|
点云处理错误。 |
5 |
|
算法处理失败。 |
99 |
|
内部错误。 |
C++ 使用 getLastError()、getLastStatus() 和 statusToString(status) 查询诊断信息;Python 使用 get_last_error() 和 get_last_status()。模型加载采用异步方式,仓库示例说明 detect 会等待加载完成;示例中的两秒等待用于推理计时准备,不是调用接口的必要步骤。
3.3.3 检测接口与结果输出
C++ 接口
StatusCode initialize(const SdkConfig& config);
StatusCode detect(cv::Mat& img, std::vector<OutputParams>& output,
cv::Mat& canvas, cv::Mat& mask_img);
StatusCode SaveMask(cv::Mat& img, const std::vector<OutputParams>& result,
const std::string& save_path,
const std::string& file_name);
OutputParams 包含类别 id、置信度 confidence、轴对齐矩形 box、旋转矩形 rotatedBox 和框内掩膜 boxMask。矩形坐标与尺寸使用图像像素单位。SaveMask 按识别结果提取并保存掩膜图片;保存 detect 返回的全局掩膜则可直接使用 cv::imwrite。
Python 接口
count, boxes, rendered_img, mask_img = segmenter.detect(img, max_boxes=100)
status = segmenter.save_mask(img, boxes, save_path, file_name)
输入 img 使用 OpenCV 的 BGR 三通道 uint8 图像,形状为 (height, width, 3)。封装内部将输入转换为连续内存。返回值说明如下:
返回项 |
含义 |
|---|---|
|
非负数表示检测到的目标数量, |
|
|
|
形状为 |
|
形状为 |
Python 目标结构不单独返回 C++ 的 rotatedBox 和 boxMask;可视化图与全局掩膜通过独立数组返回。使用上下文管理器时自动创建和销毁句柄;手动管理时依次调用 create()、initialize()、detect()、destroy()。
3.3.4 C++ 调用例程(dlseg_sdk_demo.cpp)
顶层 CMake 创建 dlseg_sdk_demo 目标,输出到 build/SDK_Demos。原示例读取 ./data/models/unload.onnx、classes.txt 和 ./data/img/demo.png,输出可视化图 result_mask.png 与全局掩膜 global_pure_mask.png。运行前准备对应工作目录和输出目录。
以下最小示例使用 CPU 推理,将两种输出保存到当前目录:
#include <iostream>
#include "CubeBraidSDK/DL_SDK/DlSegSdk.h"
int main()
{
dlseg_sdk::DlSegSdk segmenter;
dlseg_sdk::SdkConfig config;
config.model_path = "./data/models/unload.onnx";
config.class_names_path = "./data/models/classes.txt";
config.use_cuda = false;
if (segmenter.initialize(config) != dlseg_sdk::StatusCode::SUCCESS) {
std::cerr << segmenter.getLastError() << '\n';
return 1;
}
cv::Mat image = cv::imread("./data/img/demo.png");
if (image.empty()) return 1;
std::vector<dlseg_sdk::OutputParams> targets;
cv::Mat rendered, mask;
if (segmenter.detect(image, targets, rendered, mask)
!= dlseg_sdk::StatusCode::SUCCESS) {
std::cerr << segmenter.getLastError() << '\n';
return 1;
}
std::cout << "目标数量: " << targets.size() << '\n';
const bool image_saved = cv::imwrite("recognition.png", rendered);
const bool mask_saved = cv::imwrite("mask.png", mask);
return image_saved && mask_saved ? 0 : 1;
}
3.3.5 Python 图片分割例程(dlseg_sdk_img_demo.py)
在 scripts/DL_SDK 目录运行。下面的片段使用上下文管理器释放句柄,保存可视化图和全局掩膜;先按本节运行环境部署原生库与模型:
from pathlib import Path
import cv2
from dlseg_sdk import DlSegSDK
image = cv2.imread("./data/img/demo.png")
if image is None:
raise RuntimeError("无法读取输入图像")
output = Path("./data/img/output_masks")
output.mkdir(parents=True, exist_ok=True)
with DlSegSDK() as segmenter:
status = segmenter.initialize(
model_path="./data/models/unload.onnx",
class_names_path="./data/models/classes.txt",
use_cuda=0)
if status != 0:
raise RuntimeError(segmenter.get_last_error())
count, boxes, rendered, mask = segmenter.detect(image, max_boxes=100)
if count < 0:
raise RuntimeError(segmenter.get_last_error())
print(f"目标数量: {count}")
for box in boxes:
print(box)
if not cv2.imwrite(str(output / "recognition.png"), rendered):
raise RuntimeError("可视化图保存失败")
if not cv2.imwrite(str(output / "mask.png"), mask):
raise RuntimeError("掩膜图保存失败")
原仓库示例默认使用 CUDA,输出 python_rotated_mask_result.png 和 global_pure_segmentation_mask.png。模型、类别文件和图片路径相对于启动程序时的工作目录解析。
3.3.6 Python 摄像头实时分割例程(dlseg_sdk_cam_demo.py)
摄像头示例使用 cv2.VideoCapture(0) 打开视频设备,申请 1280×720 分辨率;实际输出尺寸由设备决定。模型初始化后循环读取 BGR 图像,执行 detect,在可视化图上显示目标数量和分割结果。按 q 或 Esc 退出,结束时释放摄像头并关闭窗口。
完成模型和运行库部署后,在 scripts/DL_SDK 执行:
python dlseg_sdk_cam_demo.py
实时示例使用本机视频设备,不直接连接工业 3D 相机。无图形界面的环境可使用图片分割示例保存结果;接入其他图像源时,先转换为 BGR 三通道 uint8 图像,再调用同一检测接口。