C++ SDK开发文档
约 4834 字大约 16 分钟
版本:0.0.2
当前包平台:windows_x64
本文讲解二进制 SDK 的集成和使用,不要求用户拥有 SDK 源码或重新编译驱动。本文中的命名空间为 dexsense,公共头文件为 dexsense/dexsense.h。
1. 集成和部署
通过 find_package(DexSense 0.0.2 EXACT CONFIG REQUIRED) 查找包,链接 dexsense::dexsense,并启用 C++17。随包示例的 examples/CMakeLists.txt 展示了完整接入方式。CMAKE_PREFIX_PATH 设置为当前平台 SDK 根目录即可,使用 CMake 导出目标可以统一获得包含目录和链接信息。
编译成功并不意味着系统已经能在运行时找到库:
| 平台 | 链接时使用 | 运行时部署 |
|---|---|---|
| Windows x64 | lib/ 中的导入库及导出目标 | 将本包 bin/ 加到当前进程 PATH,或将其中所需 DLL 放到应用程序旁;保持匹配的 MSVC 运行库 |
| Linux | lib/ 中的链接名和导出目标 | 开发时使用 LD_LIBRARY_PATH;发布时将 SO 放到应用目录的 lib/ 并为程序设置相对 RPATH |
Linux 发布应用的一种目录布局是 app/bin/my_camera_app 和 app/lib/lib*.so*,在应用 CMake 中对可执行目标设置 INSTALL_RPATH "$ORIGIN/../lib"。$ORIGIN 指运行时该可执行文件所在目录;设置该值不会自动复制 SDK 库,也不会改变其他库自己的依赖搜索路径。安装部署时保留完整 SO 文件及版本符号链接链,不要只复制未带版本的 .so 链接。ldd <应用> 可用于确认有没有缺失的运行库。
不要用 Windows 库在 Linux 链接,也不要混用 x64 与 ARM64 库。同一包里的头文件、库、示例和文档对应同一版本。二进制 ABI 或系统运行库不兼容时,应选择匹配的发布包。
2. 对象与生命周期
常规调用流程为 Context → IDiscoveredDevice → open() → Camera → capture() → Frame:
Context提供发现、按 IP 定位和日志设置。IDiscoveredDevice::info()是发现阶段的信息;open()返回已初始化的Camera。连接后的固件版本等详细信息从Camera::getDeviceInfo()获取。Camera只能移动,不能复制;它持有连接、心跳和采集资源。结束时停止流、等待异步任务,然后从外部控制线程调用disconnect()。Frame持有本帧数据。getImage()、getDepthMap()、getPointCloud()返回帧内对象的常量引用;使用这些引用和data()指针时,必须保证对应对象及底层数据仍存活。应用若要跨线程长期持有数据,可保留Frame或自行复制数据。camera.parameters()返回的引用依附于该相机,不能在相机销毁后使用。
同一台相机的采集与参数操作由应用协调串行执行。不要将单个相机对象视为允许任意并发调用的通用线程安全对象;尤其应避免采集期间从其他线程修改 KV 参数。
3. 发现、直连和网络设置
discoverDevices(timeout) 使用广播发现网络相机。空列表只表示本次没发现,不代表相机一定离线;广播可能受到网段、防火墙、网卡选择或网络环境影响。示例的 --discover 只列出信息,不自动连接列表里的第一台相机。
const auto devices = context.discoverDevices(std::chrono::milliseconds(3000));
for (const auto& device : devices)
{
const auto info = device->info();
std::cout << info.model << " IP=" << info.ip << " MAC=" << info.mac << '\n';
}
std::cout << "Discovered " << devices.size() << " device(s).\n";已知 IP 和型号时,优先使用 findByIp(ip, DeviceModel::Xema/Finch/..., timeout),再调用 open()。这个重载只按指定型号构造设备入口,不走广播,也不验证此刻设备是否可达;实际 TCP 连接、握手和驱动初始化发生在 open()。只传 IP 的重载先执行设备发现,再按 IP 过滤结果,没有 TCP 自动探测或降级直连;跨网段广播不可达时,应显式指定型号。
显式型号重载的 timeout 传给底层连接,TCP 建连、协议握手和驱动初始化共享这段时限。驱动初始化结束后恢复普通业务超时,随后包装 Camera 时仍可能读取初始参数,因此它不是整个 open() 墙钟耗时的严格上限,也不是每次 capture() 的超时设置。
USB 设备使用另一条入口:支持的平台和型号可调用 findByDevicePath(),例如 Linux KFC V4L2 设备路径。不要把网络 IP 传给 USB 接口;findByUsbId() 是预留入口,不可据其存在假定已经实现 USB 枚举。
setDeviceIp() 和 setDeviceDhcp() 用于网络地址配置,应传入发现得到的完整 DeviceInfo。调用成功只表示配置报文从主机发出,之后要按 MAC 重新发现并核对最终地址。修改地址可能中断当前会话,应作为独立配置操作执行,不在采集循环中调用。
4. 参数设置:整体 Settings 与键值接口
两套接口共用相机驱动,但用途不同。
| 需求 | 使用方式 | 注意事项 |
|---|---|---|
| 设置曝光、增益、滤波结构体或 HDR 组 | 获取 Settings,修改字段后 applySettings() | 差分下发;必须检查返回结果,不是原子事务 |
| 交互修改单个常用参数 | setExposureMs()、setGainDb() 等便捷方法 | 仍返回 ApplySettingsResult,不可丢弃 |
| 使用设备扩展参数 | parameters().setFloat() / setInt() | 先 hasKey(),类型和范围依据接口参考及设备描述 |
| 查询固件或驱动是否提供某参数 | isParamSupported(ParamKey::...) | 不等同于每个参数都支持回读 |
| 构建参数界面 | getParamDescriptors() 与 parameters().keys() | 描述符键如 exposure_ms 与 KV 键 ExposureTime 不同,不能直接互换 |
Settings::defaults() 是 SDK 固定默认模板,不是设备出厂恢复命令,也不是当前相机真实参数。日常调整推荐从 camera.getSettings() 的当前缓存复制后修改。Settings::validate() 做本地基础范围校验,不保证当前硬件和固件接受该值。
统一接口 Settings::setExposureMs() 和 KV ExposureTime 的单位是 毫秒。FINCH 扩展 RgbExposure 的单位是 微秒,不能因为名称里都有 Exposure 就共用数值。枚举参数通过 setInt() 和对应枚举转换使用;布尔 KV 参数通常使用整数 0/1。结构体参数不通过 KV 读写,应使用 Settings 中的对应结构体。
对关键设置必须检查每项结果:
ParamStatus | 含义 | 应用处理 |
|---|---|---|
Applied | SDK 成功执行该项写入 | 关键参数继续回读核对 |
Skipped | 与缓存相同,差分跳过 | 不代表本次已发命令或已回读 |
Unsupported | 当前设备不支持 | isSuccess() 仍可为 true,业务要求此能力时应拒绝继续 |
Failed | 该项应用失败 | 检查错误详情,处理部分成功的状态 |
applySettings() 逐项处理,部分失败不会回滚已经成功的参数。当前实现只将已应用的设备参数同步到 Settings 缓存;采集模式和重复次数是客户端设置,另外更新缓存。整体结果也可能列出本型号不支持、且本次没有修改的其他字段。快速入门对任何 Failed 项停止后续采集;对 Unsupported 则检查是否属于本次明确请求的必需参数,避免把设备原本不具备的可选字段当作拍照失败。
5. 缓存、回读和保存配置
必须区分“希望设置成什么”和“设备实际返回什么”:
getSettings()不访问设备,只返回 SDK 缓存,不是参数验收证据。readSettingsFromDevice()尝试读取 Settings 覆盖的设备参数并更新缓存。当前批量读取对单项读取异常会跳过,未读取成功的字段可能保留默认值,且不覆盖纯 KV 扩展参数。因此不能把返回一份 Settings 理解为所有字段都已成功回读。KV
getFloat()/getInt()调用驱动读取,并保留异常;对关键可读参数应显式调用并与目标值比较。具体驱动的客户端参数或只写参数不一定有设备回读能力。KV
setFloat()/setInt()会记住此前成功写入的值,重复值可能跳过下发;部分标准参数写入后同步 Settings 缓存。KV 读取不会自动把所有扩展参数合并进 Settings。
auto& parameters = camera.parameters();
if (parameters.hasKey("ExposureTime"))
{
// ExposureTime 在统一接口中的单位为 ms;调用驱动回读,不是 getSettings() 缓存。
const float actualExposureMs = parameters.getFloat("ExposureTime");
std::cout << "ExposureTime readback=" << actualExposureMs << " ms\n";
}hasKey() 表示该 KV 参数可用于当前设备,不保证同时支持读取。只写参数的 get*() 可能抛 NotSupportedError。外部程序修改设备、重新连接或不同配置入口交替使用时,不要假定缓存已自动感知变化;关键值单独回读,必要时重建会话再配置。不要通过反复设置同一个值来当作强制重发机制。
Settings 提供 saveToFile()/loadFromFile()、YAML 和 JSON 序列化。这些保存的是 Settings 覆盖的字段,不包含所有纯 KV 扩展参数,也不是无损设备配置备份。若业务使用 CaptureEngine、CameraSelect 等扩展项,应在自己的配置格式中保存,并在加载时检查支持能力后重新应用。序列化配置不要与设备标定文档混为一谈。
6. 采集、图像、深度和点云
调用 capture() 前先完成参数设置。采集使用当前设备参数及客户端采集设置,不会把全部 Settings 再下发一遍。取得帧后分别检查所需数据的 isEmpty(),frame.isEmpty()==false 不保证图像、深度和点云全部存在。
| 数据 | 访问接口 | 布局与单位 |
|---|---|---|
| 结构光主图 | frame.getImage() | 检查宽、高、channels()、format();不能只根据通道数推断 RGB/BGR 顺序 |
| 双目左右图 | frame.getLeftImage() / getRightImage() | KFC 双目图使用独立左右图,getImage() 为空不是采集失败 |
| 深度图 | frame.getDepthMap() | float,按行排列,单位毫米;at(row,col) 按行列访问 |
| 点云 | frame.getPointCloud() | XYZ 交错 [x0,y0,z0,x1,y1,z1,...],单位毫米 |
灰度图、彩色图和 Bayer 原始图不是同一个概念。读取 PixelFormat 决定通道解释;交给 OpenCV 等第三方库显示时,按第三方要求处理 RGB/BGR,而不是一律交换通道。SDK 的 savePng() / saveBmp() 已处理其支持的 BGR 三通道保存转换;原始 Bayer 数据需按格式另行处理,不能只换扩展名就得到彩色图。
深度无效值需要过滤。SDK 的 isValid(row,col) 判断正值且非 NaN;业务计算还可用 std::isfinite() 排除无限值。不要把无效点当作零距离测量值。
frame.saveAll(directory) 会创建目录并保存帧中存在的内容:点云为 pointcloud.ply,结构光图为 brightness.png 或 color.png,双目图为 left.png 和 right.png。它不保存深度数组或 Settings,也不自动创建每帧独立子目录。保存单项可用 Image::savePng()/saveBmp()、PointCloud::saveToPly()/saveToPcd();按实际需求检查输出文件和磁盘空间。
快速入门用下面的应用侧函数补充深度 CSV,便于直接核对数据。生产中大图逐像素文本保存开销较大,可选择自己的二进制格式并同时记录宽、高、浮点类型和单位。
/**
* @brief 按图像行列保存毫米单位的深度 CSV,无效点写为 nan。
* @param depth 待保存的深度图。
* @param path 目标文件,父目录必须已存在。
* @throws std::runtime_error 文件创建或完整写入失败。
*/
void saveDepthCsv(const dexsense::DepthMap& depth, const std::filesystem::path& path)
{
if (depth.isEmpty()) return;
std::ofstream output(path);
if (!output) throw std::runtime_error("Cannot create depth CSV: " + path.string());
output << std::setprecision(std::numeric_limits<float>::max_digits10);
for (int row = 0; row < depth.height(); ++row)
{
for (int col = 0; col < depth.width(); ++col)
{
if (col != 0) output << ',';
const float value = depth.at(row, col);
if (depth.isValid(row, col) && std::isfinite(value))
output << value;
else
output << "nan";
}
output << '\n';
}
output.close();
if (!output) throw std::runtime_error("Cannot finish depth CSV: " + path.string());
}getCaptureSettings() 是帧关联的 SDK 设置快照,不包含完整 KV 扩展配置,也不是在曝光瞬间从所有设备寄存器读取的状态。getTimestamp() 返回 SDK 提供的文本时间戳;不要在未验证具体设备的时钟语义前用于严格的多相机硬件同步。
7. 按设备选择模式和参数
统一接口不代表每个型号、固件版本、传输方式支持同样功能。先通过 isFeatureSupported()、isParamSupported()、KV hasKey() 和参数描述符查询,然后参考包内对应型号的完整示例。
XEMA:基础采集见
xema_capture。CaptureEngine选择采集引擎,Settings::brightness()是亮度图生成相关配置,两者不可互相替代;主曝光、亮度图曝光也不能混为一个参数。颜色输出还与实际相机硬件和采集路径有关。应按示例设置所需路径,再检查返回图像格式,而不是仅设置一个“RGB 开关”就保证所有模式都输出彩色。FINCH:完整参数流程见
finch_capture。CameraSelect用CameraSelect::Gray/RGBHalf/RGBFull选择路径。Gamma、RGB 曝光/增益、块状外点滤波和深度补全等扩展项都需先检查支持情况。新固件功能可能在旧固件上不存在;不可仅按型号名推断所有参数可用。KFC:双目数据从左右图接口取;当前通用帧不凭空提供结构光深度和点云。USB 路径和以太网路径使用对应示例,能力受传输方式和固件约束。
HDR、重复采集、流式采集:
CaptureMode与设备的Feature::HDR、Feature::Streaming等能力相结合使用;HDR 组、LED 和曝光组合参见型号示例及hdr_yaml。先检查能力,再应用并检查结果。AI 结构光:使用支持该能力的设备、
Feature::AiStructuredLight及多模态接口。captureMultiModal()返回带角色和数据类别的信息,不能把子图列表当作固定顺序的普通 RGB 图。相机端标定与查找表使用专门接口读取;参见包内的相关型号示例(若本平台包包含)。
样例中演示的参数不是适合所有工件的生产默认值。特别是曝光、LED 和滤波,应结合自己的图像与点云结果验收。没有做过实机验证的设备或固件组合,不能因编译成功就认为已获得同等效果。
8. 异步与连续采集
captureAsync() 返回 std::future<Frame>:先提交一次采集,在当前线程处理上一帧,最后调用 future.get() 取结果。采集异常在 get() 处重新抛出。异步任务结束前不得移动、析构或断开它引用的 Camera;不要同时提交多个拍照请求来期望同一设备并行曝光。
startStreaming(callback) 前检查 isFeatureSupported(Feature::Streaming)。先完成配置,再启动流;SDK 工作线程逐帧调用回调。回调中应只做短时间的数据转交,例如把帧送入有容量限制的工作队列,避免磁盘保存或耗时算法阻塞采集。
当前实现调用帧回调时持有相机内部锁,因此不要在帧回调内调用该相机的 capture()、参数配置、getSettings()、stopStreaming() 或 disconnect();可能造成锁等待或线程等待自身。由外部控制线程观察状态/通知,调用 stopStreaming() 等待退出后再改参数、重启或断开。断连回调也应只报告事件,由外部线程处理恢复。应用应保证回调捕获的对象在停止完成前仍然有效,并妥善处理回调自己的异常。
流错误通过日志、流状态和可能的断连通知观察,不会自动变成调用 startStreaming() 的线程上的异常。退出应用前主动停止流,并处理队列内尚未完成的帧。
9. 标定读取与写入
getCalibration() 提供通用计算所需的标定视图,不等价于设备完整无损备份。无损导出使用 exportActiveCalibration() / exportOriginalCalibration(),能力先通过 isCalibrationOperationSupported() 查询。CalibrationDocument 带设备身份、固件版本、载荷格式、原始载荷及校验和,isValid() 校验载荷与校验和。
读标定和写标定必须区别对待。使用 importActiveCalibration() 前,先将当前 exportActiveCalibration() 返回的完整文档持久化到可靠存储,并保留设备身份、格式和校验和,不能用待导入文档覆盖写前备份。目标文档必须属于当前设备。完整校正写入使用 writeCorrectedCalibration() 及该型号要求的全部附件;某个字段存在不代表可以跳过其他必需附件。
写入、ACK 或回读失败时,设备可能已发生部分改变,不要假定 SDK 已自动回滚,也不要盲目重复写入。核对设备状态后再决定恢复方案。普通采集程序不需要执行标定写入;随包 calibration_inspect 用于了解读取流程,kfc_calibration_import 演示受控导入及备份要求。
getCalibrationFrameDescriptors() 查询具名标定帧的角色、索引、尺寸和原始像素格式,不触发拍照。captureCalibrationFrames() 返回实际数据;用角色和索引匹配,不依据数组位置猜测左右目或相移图。
10. 异常、日志和常见问题
SDK 异常继承自 dexsense::Exception,可读取 what() 和 errorCode()。连接失败、未找到设备、采集失败、参数错误、不支持和超时有各自的异常类型;ConnectionError 仅在 hasProtocolCode() 为 true 时附带原始协议码。批量参数失败则还必须检查 ApplySettingsResult,不能只依赖 try/catch。
文件系统和应用层代码也可能抛出标准异常。快速入门的处理示例同时保留 SDK 错误码,并在失败后尝试断开:
catch (const dexsense::ConnectionError& error)
{
std::cerr << "Connection error: " << error.what() << " code=" << error.errorCode();
if (error.hasProtocolCode()) std::cerr << " protocol=" << error.protocolCode();
std::cerr << '\n';
exitCode = 1;
}
catch (const dexsense::Exception& error)
{
std::cerr << "SDK error: " << error.what() << " code=" << error.errorCode() << '\n';
exitCode = 1;
}
catch (const std::exception& error)
{
std::cerr << "Application error: " << error.what() << '\n';
exitCode = 2;
}
// 发生 SDK、文件或命令行异常后也执行断开;Camera 析构进一步释放资源。
try
{
camera.disconnect();
}
catch (const std::exception& error)
{
std::cerr << "Disconnect error: " << error.what() << '\n';
exitCode = 1;
}| 现象 | 首先核对 |
|---|---|
find_package 找不到包 | 平台根目录是否正确,是否包含 lib/cmake/DexSense,要求版本是否一致 |
| 程序缺少 DLL/SO | 运行库路径、处理器架构、版本链接链、系统运行库兼容性 |
| 发现为空但 IP 可达 | 广播可达性;已知型号时改用 IP + 型号直连 |
| 连接被拒绝或超时 | 型号、IP、网络、防火墙、占用会话、设备状态和完整错误日志 |
| 设置返回成功但图像没变化 | 是否实际 Applied,是否用了错误单位或不同采集路径,关键值是否回读,是否只看了缓存 |
| 预期彩色但得到单通道 | 实际硬件、引擎/相机选择、亮度图路径与像素格式,不从数组形状反推参数语义 |
| 没有点云或深度文件 | 当前设备/模式是否提供该数据;saveAll() 不写深度数组 |
| 流采集卡住 | 回调是否耗时、是否回调内重入相机方法、队列是否阻塞 |
排查时记录 SDK VERSION、平台、相机型号、固件版本、连接方式、应用参数、完整错误信息及最小复现命令。可通过 Context::setLogLevel() 调整 SDK 日志等级。