Supercharged HM-LD1 OpenCV Demo

hm_ld1_opencv_demo is an OpenCV demo for visualizing HM-LD1 depth frames and point clouds. It builds two applications:

• hm_ld1_depth_viewer
• hm_ld1_pointcloud_viewer

Supported transports:

• serial
• udp
• uvc

Applications

• hm_ld1_depth_viewer: renders colorized depth images, supports snapshots, zoom, pan, and headless mode
• hm_ld1_pointcloud_viewer: renders interactive point clouds, supports rotate, pivot, zoom, and headless mode

Features

• Uses the SDK FrameSet API across all transports
• Renders depth images with auto range or fixed display range
• Renders point clouds with interactive camera controls
• Supports snapshots and no-window execution for quick capture or scripting
• Prints device information and frame summaries for debugging

Quick Start

Recommended layout:

tof_test/
|-- Dtof-SSL-HM-LD1-sdk/
`-- hm_ld1_opencv_demo/

git clone https://github.com/myrobotproject/Dtof-SSL-HM-LD1-sdk
cmake -S hm_ld1_opencv_demo -B hm_ld1_opencv_demo/build -DCMAKE_BUILD_TYPE=Release
cmake --build hm_ld1_opencv_demo/build -j
./hm_ld1_opencv_demo/build/hm_ld1_depth_viewer --transport uvc --uvc-device /dev/video0

For a one-frame headless capture:

./hm_ld1_opencv_demo/build/hm_ld1_depth_viewer \
  --transport uvc \
  --uvc-device /dev/video0 \
  --headless \
  --max-frames 1 \
  --snapshot-path depth.png

Repository Layout

hm_ld1_opencv_demo/
|-- include/
|   |-- cli/
|   |-- core/
|   |-- hm_ld1_sdk/        Used when storing SDK headers in-repo
|   |-- render/
|   `-- viewer/
|-- lib/                   Used when storing SDK libraries in-repo
|-- src/
|   |-- apps/
|   |-- cli/
|   |-- core/
|   |-- render/
|   `-- viewer/
|-- CMakeLists.txt
|-- README.md
`-- README_CN.md

Requirements

• CMake >= 3.16
• A C++17 compiler
• OpenCV with core, imgproc, highgui, and imgcodecs
• HM-LD1 SDK: https://github.com/myrobotproject/Dtof-SSL-HM-LD1-sdk

SDK Setup

This repository does not include SDK headers or shared libraries. Prepare the SDK in one of the following ways before building.

1. Recommended: clone the SDK next to this repository

CMakeLists.txt automatically detects the sibling SDK repository and builds it with add_subdirectory().

2. Pass HM_LD1_SDK_ROOT

cmake -S . -B build -DHM_LD1_SDK_ROOT=/path/to/Dtof-SSL-HM-LD1-sdk
cmake --build build -j

HM_LD1_SDK_ROOT may point to:

• the SDK source repository
• an installed SDK prefix
• a prebuilt SDK directory containing include/ and lib/

3. Use an installed SDK package

If the SDK was installed with cmake --install, this demo can load it through find_package(hm_ld1_sdk) using CMAKE_PREFIX_PATH or the system default package search path.

4. Store the SDK inside this repository

hm_ld1_opencv_demo/
|-- include/hm_ld1_sdk/hm_ld1_sdk.hpp
`-- lib/libhm_ld1_sdk.so

Use this layout if you want the demo and SDK files in the same directory tree.

Build

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

Generated binaries:

• build/hm_ld1_depth_viewer
• build/hm_ld1_pointcloud_viewer

Usage Examples

Serial depth viewer

./build/hm_ld1_depth_viewer --transport serial --port /dev/ttyUSB0

UDP depth viewer

./build/hm_ld1_depth_viewer --transport udp --udp-bind 0.0.0.0 --udp-port 2368

UVC depth viewer

./build/hm_ld1_depth_viewer --transport uvc --uvc-device /dev/video0

UVC point-cloud viewer

./build/hm_ld1_pointcloud_viewer --transport uvc --uvc-device /dev/video0

Headless snapshot

./build/hm_ld1_depth_viewer \
  --transport serial \
  --port /dev/ttyUSB0 \
  --headless \
  --max-frames 1 \
  --snapshot-path depth.png

Common CLI Options

Transport options

• --transport <serial|udp|uvc>
• --port <name>
• --baud <value>
• --udp-bind <address>
• --udp-port <value>
• --udp-interface <name>
• --udp-auto-config
• --udp-auto-timeout-ms <ms>
• --uvc-device <path>
• --uvc-stream-width <px>
• --uvc-stream-height <px>
• --uvc-bootstrap-timeout-ms <ms>

Common viewer options

• --width <value>
• --height <value>
• --rotate <0|180>
• --depth-min <value>
• --depth-max <value>
• --auto-range
• --crc-mode <auto|none|crc8|crc8_itu|maxim|rohc>
• --snapshot-path <path>
• --headless
• --max-frames <count>
• --idle-timeout-ms <ms>

Point-cloud options

• --pc-width <value>
• --pc-height <value>
• --pc-point-size <value>
• --pc-yaw <deg>
• --pc-pitch <deg>
• --pc-zoom <value>

Controls

Depth viewer

• Mouse wheel or + / -: zoom
• Left drag: pan
• R or 0: reset view
• Q or Esc: quit

Point-cloud viewer

• Left drag: rotate
• Right drag: move the pivot on the XZ plane
• Mouse wheel or + / -: move the camera
• W / S: pitch
• A / D: yaw
• R or 0: reset
• Q or Esc: quit

Verified Environment

The current version has been verified with:

• Debian Linux on aarch64
• GCC 14.2.0
• OpenCV 4.10.0
• HM-LD1 UVC device on /dev/video0

Troubleshooting

• Could not find hm_ld1_sdk: clone the SDK next to this repository, set HM_LD1_SDK_ROOT, or install the SDK package first
• Failed to open UVC device: check the device path, permissions, and whether the sensor appears under /dev/video*
• OpenCV not found during CMake configure: install the OpenCV development package and make sure CMake can find it
• No frame arrives in headless mode: verify the transport settings, device connection, and timeout values

License

This repository is released under the MIT License. See LICENSE.

Official Website:https://myrobotproject.com/product/dtof-solid-state-lidar-hm-ld1/
GitHub Repository:https://github.com/myrobotproject/HM-LD1-OpenCV-Demo