Close
Enter your
text here
View Categories

SDK Overview

Table of Contents

 This document covers topics relating to operation of the SENSUS SDK.

What can you do with the SENSUS SDK? #

  • Interface with a connected PULSE sensor
  • Collect raw, timestamped datasets and save them to a file directory for later use
  • Perform imaging on PULSE sensor data (either in real time or using previously saved datasets), producing a 3-D point cloud image, 2-D heat maps or centroid data
  • Save imaging datasets along with the raw data and parameters used to generate the imaging data
  • Integrating with client applications

Each of these topics will now be explored in the following sections.

Interfacing with PULSE #

Pulse sensors offer a USB-C interface allowing them to communicate with your system. The software you have downloaded includes all of the necessary drivers required for interfacing with the sensor. However, on Linux systems, there are some extra steps that are necessary in order for the device to be able to communicate properly with the Linux kernel. This is covered in “Steps for Linux Users“.

To open a connected sensor with the SDK, you must first know its serial number. You can find this printed on the box your PULSE sensor came in.

Using the SDK Driver #

Pre-compiled ‘Driver’ executables have been provided along with the SDK in order to get up and running. These can be found at:

/<calyosensus_sdk_dir>/bin/<your_platform>/<your_architecture>/

There are two variants:

  • Driver
    • Supported on any Ubuntu 22.04+ system
    • Supports only ‘CPU’ processing backend
  • DriverCuda
    • Supported on Ubuntu 22.04+ systems with Cuda version 12 and above
    • Supports both ‘CPU’ and ‘CUDA’ processing backends

To run the executable, run the following command, where ‘config.json’ is the path to your configuration file (explained in the next section). 

# For CPU version
./Driver config.json

# For CUDA-supported version
./DriverCuda config.json

Configuration Files #

The primary interface for configuring the SDK uses a JSON file format to upload context data on startup, which tells the SDK which devices, datasets and modules to load, along with any other options and parameters.

The general structure of this configuration file is shown below:

{
    "type" : "calyosensus",
    "processing_backend" : "CUDA",
    "reader" : {
        "type" : <reader type>,
        <list of initialisation params>
    },
    "processor" : {
        "type" : <processor pipeline type>,
        <list of initialisation params>
    },
    "writer" : {
        "type" : <writer type>,
        <list of initialisation params>
    }
}

There are a few concepts to learn about this structure:

  • type: the SDK expects all configuration files to have this field, set to “calyosensus”
  • processing_backend: the selected backend for the processors, can be either “CPU” or “CUDA” (on supported platforms only)
  • reader: specifies the input to the driver, for example “XMLReader” will cause the driver to load XML datasets from a specified path, while “DeviceReader” will connect to a PULSE device and begin acquiring datasets
  • processor: specifies the ‘processing pipeline’ to be run by the driver. This option is how you can configure the driver to produce different types of outputs from the input data, for example raw signal data, 2/3-D images, or 2/3-D pipelines
  • writer: specifies the output of the driver, for example “XMLWriter” will cause the driver to write the output datasets to xml files at the specified output directory

Detailed information about all of the available reader, writer and processor types can be found at the SDK Reference page.

Collecting Datasets #

Let’s look at the most basic configuration option available: collecting datasets and writing them to files.

{
    "type" : "calyosensus",
    "processing_backend" : "CPU",
    "reader" : {
        "type" : "DeviceReader",
        "serial_number" : "CP66156A50003",
        "max_distance" : 5.0
    },
    "writer" : {
        "type" : "XMLWriter",
        "output_path" : "/home/MyDatasets/"
    }
}

This particular file describes an SDK context that will carry out the following processes:

  • Load a PULSE sensor with the serial number CP66156A50003 and configure its maximum sensing range to be 5m
  • Enter a real time loop in which the data is streamed to the processing engine, which:
    • Writes the raw data packets to timestamped files, saved in a folder prefixed with the path /home/MyDatasets

Here is another example which uses a very basic processor_pipeline to reconstruct the data into floating point values, scaled between -0.5 and 0.5:

{
    "type" : "calyosensus",
    "processing_backend" : "CPU",
    "reader" : {
        "type" : "DeviceReader",
        "serial_number" : "CP66156A50003",
        "max_distance" : 5.0
    },
    "processor" : {
        "type" : RawSignalAsScaledFloat
    }
    "writer" : {
        "type" : "XMLWriter",
        "output_path" : "/home/MyDatasets/"
    }
}

This file describes an SDK context that will carry out the following processes:

  • As before, load a PULSE sensor with the serial number CP66156A50003 and configure its maximum sensing range to be 5m
  • Enter a real time loop in which the data is streamed to the processing engine, which:
    • Reconstructs the raw sensor data into floating point signal data, scaled between -0.5 and 0.5
    • Writes the scaled signal data to timestamped files, saved in a folder prefixed with the path /home/MyDatasets as before

Imaging #

The SENSUS SDK supports real-time imaging using live sensor data or previously saved datasets. The SDK can generate various data representations, including 2-D and 3-D point clouds. This section describes configurations for setting up the SDK driver to create these imaging outputs.

Example 1: 2-D Imaging (Region of Interest) #

This configuration generates a 2-D image representing a specified Region of Interest (ROI) in real time. The ResolutionImager2Pipeline processor will reconstruct data from the live sensor input to create a 2-D point cloud image, covering the area defined by min_x, min_y, max_x, and max_y in meters.

{
    "type": "calyosensus",
    "processing_backend": "CPU",
    "reader": {
        "type": "DeviceReader",
        "serial_number": "CP66156A50003",
        "num_cycles": 10,
        "max_distance": 5.0
    },
    "processor": {
        "type": "ResolutionImager2Pipeline",
        "min_x": -5.0,
        "min_y": -5.0,
        "max_x": 5.0,
        "max_y": 5.0,
        "max_r": 10.0,
        "pixel_size": 0.05
    },
    "writer": {
        "type": "XMLWriter",
        "output_path": "/Output/Path/Imaging_2D_Output/"
    }
}

Explanation:

  • reader: Connects to the PULSE sensor with the specified serial_number and limits data collection to a maximum range (max_distance) of 5m.
  • processor: The ResolutionImager2Pipeline produces a 2-D image over an area specified by min_x, min_y, max_x, and max_y. pixel_size controls the resolution of each pixel in meters.
  • writer: Saves the output as XML files in the specified output_path.

This configuration produces a high-resolution 2-D image of the specified ROI.

Example 2: 3-D Point Cloud with Log Conversion and Thresholding #

This configuration generates a 3-D point cloud image, using log-converted intensity values. The ResolutionImager2Pipeline processor reconstructs data from the live sensor input, focusing on a 3-D region specified by the min_x, min_y, max_x, max_y, and max_r parameters. Additional processor parameters allow thresholding and truncation of low-intensity points to enhance image clarity.

{
    "type": "calyosensus",
    "processing_backend": "CUDA",
    "reader": {
        "type": "DeviceReader",
        "serial_number": "CP66156A50003",
        "num_cycles": 10,
        "max_distance": 5.0
    },
    "processor": {
        "type": "ResolutionImager2Pipeline",
        "min_x": -5.0,
        "min_y": -5.0,
        "max_x": 5.0,
        "max_y": 5.0,
        "max_r": 10.0,
        "pixel_size": 0.05,
        "threshold_enable": true, 
        "threshold_cutoff": "-7", 
        "truncate_enabled": true
    },
    "writer": {
        "type": "XMLWriter",
        "output_path": "/Output/Path/Imaging_2D_Output/"
    }
}

Explanation:

  • reader: Connects to the PULSE sensor and sets max_distance to 5m, limiting data collection to a specified sensing range.
  • processor: The ResolutionImager2Pipeline generates a 3-D point cloud:
    • threshold_enable and threshold_cutoff are used to set a threshold, discarding points below -7dB.
    • truncate_enabled removes zero-intensity points, providing a clearer visualisation.
  • writer: Saves the output as XML files at the given output_path.

This configuration creates a 3-D image that represents the specified ROI, converting raw intensities to a logarithmic scale and applying filters for more refined visualisation.

These examples illustrate how to configure the SENSUS SDK for 2-D and 3-D imaging with specific region parameters, point filtering, and processing backends. Additional details on available processors, readers, and writers can be found in the SDK Reference.

Conclusion #

The SENSUS SDK provides flexible and powerful tools for interfacing with Pulse sensors, allowing for the collection, processing, and visualisation of real-time or saved sensor data in various formats. This guide has illustrated some foundational configurations, but further customisation is possible by leveraging the wide range of processors, readers, and writers detailed in the SDK Reference. With these tools, developers can seamlessly integrate advanced imaging and data collection functionalities into their own applications. Further integration options are available via C++, Python wrappers, ROS2, Docker. Make sure to check our Docs for the latest integrations!