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.

Displaying Outputs

While the SDK supports outputting data to various writer types (e.g., XMLWriter, RosDatasetPublisher), it is often neccessary to be able to access the pipeline's output data directly in code. This can be acheived by using the FrameBufferWriter , which writes the output packets to an internal frame buffer which can then be flushed out from the SDK. It is this frame buffer, for example, that allows the VIEWER to access output data for plotting to the screen.

The FrameBufferWriter is more useful than that, however, because it can also be used to visualise the data that is being sent to any of the other writers. This is because, in certain conditions, the FrameBufferWriter is implicitly invoked and attached to the chosen writer type, meaning that the output packets will be both handled by the writer and written to the frame buffer. For example, say the user has selected XMLWriter because they want to capture a dataset for future processing: if the FrameBufferWriter is also evoked (given one or more of the conditions below), they will also be able to visualise the data that is being written to files at the same time.

Below are the three conditions in which the outputs of pipelines are available in the frame buffer:

  1. the writer type of the pipeline is FrameBufferWriter
  2. there are pipelines whose input type is FrameBufferReader. in this case, the output packets of the pipeline specified by source_pipeline_id will automatically be written to the frame buffer, regardless of that pipeline's writer type.
  3. in the pipeline scope of the json, view_output is set to true. This tells the sdk to write all output packets from this pipeline to the frame buffer, regardless of its writer type.

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

rmid

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

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

centre_frequency

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

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

use_hanning

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

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​

Configuration dependent (see Configuration Options below):

If algorithm == resolution

  • filtered_signals

If algorithm == precision

  • filtered_spectrum

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

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

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

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

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

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

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: 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

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

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

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

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

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

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.
  • Application Note: when the imaging algorithm is precision, setting this parameter to Cartesian means that the image is converted from Polar to cartesian with linear interpolation. To tune the resolution and performance, both the Polar and Cartesian ROI arguments will take effect. Conversely, the resolution imaging algorithm supports both coordinate systems natively (no interpolation).

Cartesian ROI Parameters​

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

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

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: 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

Polar ROI Parameters​

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.

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

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

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

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

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)Β·

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

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

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

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

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

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

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

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

min_pts

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

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

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.

Last updated on by PatJRobinson