The Hammerhead Development Kit (HDK) offers several communication options enabling integration into diverse applications. Here, we outline three primary methods of interaction: ROS2, ZeroMQ, and the ZeroMQ/ROS2 Bridge. The following sections provide detailed instructions on configuring the HDK for these communication protocols and practical examples to facilitate integration. ZeroMQ is more efficient for data transmission, and we suggest using the ZeroMQ/ROS2 Bridge if you wish to connect to ROS2, as it optimizes bandwidth and data transfer.

1. Output data topics and files

Topic Description
disparity Contains disparity maps in unsigned 16-bit format. They are saved as uncompressed TIFF files.
details Stores metadata in CSV format. These CSV files provide additional information about the dataset, such as capture conditions or object details.
left-rect Left rectified images; saved in uncompressed TIFF format.
topbot Contains the raw Bayer left and right images stacked vertically; saved in TIFF format.
timestamp-<DATE>.csv A CSV file that contains timestamps associated with the data.
bounding_boxes_and_velocities Contains CSV files with bounding box and velocity data for objects in the scene. Each row in the CSV files has the following format: x1, z1, x2, z2, x3, z3, x4, z4, vx, vz, where x and z represent coordinates and vx and vy are velocities. Currently, the velocities are zeroed out.
master_config.ini The master configuration file (master_config.ini) is a simple text file used for configuring Hammerhead. Its complete description can be found here: master_config.ini.
rectification_config.enc Hammerhead’s internal rectification configuration file.

2. Interaction Via ROS2

The ROS2 features of the HDK can be enabled by settingcommunication_lib = ros2 in the master configuration file. When enabled, the HDK can publish several message topics over ROS2. For example:

  1. Raw images from the left and right cameras
  2. Rectified images from the left and right cameras
  3. A custom message type from which Point Clouds can be generated
  4. Bounding box coordinates (for Grid Detect)

NOTE - You would be able to interact using ROS2 only if hammerhead was compiled with ROS2 support.

To control precisely what is published, you need to modify the publishimagetype and publishpointcloud_type fields in the master config.

In addition to publishing messages, a ROS2 service will start, allowing you to modify the camera parameters in real-time (e.g. the camera exposure and gain).

Please note that enabling the ROS2 interface creates additional computational overhead for the HDK, which can reduce framerates. For optimal performance, we recommend using the built-in recording mechanism instead. Additionally, we advise against running both the ROS2 interface and default recording mechanism simultaneously.

Several examples demonstrating how to interact with the HDK through ROS2 are provided here for your convenience:

https://github.com/nodarhub/hammerhead_ros2

3. Interaction Via ZeroMQ

The ZeroMQ features of the HDK can be enabled by setting communication_lib = zmq in the master configuration file. When enabled, the HDK will publish several message topics over ZeroMQ. For example:

  1. The raw images from the left and right cameras
  2. The rectified images from the left and right cameras
  3. A custom message type from which Point Clouds can be generated