Creating a New Scene

Introduction

This page will walk you through the process of creating and setting up a scene in SightLab VR. Whether you're working with 3D models or 360 media, this will help you get started with your project.

See this page for supported 3D model types and where to get 3D models. One good source for getting 3D models is http://www.sketchfab.com (download as .glb see this tutorial for more info). There are also a few environments you can start with in the environments folder in the Sample Project (or clicking "Built In", as well as some sample objects in the “sightlab_resources” folder.)

Setting Up Your Project

Locate your project folder:
- Use the SightLab SampleProject (default location: Documents\SightLab VR Projects 2.0)
- Make a copy of the "BlankProject" folder (recommended)
- Set up your own project folder
Prepare your assets:
- Add 3D models or 360 media to your project folder
- Sample environments are available in the "environments" folder
- Sample objects can be found in the sightlab_resources folder

Using the GUI Editor

Open the SightLab VR script:
- Double-click the SightLab_VR.py script file in your project folder (or the SightLab VR shortcut from the main Projects folder if using the Sample Project)
- This will launch the GUI editor

Note: if you have a different python editor installed on your system in addition to Vizard, you will need to ensure that the file opens in the Vizard python environment. If the GUI doesn't load, try right clicking on the script and choosing "Open With- Vizard 7" (in C:\Program Files\WorldViz\Vizard7\bin\winviz.exe if it's not available in the list).

2. Choose your hardware mode:

- Select "Desktop" if you're just setting up your experiment.
  
  Selecting a headset will make the scene in the GUI look strange as it will be linked to the headset tracking, you can select your headset after the experiment is configured when running the session.

Create a new project:

Click "New"
Enter a name for your project
Click "Save Project"

Additional options:

Load existing .stlb files (SightLab experiment files)
Edit your Python script by clicking "Edit [filename]"
Open your project folder by clicking the folder icon

Opening the Experiment Options Editor

In the GUI editor, click "Modify" to open the Experiment Options editor.
This is where you can edit and open your 3D models or 360 media, as well as set up all your individual trial options (start/stop conditions, tracking, etc.)

Note: You can also run the Inspector 3D model editor directly from the Inspector shortcut in the main SightLab projects folder, or from the "Tools" menu in the Vizard IDE.

Managing 3D Models and Media

In the Experiment Options editor, you'll see any 3D models and media you've added to your resources folder.

Click the Environment dropdown to see available 3D models.
Select "360 Media" if you're using 360 media instead.

Changing Working Environment

Click "Change" to switch the working environment directory to another folder within your project folder.
Click "Built-In" to use the assets included with SightLab.

Left Shift - Toggle locking the scene (this will also go into region of interest selection mode with 360 media)

. (period)/ F1 - Toggle hiding the menu

Use the mouse to look around

WASD to move left/right/forward/backward (or arrow keys)

Z to move down, X to move up (or Pageup and PageDown)

Q, E rotate left and right (or use mouse)

R Reset viewpoint

/ Take screenshot

; Toggle Mouse Lock

, Toggle showing the scene

F2- Toggle fullscreen

F3- Toggle rendering/ wireframe modes

F4- show frame rate (click again to show graphics performance)

Escape - Exit

ctrl+ F6 - Toggle docked with code

SPACEBAR- Toggle playback of media if using 360 media

1 - Select Regions of Interest with 360 Media

IJKL - Move virtual gaze point (or just use mouse)

Alt + i - Float window and activate Vizard IDE interactive input

Editing Models

Click "Edit" to open the chosen model in the 3D model editor (Inspector) where you can add new objects for collecting data or interacting with, tagging regions of interest, adding lighting, swapping textures, setting your starting point, and more.
For 360 media, this will open the media in your preferred media player.
After making changes in Inspector, click the "Refresh" icon to apply them.

Adding New Models

Click the "+" icon to load a new model not already in your project folder.
This opens a blank instance of Inspector.
In Inspector, click "File - Load" to open a new model.

Using Inspector

Inspector is SightLab's 3D model editor

Inspector Controls

Drag Left Mouse Button: Orbit the viewpoint

Shift + Click Left Mouse Button: Move viewpoint to clicked on surface

Drag Right Mouse Button: Pan the view

Scroll Wheel: zoom towards/away from viewpoint

Z: zoom to selected node

- For more information on Inspector see this page in the Vizard documentation

Opening Models in Inspector

If you clicked "Edit" in the Experiment Options editor, your selected model will load automatically.
If you clicked the "+" symbol, use "File - Open" to add a new model.

Checking Environment Size

Click on the root node in the top left scene graph.
Look at the bottom right to see the size in meters.

Setting the Starting Point

Click "File - Add".
Either use the "SIGHTLAB_STARTING_POINT" in the "scene_objects" folder included in the "Sample Project" (Projects\SampleProject\Resources) or navigate to C:\Program Files\WorldViz\Vizard7\resources\sightlab_resources\objects.
Add the SIGHTLAB_STARTING_POINT object.

Note: There's also a shortcut to this location at Documents\SightLab VR Projects 2.0\Util_Files\SightLab_Resources.

Transforming Objects

Use these tools to modify objects in your scene:

Move: Reposition objects
Scale: Change object size
Rotate: Change object orientation

To change the participant's starting position, move and rotate the SIGHTLAB_START_POINT object.

Adding Objects of Interest

If your environment model doesn't include all the objects you want to measure eye tracking data on:

Go to "File - Add".
Add the desired objects.
Use the transform tools to position, rotate, and scale the object(s).

Understanding Nodes

The scene graph on the left shows your list of nodes.
A red, blue, and green node is a group node, which is crucial for collecting data on objects.

Creating Group Nodes

Most added objects come in as group nodes.
If not, right-click and select "Insert Above - Group" on any node you wish to add as an object of interest.

For objects already in your model that you want to collect data on, add a group node above them.
For selecting areas of interest, see the section about that below.
To move, scale or rotate the objects, click on the transform node (with the gear icon) and use the transform tools. If there is no transform node, right click and choose Insert Above- Transform. Note: there may be issues if you have a group node object underneath another scene object.

Renaming Objects

Right-click on the group node.
Select "Rename".
Enter a unique name (check for existing names using the "Search" option in the top right).

Tip: To automatically exclude an object from data collection, add the tag "_env" to its group name.

Adding Regions of Interest to 3D Model Scenes

Regions of Interest (ROIs) allow you to specify areas in your scene for data collection or interaction. Here's how to add them:

Adding ROI Objects

In Inspector, select "File - Add".
Either use the "RegionOfInterest.osgb" in the "scene_objects" folder included in the "Sample Project" (Projects\SampleProject\Resources) or navigate to C:\Program Files\WorldViz\Vizard7\resources\sightlab_resources\objects.
Add one of the RegionOfInterest.osgb objects.

Positioning ROIs

Click on the "rootNode" under the "FixationRegion" group.
Use the move, rotate, and scale transform tools to position and size the region.

Naming ROIs

In the Scene Graph on the left, right-click on the region.
Select "Rename".
Give the region a descriptive title (e.g., "PeanutButter").

Creating Multiple ROIs

Repeat the process for each area you want to add.
Shortcut: Hold down "Shift" and move a region to automatically create a new one.

You can also add things such as lights, backgrounds and more with Inspector. To add a light, go to Create- Light and choose Directional, Point or Spot Light. Clicking on the light will bring up its attributes on the right.

Saving Changes

Select "File - Save" to save your changes in Inspector.
Close the 3D model editor window.

Click the "Refresh" icon in SightLab to update the changes.

Next, select which child objects of the scene you want to collect additional data on (such as view count, dwell time, total fixations, etc.), be made visible per trial or be grabbable. Use the top checkboxes to select or deselect all. Make sure to deselect "Visible" on any regions of interest you have added that you don't want a participant to see the outline of.

Working with 360 Media

SightLab VR also supports 360-degree videos and images. Here's how to work with them:

Switching to 360 Media Mode

In the Experiment Options editor, switch the Mode to "360 Media".
This enables adding 360 videos and images to your session.

Selecting Media

Use the dropdown to see media added to your resources/media folder.
Click "Change" to switch to another folder inside your project folder.
Click "Built-In" to work with the included 360 media resources.
Click "Edit" to open the media in your default media player.

Media Options

Adjust these settings for your 360 media:

Media Type: Choose between videos or images.
Format: Select stereo or mono files.

Adding Regions of Interest to 360 Media

Click "Add" or press the left Shift key to enter ROI tagging mode (requires being in Desktop mode for the GUI, i.e. selecting "Desktop" from the first dropdown)
A virtual gaze point will appear for placing ROIs.

Tip: Press the ";" (semicolon) key to lock the mouse cursor on the window and maintain focus.

Placing ROIs in 360 Media

Move the virtual gaze point
Press the "1" key to set new regions.

Customizing ROIs

After setting a new region, you can:

Give the region a name
Adjust scale and opacity using the sliders
Change the debug color by clicking on the color wheel icon
Delete regions using the trash can icon

Tip: Reduce the opacity of ROIs once you've set them all so participants don't see them during the experiment.

Configuring Trials

After setting up your 3D models and/or 360 media, you can configure trial-by-trial or condition parameters in the "Trials" section.

Count - Enter the number of trials you want to generate in the "Count" field and click "Generate" (these will then be able to be saved as your project or a block of trials in the .stlb project file).

Current Trial - Click the dropdown to jump to any of the trials or conditions, where you can adjust parameters such as the various conditions of which environment you are using, which objects are being modified, various triggers and more.

Can also use the left and right arrow keys to go between trials/conditions and use the "+" and "-" symbols to add or delete trials (if adding a trial this will insert it directly after the current one, deleting will delete the current one).

Tracking - Keep this checked to save to the data files and allow for the session replay. Uncheck if you are wanting to run practice trials or not save any data or use the replay mode.

In the "Label" field you can enter a specific label or condition for this trial. This will save into the data files.

Adjust what are the start and end conditions per trial (or select default to apply this to all trials). For instance you can choose the start or end of a trial to be the following:

Keypress or button press
Timer
Custom Event
The end of a media file
A Gaze Event (put the name of the object that you are waiting for a user to view for over the treshold)
None, if specified to something in the code

When you are finished with setting your Experiment Options, click "Done"

Finalizing Your Project

Give your project a name (if not done already).
Click "Save Config".
Optional: Click "Randomize" to shuffle the order of your trials.
Choose if you want to have your tracking data files save one data file per trial or one combined file.

Note: For more advanced randomization options or to randomize blocks of trials, you'll need to use the code.

Thresholds Section

- Dwell TIme Threshold - The threshold to use for saying when an object is being viewed. Default is 500 milliseconds, can be modified either with this slider or in the code.
- Fixation Duration - The amount of time to wait before checking for the dispersion angle to denote a fixation. Set to 100 milliseconds by default.
- Dispersion Angle - The angle in degrees to check for a fixation (set to 1 degree of angular distance by default).
- Noise Reduction - Adjusts the number of frames to average the data from for filtering out noise

Options Section

- Screen Record - Will record a video of the session (see below)
- BIOPAC Markers - If using Biopac, start up Acqknowledge and if this is checked will synchronize and start the Acqknowledge server and send events either when an object is being viewed or for custom events.
- Press "Continue" when done.

Now you can click "Continue" to test your project. This can now be run as a participant with your chosen hardware. See the section "Running a Session Single User" or "Running a Session Multi-User", or see "Supported Hardware" with links to how to set up your hardware configuration.