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