ATC.cs - UF-CSSALT/SMARTS-SDK-Unity-Asset-Package GitHub Wiki

The main function of the ATC is interacting with the ascension tracking software, to establish and maintain connections, and move tracked objects within software. It also provides users with intuitive and easy to use replay functionality. The ATC.cs script is used as a singleton. A single static reference is maintained within the scene. This static ATC can be accessed using the public static ATC field ATC.ME. An instance of the ATC.cs script must exist within the scene for the static reference to be created in Awake(). All redundant instances of the script are destroyed in Awake() leaving only the single instance referenced through ATC.ME.

Namespace

SMARTS_SDK:

To use the ATC.cs script and access its functionality, any scripts must be using the SMARTS_SDK namespace.

Static fields

ATC.ME:

This is the singleton reference of the ATC.cs script. It provides simple access to any external scripts using the SMARTS_SDK namespace.

Public Enums

InputMode:

  • ATC
  • Replay_Data

Connection_Status:

  • Connected
  • Establishing_Connection
  • Not_Connected

Zone:

  • FRONT
  • BACK
  • TOP
  • BOTTOM
  • LEFT
  • RIGHT

AlignSensor:

  • NONE
  • Sensor1
  • Sensor2
  • Sensor3
  • Sensor4

EEPROM:

  • NONE
  • Sensor1
  • Sensor2
  • Sensor3
  • Sensor4
  • Transmitter
  • Board

Public Fields

GameObject BaseObject:

The BaseObject is the tracked platform reference onto which most anatomy is built and calibrated. Typically, this object is the standard CSSALT Index Plate.

bool EnableTrackingBaseObject:

In normal operation mode (see CurrentInputMode) this boolean can be used to toggle tracking on and off for the given base object. When true, BaseObject moves according to the connected transmitter, when false, the BaseObject is not moved by the ATC. In replay mode (see CurrentInputMode), this Boolean cannot be written (will throw unauthorized access exception), and returns the state of this field at the time of the replay data being recorded.

GameObject TrackedObject1:

The TrackedObject1 is the first tracked object, and is connected to the first sensor input of the Ascension 3D Guidance driveBAY. In a typical CSSALT simulation configuration, this sensor is tied to the TUI camera controller. During replay mode (see CurrentInputMode), it is important to make sure this tracked object is the same as the object that was tracked during recording. The CSSALT provided Record_Manager.cs saves records with a header labeling the ATC TrackedObjects. This can be used to ensure accuracy of all replays. All TrackedObject GameObjects should be correctly assigned before a replay begins.

bool EnableTrackingObject1:

In normal operation mode (see CurrentInputMode) this boolean can be used to toggle tracking on and off for the given tracked object. When true, TrackedObject1 moves according to the connected sensor movements in the real world. When false, TrackedObject1 is not moved by the ATC. In replay mode (see CurrentInputMode), this Boolean cannot be written (will throw unauthorized access exception), and returns the state of this field at the time of the replay data being recorded.

GameObject TrackedObject2:

The TrackedObject2 is the second tracked object, and is connected to the second sensor input of the Ascension 3D Guidance driveBAY. In a typical CSSALT simulation configuration, this sensor is tied to the Ultasound Probe. During replay mode (see CurrentInputMode), it is important to make sure this tracked object is the same as the object that was tracked during recording. The CSSALT provided Record_Manager.cs saves records with a header labeling the ATC TrackedObjects. This can be used to ensure accuracy of all replays. All TrackedObject GameObjects should be correctly assigned before a replay begins.

bool EnableTrackingObject2:

In normal operation mode (see CurrentInputMode) this boolean can be used to toggle tracking on and off for the given tracked object. When true, TrackedObject2 moves according to the connected sensor movements in the real world. When false, TrackedObject2 is not moved by the ATC. In replay mode (see CurrentInputMode), this Boolean cannot be written (will throw unauthorized access exception), and returns the state of this field at the time of the replay data being recorded.

GameObject TrackedObject3:

The TrackedObject3 is the third tracked object, and is connected to the third sensor input of the Ascension 3D Guidance driveBAY. In a typical CSSALT simulation configuration, this sensor is tied to the tracked needle. During replay mode (see CurrentInputMode), it is important to make sure this tracked object is the same as the object that was tracked during recording. The CSSALT provided Record_Manager.cs saves records with a header labeling the ATC TrackedObjects. This can be used to ensure accuracy of all replays. All TrackedObject GameObjects should be correctly assigned before a replay begins.

bool EnableTrackingObject3:

In normal operation mode (see CurrentInputMode) this boolean can be used to toggle tracking on and off for the given tracked object. When true, TrackedObject3 moves according to the connected sensor movements in the real world. When false, TrackedObject3 is not moved by the ATC. In replay mode (see CurrentInputMode), this Boolean cannot be written (will throw unauthorized access exception), and returns the state of this field at the time of the replay data being recorded.

GameObject TrackedObject4:

The TrackedObject4 is the second tracked object, and is connected to the second sensor input of the Ascension 3D Guidance driveBAY. In a typical CSSALT simulation configuration, this sensor is unused, and is generally reserved for more specialized simulations. During replay mode (see CurrentInputMode), it is important to make sure this tracked object is the same as the object that was tracked during recording. The CSSALT provided Record_Manager.cs saves records with a header labeling the ATC TrackedObjects. This can be used to ensure accuracy of all replays. All TrackedObject GameObjects should be correctly assigned before a replay begins.

bool EnableTrackingObject4:

In normal operation mode (see CurrentInputMode) this boolean can be used to toggle tracking on and off for the given tracked object. When true, TrackedObject4 moves according to the connected sensor movements in the real world. When false, TrackedObject4 is not moved by the ATC. In replay mode (see CurrentInputMode), this Boolean cannot be written (will throw unauthorized access exception), and returns the state of this field at the time of the replay data being recorded.

bool DisableATCConnectionRoutine:

This field is used to sever any ATC connection and to prevent further connection attempts from being made.

InputMode CurrentInputMode:

Determines the operating mode of the ATC. Depending on the defined InputMode, certain elements of the ATC are displayed using either the current ATC input and connection satus, or by using user provided replay data. The fields affected by this InputMode are:

  • Connected
  • ConnectionStatus
  • EnableTrackingBaseObject
  • EnableTrackingObject(1-4)
  • TrackedObject(1-4) are also moved and rotated differently

When the current input mode is set to Replay_Data, these fields reflect the state of this ATC at the time the replay data was recorded. An ATC connection will still be maintained in the background.

string ReplayDataInput:

This field is used to give the ATC input data. When the CurrentInputMode is set to Replay_Data, any data recorded using the ReplayFormattedATCInputString field will be parsed, and the state of the ATC at the time of recording will be replicated. To see which fields will be updated using this mode, see CurrentInputMode.

string ReplayFormattedATCInputString (readonly):

This field is used to save raw ATC input to later replay using the ATC. The ATC has built in replay functionality and can replay the ATC’s state at the time of this string’s recording natively at a later time. This string cannot be accessed when CurrentInputMode is set to Replay_Data.

bool Connected (readonly):

In normal operation mode (see CurrentInputMode) returns true if maintained connection to tracking system has been established, false otherwise. In replay mode (see CurrentInputMode) returns true if the most recent replay provided data indicated stable connection at the time of the replay data being recorded, false otherwise.

Connection_Status ConnectionStatus (readonly):

In normal operation mode (see CurrentInputMode) returns Connected if maintained connection to tracking system has been established, Establishing_Connection if a connection attempt is currently being made, Not_Connected otherwise. In replay mode (see CurrentInputMode) returns Connected if the most recent replay provided data indicated stable connection at the time of the replay data being recorded, Establishing_Connection if a connection attempt was being made, Not_Connected otherwise.

bool PowerFailure (readonly):

Power failure returns true if ATC is not connected because of lack of power, false otherwise. This value is used by the BlueScreenManager to generate custom failure messages.

ZONE Hemisphere:

The hemisphere specifies the tracking volume’s reference orientation. Generally the ZONE.TOP hemisphere is used. It works by setting the TransmitterRotation to pre-defined orthogonal orientations.

Vector3 TransmitterRotation:

To give more control over the tracked volume’s orientation, the TrasmitterRotation can be used to attain non-orthogonal orientations.

bool UseModularPresetRotation:

If true, the tracking orientation is defined using the Hemisphere ZONE value’s corresponding preset values. If false, the tracking volume can be rotated using the TransmitterRotation Vector3.

bool UsePresetsForSRT:

When true, the tracking system calibration is set to the default CSSALT settings. When false, the different tracking settings can be modified. A list of the settings reverted to defaults can be found below:

  • SamplingFrequency = 255;
  • ApplyCustomFilters = true;
  • IgnoreLargeChanges = false;
  • AC_WideNotchFilter = true;
  • AC_NarrowNotchFilter = false;
  • DC_AdaptiveFilter = true;
  • Vm = {1,1,1,1,1,10,200};
  • AlphaMin = 50;
  • AlphaMax = 15000;

int SamplingFrequency:

Adjusting the sampling frequency adjusts the tracking system’s measurement rate. A higher sampling frequency means a faster measurement rate, with 255 measurements/second being the maximum and 20 measurements/second being the minimum. The default CSSALT setting is 255 measurements/second.

bool ApplyCustomFilters:

When true, upon connection, all sensors’ filter parameters are set. All filter parameters are applied to all sensors. A list of applicable filter settings can be found below:

  • IgnoreLargeChanges
  • AC_WideNotchFilter
  • AC_NarrowNotchFilter
  • DC_AdaptiveFilter
  • Vm
  • AlphaMin
  • AlphaMax

bool IgnoreLargeChanges:

This is a filter setting used by the tracking system to deal with sudden large changes in position and orientation. If true, upon detecting a sudden large change, locks the output to the current position and orientation. The CSSALT default setting is false.

bool AC_WideNotchFilter:

This is a filter setting used by the tracking system to filter out signals of frequencies between 30 and 72Hz. The CSSALT default setting is true.

bool AC_NarrowNotchFilter:

This is a filter setting used by the tracking system to filter out a narrow band of sinusoidal noise. The CSSALT default setting is false.

bool DC_AdaptiveFilter:

An alpha filter that is used in conjunction with AlphaMin and AlphaMax parameters to modify alpha filtering in the tracking system. The CSSALT default parameter is true. See AlphaMin and AlphaMax for CSSALT default values.

int[] VM:

This is a filter setting used by the DC filter tracking system and is used to represent expected noise the DC filter will measure. The CSSALT default is {1,1,1,1,1,10,200}.

int AlphaMin:

The AlphaMin value defines the lower ends of the adaptive range. The CSSALT default is 50.

int AlphaMax:

The AlphaMax value defines the upper ends of the adaptive range. The CSSALT default is 15000.

float VolumeCorrectionFactor:

To be added at a later date.

AlignSensor EditSensor:

To be added at a later date.

Vector3 OffsetPosition:

To be added at a later date.

Vector3 OffsetRotation:

To be added at a later date.

Vector4 Utilities:

To be added at a later date.

Vector4 Sensor1Utilities:

To be added at a later date.

Vector4 Sensor2Utilities:

To be added at a later date.

Vector4 Sensor3Utilities:

To be added at a later date.

Vector4 Sensor4Utilities:

To be added at a later date.

string MemorySensorPlug1:

To be added at a later date.

string MemorySensorPlug2:

To be added at a later date.

string MemorySensorPlug3:

To be added at a later date.

string MemorySensorPlug4:

To be added at a later date.

string MemoryTransmitterPlug:

To be added at a later date.

string MemoryTrackingUnit:

To be added at a later date.

EEPROM UploadTarget:

To be added at a later date.

String UploadText:

To be added at a later date.

bool DebuggingActive:

When true, uses Debug.Log() to print useful information about connection attempts to the console. Otherwise, does nothing.

bool ErrorDebuggingActive:

When true, uses Debug.LogError() to print information to the console about critical errors, exceptions and malfunctions. When true, this information will print to the console in an executable built as a Development Build.

Public Methods

Vector4 LookUpTrackedObjectUtilities(string trackedObjectName)

When called, returns the sensor utilities written to the white box’s tracking unit corresponding to the GameObject whose name is trackedObjectName. If the name is invalid, returns Vector4.zero.

Input Parameters:
string trackedObjectName:

This string input is the name of the GameObject of the tracked tool whose utilities the user wishes to access.

Return:

The return value is the Vector4 containing the utilities of the requested tracked tool. 

void UploadToEEPROM() (editor only)

void GenerateSensorEEPROMAlignmentString() (editor only)

Generates string from tracked sensor and upload targets, and prints to console for review.

void GenerateTransmitterEEPROMAlignmentString() (editor only)

  • Title Text: the basic description of the error
  • Diagnostic Text: a more technical description
  • Troubleshoot Text: an explanation of how to address the error
  • Error Image: an appropriate image sprite for the error