SDK Python Reference

`module` `sensus`

SENSUS Python (sensus.py) provides Python wrappers for integrating the SENSUS SDK into a Python codebase.

Typical usage example:

from sensus import SensusST, SensusUtil

config_path = <REPLACE-WITH-CONFIG> #e.g. (./example.json)
pulse = SensusST(SensusUtil.load_json_as_string(config_path), 'CUDA')
packets = pulse.acquire_single_frame()

`function` `load_json_as_string`

load_json_as_string(file_path: str) → str

Helper function to load a JSON file (UTF-8 encoded) and return its contents as a formatted string.

Args:

file_path (str): Pathname to a JSON file (UTF-8 encoded) (absolute or relative to the current working directory)

Returns:

str: Pretty-printed JSON string

Raises:

OSError: If the file cannot be opened or read.
UnicodeDecodeError: If the file is not valid UTF-8.
json.JSONDecodeError: If the file is not valid JSON.

`function` `load_yaml_as_string`

load_yaml_as_string(file_path: str) → str

Helper function to load a YAML file (UTF-8 encoded) and return its contents as a formatted string.

Args:

file_path (str): Pathname to a YAML file (UTF-8 encoded) (absolute or relative to the current working directory)

Returns:

str: Pretty-printed YAML string

Raises:

OSError: If the file cannot be opened or read.
UnicodeDecodeError: If the file is not valid UTF-8.
yaml.YAMLError: If the file is not valid YAML or cannot be parsed.

`class` `SensusST`

SensusST (Single-Threaded), provides a synchronous interface (blocking) to the sensus-sdk.

This class is intended for frame-by-frame workflows (the most common usage pattern) and simplifies setup by handling low-level initialisation internally during instantiation.

It wraps the lower-level _Sensus interface and configures the SDK using the provided backend and JSON configuration. Additional helper methods specific to single-threaded operation such-as acquire_single_frame() are also provided.

Args:

_Sensus (type): Inherits underlying _Sensus class that manages the sensus-sdk C API interface.

`method` `SensusST.init`

__init__(
    config_data: str,
    backend: Literal['CPU', 'CUDA'] = 'CPU',
    skip_validation: bool = False
)

Initialise the sensus-sdk in single-threaded mode with the given configuration.

This constructor sets up the SDK using the provided JSON configuration and specified compute backend (CPU or GPU) and wraps the lower-level C API call Sensus_create to create a new instance, raising an error if initialisation fails. The native SDK library itself is loaded internally by the base _Sensus class.

For more details about the compute backend and how to configure sensus-sdk with JSON please read the SDK Reference.

Args:

config_data (str): A JSON string specifying the configuration for the sensus-sdk. (See SDK Reference)
backend (Literal["CPU", "CUDA"], optional): Specifies the type of hardware acceleration to use. Defaults to "CPU".
skip_validation (bool): Allows user to skip automatic validation of the config_data against JSON schema. Defaults to False.

Raises:

RuntimeError: If the underlying Sensus_create call fails (non-zero return code).
ConfigValidationError: Invalid SENSUS config_data.

`method` `SensusST.acquire_single_frame`

acquire_single_frame() → list

Acquire and decode the next available frame in single-threaded mode.

This high-level helper method combines SensusST.get_next() and SensusST.flush() to retrieve the next frame of decoded packets from the SDK. If retrieving the next frame fails, diagnostic logs are automatically flushed using SensusST.flush_logs() and printed to assist with debugging.

Raises:

RuntimeError: If getting the next frame fails. This may indicate that the SDK was not properly initialised, or that the pipeline has finished. Logs from flush_logs()will be printed to aid troubleshooting.

Returns:

list: A list of decoded Sensus packets (dictionaries), typically including image or point cloud data. See the flush() method for details on the structure and supported packet types.

`method` `SensusST.check_initialised`

check_initialised() → bool

Check whether the SDK has finished the initialisation process. This does not include any information about whether the initialisation was successful or not.

This function calls the underlying Sensus_check_initialised.

For SensusMT, the function will return true if the initialisation on the worker thread has completed.

There is no reason to call this function on SensusST (it will always return true, since initialisation occurs in the constructor and blocks).

Raises:

RuntimeError: If the call to Sensus_check_initialised fails (non-zero return code).

Returns:

bool: description

`method` `SensusST.finished`

finished() → bool

Check whether the SDK has finished or exited early (e.g., sensor stopping, dataset folder completed, or a failure during initialisation or execution).

This function calls the underlying Sensus_finished API to determine if the SDK is in a finished state. A True result typically indicates that the SDK was stopped, failed to initialise, or terminated early.

For more detailed information on why the SDK finished, use SensusMT/ST.flush_logs() immediately after calling this method.

Raises:

RuntimeError: If the call to Sensus_finished fails (non-zero return code).

Returns:

bool: True if the SDK has finished or exited early, False if it is still running.

`method` `SensusST.flush`

flush() → list

Retrieve and decode the most recent frame from the frame queue, clearing all queued frames in the process.

This function calls the underlying Sensus_flush API to retrieve the most recent frame from the frame queue and decodes each packet in the frame into Python-native structures based on their type. The resulting data is returned as a list of dictionaries, with each entry describing a decoded packet from the most recent frame.

After, the whole frame queue is cleared by invoking the Sensus_flush_free API, releasing internal memory allocated by the C API.

Supported packet types include:

Mat2 (float, boolean, or complex)
Mat3 (float, boolean, or complex)
PointCloud2 (2D point clouds with intensity)
PointCloud3 (3D point clouds with intensity)
Unknown (packet could not be decoded or is unsupported)

Raises:

RuntimeError: If the call to Sensus_flush fails (non-zero return code).

Returns:

list: A list of dictionaries, each representing a decoded data packet with keys such as "type", "rows", "cols", "slices", "nele", and "data", depending on the packet type.

`method` `SensusST.flush_logs`

flush_logs(buffer_size: int = 8196) → str

Flushes the internal C API's logging buffer and returns the output as a string.

Args:

buffer_size (int, optional): The size of the string buffer in bytes used to store the log output. Defaults to 1024.

Raises:

RuntimeError: If the underlying Sensus_flush_logs call fails (non-zero return code).

Returns:

str: The flushed log output as a UTF-8 decoded string.

`method` `SensusST.get_json_string`

get_json_string(buffer_size: int = 1024) → str

This method is not yet documented and its use is not recommended.

Warning: This function is currently undocumented and may change in future releases.

`method` `SensusST.get_next`

get_next() → bool

Attempt to retrieve the next frame or check for new data availability.

The functionality and return value depends on the type of the Sensus instance:

SensusST (Single-Threaded): Attempts to retrieve the next frame, blocking until the call returns.
- True: Successfully retrieved the next frame.
- False: No more frames are available (typically due to the sensor/sdk being stopped or an error occurred).
SensusMT (Multi-Threaded): Checks for new data availability in the internal frame queue without blocking.
- True: New data is available and ready in the frame queue.
- False: No new data is currently available in the frame queue.

Raises:

RuntimeError: If the underlying Sensus_get_next call fails (see error code).

Returns:

bool: Indicates whether data was successfully retrieved (or is available), based on the behaviour described above.

`method` `SensusST.get_parameter_svr_id`

get_parameter_svr_id(idx: int, buffer_size: int = 256) → str

This method is not yet documented and its use is not recommended.

Warning: This function is currently undocumented and may change in future releases.

`method` `SensusST.read_json_file`

read_json_file(json_path: str)

This method is not yet documented and its use is not recommended.

Warning: This function is currently undocumented and may change in future releases.

`method` `SensusST.stop`

stop()

This method is not yet documented and its use is not recommended.

Warning: This function is currently undocumented and may change in future releases.

`class` `SensusMT`

SensusMT (Multi-Threaded), provides asynchronous interface (non-blocking) to the sensus-sdk.

This class is designed for asynchronous use, allowing the SDK to run in a separate thread while the main thread interacts with it independently. It enables streaming data acquisition where frames are queued internally and can be retrieved without blocking the calling thread.

SensusMT wraps the lower-level _Sensus interface and handles SDK initialisation using the provided backend and JSON configuration. It is suitable for applications that require concurrent processing, continuous data capture or GUIs.

Use get_next() to check for new data, and flush() to retrieve the latest packets from the internal queue.

Args:

_Sensus (type): Inherits underlying _Sensus class that manages the sensus-sdk C API interface.

`method` `SensusMT.init`

__init__(
    config_data: str,
    backend: Literal['CPU', 'CUDA'] = 'CPU',
    skip_validation: bool = False
)

This initialisation simply sets up the object and does not start the config etc meaning it does not block like SensuST.

Args:

config_data (str): description
backend (Literal["CPU", "CUDA"], optional): description. Defaults to "CPU".
skip_validation (bool): Allows user to skip automatic validation of the config_data against JSON schema. Defaults to False.

Raises:

RuntimeError: Failed to create Sensus Object.
ConfigValidationError: Invalid SENSUS config_data.

`method` `SensusMT.check_initialised`

check_initialised() → bool

Check whether the SDK has finished the initialisation process. This does not include any information about whether the initialisation was successful or not.

This function calls the underlying Sensus_check_initialised.

For SensusMT, the function will return true if the initialisation on the worker thread has completed.

There is no reason to call this function on SensusST (it will always return true, since initialisation occurs in the constructor and blocks).

Raises:

RuntimeError: If the call to Sensus_check_initialised fails (non-zero return code).

Returns:

bool: description

`method` `SensusMT.finished`

finished() → bool

Check whether the SDK has finished or exited early (e.g., sensor stopping, dataset folder completed, or a failure during initialisation or execution).

For more detailed information on why the SDK finished, use SensusMT/ST.flush_logs() immediately after calling this method.

Raises:

RuntimeError: If the call to Sensus_finished fails (non-zero return code).

Returns:

bool: True if the SDK has finished or exited early, False if it is still running.

`method` `SensusMT.flush`

flush() → list

Retrieve and decode the most recent frame from the frame queue, clearing all queued frames in the process.

After, the whole frame queue is cleared by invoking the Sensus_flush_free API, releasing internal memory allocated by the C API.

Supported packet types include:

Mat2 (float, boolean, or complex)
Mat3 (float, boolean, or complex)
PointCloud2 (2D point clouds with intensity)
PointCloud3 (3D point clouds with intensity)
Unknown (packet could not be decoded or is unsupported)

Raises:

RuntimeError: If the call to Sensus_flush fails (non-zero return code).

Returns:

list: A list of dictionaries, each representing a decoded data packet with keys such as "type", "rows", "cols", "slices", "nele", and "data", depending on the packet type.

`method` `SensusMT.flush_logs`

flush_logs(buffer_size: int = 8196) → str

Flushes the internal C API's logging buffer and returns the output as a string.

Args:

buffer_size (int, optional): The size of the string buffer in bytes used to store the log output. Defaults to 1024.

Raises:

RuntimeError: If the underlying Sensus_flush_logs call fails (non-zero return code).

Returns:

str: The flushed log output as a UTF-8 decoded string.

`method` `SensusMT.get_json_string`

get_json_string(buffer_size: int = 1024) → str

This method is not yet documented and its use is not recommended.

Warning: This function is currently undocumented and may change in future releases.

`method` `SensusMT.get_next`

get_next() → bool

Attempt to retrieve the next frame or check for new data availability.

The functionality and return value depends on the type of the Sensus instance:

SensusST (Single-Threaded): Attempts to retrieve the next frame, blocking until the call returns.
- True: Successfully retrieved the next frame.
- False: No more frames are available (typically due to the sensor/sdk being stopped or an error occurred).
SensusMT (Multi-Threaded): Checks for new data availability in the internal frame queue without blocking.
- True: New data is available and ready in the frame queue.
- False: No new data is currently available in the frame queue.

Raises:

RuntimeError: If the underlying Sensus_get_next call fails (see error code).

Returns:

bool: Indicates whether data was successfully retrieved (or is available), based on the behaviour described above.

`method` `SensusMT.get_parameter_svr_id`

get_parameter_svr_id(idx: int, buffer_size: int = 256) → str

This method is not yet documented and its use is not recommended.

Warning: This function is currently undocumented and may change in future releases.

`method` `SensusMT.pause`

pause() → bool

summary

Raises:

RuntimeError: description

Returns:

bool: description

`method` `SensusMT.play`

play() → bool

summary

Args:

timeout_ms (int, optional): description. Defaults to _SENSUS_DEFAULT_TIMEOUT=2000.

Raises:

RuntimeError: description

Returns:

bool: description

`method` `SensusMT.read_json_file`

read_json_file(json_path: str)

This method is not yet documented and its use is not recommended.

Warning: This function is currently undocumented and may change in future releases.

`method` `SensusMT.stop`

stop()

This method is not yet documented and its use is not recommended.

Warning: This function is currently undocumented and may change in future releases.

File last updated: 2026-02-17

module sensus​

function load_json_as_string​

function load_yaml_as_string​

class SensusST​

method SensusST.__init__​

method SensusST.acquire_single_frame​

method SensusST.check_initialised​

method SensusST.finished​

method SensusST.flush​

method SensusST.flush_logs​

method SensusST.get_json_string​

method SensusST.get_next​

method SensusST.get_parameter_svr_id​

method SensusST.read_json_file​

method SensusST.stop​

class SensusMT​

method SensusMT.__init__​

method SensusMT.check_initialised​

method SensusMT.finished​

method SensusMT.flush​

method SensusMT.flush_logs​

method SensusMT.get_json_string​

method SensusMT.get_next​

method SensusMT.get_parameter_svr_id​

method SensusMT.pause​

method SensusMT.play​

method SensusMT.read_json_file​

method SensusMT.stop​

`module` `sensus`

`function` `load_json_as_string`

`function` `load_yaml_as_string`

`class` `SensusST`

`method` `SensusST.init`

`method` `SensusST.acquire_single_frame`

`method` `SensusST.check_initialised`

`method` `SensusST.finished`

`method` `SensusST.flush`

`method` `SensusST.flush_logs`

`method` `SensusST.get_json_string`

`method` `SensusST.get_next`

`method` `SensusST.get_parameter_svr_id`

`method` `SensusST.read_json_file`

`method` `SensusST.stop`

`class` `SensusMT`

`method` `SensusMT.init`

`method` `SensusMT.check_initialised`

`method` `SensusMT.finished`

`method` `SensusMT.flush`

`method` `SensusMT.flush_logs`

`method` `SensusMT.get_json_string`

`method` `SensusMT.get_next`

`method` `SensusMT.get_parameter_svr_id`

`method` `SensusMT.pause`

`method` `SensusMT.play`

`method` `SensusMT.read_json_file`

`method` `SensusMT.stop`