Skip to main content

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.

Pipeline Configuration​

The SENSUS SDK provides a lot of flexibility in the range of processing tasks it can carry out, while also providing numerous integration options. The main method for applying configurations is by providing JSON configuration files to the SDK which specify, most basically, one or more Pipelines for the software to run. The basic structure of a pipeline is shown in the diagram below.

flow chart showing basic composition of pipelines

As shown in the diagram above, all pipelines consist of a Reader, ProcessorPipeline and Writer, which are all explained in detail below. Notably, the ProcessorPipeline is itself a pipeline made up of a number of stages and configurable units.

Due to the variety of configuration options supported, it can take a bit of work understanding the configuration model, which is why we have supplied many examples for common applications elsewhere in the documentation. This reference is intended for advanced users who are looking to make the most out of the Sensus software.

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.

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".
    • Note: can also be set to "any", in which case the first available sensor will be used. Good for convenience when only one sensor is connected.
  • num_cycles (integer): The number of data acquisition cycles to perform.
  • max_distance (float): Maximum distance in meters for data capture. Example: 5.0.

DeviceReaderMT​

Description: Same as DeviceReader (see above), but dispatches the data acquisition on a worker thread, buffering the data in a double buffer for improved runtime efficiency, at the cost of memory usage.

Arguments:

  • serial_number (string): Specifies the unique serial number of the PULSE device. Example: "CP66156A50003".
    • Note: can also be set to "any", in which case the first available sensor will be used. Good for convenience when only one sensor is connected.
  • num_cycles (integer): The number of data acquisition cycles to perform.
  • max_distance (float): Maximum distance in meters for data capture. Example: 5.0.

XMLReader​

Description: Reads datasets from a specified dataset folder, captured in XML format using 'XMLWriter'. This reader type will read all datasets in a folder, in order by timestamp, and terminate once complete.

Arguments:

  • input_path (string): Path to the folder containing the dataset files. Example: "/path/to/dataset/folder".

FrameBufferReader​

Description: Reads the output of a previously-specified pipeline. Useful for connecting different pipelines together, which is done so as to customise the processing to be done and allow writing of data at intermediate stages. 'FrameBufferReader' will cause the source pipeline to automatically attach a 'FrameBufferWriter' to whichever writer type is specified. To use this reader type, the pipeline type must be compatible with that of the source pipeline. See more at [[pipeline compatibility]].

Arguments:

  • source (string): the pipeline_id of the source pipeline.

RosDatasetSubscriber​

Description: Creates a ROS2 subscriber, listening on the specified topic, enabling pipelines to be carried out by receiving ROS2 messages, i.e., playing back RosBags.

Arguments:

  • topic_name (string): the pipeline_id of the source pipeline.
  • message_type (string): the message type for the incoming messages. Can either be CalyoMat2 or CalyoPointCloud
  • mode (string): the Calyo message type version legacy for calyosensus_msgs or standard for calyo_msgs

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.

XMLWriter​

Description: Writes data to an XML file format. Supports all β€˜CalyoPacketType’ dataset types.

Arguments:

  • output_path (string): Path where the output XML files will be saved. Example: "/path/to/desired/output/folder".

PNGWriter​

Description: Writes PNG images. Supports all β€˜Mat2’ dataset types. The output images will be grayscale (single channel byte), normalised between 0 - 255. Note: this writer type does not record AcquisitionInfo, so take care that this information is not lost, perhaps by keeping an intermediate pipeline.

Arguments:

  • output_path (string): Path where the output PNG files will be saved. Example: "/path/to/desired/output/folder".

RosDatasetPublisher​

Description: Publishes data as a ROS2 topic, enabling integration with a ROS2-based ecosystem. Supports all β€˜CalyoPacketType’ dataset types.

Availability

  • Only available in ROS2 packages
  • Accessible in both driver and listener executables

Arguments:

  • topic_name (string): Name of the ROS2 topic to publish the processed data.
  • frame_id (string): Name of the ROS2 frame id.

Processor Pipelines​

Processor pipelines make up a subset of the total pipeline which handle taking the data from the reader, applying a range of algorithms and transformations to that data, before outputting the result to the writer. By using JSON configurations, we can specify, to a high degree of detail, what exactly these operations should be. Below is a diagram showing the stages of any processor pipeline, and which class they each belong to.

flow diagram showing processor stages

Each processor stage in the above diagram represents a point to which a writer can be attached in order to output the data produced from that stage. Each of the stages can then be further customised with ConfigurationOptions (which vary depending on their class, e.g., Raw Signal Capture, Filtering, Imaging, etc.), and RuntimeParameters (which vary depending on the ConfigurationOptions). For example, a processor pipeline which specifies the logconversion stage will produce log-converted images as output, whereas the filtered_spectrum stage will produce only filtered, frequency-domain signals, and the subsequent stages will not run.

Additionally, each processor pipeline may accept data from any stage up to that specified in its configuration (this information is recorded in the output packet data). For example, a pipeline with the stage image can accept data that produced at any of the previous stages to image (i.,e., passthrough, filtered_spectrum, and filtered_signals). This allows for flexibility in chaining together pipelines so as to collect/plot data at multiple possible stages simultaneously, or to run processing tasks distributed across different instances of the sensus-sdk running on multiple machines.

For example, it would be possible to have a data-acquisition platform running the sensus-sdk to capture and filter signals from a live device, before transmitting the data via a networked writer type (e.g., RosDatasetPublisher)so that another machine running the sensus-sdk may read the filtered signal data via a networked reader type (e.g., RosDatasetSubscriber) before carrying out imaging and plotting the results. As you can imagine, this feature makes the sensus-sdk very manageable in robotic applications. This feature can additionally be applied through writing to and reading from files, thus storing data at various pipeline stages, allowing for processing distributed across time.

ProcessorPipeline Configuration

To configure the processor pipeline, you must select a processing stage. From there, look for which ConfigurationOptions are supported by that stage. These options will configure various aspects about how the processing will be applied (for example, whether imaging should be done in 2-D or 3-D), and will also determine which RuntimeParameters will be available.

Each processor pipeline can be invoked by defining a json object called "processor" in the JSON configuration file. Inside this object, the "stage" variable should be set to one of the stages in the above diagram, which are detailed below. The ConfigurationOptions provided by that stage can then be provided as JSON variables in the same object. When a processor stage inherits from a previous one, the configuration options and runtime parameters are also inherited, and can be specified in the same JSON object. An example such JSON object is shown below:

"processor" : {
    "type" : {
        "stage" : "dbscan",
        "configuration_options" : {
            "algorithm" : "resolution",
            "dimensions" : 2
        }
    },
    "runtime_parameters" : {
        "x_min" : -5.0,
        "x_max" : 5.0,
        "y_max" : 8.0,
        "r_min" : 0.8,
        "r_max" : 10,
        "r_step" : 0.1,
        "az_min_rads" : -1.57,
        "az_max_rads" : 1.57,
        "roi_pol2d_r_max": 10,
        "pixel_size" : 0.1,
        "angle_limit_enable" : true,
        "angle_limit_degrees" : 86.0,
        "normalisation_mode" : "norm2max",
        "normalisation_value" : 0.02,
        "db_enabled" : true,
        "db_scale" : -8.0,
        "cfar_enabled" : false
    }
}

In the above example, the dbscan stage is invoked. Because this stage inherits from pointcloud_generation, which in turn inherits from log_conversion and image_generation, the configuration options for image_generation are available. Similarly, the runtime_parameters from each of these inherited stages are also available to be set.

passthrough​

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

Configuration Options​

  • None

Runtime Parameters​

  • None

signal_reconstruction​

Applies conversion of raw signal bytes into 32-bit floating point signals.

Configuration Options​

  • None

Runtime Parameters​

  • None

filtered_spectrum​

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

Configuration Options​

  • None

Runtime Parameters​

signal_removal_enable

  • Description: Sets whether the incident signal should be removed from the signal.
  • Type: bool
  • Default: true
  • Enabled When: Always

rmid

  • Description: Sets the gradient for the signal remover: higher value = steeper cutoff.
  • Type: float
  • Min: 0.01
  • Max: 1.0
  • Default: 0.5
  • Enabled When: Always

window_length_multiplier

  • Description: Sets the multiplicand for the window length used in removing the incident signal. Useful for when the wavetrain is long, and ringing occurs.
  • Type: float
  • Min: 1.0
  • Max: 5.0
  • Default: 1.0
  • Enabled When: Always

centre_frequency

  • Description: Defines the cutoff frequency for the bandpass filter in Hz.
  • Type: float
  • Min: 20'000
  • Max: 80'000
  • Default: 40'000
  • Enabled When: Always

half_bandwidth

  • Description: Specifies the filter bandwidth as a proportion of the total signal spectrum.
  • Type: float
  • Min: 0.01
  • Max: 1.0
  • Default: 0.2
  • Enabled When: Always

use_hanning

  • Description: Enables the hanning window function for the filter.
  • Type: bool
  • Default: true
  • Enabled When: Always

filtered_signals​

Converts filtered signals back into time domain.

Inherits From​

  • filtered_spectrum

Configuration Options​

  • None

Runtime Parameters​

  • None

image_generation​

Generates an image from filtered signal data, allowing configuration of the imaging region and pixel resolution.

Inherits From​

  • filtered_signals

Configuration Options​

NameDescriptionTypeValue Options
algorithmSelects the imaging algorithm to usestringresolution, precision
dimensionsSelects the number of dimensions to image overinteger2, 3

Runtime Parameters​

angle_limit_enable

  • Description: Applies a mathematical function to focus image intensity between two angles in the azimuth and elevation planes. This angle is specified by angle_limit_degrees shown below. Note: the angle limiter provides a smoother filtering than that achieved using simple ROI masks.
  • Type: bool
  • Default: true
  • Enabled When: algorithm is set to resolution

angle_limit_degrees

  • Description: Specifies the angle, in degrees, between which the image intensity will be focused, if the angle limiter is enabled. Applies to both the azimuth and elevation planes, such that -x <= I <= x, where x is the angle specified.
  • Type: float
  • Min: 10.0
  • Max: 90.0
  • Default: 60.0
  • Enabled When: algorithm is set to resolution

r_comp_mode

  • Description: Specifies the r compensation mode to be used in imaging, encoded as an integer value, as described below. Each mode applies a compensation according to the appropriate expression below, such that Cr = expr(r, x), where C is the compensation value at radius r (to be multiplied with the pixel intensity), r is the radius, or distance to the pixel and x is the parameter to be set.

  • Value Options

    • 0: SQUARE_ROOT: Cr = √r * x
    • 1: LINEAR_SCALE: Cr = r * x
    • 2: QUADRATIC: Cr = rΒ² * x
    • 3: EXPONENTIAL: Cr = rΛ£
    • 4: LINEAR_APPROX: Cr = 1 + r * x

  • Enabled When: algorithm is set to resolution

r_comp

  • Description: Specifies the r compensation parameter x for the expression selected by r_comp_mode.
  • Type: float
  • Min: 0.0
  • Max: 5.0
  • Default: 0.03
  • Enabled When: algorithm is set to resolution

offset_x

  • Description: Offsets the Region of Interest (ROI) in Cartesian space along the X axis, in metres.
  • Type: float
  • Min: -25.0
  • Max: 25.0
  • Default: 0.0
  • Enabled When: algorithm is set to resolution

offset_y

  • Description: Offsets the Region of Interest (ROI) in Cartesian space along the Y axis, in metres.
  • Type: float
  • Min: -25.0
  • Max: 25.0
  • Default: 0.0
  • Enabled When: algorithm is set to resolution

offset_z

  • Description: Offsets the Region of Interest (ROI) in Cartesian space along the Z axis, in metres.
  • Type: float
  • Min: 0.0
  • Max: 25.0
  • Default: 0.0
  • Enabled When: algorithm is set to resolution and dimensions is set to 3

cfar_enabled

  • Description: Sets whether pipeline should use Constant False Alarm Rate (CFAR) thresholding. Note: it is strongly recommended that CFAR be applied in Polar coordinate system, since the sliding window more closely matches the Point Spread Function when in Polar.
  • Type: bool
  • Default: false
  • Enabled When: Always

cfar_guard_cells_x

  • Description: Sets the number of guard cells in the x dimension to be used in CFAR thresholding.
  • Type: integer
  • Min: 0
  • Max: 20
  • Default: 2
  • Enabled When: Always

cfar_guard_cells_y

  • Description: Sets the number of guard cells in the y dimension to be used in CFAR thresholding.
  • Type: integer
  • Min: 0
  • Max: 20
  • Default: 2
  • Enabled When: Always

cfar_guard_cells_z

  • Description: Sets the number of guard cells in the z dimension to be used in CFAR thresholding.
  • Type: integer
  • Min: 0
  • Max: 20
  • Default: 2
  • Enabled When: dimensions is set to 3

cfar_training_cells_x

  • Description: Sets the number of training cells in the x dimension to be used in CFAR thresholding.
  • Type: integer
  • Min: 1
  • Max: 40
  • Default: 10
  • Enabled When: Always

cfar_training_cells_y

  • Description: Sets the number of training cells in the y dimension to be used in CFAR thresholding.
  • Type: integer
  • Min: 1
  • Max: 40
  • Default: 10
  • Enabled When: Always

cfar_training_cells_z

  • Description: Sets the number of training cells in the z dimension to be used in CFAR thresholding.
  • Type: integer
  • Min: 1
  • Max: 40
  • Default: 10
  • Enabled When: dimensions is set to 3

cfar_ratio

  • Description: Sets the minimum ratio of Cell Under Test's (CUT) intensity to the average of the training cells required to remain in the thresholded output image.
  • Type: float
  • Min: 1.0
  • Max: 50.0
  • Default: 2.0
  • Enabled When: Always

coordinate_system

  • Description: Specifies the coordinate system to be used in imaging, encoded as an integer value, as described below:
    • 0: Cartesian: the image will be a Z-X plot, where Z is the forward direction from the sensor, and X is the horizontal.
    • 1: Polar: the image will a polar plot (R-AZ, where R is the distance from the sensor, and AZ is the azimuth angle.
  • Enabled When: algorithm is set to resolution

Cartesian ROI Parameters​

These parameters are only available for the resolution algorithm.

When enabled, the cartesian parameters have a dual purpose, depending on the selection for coordinate_system. If set to 0 (Cartesian), these parameters will determine the region of interest (ROI) and determine the size of the output image. If set to 1 (Polar), the effect of the Cartesian ROI parameters will be to apply a mask over the polar image such that pixels outside of the mask are set to zero.

x_min, x_max

  • Description: Sets the X-axis range for imaging in metres.
  • Type: float
  • Min: -25.0
  • Max: 25.0
  • Default: -5.0 to 5.0
  • Enabled When: algorithm is set to resolution

y_min, y_max

  • Description: Defines the Y-axis range for imaging in metres.
  • Type: float
  • Min: -25.0
  • Max: 25.0
  • Default: -5.0 to 5.0
  • Enabled When: algorithm is set to resolution

z_min, z_max

  • Description: Defines the Z-axis range for imaging in metres.
  • Type: float
  • Min: 0.0
  • Max: 25.0
  • Default: 0.0 to 10.0
  • Enabled When: algorithm is set to resolution and dimensions is set to 3

pixel_size

  • Description: Sets voxel resolution in meters. Only takes effect when coordinate_system is set to 0 (Cartesian).
  • Type: float
  • Min: 0.001
  • Max: 0.5
  • Default: 0.01
  • Enabled When: algorithm is set to resolution

Polar ROI Parameters​

These parameters are available for both the resolution and precision algorithms.

When algorithm is set to resolution, these parameters have a dual purpose, depending on the selection for coordinate_system. If set to 1 (Polar), these parameters will determine the region of interest (ROI) and determine the size of the output image. If set to 0 (Cartesian), the effect of the Polar ROI parameters will be to apply a mask over the Cartesian image such that pixels outside of the mask are set to zero.

When algorithm is set to precsion, these parameters will set the region of interest and determine the size of the output image.

az_min_rads, az_max_rads

  • Description: Sets the azimuth axis range for imaging in radians.
  • Type: float
  • Min: -1.571
  • Max: 1.571
  • Default: -1.571 to 1.571
  • Enabled When: Always

num_az_dirs

  • Description: Sets the number of azimuth directions (scan lines) for the imaging. I.e., num_az_dirs equals the horizontal number of voxels in the output image. Note: only takes effect when coordinate_system is set to 1 (Polar).
  • Type: integer
  • Min: 4
  • Max: 300
  • Default: `50
  • Enabled When: Always

el_min_rads, el_max_rads

  • Description: Sets the elevation axis range for imaging in radians.
  • Type: float
  • Min: -1.571
  • Max: 1.571
  • Default: `-1.571 to 1.571``
  • Enabled When: dimensions is set to 3

num_el_dirs

  • Description: Sets the number of elevation directions (scan lines) for the imaging. I.e., num_el_dirs equals the vertical number of voxels in the output image. Note: only takes effect when coordinate_system is set to 1 (Polar).
  • Type: integer
  • Min: 4
  • Max: 300
  • Default: `50
  • Enabled When: dimensions is set to 3

r_min, r_max

  • Description: Defines the R-axis range for imaging in metres.
  • Type: float
  • Min: 0.0
  • Max: 25.0
  • Default: 0.0 to 10.0
  • Enabled When: Always

r_step

  • Description: Sets r resolution in meters. Only takes effect when coordinate_system is set to 1 (Polar).
  • Type: float
  • Min: 0.01
  • Max: 1
  • Default: 0.1
  • Enabled When: Always

logconversion​

Converts the image output of the image_generation stage to a logarithmic (dB) scale.

Inherits From​

  • image_generation

Configuration Options​

  • none

Runtime Parameters​

normalisation_mode

  • Description: Specifies the normalisation mode to be applied to the output image:
    • 0: Norm2Max: the output image in normalised between 0 and the maximum intensity in the image.
    • 1: fixed_value: the output image in normalised between 0 and the value specified by normalisation_value (shown below)Β·
  • Enabled when: Always

normalisation_value

  • Description: Specifies the normalisation value, in pressure (Pa), to be applied to the image if normalisation_mode is set to 1 ('fixed_value'), such that the output image is normalised between 0 and this value.
  • Type: float
  • Min: 0
  • Max: 2'000
  • Default: 0.02
  • Enabled when: Always

db_enabled

  • Description: Sets whether pipeline should threshold the image based on a specified Decibel scale, set via db_scale (shown below).
  • Type: bool
  • Default: `false
  • Enabled when: Always

db_scale

  • Description: Specifies the Decibel scale to use for thresholding if db_enabled is set to true. Value x will apply thresholding such that x <= I <= 0 pixels remain in the output image, where I is the intensity of the Cell Under Test (CUT).
  • Type: float
  • Min: -60.0
  • Max: 0.0
  • Default: -7.0
  • Enabled when: Always

pointcloud_generation​

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

Inherits From​

  • log_conversion

Configuration Options​

  • none

Runtime Parameters​

threshold_enable

  • Description: Sets whether pipeline should threshold the point cloud based on a specified Decibel scale, set via db_scale (shown below).
  • Type: bool
  • Default: false
  • Enabled when: Always

threshold_cutoff

  • Description: Specifies the Decibel scale to use for point cloud thresholding if db_enabled is set to true. Value x will apply thresholding such that x <= I <= 0 pixels remain in the output image, where I is the intensity of the Cell Under Test (CUT).
  • Type: float
  • Min: -60.0
  • Max: 0.0
  • Default: `-7.0
  • Enabled when: Always

truncate_enabled

  • Description: Sets whether pipeline should truncate the point clouds only to points above the threshold. If set to false, the resulting pointcloud will be dense where the intensity of points below the threshold are set to zero.
  • Type: bool
  • Default: true
  • Enabled when: Always

DbScan​

Applies clustering to the point cloud sensor data, assigning an integer 'cluster label' to each point, stored in its intensity (will overwrite intensity data). Additionally, points that are detected as noise are filtered out. The output is a 2-D point cloud. There is also an option to calculate the centroids of the clusters. If this is selected, the output point cloud will contain only the centroid points.

Inherits From​

  • pointcloud_generation

Configuration Options​

  • none

Runtime Parameters​

dbscan_enabled

  • Description: Sets dbscan should be applied to point cloud. If disabled, output will be the same as ResolutionImager2PointCloudPipeline, and following parameters will have no effect.
  • Type: bool
  • Default: true
  • Enabled when: Always

epsilon

  • Description: Specifies the maximum distance in metres between points to be considered as belonging to the same cluster.
  • Type: float
  • Min: 0.001
  • Max: 2.0
  • Default: 0.2
  • Enabled when: Always

min_pts

  • Description: Specifies the minimum number of points required to create a cluster.
  • Type: integer
  • Min: 5
  • Max: 100
  • Default: 20
  • Enabled when: Always

centroids_enabled

  • Description: Sets whether pipeline should calculate centroids of the clusters. If enabled, output point cloud will contain only the centroid points.
  • Type: bool
  • Default: false
  • Enabled when: Always

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.