SDK Reference

This document provides an overview of the primary components in the SENSUS SDK configuration: Readers, Writers, and Processors. Each section outlines the options and key arguments for configuring each component.

Readers #

Readers are components that handle data input for the processing pipeline. The SENSUS SDK provides various reader options to accommodate different data sources, such as real-time device data or pre-existing datasets.

Available Readers #

1. DeviceReader
   • Description: Reads data directly from a connected PULSE device. Generates datasets of type ‘Mat2::bytes’.
   • Arguments:
     • serial_number (string): Specifies the unique serial number of the PULSE device. Example: "CP66156A50003".
     • num_cycles (integer): The number of data acquisition cycles to perform.
     • max_distance (float): Maximum distance in meters for data capture. Example: 5.0.
2. BinaryReader
   • Description: Reads binary data from a specified dataset folder. Useful for pre-recorded datasets. Supports all ‘CalyoPacketType’ dataset types.
   • Arguments:
     • input_path (string): Path to the folder containing the dataset files. Example: "/path/to/dataset/folder".

Writers #

Writers define how processed data is saved or outputted from the SDK pipeline. The SDK supports various writers to output data in different formats or publish it to ROS2 topics.

Available Writers #

1. XMLWriter
   • Description: Writes data to an XML file format. Supports all ‘CalyoPacketType’ dataset types.
   • Arguments:
     • output_path (string): Path where the output XML file will be saved. Example: "/path/to/desired/output/folder".
2. RosDatasetPublisher
   • Description: Publishes data as a ROS2 topic, enabling integration with a ROS2-based ecosystem. Supports all ‘CalyoPacketType’ dataset types.
   • Arguments:
     • topic_name (string): Name of the ROS2 topic to publish the processed data. Example:
     • "test_pub".

Processor Pipelines #

The SENSUS SDK offers a suite of processor pipelines for handling and transforming data with varying complexity. Each pipeline provides a specific processing chain for raw data, allowing users to configure data capture, filtering, imaging, and point cloud conversion steps. Below are the available processor pipelines, their purposes, and key arguments for configuration.

Available Processor Pipelines #

---

RawSignalCapturePipeline #

Purpose: Captures raw signal data and converts it from bytes to float format.
Configuration:

• Processor Backend: Specifies the backend used for processing.

---

PassThroughPipeline #

Purpose: Directly passes through data without transformation. Useful for quick integration, dataset conversions or debugging.
Configuration:

• Processor Backend: Specifies the backend for processing.
• CalyoPacketType: Defines the specific packet type being passed through.

---

FilteredSignalCapturePipeline #

Purpose: Processes raw signal data with byte-to-complex conversion and filters in the frequency domain, resulting in a complex signal matrix (Mat2::Complex).
Configuration:

• filter_cutoff_frequency (float): Defines the cutoff frequency for the bandpass filter. Default is 40,000 Hz.
• filter_half_bandwidth (float): Specifies the filter bandwidth. Default is 0.2.
• filter_use_hanning (bool): Enables the Hanning window function in filtering. Default is true.

---

ResolutionImager2Pipeline #

Purpose: Generates a 2D resolution image from filtered signal data, allowing configuration of the imaging region and pixel resolution.

Dependencies: This pipeline depends on the FilteredSignalCapturePipeline, inheriting its configurations for filtering.

Configuration:

• min_x, max_x (float): Sets the X-axis range for imaging. Default is -5.0 to 5.0.
• min_z, max_z (float): Defines the Z-axis range for imaging. Default is 0.0 to 10.0.
• pixel_size (float): Sets pixel resolution in meters. Default is 0.05.

---

ResolutionImager3Pipeline #

Purpose: Generates a 3D resolution image from filtered signal data, allowing configuration of the imaging region and pixel resolution.

Dependencies: This pipeline depends on the FilteredSignalCapturePipeline, inheriting its configurations for filtering.

Configuration:

• min_x, max_x (float): Defines the X-axis range. Default is -5.0 to 5.0.
• min_y, max_y (float): Sets the Y-axis range for 3D imaging. Default is -5.0 to 5.0.
• min_z, max_z (float): Specifies the Z-axis range. Default is 0.0 to 10.0.
• pixel_size (float): Defines pixel resolution. Default is 0.05.

---

ResolutionImager2LogConvertedPipeline #

Purpose: Normalises the output of the ResolutionImager2Pipeline to its maximum value, and converts to a logarithmic scale.

Dependencies: It requires the ResolutionImager2Pipeline, inheriting its ROI configuration options.

Configuration:

• Processor Backend: Specifies backend used for processing.
• normalisation_mode (string): Specifies the method of normalisation used before log conversion. Can be either “norm2max” or “fixed_value”. Default is “norm2max”, which normalises the data to the maximum.
• normalisation_value (float): Specifies the value for normalisation in the case that normalisation_mode is equal to “fixed_value”. Default is 200, min is 0 and max is 2000.

---

ResolutionImager3LogConvertedPipeline #

Purpose: Normalises the output of the ResolutionImager3Pipeline to its maximum value, and converts to a logarithmic scale.

Dependencies: It requires the ResolutionImager3Pipeline, inheriting its ROI configuration options.

Configuration:

• Processor Backend: Specifies backend used for processing.

---

ResolutionImager2PointCloudPipeline #

Purpose: Generates a 2D point cloud from log-converted 2D resolution image data, with configurable thresholding options.

Dependencies: It requires the ResolutionImager2LogConvertedPipeline, inheriting all of its configuration options.

Configuration:

• threshold_enable (bool): Enables threshold filtering. Default is false.
• threshold_cutoff (float): Sets the threshold cutoff (dB) level. Default is -7. Must be between -60 and 0.
• truncate_enabled (bool): Enables truncation of values. Default is false. When enabled, all points below the threshold will be removed from the point cloud. Thresholding must be enabled for truncation to take effect.

---

ResolutionImager3PointCloudPipeline #

Purpose: Generates a 3D point cloud from log-converted 3D resolution image data, suitable for spatial analysis in 3D space.

Dependencies: It requires the ResolutionImager3LogConvertedPipeline, inheriting all of its configuration options.

Configuration:

• threshold_enable (bool): Enables threshold filtering. Default is false.
• threshold_cutoff (float): Sets the cutoff level. Default is -7, with a range from -60 to 0.
• truncate_enabled (bool): Enables truncation of data based on threshold. Default is false.

---

Each pipeline integrates seamlessly with the SENSUS SDK, enabling complex data processing workflows tailored to specific application requirements.

Conclusion #

By leveraging these components, users can configure and customize the SDK pipeline according to their data processing needs. The Readers manage input data, the Processors handle transformations, and the Writers define output formats, all providing flexible options for developing robust applications with the SENSUS SDK.