Street Walking Example

The Street Walking Example demonstrates how SightLab can be used to create an immersive single- or multi-user pedestrian study while simultaneously recording eye tracking, participant movement, traffic behavior, and experiment events.

The example is a useful starting point for studies involving:

Pedestrian attention and street-crossing behavior
Visual attention to vehicles, signs, pedestrians, and hazards
Traffic-density comparisons
Vehicle-speed manipulations
Spatial navigation and walking behavior
Multi-user pedestrian studies
Eye tracking and fixation analysis
Behavioral, survey, and demographic data collection

Overview

Participants physically or virtually move through a street environment while SightLab records their experience — and the example demonstrates a wide slice of what SightLab can do for pedestrian and traffic research in one working setup:

Real traffic flow — vehicles follow recorded routes on any environment, keep their distance, stop at traffic lights, brake for the participant, and never drive through walls or each other; vehicle count, speed, lights, and yielding vary per trial from a simple condition file (see Traffic System)
Flexible trial ending — end trials on a proximity event, a timer, a key press, or a combination
Immersive audio — ambient city sound built in, with room to layer in traffic noise, sirens, or spoken instructions
Eye tracking on real objects — vehicles, and anything else in the scene, can be registered as gaze-tracked Regions/Objects of Interest, so attention to individual cars, signs, or hazards can be measured directly
Full participant movement tracking — walking path, position, velocity, and turning behavior recorded alongside gaze on the same timeline, with support for full-body tracked avatars in addition to standard head and hand tracking
Rich data export — raw tracking, eye-tracking, fixation, and trial-timeline data, plus a summarized experiment export (including average walk speed, walk velocity, traffic count, fixation count, and more), ready for Python, R, MATLAB, Excel, or SPSS
Session Replay — walk paths, scan paths, fixations, and heatmaps visualized directly inside the original 3D environment, not just as spreadsheet rows
Multi-user support — the same experiment can run as a synchronized, multi-participant study
Participant input — rating scales, instructions, and demographic questionnaires drop into the same trial workflow
The rest of the SightLab platform — hand/foot/face tracking, avatars, biofeedback integrations, adaptive trials, and more are all available to layer on top

The project folder includes:

File	Purpose
`Street-Walking-Sample.py`	Single-user experiment
`Street-Walking-Sample_Server.py` / `_Client.py`	Multi-user version using SightLab's server/client framework
`Street-Walking-Sample-NonGUI-STIM.py`	Non-GUI (auto-start) version that reads its trial conditions from a STIM/spreadsheet file (`Resources/stim_file-non-GUI.csv`) instead of the GUI config tool.
`Street-Walking-Sample_Replay.py`	Opens recorded sessions in Session Replay
`traffic_config.py`	All traffic settings: vehicle pool, speeds, signal timing, pedestrian yielding, recorder keys
`modules/traffic/`	The reusable traffic system (routes, vehicles, lights, simulation, route recorder)
`Resources/traffic/`	One route file per environment (`street_day.json` and `street__night.json` included; others are recorded in-app)
`Resources/vehicles/`	Vehicle models; every model in this folder is used as traffic

The sections below cover each of these in more detail, including how they can be extended for a specific study.

Running the Street Walking Study

The Street Walking Example uses the normal SightLab trial workflow: each trial loads a row of conditions, plays out, and is recorded.

A stimulus/condition file is a convenient way to define those conditions per trial — one row per trial, one column per condition. The supplied Resources/stim_file.csv is an example:

Trial	number of vehicles	traffic speed	traffic lights	yield to pedestrian	starting point	weather	median	fog
1	3	10	on	on	position1	day	on	off
2	1	12	off	on	position2	night	off	on
3	1	8	on	off	position3	day	on	off

The four traffic columns are read by the traffic system (see Traffic System); starting point, weather, median, and fog are placeholders showing how further conditions fit in. Additional columns — audio, instructions, or anything else a study needs — can be added the same way and read via StimReader.

These conditions can be stored alongside the participant's behavioral and eye-tracking data for later analysis.

Ending a Trial

The shipped scripts end each trial on a key press (the GUI version uses whatever End condition is set in the trial settings). Any of the following can be used instead, or combined so the trial ends on whichever happens first:

Proximity event — end when the participant reaches a waypoint, crosses to the far sidewalk, or a vehicle gets too close. See Proximity Sensors.
Timer — give the participant a set amount of time to walk.
Key or trigger press — let the participant free roam until a key or controller trigger is pressed.
Gaze event — end once the participant has looked at a specified object, such as the traffic signal.
Custom event — end from any other logic in code with viz.sendEvent(INITIATE_TRIAL_END).

These are chosen in the GUI's trial settings (End condition) or, in the non-GUI version, by replacing the yield viztask.waitKeyDown(' ') line before sightlab.endTrial().

Configurable Trial Conditions

Traffic, vehicle behavior, environment, and audio can all vary by trial — usually driven by a stimulus/condition file like the one above, though conditions can also be set directly in code. Any of these can be stored alongside the participant's gaze and movement data for analysis.

Traffic

The number of vehicles present (number of vehicles) and whether traffic lights are active (traffic lights) can vary by trial, letting researchers compare low- and high-traffic or signalized and unsignalized conditions and analyze whether, when, and for how long a participant looked at each vehicle. Whether vehicles brake for the participant (yield to pedestrian) is a per-trial condition as well. The mechanics are described under Traffic System.

Vehicle Speed

Vehicle speed can be set per trial with the traffic speed column (meters per second) — for example comparing slow, medium, and fast traffic — and examined against changes in gaze behavior or walking speed as vehicles approach. Left blank, each lane uses the speed saved in its route file.

Starting Position & Environment

Where the participant begins, the weather (day/night, fog), lighting, and road or median configuration can all be varied by trial to study how environmental context affects visual search and crossing behavior.

Audio

The example includes a looping city-ambience track that plays for the duration of each trial. The same approach can add other layers — traffic noise, horns, sirens, spoken instructions — either as a constant backdrop or as a trial-varying condition.

Traffic System

The example ships with a reusable traffic system (modules/traffic/, configured in traffic_config.py) that gives the street real, controllable traffic flow: vehicles follow the road, keep their distance from each other, obey traffic lights, brake for the participant, and never drive through walls or each other. It works in any environment without a 3D modeling tool, because routes are recorded inside the running experiment.

How it works

The system is kinematic (no physics engine), so it stays cheap even with a dozen vehicles in a large city model:

Routes, not physics — each lane is a line recorded along the road and saved as Resources/traffic/<environment>.json. When a trial starts, the lane is smoothed, resampled every meter, and each sample is snapped to the ground with a single downward ray. Vehicles then follow that baked path, so they sit on the road surface across hills, ramps, and bridges with no per-frame ground raycasts.
Car following — vehicles in the same lane keep a speed-dependent gap (Intelligent Driver Model) and can never overlap. Vehicles from other lanes that cross or merge ahead are treated as obstacles too.
Traffic lights — a stop line on a lane belongs to a signal group of an intersection. Each intersection cycles its groups through green → yellow → all-red, and vehicles queue behind the stop line on red. An intersection with a single group acts as a mid-block pedestrian crossing (the all-red stage is the walk phase). Lights are built procedurally (no model needed) and registered as gaze objects, so looks at the signal are recorded.

Bumper rays — the same slope-aware raycast sweep as the Driving Example runs ahead of every vehicle along its lane. If a wall, prop, or anything else intersectable is in the way (for example a mis-recorded route), the vehicle brakes instead of passing through, and a console warning names what blocked it.
Participant awareness — a vehicle brakes for the participant standing in its lane ahead (yield to pedestrian), and a hit fires a TRAFFIC_HIT event with a crash sound. Nearest-vehicle distance is logged every frame.

Recording routes for an environment

Routes are authored in-app with the route recorder. This is how a new environment (for example city_rtx2.osgb, which ships without a route) gets traffic:

Set RECORD_ROUTES = True in traffic_config.py and run Street-Walking-Sample.py.
Start a trial in the environment, then press F5 to open the recorder (traffic pauses, and the key list appears on screen).
Walk or fly along a lane in the direction cars should drive, pressing F6 at each bend (or t to drop a waypoint automatically every few meters while you walk). Waypoints are snapped to the ground under you.
Press F8 to close the lane as a loop, or F9 for an open road whose vehicles respawn at its start. Repeat for the other lanes.
Stand where cars should stop and press F10: a stop line is added to the last lane and a traffic light is placed at the curb, facing the approaching traffic. PAGE DOWN cycles the signal group (A, B, C, D) used for the next stop line, so opposing streets get different groups. INSERT starts a new intersection centered where you stand.
Press F12 to save. The file is written, re-baked, and traffic starts on it immediately.

Key	Action
F5	Show / hide the recorder
F6	Drop a waypoint at your position
t	Toggle automatic waypoint dropping while walking
F7	Undo the last waypoint
PAGE UP	Delete the waypoint nearest to you
F8 / F9	Finish the lane as a loop / as an open road
F10	Add a stop line + traffic light to the last lane
INSERT	Start a new intersection at your position
PAGE DOWN	Cycle the signal group for the next stop line
END / HOME	Raise / lower the last lane's speed by 1 m/s
DELETE	Delete the last lane
F11 (twice)	Clear everything and start over
F12	Save and reload

All keys can be changed in RECORDER_KEYS in traffic_config.py. Route files are plain JSON and can also be edited by hand; set DEBUG_DRAW_ROUTES = True to draw the loaded lanes, stop lines, and intersections during a normal run. The included street_day.json / street__night.json define two lanes along the street with a signalized crossing in front of the start point, so the example's street trials have traffic out of the box. An environment without a route file simply runs without traffic (a message is printed), so record a route for each other environment you use.

Vehicle models

Every .osgb in Resources/vehicles/ is used as a traffic vehicle; the pool (MAX_VEHICLES, 12 by default) cycles through the files, so adding a model is a matter of dropping it in the folder. Models are re-centered and turned to face the road automatically. If a model drives backwards or is the wrong size, add an override:

VEHICLE_MODEL_OVERRIDES = {'car3.osgb': {'yaw': 180}, 'Taxi.osgb': {'yaw': 180, 'scale': 1.0}}

Vehicles are registered as gaze objects (traffic_car_00 … traffic_car_11), so dwell and fixation data is recorded per vehicle, and they appear in Session Replay.

Per-trial control from the STIM file

The traffic columns in Resources/stim_file.csv (and stim_file-non-GUI.csv) are read for each trial; any column that is missing or blank falls back to the default in traffic_config.py:

Column	Meaning
`number of vehicles`	How many vehicles from the pool are active (0 to `MAX_VEHICLES`)
`traffic speed`	Target speed in m/s for every lane (blank = each lane's own speed)
`traffic lights`	`on` / `off` — with lights off, crossing lanes yield to each other at the intersection instead
`yield to pedestrian`	`on` / `off` — whether vehicles brake for the participant in their lane

The same settings can be applied in code with traffic.configure({'number of vehicles': 4, 'traffic lights': 'off'}) before traffic.start().

Data recorded

Raw trial data: Nearest Vehicle Distance (meters from the participant to the closest vehicle body, every frame) and a hit by traffic_car_XX flag when a moving vehicle reaches the participant.
Experiment summary: Traffic Count, Min Vehicle Distance, Vehicle Hits.
Gaze data: per-vehicle and per-light dwell time, view counts, and fixations, like any other gaze object.
Events: viz.getEventID('TRAFFIC_HIT') is sent with the vehicle name, which can end a trial or trigger a rating.

Configuration

The most useful options in traffic_config.py:

ADD_TRAFFIC, RECORD_ROUTES, DEBUG_DRAW_ROUTES — master switch, recorder, and route visualization.
MAX_VEHICLES, DEFAULT_VEHICLES, DEFAULT_SPEED_MPS, SPEED_JITTER — pool size and speeds when the STIM file does not specify them.
MIN_GAP, TIME_HEADWAY, MAX_ACCEL, COMFORT_DECEL — car-following behavior.
GREEN_TIME, YELLOW_TIME, ALL_RED_TIME, STOP_LINE_MARGIN — signal timing (a route file can override the timing per intersection).
CORRIDOR_HALF_WIDTH, PEDESTRIAN_LOOKAHEAD, HIT_RADIUS, HIT_SOUND — how vehicles react to the participant.
BUMPER_HEIGHT, BUMPER_RANGE, SLOPE_LIMIT, RAYCAST_EVERY_N_FRAMES, BUMPER_EXCLUDE_NODE_NAMES — bumper rays. Invisible gaze-catcher geometry such as crate.osgb in the street scenes is excluded by name so it never blocks traffic.
RANDOM_SEED — fixed so every run (and every multi-user peer) gets the same vehicle layout.

Multi-user and replay

In the server/client scripts the server simulates the traffic and SightLab's scene-object synchronization pushes vehicle positions to every client; the client creates the same vehicle pool with simulate=False. Session Replay rebuilds the vehicles from their model files and plays back their recorded movement alongside the participant.

Troubleshooting

"no route file … set RECORD_ROUTES = True" — the environment has no Resources/traffic/<name>.json yet; record one as described above. Traffic is simply disabled for that trial.
"… has been blocked for 5 s by …" — a vehicle's bumper rays are hitting scene geometry. Move the route away from the object, or add the node name to BUMPER_EXCLUDE_NODE_NAMES if it is invisible helper geometry.
A vehicle drives backwards or floats — add a yaw or scale entry in VEHICLE_MODEL_OVERRIDES.
Vehicles nose the wrong way on slopes — flip PITCH_SIGN.

Eye Tracking and Visual Attention

Vehicles and other objects in the environment can be registered as gaze-tracked Regions or Objects of Interest, which is what lets SightLab associate a participant's gaze behavior with specific objects — crosswalks, signs, buildings, or approaching traffic.

This makes it possible to analyze, for any registered object, whether it was viewed, how long, how many separate times, and when during the trial.

Participant Movement

SightLab records the participant's tracked movement through the environment, making it possible to reconstruct not only what someone looked at, but also where they were and how they moved while looking at it.

Recorded and derived measures include:

Walking path and position over time
Direction of travel and movement velocity
Stops, pauses, and turning behavior
Relationship between participant and vehicle position

This can be tracked using standard head and hand tracking, or extended to full-body tracked avatars for studies that need whole-body posture and movement.

This is particularly useful for pedestrian research because gaze and movement can be examined on the same timeline. For example:

A participant slows while approaching the curb, looks left toward a fast-moving vehicle, waits for the vehicle to pass, and then continues across the street.

SightLab's recorded data and Session Replay allow these events to be examined together.

Data Collection and Export

SightLab records experiment data that can be exported for additional analysis. The data pipeline can include several complementary files rather than only a single summary spreadsheet:

Raw Tracking Data

Frame-by-frame or sample-level information used to reconstruct the participant's session — head/user position and orientation, eye gaze, gaze intersection, tracked objects, walking speed, nearest-vehicle distance, and trial time.

Eye-Tracking Data

Depending on the eye tracker and configuration: gaze position/direction, gaze intersections, fixations, saccades, dwell behavior, and view counts.

Fixation Data

SightLab performs fixation/saccade analysis and generates fixation-specific timeline information — location, timing, duration, and sequence of visual attention.

Trial Timeline

A chronological representation of events during the trial, useful for relating:

Participant movement
        ↓
Vehicle approaches
        ↓
Participant fixation on vehicle
        ↓
Participant slows/stops
        ↓
Vehicle passes
        ↓
Participant continues walking

Experiment Summary

Aggregated metrics and custom experiment values, e.g.:

Participant_ID
Trial
Weather
Traffic_Count
Vehicle_Speed
Min_Vehicle_Distance
Vehicle_Hits
Average_Walking_Speed
Rating

Replay Data

SightLab also saves the information necessary to reconstruct the session inside Session Replay.

The exported data can subsequently be analyzed using tools such as Python, R, MATLAB, Excel, SPSS, or custom research pipelines.

Session Replay

One of the major advantages of the Street Walking Example is that a session doesn't have to be understood only through spreadsheets — SightLab Session Replay reconstructs the participant's recorded session inside the original virtual environment, and researchers can move through the replay timeline to inspect gaze and movement spatially.

Replay supports several visualization modes, which can be toggled and combined:

Walk Paths

Shows the participant's physical trajectory through the street environment in 3D, instead of examining only X/Y/Z values in a spreadsheet. This makes behaviors like curb hesitation, stepping toward the roadway and backing away, or route deviations immediately visible.

Scan Paths

Shows how visual attention moved through the scene over time — for example crosswalk → approaching car → traffic light → opposite sidewalk. This answers not just what was viewed, but in what order, which can reveal the strategies participants use to decide whether it's safe to cross.

Fixations

Visualizes calculated fixation locations in the environment, alongside fixation duration, sequence, and the object being fixated on — useful for examining a participant's visual decision-making process as they move through the scene.

Heatmaps

Aggregates visual attention into a heatmap over the scene, useful for quickly seeing whether participants are primarily looking at vehicles, checking the traffic signal, or scanning the roadway more broadly under different conditions.

Multiple Participants

Because SightLab Replay is also built for multi-user recordings, the same framework can show multiple participants' walk paths and gaze simultaneously — useful for pedestrian-to-pedestrian interaction, group navigation, or shared decision-making studies.

Multi-User Studies

The Street Walking workflow can natively use SightLab's server/client multi-user architecture via the included Street-Walking-Sample_Server.py and _Client.py.

These scripts extend the same setup — traffic, audio, and gaze tracking work the same way as the single-user version, with SightLab's server/client framework keeping participants synchronized. The server simulates the traffic and its vehicle positions are synchronized to every client, so all participants see the same cars.

Possible applications include:

Two pedestrians deciding when to cross together
Social influence on crossing behavior
Pedestrian/driver experiments
Instructor and participant scenarios

Because this is built on SightLab's multi-user framework, the study can also take advantage of SightLab's other multi-user features, including avatars, synchronized trials, presentation control, and multi-user replay.

Participant Input: Ratings, Instructions & Demographics

None of the following are wired into the base Street Walking sample, but they're standard SightLab patterns that fit naturally into the same trial loop shown above.

Rating Scales

For example, after crossing the street:

yield sightlab.showRatings(
    "How safe did you feel crossing the street?",
    ratingScale=["1", "2", "3", "4", "5"],
    pauseTimer=True
)

Rating responses are saved with the participant's experiment data, and can answer questions like how safe or realistic a crossing felt, or how confident the participant was in their decision.

Instructions

SightLab's normal instruction system can display text such as:

Walk along the sidewalk. When you believe it is safe, cross the street and continue to the marked destination.

Instructions can be shown at the start of the experiment, before individual trials, between conditions, or before a questionnaire.

Demographics

SightLab examples demonstrate using input dialogs to collect demographic or questionnaire information and save it into the experiment summary — for example age, driving experience, walking frequency, or VR experience — so it can be combined with behavioral and eye-tracking measures during analysis.

Other SightLab Features

Because the Street Walking study is a normal SightLab experiment, it isn't limited to the functionality demonstrated in the base sample. Capabilities commonly relevant to pedestrian and traffic studies include:

Regions of Interest, dwell time, and view counts
Gaze-based interactions and object grabbing
Hand, foot, and face tracking; full-body avatars
Trial randomization and adaptive experiments
External data synchronization (e.g. Lab Streaming Layer, BIOPAC)
Screen recording and custom experiment events
Custom Python libraries and experiment logic

The full platform feature set is covered in the SightLab Documentation.

Example Research Questions

Visual Attention

When does a participant first notice an approaching vehicle?
Which objects receive the greatest fixation time?
Does visual search behavior change as vehicle speed increases?

Pedestrian Movement

Where does the participant stop before crossing, and how long do they hesitate?
Does their walking velocity change when a vehicle approaches?

Traffic

Does increasing traffic density affect crossing decisions?
How does vehicle speed affect visual attention?

Environmental Conditions

Does night or fog alter walking speed or fixation duration?

Multi-User Behavior

Does another pedestrian influence crossing behavior?
Where do users look during social interaction?

Example Study Workflow

A complete Street Walking experiment could follow this workflow:

1. Collect participant information
            ↓
2. Show experiment instructions
            ↓
3. Load experimental condition
   • Traffic count
   • Vehicle speed
   • Weather
   • Audio
            ↓
4. Start SightLab recording
            ↓
5. Participant walks through street
            ↓
6. Record simultaneously
   • Eye tracking / fixations
   • Head/user movement and position
   • Traffic and vehicle behavior
   • Trial events
            ↓
7. End trial
   • Waypoint reached, timer, key press, or combination
            ↓
8. Present rating scale/questionnaire
            ↓
9. Continue to next condition
            ↓
10. Export experiment data
            ↓
11. Open Session Replay
            ↓
12. Analyze walk paths, scan paths, fixations, heatmaps, and trial summaries

For additional information, see the SightLab documentation:

SightLab Documentation: https://help.worldviz.com/sightlab/
Session Replay: https://help.worldviz.com/sightlab/session-replay/
Example Scripts: https://help.worldviz.com/sightlab/example-scripts/
Adding Instructions: https://help.worldviz.com/sightlab/adding-instructions/
Multi-User Custom Experiments: https://help.worldviz.com/sightlab/multi-user-custom-experiments/
Proximity Sensors: https://help.worldviz.com/sightlab/proximity-sensors/
Using a Timer for Experiment: https://help.worldviz.com/sightlab/using-a-timer-for-experiment/
Driving / Vehicle Examples: https://help.worldviz.com/sightlab/driving-example/

Summary

The Street Walking Example demonstrates how a pedestrian VR experiment can combine moving traffic, audio, eye tracking, participant movement, raw data collection, and interactive Session Replay in one research workflow, starting from a small, concrete base script.

The experiment can scale from a relatively simple single-user crossing study — as shipped — to a multi-condition or multi-user research platform by adding more conditions to the same trial-based pattern.

After data collection, researchers can move beyond spreadsheets and reconstruct the participant's experience directly in the virtual environment: where they walked, where they looked, what they fixated on, and how those behaviors related to traffic and experimental conditions.

Street Walking Example

Overview

Running the Street Walking Study

Ending a Trial

Configurable Trial Conditions

Traffic

Vehicle Speed

Starting Position & Environment

Audio

Traffic System

How it works

Recording routes for an environment

Vehicle models

Per-trial control from the STIM file

Data recorded

Configuration

Multi-user and replay

Troubleshooting

Eye Tracking and Visual Attention

Participant Movement

Data Collection and Export

Raw Tracking Data

Eye-Tracking Data

Fixation Data

Trial Timeline

Experiment Summary

Replay Data

Session Replay

Walk Paths

Scan Paths

Fixations

Heatmaps

Multiple Participants

Multi-User Studies

Participant Input: Ratings, Instructions & Demographics

Rating Scales

Instructions

Demographics

Other SightLab Features

Example Research Questions

Visual Attention

Pedestrian Movement

Traffic

Environmental Conditions

Multi-User Behavior

Example Study Workflow

Related SightLab Documentation

Summary