NDI Aurora API¶

This is an inofficial implementation for the NDI Aurora System. For other NDI systems it is possible to use the C++ implementation https://github.com/PlusToolkit/ndicapi. The main reason for this API is that the ndicapi was not available for python at the time and unknown at the beginning of the project.

Hint

Not all commands and errors are implemented yet.

The aurora module, is a python implementation of NDI Aurora System API Revision 4. The guide is in the docs directory in GitHub accessable.

Supported NDI API Version:

Combined Firmware Revision: 011 API Revision: D.001.007

Classes

Aurora: The main class of the API, utiilzes pyserial (3.4) in order to communicate with the Aurora System. Most of the basic available commands are implemented, based on the Aurora_API_Guide_v4.
Handlemanager: The Handlemanager is an optional object, which can be used to keep track of the current state of the Aurora System. It provides methods to get state of the system and it can hold the current handle data.
Handle: Represents the data model of an handle. This object can be used, to access the handle data more consistently.

class aurora.Aurora(ser, debug_mode=False)¶

Parameters

ser (serial.Serial) – :class:serial.Serial object for communicating with NDI Aurora System.
debug_mode (bool) – Flag for debugging.

The aurora class provides for communicating with NDI Aurora system. For the processing the responses from this class please refer to the NDI API v4 doc or extend this documentation.

_callback(key)¶

Parameters: key (str) – Key / functionname of Observed method in UltraVisModel.

Calls the observers methods, based on the methodkey of UltraVisModel method.

apirev()¶: Returns the API revision number.

beep(num)¶

Parameters: num (int) – 1-9 beeps.

Sounds the system beeper.

bx(option=None)¶

Parameters: option (int) – TBD
Returns: Header bytes and bx_data bytes as two params.

Returns the latest tool transformations and system status information in binary format. Its faster than tx due to shorter response length.

check_aurora_error(msg)¶

Parameters: msg (str) – Byte string response from the NDI aurora system.
Raises: Warning – Will be raised if error is found. Maybe introduce own Exception type later.

Interprets the errorcode from the NDI Aurora system and logs it.

get(attr=None)¶

get_aurora_errormsg(errorcode)¶

Parameters: errorcode (str) – Number in hex as a string. (Can be rewritten) for the error code.
Returns: Return the aurora error message as a string.
Return type: str
Note: Not all error messages are implemented yet.

get_sysmode()¶

init()¶: Initializes the system.

pdis(option=None)¶

pena(handle, mode)¶

Parameters

handle (Handle) – Handle to be enabled.
mode (str) –
A single character which is either ‘S’,’D’ or ‘B’.
- Static: a static tool is considered to be relatively immobile, e.g. a reference tool
- Dynamic: a dynamic tool is considered to be in motion, e.g. a probe.
- Button box: a button box can have switches and LEDs, but no sensor coils. No transformations are returned for a button box tool, but switch status is returned

Enables the reporting of transformations for a particular port handle.

phsr(option=0)¶

Parameters

option (int) –

Specifies which information will be returned. Defaults to 0.

0 - Reports all allocated port handles (default)
1 - Reports port handles that need to be freed
2 - Reports port handles that are occupied, but not initialized or enabled
3 - Reports port handles that are occupied and initialized, but not enabled
4 - Reports enabled port handles

Returns the number of assigned port handles and the port status for each one. Assigns a port handle to a tool.

pinit(handle)¶

Parameters: handle (Handle) – Handle to be initialized.

Initializes a port handle.

readSerialByteCode(length)¶

read_serial(expected=b'\r', to_log=True)¶

Parameters

expected (str) – Byte string for the ending characters.
to_log (bool) – Flag for logging the responses.

Returns

Return the response from serial system as a byte string.

Reads the response from the serial interface and logs it to console.

register(key, observer)¶

Parameters

key (str) – Function name of the observed function in the model.
observer (function) – Observer method or function to be called back.

Implementation of observer pattern. Observers can register methods for a callback. The key should be the UltraVisModel methodname. When the method in the model is executed the _callback() is triggered.

reset()¶: Resets the system.

reset_and_init_system()¶: Resets and initiliazes the NDI Aurora System

set_sysmode(mode: str)¶

sflist(option=None)¶

Parameters: option (int) – TODO

Returns information about the supported features of the system.

tstart(option=None)¶

Parameters

option (int) –

40 or 80. The reply options are hexadecimal numbers that can be OR’d (C0).

40 (Optional, starts tracking in faster acquisition mode)
80 (Optional, resets the frame counter to zero)

Starts Tracking mode.

tstop()¶: Stops Tracking mode.

tx(option=None)¶

Parameters: option (str) – Option for response format. * 0001 - Transformation data (default) * 0800 - Transformations not normally reported

Returns the latest tool transformations and system status in text format. It is recommended to work with Handle object to easier manage the response data.

write_cmd(cmd: str, expect=False)¶: Writes a command to the NDI Aurorasystem and strips trailing blanks. If expect is True, the read_until() method will use specified ending character.

class aurora.Handle(ID, handle_state, refname='DEFAULT', MISSING=None, Q0=None, Qx=None, Qy=None, Qz=None, Tx=None, Ty=None, Tz=None, calc_Err=None, port_state=None, frame_id=None)¶

Parameters

ID (str) – The handle ID - (is actually a hex number)
handle_state (str) – The doctor performing the examination.
refname (str) – The reference name of the handle/sensor (e.g. Left hip, sternum etc.)
MISSING (bool) – Indicator for a missing handle (e.g. out of volume).
Q0 (float) – Scalar of unit quaternion.
Qx (float) – x Vector part of unit quaternion.
Qy (float) – y Vector part of unit quaternion.
Qz (float) – z Vector part of unit quaternion.
Tx (float) – x-position of handle.
Ty (float) – y-position of handle.
Tz (float) – z-position of handle.
calc_Err (float) – An estimate of how well the Aurora System calculated the transformation. Value range is >= 0.
port_state (float) – State of the port handle. See Port and NDI Aurora Doc for more.
frame_id (float) – frame-id of the recorded tracking data.

The data model of an handle of the NDI Aurora system. Can be instantiated as empty object.

get_orient_data()¶: Return Translational Data as list Q0,Qx,Qy,Qz in quaternion

get_trans_data()¶: Return Translational Data as list x,y,z in mm

set_reference_name(refname)¶

set_tx_data(MISSING=False, Q0=None, Qx=None, Qy=None, Qz=None, Tx=None, Ty=None, Tz=None, calc_Err=None, port_state=None, frame_id=None)¶: Setter for tx or transformation data.

class aurora.HandleManager(phsr)¶

Parameters: phsr (str) – String from Aurora.phsr()

The HandleManager`is a utility class for an easier handling of the NDI Aurora API. It can directly process the responses from the :class:`Aurora class and translate it into a more useful format for the developer.

_hex_to_string(hex_val)¶

Parameters: hex_val (bytestring) – Input hex value in binary.
Returns: string
Return type: str

Converts a hex value to string.

_string2dec(string, separator_index, round_to=4)¶

get_handles(real_copy=False)¶

Parameters: real_copy (bool) – Flag for getting a real_copy of the handles or the referenced dict.
Returns: Return the current handle data as a dictionary.
Return type: dict

get_missing_handles()¶

Returns: Return the missing handle data as a list.
Return type: list

get_numhandles()¶: Return the number of identified handles.

update_handles(tx_str)¶

Parameters: tx_str (str) – The transformation data as a string.

Updates handle data based on response from Aurora.tx()

update_handlesBX(bx_header, bx_data)¶

Parameters

bx_header (bytes) – The header contains meta data about the response (e.g. reply_length, number handles etc.)
bx_data (bytes) – The bx data from the :func:Aurora.bx method.

Returns

Return the success boolean whether the data could be correctly processed or not.

Return type

bool

42 Byte vollständiger Handle. Ansonsten 10 Byte der Handle.

Please check the BX command in the NDI Aurora API Guide for more details.

class aurora.Port¶

from_bitarray(bit_array)¶

from_string(string)¶