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 thesensus-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 thesensus-sdk
. (See SDK Reference)backend
(Literal["CPU", "GPU"], optional): Specifies the type of hardware acceleration to use. Defaults to "CPU".
Raises:
RuntimeError
: If the underlyingSensus_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 fromflush_logs()
will be printed to aid troubleshooting.
Returns:
list
: A list of decoded Sensus packets (dictionaries), typically including image or point cloud data. See theflush()
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 toSensus_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 toSensus_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 underlyingSensus_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 underlyingSensus_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 thesensus-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): descriptionbackend
(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 toSensus_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 toSensus_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 underlyingSensus_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 underlyingSensus_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