Truck Pre-Trip Inspection VR Walkthrough

Truck Pre-Trip Inspection

Overview

This proof of concept implements an FMCSA/CVSA-aligned pre-trip inspection checklist for a 2-axle cargo truck. It supports both single-user and multi-user modes with synchronized inspection checklists, horn/headlight interactions, and teleportation.

Interactive 3D checklist panel with proximity-based navigation
Touch-based inspection — touch spheres to check/uncheck items, confirm with YES/NO
Horn and headlight verification — physical interaction required before marking those items complete
Teleport navigation — jump between predefined inspection locations around the truck
Shared checklist (multi-user) — all clients update a single server-managed checklist
Progress tracking — saves to CSV and generates text reports per session
SightLab integration — eye-tracking, gaze analytics, and session replay

File Structure

Truck_Walkthrough/
├── Truck_Inspection.py               # Single-user inspection script
├── Truck_Inspection_Server.py        # Multi-user server script
├── Truck_Inspection_Client.py        # Multi-user client script (locations set 1)
├── Truck_Inspection_Client2.py       # Multi-user client script (locations set 2)
├── Truck_Inspection_Replay.py        # Session replay viewer
├── inspection_checklist_manager.py   # Checklist data management
├── proximity_inspection_system.py    # 3D touch-based inspection UI
├── data/
│   ├── pretrip_inspection_checklist.csv   # Checklist template (do NOT edit during sessions)
│   └── <timestamp>__experiment_data/      # Session output folders (created per run)
│       ├── pretrip_inspection_checklist.csv               # Working checklist copy
│       ├── <timestamp>__pretrip_inspection_checklist.csv   # Final checklist snapshot
│       ├── <timestamp>__inspection_report_trial_N.txt      # Text report
│       ├── <timestamp>__experiment_summary_client_N.csv    # SightLab summary
│       ├── trial_data/                                     # Gaze/tracking CSVs
│       └── replay_data/                                    # Session replay files
├── locations/
│   └── locations.txt                 # Teleport positions (Client 1 / single-user)
├── locations2/
│   └── locations.txt                 # Teleport positions (Client 2)
├── sightlab_configs/                 # SightLab configuration files
└── Resources/
    └── environments/
        └── Truck_Showroom.osgb       # Truck environment model

Running the Application

Single-User Mode

Run Truck_Inspection.py
Press SPACE to start the inspection trial
Complete the checklist using touch interactions
Press SPACE to end the trial and save progress

Multi-User Mode

Multi-user mode uses a server–client architecture. The server is the source of truth for the checklist — all item checks, clears, and resets from any client are sent to the server, which updates the master checklist and broadcasts changes to all connected clients.

Open Truck_Inspection_Server.py and run it
Open Truck_Inspection_Client.py on the first client machine and run it
Open Truck_Inspection_Client2.py on the second client machine and run it
Client2 uses a separate set of teleport locations (locations2/) so that users don't overlap with each other at the same positions
Each client connects to the server via the SightLab GUI
Start the experiment from the server GUI — all clients begin simultaneously
Any client (or the server operator) can check items, sound the horn, or toggle headlights — all actions sync across all participants

Teleportation in multi-user mode:
- Number keys (1–9) — teleport only the individual user who pressed the key to that location
- Panel teleport buttons (touching a location sphere on the menu) — teleport all clients and the server view to the selected location

Other key behaviors in multi-user mode:
- The checklist CSV is saved only on the server, in the session's experiment_data folder
- Horn sound and headlight toggle sync to all clients instantly
- The template file in data/pretrip_inspection_checklist.csv is never modified

Controls

Inspection Panel

Key	Action
`M`	Reposition panel in front of you
`LEFT` / `RIGHT`	Navigate to previous / next item
`C` / `V`	Navigate to previous / next item (alternative)
`N`	Jump to next unchecked item
`B`	Clear (uncheck) current item
`G`	Clear all items (reset entire checklist)
`U`	Toggle debug visualization (show proximity sensors)

VR Interactions

Action	How
Check item	Touch the blue sphere, then touch YES (green) to confirm
Cancel check	Touch NO (red) to cancel
Sound horn	Move hand near the horn object and press trigger
Toggle headlights	Move hand near the headlights switch and press trigger
Teleport	Touch a location sphere on the panel

Other Keys

Key	Action
`SPACE`	Start / End trial
`H`	Toggle horn proximity debug
`L`	Toggle headlights proximity debug
`/`	Save current position as teleport location and take screenshot
`1`–`9`	Quick teleport to numbered locations

Session Replay

Truck Pre-Trip Inspection

Use Truck_Inspection_Replay.py to review completed sessions. You must run at least one experiment session before replay data is available.

Starting Replay

Open Truck_Inspection_Replay.py in Vizard and run it
Select a session from the list
Choose Desktop Mode or a headset configuration for viewing

Replay Controls

Key	Action
`SPACE`	Start / Stop playback
`R`	Reset playback to beginning
`C` / `V`	Scrub backward / forward (or use the slider)
`B` / `N`	Step frame-by-frame
`W` / `A` / `S` / `D`	Move free camera
`Z` / `X`	Move camera down / up
`Q` / `E`	Rotate camera
`.` or `F1`	Hide / show menu
`/`	Take screenshot
`I`	Show instructions
`ESC`	Exit

Replay Features

Trial Selection — choose any trial to replay
Client ID (multi-user) — view visualizations for a specific client
Avatar Visualization — toggle head and hand display
Gaze Visualizations — gaze ray, gaze point, dwell spheres (per eye or combined)
Fixation Spheres — view fixation points statically or sequentially numbered
Heat Map — dynamic (over time) or static (aggregated); supports occlusion and gradient modes
Scan Path — gaze path and dispersion path visualization
Walk Path — directional arrows showing movement with velocity indication
First/Third Person View — toggle camera perspective
Open Data Folder — quick access to session files

The replay uses a free camera mode — use WASD/ZX to move around, or walk freely if viewing in a headset.

Data Output

All session data is saved to a timestamped folder under data/, e.g.:

data/02-09-2026-15-14-18__experiment_data/

Inspection Checklist CSV

The working checklist (pretrip_inspection_checklist.csv) tracks all 66 inspection items with columns:

Column	Description
`category`	Inspection category (e.g., "Engine Compartment")
`item_id`	Unique identifier (e.g., `DRV001`, `CAB001`)
`item_name`	Display name
`description`	Detailed description
`inspection_type`	gaze / proximity / visual / interaction
`checked`	`0` or `1`
`timestamp`	ISO timestamp when checked
`location`	Optional teleport location (e.g., `location1`) — see Adding Teleport Locations

A final snapshot is also saved with the session timestamp prefix (e.g., 02-09-2026-15-14-18__pretrip_inspection_checklist.csv).

Inspection Report (Text)

A human-readable report saved as <timestamp>__inspection_report_trial_N.txt containing:
- Overall progress percentage
- Category-by-category breakdown
- Timestamp for each checked item

Eye Tracking & Movement Data (SightLab)

SightLab automatically generates several data files per session in the trial_data/ subfolder. These capture eye tracking, head movement, and gaze analytics.

Trial Data

*__trial_data_N_client_N.csv — Per-frame tracking data recorded at the headset update rate (e.g., 90 Hz for a 90 Hz headset). Includes:
- Timestamps (session-relative and Unix)
- Trial label and average frame rate
- Gaze intersect coordinates (combined and per-eye)
- Eye Euler angles (combined and per-eye)
- Head position and orientation (6DOF)
- Fixation/saccade status, saccade amplitude, velocity, average amplitude, peak velocity
- Pupil diameter and eye openness (if supported by hardware)
- Grab/release events and custom flags

Experiment Summary

*__experiment_summary_client_N.csv — Per-trial summary statistics including:
- Dwell view count, fixation count, and dwell time per object
- Average view time and time to first fixation
- Per-trial saccade calculations
- Trial length and any additional custom measurements

Trial Timeline Dwell

*__trial_timeline_dwell_N_client_N.csv — Timeline of gaze dwell events showing:
- When each object was viewed, for how long, and how many fixations occurred per object
- Custom flags added during the session

Trial Timeline Fixation & Saccade

*__trial_timeline_fixation_saccade_N_client_N.csv — Timeline of individual fixations and saccades including:
- Fixation and saccade duration
- Average fixation dispersion angle and average saccade velocity
- Delta angles and velocity between events

Customization

Adding Teleport Locations

Teleport locations are stored in locations/locations.txt (or locations2/locations.txt for Client 2). Each location consists of a position and orientation pair:

location1=1.333,0.0,-0.523
orientation1=0.0,0.0,0.0
location2=0.715,0.903,2.819
orientation2=-166.93,0.0,0.0

To add a new location at runtime:

Start the application and begin a trial
Navigate to the desired position in the scene (walk there in VR or use the keyboard)
Press / — this saves your current position and orientation as a new numbered location, appended to locations/locations.txt
The new location is immediately available via its number key (e.g., press 3 to teleport to location3)
You can also assign it to checklist items in the CSV (see below)

To edit locations manually, open locations/locations.txt in a text editor. Each location needs two lines:
- locationN=x,y,z — the 3D position
- orientationN=yaw,pitch,roll — the facing direction

Where N is a sequential integer starting from 1.

Adding New Inspection Items

Inspection items are defined in the template CSV file: data/pretrip_inspection_checklist.csv. Edit this file before starting an experiment session (a working copy is created per session at trial start).

To add a new item, append a row to the CSV with these columns:

Column	Required	Example	Notes
`category`	Yes	`Engine Compartment`	Must match one of the predefined categories (see Inspection Categories)
`item_id`	Yes	`ENG007`	Unique ID — use the category prefix + sequential number
`item_name`	Yes	`Turbo Charger`	Short name shown on the 3D panel
`description`	Yes	`Inspect turbo for oil leaks or damage`	Detailed description shown below the name
`inspection_type`	Yes	`visual`	One of: `visual`, `functional`, `gauge`, `auditory`
`checked`	Yes	`0`	Always `0` in the template
`timestamp`	Yes	(empty)	Leave empty in the template
`location`	No	`location2`	Optional — if set, the user auto-teleports to this location when navigating to the item

Example — adding a new item with a teleport location:

Engine Compartment,ENG007,Turbo Charger,Inspect turbo for oil leaks or damage,visual,0,,location2

When a user navigates to this item (via arrow keys, touch navigation, or "next unchecked"), they will automatically teleport to location2 as defined in locations/locations.txt.

Tips:
- Items appear in the inspection panel in the same order as the CSV rows
- The location column is optional — items without a location value work as before (no teleport)
- Location values must match entries in locations/locations.txt (e.g., location1, location2, location3)
- To reorder items, rearrange the rows in the CSV
- Do not edit the working copy inside a session's experiment_data folder — always edit the template in data/

Requirements

WorldViz Vizard 8
SightLab VR (sightlab_utils)
Truck_Showroom.osgb environment model