Python SDK Development Guide
About 2238 wordsAbout 7 min
This document is for engineers developing camera applications with the DexSense Python SDK. It covers installation of the deliverables, device connection, parameter settings, image and point cloud capture, saving, display, asynchronous capture, and common issues.
1. Deliverable Contents
The Python SDK deliverables have the following directory structure:
python/<平台>/
├── wheel/ Python wheel 安装包
├── examples/ 可直接运行的示例
├── docs/ 辅助文档
└── README.md 本使用指南Both the package name and import name are dexsense:
import dexsense as sdk2. Runtime Environment
The wheel filename identifies the supported Python ABI and operating system platform. For example:
dexsense-1.0.0-cp310-cp310-linux_aarch64.whlHere, cp310 means CPython 3.10, and linux_aarch64 means Linux ARM64. Before installation, confirm that the current Python version and system architecture match the wheel filename:
python3 --version
python3 -c "import platform; print(platform.machine())"The current Linux ARM64 deliverables support:
Linux ARM64 (aarch64)
CPython 3.10
XEMA and FINCH network cameras
For Windows deliverables, refer to the cpXXX tag in the wheel filename for the supported Python version.
The wheel includes the Python extension and SDK dynamic libraries. After a normal installation, there is no need to copy libdexsense.so, libcamera.so, or DLLs separately, or to configure the SDK dynamic library search path.
3. Installation and Uninstallation
3.1 Use of a Virtual Environment Is Recommended
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 Install the Release Version
After entering the deliverables directory, install the actual file in the wheel directory:
python -m pip install ./wheel/dexsense-1.0.0-cp310-cp310-linux_aarch64.whlThe installer also checks for and installs the NumPy dependency. If the deployment environment cannot access the internet, install a NumPy version compatible with the current Python version in advance from an internal network source or an offline package.
Verify the installation:
python -c "import dexsense; print(dexsense.__version__)"3.3 Uninstall
python -m pip uninstall dexsense4. Network Preparation
Before using an XEMA or FINCH network camera, confirm that:
The development machine’s network adapter can reach the camera network; they should usually be configured on the same subnet.
The camera IP address does not conflict with another device.
The firewall does not block camera discovery or data communication.
The same camera is not exclusively connected to another program.
You can first check IP connectivity:
ping 192.168.9.132Being able to ping the camera does not guarantee that the SDK can connect. The SDK also requires the camera service port and data channel to be available.
5. Minimal Capture Example
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()The second argument to find_by_ip() is the timeout in milliseconds. Its default value is 3000.
6. Discovering and Connecting to Devices
6.1 Broadcast Discovery
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 Connect by IP
device = context.find_by_ip("192.168.9.132", 3000)
camera = device.open()When connecting across subnets or when broadcast discovery cannot reach the camera, you can specify the camera model explicitly:
device = context.find_by_ip(
"192.168.9.132",
sdk.DeviceModel.Xema,
3000,
)For FINCH, use sdk.DeviceModel.Finch.
6.3 Set the Log Level
context = sdk.Context()
context.set_log_level(sdk.LogLevel.Info)When debugging connection issues, you can temporarily use sdk.LogLevel.Debug or sdk.LogLevel.Trace.
7. Setting Camera Parameters
7.1 Set a Few Common Parameters
When adjusting only a few scalar parameters, use the convenience methods:
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())These methods return ApplySettingsResult. Check is_success or print summary(), because the set of supported parameters may differ by model:
result = camera.set_exposure_ms(10.0)
if not result.is_success:
print("设置失败:", result.summary())Common parameter meanings:
| Parameter | Unit or range | Description |
|---|---|---|
exposure_ms | ms | Exposure time |
gain_dB | dB | Sensor gain |
led_current | 0–1023 | Projector LED current |
confidence | Model-dependent | Depth confidence threshold |
smoothing | Model-dependent | Depth smoothing level |
A commonly used default value for the LED is 1023. In an actual project, adjust it based on distance, reflectivity, and exposure requirements.
7.2 Apply Parameters in a Batch
To set multiple parameters at once, read the current settings first, then modify the target fields:
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())Starting with the current settings helps avoid unintentionally overwriting other device parameters that are already in effect.
7.3 XEMA CaptureEngine and Image Channels
XEMA uses CaptureEngine to select the capture algorithm. Use Normal for ordinary scenes:
camera.parameters.set_int(
"CaptureEngine",
int(sdk.CaptureEngine.Normal),
)
frame = camera.capture()
image = frame.image.to_numpy()
print(image.shape)Available capture engines:
sdk.CaptureEngine.Normal: Conventional structured light.sdk.CaptureEngine.Reflect: Highly reflective objects.sdk.CaptureEngine.Black: Objects with low reflectivity or black objects.
CaptureEngine selects the XEMA capture engine; it does not directly turn a monochrome sensor into a color sensor. The camera’s pixel type determines the XEMA image channel: Mono models return (H, W), while the SDK decodes BayerRG8 color models into BGR images with shape (H, W, 3).
7.4 XEMA 2D Texture Image Exposure
XEMA’s BrightnessParams defines separate parameters for generating 2D brightness and texture images. The following configuration leaves the projector off and uses a separate 500 ms exposure to capture a texture image:
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)This parameter affects the exposure method and visibility of the 2D texture image. For color models, whether a three-channel image is returned still depends on the camera’s BayerRG8 pixel type.
Settings also directly provides structured parameters such as radius_filter, depth_filter, outlier_filter, reflect_filter, and gray_rectify. They are set in the same way as brightness.
7.5 Extended Parameters
Access parameters specific to some models through the parameters interface:
parameters = camera.parameters
print(parameters.keys())
if parameters.has_key("Gamma"):
parameters.set_float("Gamma", 0.6)
print(parameters.get_float("Gamma"))Before using an extended parameter, call has_key() to check whether the current camera supports it.
8. Obtaining Capture Data
frame = camera.capture()
depth = frame.depth_map.to_numpy()
image = frame.image.to_numpy()
points = frame.point_cloud.to_numpy()Data formats:
| Data | NumPy shape | Data type | Description |
|---|---|---|---|
| Depth image | (H, W) | float32 | Unit: mm; invalid points are usually NaN or nonpositive values |
| Grayscale image | (H, W) | uint8 | Single-channel brightness image |
| Color image | (H, W, 3) | uint8 | SDK output is usually in BGR channel order |
| Point Cloud | (H, W, 3) | float32 | Each pixel corresponds to XYZ coordinates |
Filter valid depth values:
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() returns an efficient NumPy view. The SDK maintains the lifetime of the underlying data. If the data needs to cross threads, enter a long-term cache, or be held asynchronously by another library, explicitly copy it:
image_copy = frame.image.to_numpy().copy()9. Saving Images and Point Clouds
Save all available data from a frame:
frame.save_all("./capture_output")Depending on the camera model and capture mode, the directory usually contains:
brightness.pngorcolor.pngpointcloud.ply
You can also save each item separately:
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")Before saving, ensure that the parent directory exists, or use frame.save_all() to create the output directory.
10. Displaying Images
XEMA and FINCH use different image control parameters, so separate examples are provided:
examples/xema_capture.py
examples/finch_capture.pyBoth examples cover the complete process:
Print the KV parameter keys available for the current model.
Set scalar parameters, structured parameters, and parameters specific to the model.
Print the
Applied,Skipped,Unsupported, orFailedstatus of each parameter inapply_settings().After capturing an image, read back all readable parameters from the device and print the capture mode parameters recorded in the frame.
- Save the depth image, point cloud, and 2D image, and display the image if needed.
The XEMA example also applies and reads back radius filtering, depth filtering, outlier filtering, reflection filtering, grayscale correction, and 2D texture parameters. The FINCH example applies and reads back radius filtering, depth filtering, and Gamma. It also explicitly identifies the write-only RGB and brightness image parameters that cannot be read back from the firmware.
Displaying images additionally requires Matplotlib:
python -m pip install matplotlib
python examples/xema_capture.py --ip 192.168.9.132Specify an output directory and camera parameters:
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 example:
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_outputThe example output explicitly identifies three categories of parameter readback:
“From device”: Initiates actual device communication through
read_settings_from_device().“Driver-side readback”: For example, FINCH
CameraSelectcontrols SDK post-processing and image sources; it is not a firmware parameter.“Write-only parameter”: For example,
Brightness,RgbExposure,RgbGain, andRgbAutoExposurein the current FINCH firmware. Their application results can be checked, but the firmware has no corresponding GET command.
In SSH, Docker, or environments without a desktop, a graphical display service is usually unavailable, so plt.show() cannot open a window. In that case, add --no-display to save the results only.
11. Asynchronous Capture
future = camera.capture_async()
# 此处可以执行其他计算。
frame = future.result()
print(frame.timestamp)Use future.done() to check whether capture is complete. Calling result() waits for capture to complete and raises an SDK exception if capture fails.
12. Calibration Parameters and Capability Queries
Read calibration parameters:
calibration = camera.calibration()
print(calibration.fx, calibration.fy)
print(calibration.cx, calibration.cy)
print(calibration.intrinsic)
print(calibration.distortion)Query capabilities and parameter support:
print(camera.is_feature_supported(sdk.Feature.HDR))
print(camera.is_feature_supported(sdk.Feature.ColorCamera))
print(camera.is_param_supported(sdk.ParamKey.LedCurrent))Application code should not assume that every model supports exactly the same parameters. Query capabilities first or handle NotSupportedError.
13. Exception Handling and Resource Release
The SDK provides these main exceptions:
sdk.DeviceNotFoundErrorsdk.ConnectionErrorsdk.CaptureErrorsdk.ParameterErrorsdk.TimeoutErrorsdk.NotSupportedErrorsdk.HardwareErrorsdk.Exception: Base class for the SDK exceptions above
Recommended structure:
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()Call disconnect() before the program exits to avoid leaving the camera session occupying the device.
14. Common Issues
14.1 The Wheel Cannot Be Installed
If not a supported wheel on this platform appears, the Python ABI or system architecture usually does not match. Check:
python --version
python -c "import platform; print(platform.machine())"Compare the results with the cpXXX and platform tags in the wheel filename.
14.2 A Dynamic Library Cannot Be Found During Import
Confirm that you installed the complete wheel instead of copying only the .so or .pyd extension module. The Linux wheel uses a relative runtime path to load dynamic libraries within the package and should not depend on the SDK build directory.
You can reinstall it in the current virtual environment:
python -m pip install --force-reinstall ./wheel/<实际wheel文件名>14.3 The Camera Cannot Be Found
Check the following in order:
Camera power and network cable connection.
Whether the host network adapter IP can reach the camera IP.
Firewall and network routing.
Whether another program is using the camera.
- When connecting across subnets, whether
DeviceModelis explicitly specified infind_by_ip().
14.4 The Parameter Result Includes “Unsupported”
Different camera models support different parameters. A convenience parameter method applies the target value based on the current settings, so the result may also list fields unsupported by other models. Check whether the target parameter was applied successfully and the value of is_success. Use is_param_supported() or parameters.has_key() to query the model’s capabilities.
14.5 Image Colors Are Incorrect
The SDK’s three-channel color images are usually in BGR order. Convert them to RGB for display with Matplotlib:
plt.imshow(image[..., ::-1])OpenCV uses BGR by default, so the image can generally be displayed directly:
cv2.imshow("DexSense", image)14.6 The Display Window Does Not Open
Confirm that the program is running in a terminal with a desktop environment and that DISPLAY or a Wayland environment is available. In a terminal accessed only through SSH, save the image first and then copy it to your local machine for viewing.
15. Recommended Complete Examples
For initial integration, run examples/xema_capture.py for XEMA or examples/finch_capture.py for FINCH. Both examples cover:
Discovering and connecting to a camera by specifying its IP
Setting common capture parameters
Capturing one frame synchronously
Obtaining the depth image, image, and Point Cloud
Calculating statistics for valid depth values
Saving images and Point Clouds
Displaying a grayscale or color image
Handling exceptions and releasing the connection
After the example runs successfully, copy the connection, parameter setting, and capture portions into your application project.