SightLab  2.0 Code Attributes and Methods

importing SightLab

• No Longer need to import vizconnect, viz, vizfx, viztask as those are now added to the settings file

Creating and configuring a SightLab instance

sightlab = sightlab.SightLab()

• Setting to not use GUI

sightlab = sightlab.SightLab(gui = False)

Class SightLab

    The SightLab class initializes an environment for visual experiments with configurable attributes for GUI elements, data logging, and screen recording settings.

    Attributes:

Setting the Environment 

env = vizfx.addChild('sightlab_resources/environments/dojo2.osgb')

sightlab.setEnvironment(env)

Configures the environment settings for the experiment.

Setting Trial Count

sightlab.setTrialCount(1)

Adding Target Objects

sightlab.addSceneObject(name,sceneObject,gaze = True)

Note: If not a child of the environment, then SceneObjects must be added before scheduling sightlab in the code (i.e. before sightlab.startTrial())

Grabbing Objects

 sightlabObject.addSceneObject("tablet", tablet, gaze = False, grab = True)

Adding Object Only for Tracking

sightlab.addSceneObject('ball', ball)

Multiple Objects

Starting Trials

Starting a trial in SightLab can be done using the start/end conditions in the GUI, keyboard events or programmatically within a script. Below are methods to initiate trials:

Using Keyboard Events:

To start a trial using the spacebar, you can set up a keyboard event:

vizact.onkeydown(' ', sightlab.startTrial)

This binds the spacebar to start the trial.

Programmatic Start:

To start a trial programmatically, use the following approach within a Vizard task:

yield viztask.waitKeyDown('s')  # Waits for the 's' key to be pressed

yield sightlab.startTrial(trialLength=60, trialLabel ="A", startTrialText="Beginning Trial", textContinueEvent='triggerPress')

This example waits for the 's' key and then starts the trial with specified parameters.

Parameters:

startTrial(condition = NO_CONDITION, trialLength=-1, trialLabel="A", startTrialText=None, startExperimentText=None, textContinueEvent='triggerPress', textContinueKey=None, trackingDataLogging=True, replayDataLogging=True, experimentSummaryLogging = None, timeLineLogging = None, startPoint = None, startEuler = None)

• condition : Can choose what starts the trial (options are KEY_PRESS, TIMER, ON_MEDIA_END, ON_GAZE_TIME and CUSTOM_EVENT). Note this can also be left to None and use a yield viztask like "yield viztask.waitKeyDown" or this can be set up in the GUI. 

• trialLength (int): Duration of the trial in seconds. -1 means no time limit.

• trialLabel (str): Sets the trial label.

• startTrialText (str): Optional text to display at the start of the trial.

• startExperimentText (str): Optional text to display at the start of the experiment.

• startRatings: Set up a start rating scale

• textContinueEvent(str): event to start the trial (i.e. 'triggerPress')

• textContinueKey: key to start the trial (i.e. ' ')

• trackingDataLogging(bool): track data logging on or off

• replayDataLogging(bool): track logging for the replay

• experimentDataLogging(bool): track logging for the experiment summary

• timelineLogging(bool): track logging for the timeline

• startPoint: change the starting position

• startEuler: change the starting rotation

Ending Trials

Ending a trial can be done via keyboard events, callbacks, or directly within a function.

Using Keyboard Events:

vizact.onkeydown('e', sightlab.endTrial)

Programmatic End: 

yield sightlab.endTrial()

Using Callbacks: 

viztask.schedule(sightlab.endTrial())

Schedules the trial to end based on specific events or conditions within your experiment flow.

Parameters:

endTrial(condition = NO_CONDITION, endTrialText = None, endExperimentText = None, textContinueEvent = "triggerPress", textContinueKey = None, textContinueTimer = None, endRatings = None)

• condition = NO_CONDITION: Choose what ends the trial. (options are KEY_PRESS, TIMER, ON_MEDIA_END, ON_GAZE_TIME and CUSTOM_EVENT)

• endTrialText (str): Optional text to display at the end of the trial.

• endExperimentText (str): Optional text to display at the end of the experiment.

• endRatings : Set up an end rating scale

Direct Event Trigger:

To directly send an event to end a trial from within a function: 

viz.sendEvent(INITIATE_TRIAL_END)

Use this method when you need to trigger the end of a trial based on specific logic or external conditions. 

Scheduling SightLab

 viztask.schedule(sightlab.runExperiment())

Setting Condition Based on Vizconnect being Used

if sightlab.getConfig() == "Meta Pro Body":

Changing Starting Position

SightLab (can also add a Starting Point object in the GUI (see Creating a New Scene)

sightlab.transportNode.setPosition([0,0,0])

#or can use this

sightlab.setStartPoint((2,0,0))

Session Replay Starting Point

replay.transportNode.setPosition([0,0,0])

Checking which object is being Targeted

if e.object == sightlab.sceneObjects[GAZE_OBJECTS][TARGET_PAINTING]:

Get Current Time

sightlab.hud.getCurrentTime()

Accessing the Environment Object

env = sightlab.getEnvironment()

Using the environment object in context

#Access after EXPERIMENT_START

def sightLabExperiment():

    global env

    yield viztask.waitEvent(EXPERIMENT_START)

    env = sightlab.getEnvironment()

#If need access to it before use env = None, and put inside a function that can be called after it is set in the trial

def initialize_environment():

        target = env.getChild(name)

def sightLabExperiment():

    global env

    yield viztask.waitEvent(EXPERIMENT_START)

    env = sightlab.getEnvironment()

    initialize_environment()

Changing Models to use for Avatar

Other way

sightlab.setAvatarHead(head = vizfx.addChild(AVATAR_HEAD_RESOURCE_PATH+'/Male1.osgb'))

#Setting Hands

sightlab.setAvatarRightHand(rightHand= vizfx.addChild(AVATAR_HANDS_RESOURCE_PATH+'/empty.osgb'))

Toggling Visibility of Overlays

sightlab.toggleHUD()

Settings

Many settings are now accessible via the sightlab object (see here). The settings file is now in the sightlab_utils folder. See the settings documentation page for more details

Adding to the Data Files

•  addCustomFlagColumn(self, columnName)

•  addTrackingTrialDataColumn(self, columnName, trackedObject, dataType='SIXDOF', mode=4)

• sightlab.setExperimentSummaryData('condition',condition)

Adding a Custom Flag

• sightlab.setCustomTrialData('name of flag')

Changing Data Directories

• sightlab.setDataDirectory()

Setting multiple objects to Experiment Summary

# Create a dictionary with all the data

experimentData = {

'Object Size': sceneObjectSizeString,

'NUM_OBJ': NUM_OBJ,

'Time to Find Target': time_to_find_target,

'Target Position': targetPos,

'Target Correct': targetCorrect,

'Confidence Level': sightlab.ratingChoice}

# Iterate through the dictionary and set each item

for columnName, data in experimentData.items():

    sightlab.setExperimentSummaryData(columnName, data)

    sightlab.customExperimentDataColumns = experimentData

Setting Condition/Label

yield sightlab.startTrial(trialLabel = "A")

HeadLight On or Off

sightlab.setHeadLight(state, intensity = None, color = None)

Adding additional file to the Data folder

fileName = '{d}_{p.id}_experiment_data._trial_{t}.pdf'.format(d=sightlab.dateTime, p=sightlab.participantData, t=sightlab.trialNumber)

        fullPath = os.path.join(sightlab.getExperimentDataFolderPath(), fileName)

        drawChart(fullPath, sightlab.getPlotData())

Toggling on and off tracking per trial

Session Replay

from sightlab_utils import replay as Replay

from sightlab_utils.replay_settings import *

replay = replay.SightLabReplay()

To change the name of a session replay you need to keep the end tag:

replay_data_1 tag

Set position

replay.transportNode.setPosition([x,y,z])

Accessing environment SessionReplay

env = replay.getEnvironmentObject()

Accessing Scene Objects

screen = replay.sceneObjects[GAZE_OBJECTS]['screen']

Getting Trial Number

trial_number = int(replay.currTrial)

Getting Gaze Point

gazePointObject = replay.sceneObjects[GAZE_POINT_OBJECT]['1']

Additional Functionality Changes

Rating Scale

yield sightlab.showRatings('how are you feeling?',ratingScale= scaleList, pauseTimer = True)

scaleList can be anything now (i.e. "A", "B", "C" or "Yes", "No")

sightlab.ratingChoice #Get a handle to the rating that is chosen

Can also add a start or end rating scale (see startTrial and endTrial)

Instructions

yield sightlab.showInstructions('test')

yield viztask.waitEvent('triggerPress')

yield sightlab.hideInstructions()

Gaze Based Interactions

def gazeActionEnd(e):

    if e.object == sightlab.sceneObjects[GAZE_OBJECTS]['target_objecct']:

        print('item found')

        viz.sendEvent(INITIATE_TRIAL_END)

vizact.addCallback(sightlab.GAZE_TIME_EVENT, findItem)

Adjusting Fixations/Saccade Parameters

Note: these need to be set after .startTrial()

sightlab.setDwellTimeThreshold(dwellTime = DWELL_THRESHOLD)      

sightlab.setFixationSaccadeThresholds(dispersionThreshold = 1, durationThreshold = 0.1)

Reset Position

viz.callback(viz.getEventID('ResetPosition'), sightlab.resetViewPoint)

This will reset your position back to the origin relative to your physical location. To change this point to a different value, will need to manually add the resetPosition code. 

Change Default Folder

sightlab.setEnvironmentDirectory('path_to_resources_folder')

Set Starting Text

sightlab.setStartText('press Spacebar to start')

Run a Loop per trial

for i in range(sightlab.getTrialCount()):

Scene Objects

ENVIRONMENT_OBJECT: vizfx.addChild(DEFAULT_ENVIRONMENT_PATH),

AVATAR_HEAD_OBJECT: vizfx.addChild(DEFAULT_AVATAR_HEAD_PATH),

AVATAR_RIGHT_HAND_OBJECT: vizfx.addChild(DEFAULT_AVATAR_RIGHT_HAND_PATH),

AVATAR_LEFT_HAND_OBJECT: vizfx.addChild(DEFAULT_AVATAR_LEFT_HAND_PATH),

GAZE_POINT_OBJECT: vizfx.addChild(DEFAULT_GAZE_POINT_PATH),

GAZE_OBJECTS: {},

GRAB_OBJECTS: {},

INVISIBLE_OBJECTS: {},

CUSTOM_OBJECTS: {},

AVATAR_OBJECTS: {}

Regions to not be visible

sightlab.addSceneObject("wall2", wall2, gaze = True, visible = False)

Getting Access to Eye Tracker

sightlab.getEyeTracker()

Getting Access to Regions of Interest for 360 Media

region1 = sightlab.getRegionOfInterest('tire')

Setting the STIM File Path

# Initialize StimReader with the STIM file

SR = stim_reader.StimReader(STIM_FILE_LOCATION)

SR.fillStimFileEntryList()

Additional Changes and Notes

TRIAL_END_EVENT is now TRIAL_END

VIZCONNECT_CONFIGS is now VIZCONNECT_CONFIG

ENVIRONMENT is a constant already used, use "ENVIRONMENT_MODEL" instead

Getting Position of Child Objects

If you are using env.getChild to access your objects you need to use a .getTransform to access the object's position:

targetTransform = env.getTransform('targetTransform')

It also works to call the getChild command on the GEODE associated with the object

Set Maximum Distance for intersection of Gaze Point

sightlab.setMaxDistance(1000) 

Getting 360 Media Sphere and Video File

sightlab.getMediaFile()

sightlab.getMediaObject()

Method Reference

Trial Management

• setTrialCount(count): Sets the total number of trials for the experiment.

• getTrialCount(): Returns the total number of trials.

• setTrialLength(seconds): Defines the length of each trial.

• startTrial(trialLength=-1, ...): Begins a trial, optionally specifying trial length, conditions, and starting text.

• endTrial(endTrialText=None, endExperimentText=None): Ends a trial and optionally displays text at the end of the trial or experiment.

• resetTrial(): Resets the current trial.

• getTrialNumber(): Retrieves the current trial number.

• runTrial(): Runs a trial based on pre-configured settings.

• getCurrentTrialDirectory(): Returns the directory where the current trial data is stored.

• getCurrentRepetition(): Returns the current repetition number for repeated trials.

• setStartText(text): Sets the text displayed at the start of the trial.

Object Management

• addSceneObject(name, object, gaze=False, grab=False, visible=True, avatar=False): Adds an object to the scene for gaze, grab, or tracking interactions.

• removeSceneObject(objectName): Removes a previously added scene object.

• removeGazeObject(objectName): Removes an object from gaze tracking.

• removeGrabObject(objectName): Removes an object from grab tracking.

• removeInvisibleObject(objectName): Removes objects that were set as invisible.

• setGazePointObject(): Defines an object that represents the participant's gaze.

• getGazePointObject(): Retrieves the current gaze point object.

Avatar Management

• setAvatarHead(head): Sets the head model for an avatar.

• getAvatarHead(): Retrieves the current head model of the avatar.

• setAvatarLeftHand(): Sets the left-hand model for an avatar.

• setAvatarRightHand(): Sets the right-hand model for an avatar.

• getAvatarLHand(): Gets the current left-hand model of the avatar.

• getAvatarRHand(): Gets the current right-hand model of the avatar.

Gaze and Tracking

• setDwellTimeThreshold(seconds): Sets the amount of time a participant needs to gaze at an object for it to be logged as a "dwell."

• getCurrentGazeEventData(): Retrieves the current gaze data.

• getGazeTimeObject(): Returns the current object being gazed at.

• setFixationSaccadeThresholds(): Sets the thresholds for defining fixations and saccades in the eye-tracking data.

• showGazePath(): Displays the path of the participant's gaze over time.

• toggleGazePoint(): Toggles the visibility of the gaze point in the scene.

Data Logging

• setDataDirectory(path): Sets the directory where data logs are saved.

• setExperimentSummaryData(column, value): Adds custom data to the experiment summary log.

• addTrackingTrialDataColumn(name): Adds a new column to the tracking data logs.

• setCustomTrialData(value, column): Sets a custom value in a specified trial data column.

• setDataLoggingState(state): Enables or disables data logging.

• getPlotData(): Retrieves data for creating visual plots from the trial data.

• getExperimentDataFolderPath(): Gets the folder path where experiment data is saved.

Ratings and Instructions

• showRatings(text, options): Displays a rating scale for participants to provide feedback during a trial.

• hideRatings(): Hides the rating scale from the view.

• showInstructions(text): Displays instructional text during the experiment.

• hideInstructions(): Hides the instructions currently shown to the participant.

Recording and Replay

• compressRecording(): Compresses the recorded session for playback.

• screenCapture(): Captures a screenshot of the current scene.

• storeReplayExecCode(code): Stores executable code during replay mode.

• setCustomReplayFlag(flag): Sets a custom flag for replay purposes.

• getMediaObject(): Retrieves media objects for replay.

• addToTimeline(event): Adds an event to the trial timeline for later reference.

• getTimeLineData(): Returns timeline data captured during the trial.

Control and Transport

• resetViewPoint(): Resets the participant's viewpoint to a default position.

• setStartPoint(position): Sets the starting position for the participant in the scene.

• setTransportPosition(position): Sets the position for the transport object (if using one).

• setTransportState(state): Enables or disables transport mechanics (e.g., walking, teleporting).

HUD and Console

• toggleHUD(): Toggles the visibility of the heads-up display (HUD).

• setConsoleState(state): Enables or disables the console display.

• togglePoint(): Toggles the display of point markers in the scene.

• setHeadlight(intensity): Sets the intensity of the headlight (lighting attached to the participant's viewpoint).

Region of Interest (ROI)

• addRegionOfInterest(name, object): Adds a region of interest (ROI) to the scene for tracking focus.

• getRegionOfInterest(name): Retrieves a specific ROI object from the scene.

Experiment Control

• runExperiment(): Starts the experiment loop.

• resetExperiment(): Resets the experiment to its initial state.

• conditionEventManager(): Manages condition-based events for the experiment.

• experimentSetupCompleteStatus(): Checks if the experiment setup is completed.

Miscellaneous

• getConfig(): Retrieves the configuration settings of the experiment.

• setConfigDirectory(path): Sets the directory where configuration files are stored.

• setRecordingsDirectory(path): Sets the directory where recordings are saved.

• setMaxDistance(distance): Sets the maximum distance for collecting gaze data.

• setConditionName(name): Sets the name for the current condition of the experiment.

• getConditionName(): Retrieves the current condition name.

• setHighlighter(object): Enables a highlighter on the specified object to make it visually stand out.

For more information on the additional modules and code available with Vizard see the Vizard Documentation. Or  the Vizard Command Index