Python SDK开发文档
约 2828 字大约 9 分钟
本文面向使用 DexSense Python SDK 开发相机应用的工程师,介绍成果物安装、设备连接、参数设置、图像与点云采集、保存、显示、异步采集及常见问题。
1. 成果物内容
Python SDK 成果物目录结构如下:
python/<平台>/
├── wheel/ Python wheel 安装包
├── examples/ 可直接运行的示例
├── docs/ 辅助文档
└── README.md 本使用指南安装包和导入名均为 dexsense:
import dexsense as sdk2. 运行环境
wheel 文件名包含适用的 Python ABI 和操作系统平台,例如:
dexsense-1.0.0-cp310-cp310-linux_aarch64.whl其中 cp310 表示 CPython 3.10,linux_aarch64 表示 Linux ARM64。安装前应确认当前 Python 版本和系统架构与 wheel 文件名一致:
python3 --version
python3 -c "import platform; print(platform.machine())"当前 Linux ARM64 成果物支持:
Linux ARM64(aarch64)
CPython 3.10
XEMA 和 FINCH 网络相机
Windows 成果物的 Python 版本以 wheel 文件名中的 cpXXX 标签为准。
wheel 已携带 Python 扩展和 SDK 动态库。正常安装后,无需单独复制 libdexsense.so、libcamera.so 或 DLL,也无需配置 SDK 动态库搜索路径。
3. 安装与卸载
3.1 建议使用虚拟环境
Linux:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pipWindows PowerShell:
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip3.2 安装正式版
进入成果物目录后安装 wheel 目录中的实际文件:
python -m pip install ./wheel/dexsense-1.0.0-cp310-cp310-linux_aarch64.whl安装程序会同时检查并安装 NumPy 依赖。如果部署环境不能访问外网,应提前从内网或离线包安装与当前 Python 匹配的 NumPy。
验证安装:
python -c "import dexsense; print(dexsense.__version__)"3.3 卸载
python -m pip uninstall dexsense4. 网络准备
使用 XEMA 或 FINCH 网络相机前,请确认:
开发机网卡与相机网络可达,通常应配置在同一网段。
相机 IP 没有与其他设备冲突。
防火墙没有拦截相机发现和数据通信。
同一台相机没有被其他程序独占连接。
可先验证 IP 连通性:
ping 192.168.9.132仅能 ping 通不代表 SDK 一定能连接;SDK 还需要相机服务端口和数据通道可用。
5. 最小采集示例
import dexsense as sdk
context = sdk.Context()
device = context.find_by_ip("192.168.9.132", 3000)
camera = device.open()
try:
frame = camera.capture()
image = frame.image.to_numpy()
depth = frame.depth_map.to_numpy()
points = frame.point_cloud.to_numpy()
print("image:", image.shape, image.dtype)
print("depth:", depth.shape, depth.dtype)
print("points:", points.shape, points.dtype)
finally:
camera.disconnect()find_by_ip() 的第二个参数是超时时间,单位为毫秒,默认值为 3000。
6. 发现和连接设备
6.1 广播发现
import dexsense as sdk
context = sdk.Context()
devices = context.discover_devices(3000)
for device in devices:
info = device.info
print(info.model, info.ip, info.mac, info.serial_number)6.2 按 IP 连接
device = context.find_by_ip("192.168.9.132", 3000)
camera = device.open()跨网段或广播无法到达时,可以明确指定相机型号:
device = context.find_by_ip(
"192.168.9.132",
sdk.DeviceModel.Xema,
3000,
)FINCH 使用 sdk.DeviceModel.Finch。
6.3 设置日志级别
context = sdk.Context()
context.set_log_level(sdk.LogLevel.Info)调试连接问题时可临时使用 sdk.LogLevel.Debug 或 sdk.LogLevel.Trace。
7. 设置相机参数
7.1 设置少量常用参数
只调整少量标量参数时,使用便捷接口:
print(camera.set_exposure_ms(10.0).summary())
print(camera.set_gain_dB(0.0).summary())
print(camera.set_led_current(1023).summary())
print(camera.set_confidence(8.0).summary())
print(camera.set_smoothing(1).summary())这些接口返回 ApplySettingsResult。建议检查 is_success 或打印 summary(),因为不同型号支持的参数集合可能不同:
result = camera.set_exposure_ms(10.0)
if not result.is_success:
print("设置失败:", result.summary())常用参数含义:
| 参数 | 单位或范围 | 说明 |
|---|---|---|
exposure_ms | ms | 曝光时间 |
gain_dB | dB | 传感器增益 |
led_current | 0–1023 | 投射器 LED 电流 |
confidence | 型号相关 | 深度置信度阈值 |
smoothing | 型号相关 | 深度平滑等级 |
LED 常用默认值为 1023。实际项目应根据距离、反光情况和曝光需求调整。
7.2 批量应用参数
需要一次设置多个参数时,先读取当前设置,再修改目标字段:
settings = camera.settings()
settings.exposure_ms = 10.0
settings.gain_dB = 0.0
settings.led_current = 1023
settings.confidence = 8.0
settings.smoothing = 1
issues = settings.validate()
if issues:
raise ValueError(f"参数校验失败:{issues}")
result = camera.apply_settings(settings)
print(result.summary())从当前设置开始修改,可以避免无意覆盖其他已生效的设备参数。
7.3 XEMA CaptureEngine 与图像通道
XEMA 使用 CaptureEngine 选择采集算法。普通场景使用 Normal:
camera.parameters.set_int(
"CaptureEngine",
int(sdk.CaptureEngine.Normal),
)
frame = camera.capture()
image = frame.image.to_numpy()
print(image.shape)可用采集引擎:
sdk.CaptureEngine.Normal:常规结构光。sdk.CaptureEngine.Reflect:高反光物体。sdk.CaptureEngine.Black:低反射或黑色物体。
CaptureEngine 选择 XEMA 采集引擎,不直接把单色传感器变成彩色传感器。XEMA 的图像通道由相机像素类型决定:Mono 型号返回 (H, W),BayerRG8 彩色型号由 SDK 解码为 (H, W, 3) 的 BGR 图。
7.4 XEMA 2D纹理图曝光
XEMA 的 BrightnessParams 对应独立的2D亮度/纹理图生成参数。下面的配置表示不点亮投影器,单独曝光 500ms 拍摄纹理图:
settings = camera.settings()
brightness = sdk.BrightnessParams()
brightness.model = 3 # 1=默认,2=发光,3=不发光,5=自动曝光
brightness.exposure_ms = 500.0
brightness.gain = 1.0
brightness.exposure_mode = 1 # 1=单曝光,2=亮度 HDR
settings.brightness = brightness
camera.apply_settings(settings)该参数影响2D纹理图的曝光方式和可见度;彩色型号仍由相机的 BayerRG8 像素类型决定是否返回三通道图像。
Settings 还直接提供 radius_filter、depth_filter、outlier_filter、reflect_filter 和 gray_rectify 等结构化参数,写法与 brightness 相同。
7.5 扩展参数
部分型号专有参数通过 parameters 接口访问:
parameters = camera.parameters
print(parameters.keys())
if parameters.has_key("Gamma"):
parameters.set_float("Gamma", 0.6)
print(parameters.get_float("Gamma"))使用扩展参数前应通过 has_key() 判断当前相机是否支持。
8. 获取采集数据
frame = camera.capture()
depth = frame.depth_map.to_numpy()
image = frame.image.to_numpy()
points = frame.point_cloud.to_numpy()数据格式:
| 数据 | NumPy 形状 | 数据类型 | 说明 |
|---|---|---|---|
| 深度图 | (H, W) | float32 | 单位为 mm;无效点通常为 NaN 或非正值 |
| 灰度图 | (H, W) | uint8 | 单通道亮度图 |
| 彩色图 | (H, W, 3) | uint8 | SDK 输出通常为 BGR 通道顺序 |
| 点云 | (H, W, 3) | float32 | 每个像素对应 XYZ 坐标 |
过滤有效深度:
import numpy as np
valid_depth = depth[np.isfinite(depth) & (depth > 0)]
if valid_depth.size:
print(valid_depth.min(), valid_depth.max(), valid_depth.mean())to_numpy() 返回高效的 NumPy 视图。SDK 会保持底层数据的生命周期;如果数据需要跨线程、进入长期缓存或由其他库异步持有,建议显式复制:
image_copy = frame.image.to_numpy().copy()9. 保存图像和点云
保存一帧中的全部可用数据:
frame.save_all("./capture_output")根据相机型号和采集模式,目录中通常包含:
brightness.png或color.pngpointcloud.ply
也可以分别保存:
frame.image.save_png("image.png")
frame.image.save_bmp("image.bmp")
frame.point_cloud.save_ply("pointcloud.ply")
frame.point_cloud.save_pcd("pointcloud.pcd")保存前应确保父目录已经存在,或优先使用 frame.save_all() 统一创建输出目录。
10. 显示图像
XEMA 和 FINCH 使用不同的图像控制参数,因此分别提供示例:
examples/xema_capture.py
examples/finch_capture.py两个示例均覆盖完整流程:
打印当前型号可用的 KV 参数键。
设置标量参数、结构体参数及型号专有参数。
打印
apply_settings()中每个参数的Applied、Skipped、Unsupported或Failed状态。拍照后从设备回读所有可读参数,并打印记录在帧中的采集模式参数。
- 保存深度图、点云和2D图像,按需显示图像。
XEMA 示例还会应用并回读半径滤波、深度滤波、离群点滤波、反射滤波、灰度校正和2D纹理参数。FINCH 示例会应用并回读半径滤波、深度滤波和 Gamma,同时明确显示无法由固件回读的 RGB/亮度图只写参数。
显示功能额外使用 Matplotlib:
python -m pip install matplotlib
python examples/xema_capture.py --ip 192.168.9.132指定输出目录和相机参数:
python examples/xema_capture.py \
--ip 192.168.9.132 \
--engine normal \
--texture-mode no-light \
--texture-exposure-ms 500 \
--exposure-ms 10 \
--gain-db 0 \
--led-current 1023 \
--confidence 8 \
--smoothing 1 \
--output-dir ./xema_outputFINCH 示例:
python examples/finch_capture.py \
--ip 192.168.9.51 \
--camera-select rgbhalf \
--rgb-auto-exposure off \
--rgb-exposure-us 100000 \
--rgb-gain 1.0 \
--output-dir ./finch_output参数回读分为三类,示例输出中会明确标识:
“来自设备”:通过
read_settings_from_device()发起实际设备通信。“驱动侧回读”:例如 FINCH
CameraSelect,它控制 SDK 后处理和图像来源,不是固件参数。“只写参数”:例如当前 FINCH 固件的
Brightness、RgbExposure、RgbGain和RgbAutoExposure,应用结果可以检查,但固件没有对应 GET 命令。
在 SSH、Docker 或无桌面环境中通常没有图形显示服务,plt.show() 无法弹出窗口。此时增加 --no-display,只保存结果。
11. 异步采集
future = camera.capture_async()
# 此处可以执行其他计算。
frame = future.result()
print(frame.timestamp)可通过 future.done() 查询采集是否完成。调用 result() 会等待采集完成,并在采集失败时抛出 SDK 异常。
12. 标定参数和能力查询
读取标定参数:
calibration = camera.calibration()
print(calibration.fx, calibration.fy)
print(calibration.cx, calibration.cy)
print(calibration.intrinsic)
print(calibration.distortion)查询能力和参数支持情况:
print(camera.is_feature_supported(sdk.Feature.HDR))
print(camera.is_feature_supported(sdk.Feature.ColorCamera))
print(camera.is_param_supported(sdk.ParamKey.LedCurrent))业务代码不应假设所有型号支持完全相同的参数,应先查询能力或处理 NotSupportedError。
13. 异常处理和资源释放
SDK 提供以下主要异常:
sdk.DeviceNotFoundErrorsdk.ConnectionErrorsdk.CaptureErrorsdk.ParameterErrorsdk.TimeoutErrorsdk.NotSupportedErrorsdk.HardwareErrorsdk.Exception:上述 SDK 异常的基类
推荐结构:
import dexsense as sdk
camera = None
try:
device = sdk.Context().find_by_ip("192.168.9.132", 3000)
camera = device.open()
frame = camera.capture()
except sdk.DeviceNotFoundError as exc:
print(f"未找到设备:{exc}")
except sdk.Exception as exc:
print(f"SDK 操作失败:{exc}")
finally:
if camera is not None and camera.is_connected:
camera.disconnect()程序结束前应调用 disconnect(),避免相机会话继续占用设备。
14. 常见问题
14.1 wheel 无法安装
如果出现 not a supported wheel on this platform,通常是 Python ABI 或系统架构不匹配。检查:
python --version
python -c "import platform; print(platform.machine())"并与 wheel 文件名中的 cpXXX 和平台标签比较。
14.2 导入时报动态库找不到
应确认安装的是完整 wheel,而不是只复制扩展模块 .so 或 .pyd。Linux wheel 使用相对运行路径加载包内动态库,不应依赖 SDK 构建目录。
可在当前虚拟环境中重新安装:
python -m pip install --force-reinstall ./wheel/<实际wheel文件名>14.3 找不到相机
依次检查:
相机供电和网线连接。
主机网卡 IP 与相机 IP 是否可达。
防火墙和网络路由。
相机是否已被其他程序占用。
- 跨网段时是否在
find_by_ip()中明确指定DeviceModel。
14.4 参数结果包含“不支持”
不同相机型号支持不同参数。便捷参数接口基于当前设置应用目标值,结果中可能同时列出其他型号不支持的字段。应以目标参数是否应用成功和 is_success 为准,并通过 is_param_supported() 或 parameters.has_key() 查询型号能力。
14.5 图像颜色不正确
SDK 的三通道彩色图通常是 BGR 顺序。使用 Matplotlib 显示时转换为 RGB:
plt.imshow(image[..., ::-1])OpenCV 默认使用 BGR,一般可以直接显示:
cv2.imshow("DexSense", image)14.6 无法弹出显示窗口
确认程序运行在带桌面环境的终端中,并且 DISPLAY 或 Wayland 环境可用。纯 SSH 终端建议先保存图像,再复制到本地查看。
15. 完整示例建议
首次接入时,XEMA 运行 examples/xema_capture.py,FINCH 运行 examples/finch_capture.py。两个示例覆盖:
指定 IP 发现并连接相机
设置常用采集参数
同步采集一帧
获取深度图、图像和点云
统计有效深度
保存图像和点云
显示灰度图或彩色图
异常处理和连接释放
示例跑通后,再把连接、参数和采集部分复制到业务工程中。