Skip to main content

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()

See also:
Python Intergation Docs
Python API Docs

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.

DEPRECATED: ⚠️ This method is deprecated and will be removed in a future release. Please use the SensusUtil.load_json_as_string() function instead.

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:

  • FileNotFoundError: If the file does not exist.
  • json.JSONDecodeError: If the file is not valid JSON.

class SensusST​

SensusST (Single-Threaded), provides synchronous (blocking) interface 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__(json_path: str, backend: Literal['CPU', 'GPU'] = 'CPU')

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:

  • json_path (str): A JSON string specifying the configuration for the sensus-sdk. (See SDK Reference)
  • backend (Literal["CPU", "GPU"], optional): Specifies the type of hardware acceleration to use. Defaults to "CPU".

Raises:

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

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.finished​

finished() → bool

Check whether the SDK has finished or exited early (e.g., sensor stopping 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 = 1024) → 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.ok​

ok() → bool

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 functionality with the calling thread

Args:

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

method SensusMT.__init__​

__init__(json_path: str, backend: Literal['CPU', 'GPU'] = 'CPU')

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

Args:

  • json_path (str): description
  • backend (Literal["CPU", "GPU"], optional): description. Defaults to "CPU".

Raises:

  • RuntimeError: Failed to create Sensus Object.

method SensusMT.check_initialised​

check_initialised() → bool

method SensusMT.finished​

finished() → bool

Check whether the SDK has finished or exited early (e.g., sensor stopping 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 SensusMT.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 SensusMT.flush_logs​

flush_logs(buffer_size: int = 1024) → 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.ok​

ok() → bool

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(timeout_ms: int = 2000) → 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.

class SensusUtil​

Utility class containing useful static helper methods when working with the sensus-sdk.

method SensusUtil.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:

  • FileNotFoundError: If the file does not exist.
  • json.JSONDecodeError: If the file is not valid JSON.

File last updated: 2025-04-23

Last updated on by James Barson