VR / Headset User Guide
VRGS can display 3D outcrop models, point clouds and tiled scenes in virtual reality through any OpenXR-compatible headset. In VR you can walk around an outcrop at life-size, fly through it, teleport across it, or shrink the whole model to a tabletop you can lean over and inspect.
VR runs on the Vulkan 3D view and is currently a preview. It is enabled opt-in (see Requirements) so standard desktop sessions never start a VR runtime or pay any cost.
Requirements
| Requirement | Notes |
|---|---|
| A VR headset | Meta Quest (Link/Air Link), Valve Index, HTC Vive, Windows Mixed Reality, or any OpenXR device. |
| An OpenXR runtime | e.g. SteamVR or the Oculus app, installed and running, with the headset connected and awake. |
| The Vulkan renderer | VR runs in the Vulkan 3D view. VRGS uses the Vulkan renderer by default; see Choosing the renderer. |
| Two tracked controllers | Required for navigation, the laser pointer and the menu. |
Choosing the renderer
VRGS can render the 3D view with either the Vulkan backend (required for VR) or the legacy OpenGL backend. Vulkan is the default. The choice is saved between sessions, and you can override it from the command line:
| Command-line argument | Effect |
|---|---|
-vulkan | Use the Vulkan renderer (enables VR). Saved as the new default. |
-opengl (or -gl) | Use the OpenGL renderer. Saved as the new default. |
start VRGS.exe -vulkan
If you pass nothing, VRGS uses whichever renderer you last selected (Vulkan on a fresh install).
Starting VR
- Make sure VRGS is running with the Vulkan renderer (the default — see above).
- Open a project and a 3D model view, then load a model.
- Put on the headset, then run the Connect HMD command to start the session. Run it again at any time to stop VR and return to the desktop view.
If Connect HMD reports that it can't start, it's almost always one of: VRGS is running in OpenGL mode, the OpenXR runtime isn't running, or the headset isn't connected/awake. See Troubleshooting.
Controls at a glance
The layout follows a Mode-2 drone convention (the most common RC/drone stick layout).
| Input | Action |
|---|---|
| Left thumbstick | X = turn (yaw) · Y = move up / down |
| Right thumbstick | X = strafe left / right · Y = move forward / back |
| Right grip (hold) | Speed boost while moving |
| Left grip (hold → release) | Teleport: aim, then release to jump |
| Both grips (hold) | Grab the world — scale & reposition the model |
| Right trigger | Laser pointer / select a menu item |
| Left menu button | Open / close the radial menu |
Meta Touch and Valve Index controllers use the layout above directly. On HTC Vive the trackpad stands in for the thumbstick, and the menu button opens the radial menu. Any OpenXR controller will at least show the hand models and track pose.
Moving around
There are three complementary ways to move. They work together — pick whichever suits the moment.
Free-fly (thumbsticks)
Push the sticks to fly. With the Mode-2 layout, the right stick drives forward/back and strafe (where you're going), and the left stick turns you and moves you up/down.
- Hold the right grip for a speed boost — useful for crossing large scenes quickly.
- Flying speed scales with the size of the scene, so it stays usable whether you're inspecting a hand sample or a kilometre-wide cliff.
Continuous stick movement is the most likely thing to cause motion discomfort. A comfort vignette is on by default to help, and you can cycle the speed down or switch to teleport.
Teleport
Hold the left grip to aim a ray from your left controller; a green marker shows where you'll land and a beam shows the aim. Release the grip to jump there instantly. A short haptic pulse confirms the jump.
- The ray lands on the model surface where you point; if you aim past everything it falls back to ground level.
- Teleport is a low-discomfort way to cover distance — your view doesn't slide, it cuts.
Grab the world (scale & reposition)
Hold both grips at once to grab the whole model with your hands:
- Spread your hands apart to enlarge the model (zoom in); bring them together to shrink it — for example, collapse a whole cliff face down to a tabletop you can walk around and look over.
- Move both hands together to slide the model into a comfortable position.
- The scaling happens around the point between your hands, so the feature you're holding stays put while everything scales around it.
Your scale and position persist after you let go, so you can grab, adjust, release, and keep working. Teleport and free-fly continue to work correctly at any scale.
Use Recenter in the radial menu to snap straight back to the original view at 1:1.
The laser pointer
Pull the right trigger to project a laser beam from your right controller. It doubles as the cursor for the radial menu — point at an item and the trigger selects it.
The radial menu
Press the left menu button to open a ring of options around your left controller. Point at an item with the right-controller laser (a soft haptic tick confirms the highlight) and pull the right trigger to select it. Press the menu button again to close.
| Item | What it does |
|---|---|
| Recenter | Reset position, heading and world scale — back to the starting view at 1:1. |
| Level heading | Keep your position but straighten your heading. |
| Cycle speed | Step the free-fly speed through 1× → 2× → 4× → 1×. |
| Comfort vignette | Turn the peripheral comfort vignette on or off. |
| Exit VR | End the VR session and return to the desktop view. |
While the menu is open, the thumbsticks and grips drive the menu instead of moving you, so you won't fly off while choosing an option.
Comfort and motion sickness
VR can cause discomfort for some users, especially during continuous movement. VRGS includes a few aids:
- Comfort vignette — the edges of your view gently darken while you move and clear again when you stop, which reduces the "moving scenery" effect that triggers nausea. It's on by default; toggle it from the radial menu.
- Teleport instead of free-fly to avoid sliding motion entirely.
- Lower the speed with the radial menu's Cycle speed option.
Start seated, keep sessions short, and use teleport until you're comfortable. Take the headset off as soon as you feel any discomfort.
Movement speed, turn speed and the boost multiplier are also available in the application's VR display settings if you want to tune the defaults.
Troubleshooting
Work through these in order:
- Renderer — VRGS must be using the Vulkan renderer. If you're in OpenGL mode, restart with
-vulkan(see Choosing the renderer). - OpenXR runtime — make sure SteamVR or the Oculus app is running and the headset is connected and awake.
- 3D view — open a 3D model view and load a model before connecting the HMD.
- Logs — check
logs/vrgs-debug.logfor an OpenXR error (it lists the exact failure, e.g. "no runtime" or "headset not connected").
| Symptom | Likely cause / fix |
|---|---|
| Hand controllers don't appear | Controllers off or not tracked; wake them and make sure the headset has focus (not the runtime's home/dashboard). |
| Nothing renders / black headset | The scene may be empty — load a model in the 3D view before connecting the HMD. |
| Movement feels too fast / too slow | Use the radial menu's Cycle speed, or adjust the VR movement-speed setting. |
| Motion discomfort | Keep the comfort vignette on, lower the speed, or use teleport instead of free-fly. |
Known limitations
This is an early VR preview. Notable current limits:
- World grab supports scale and reposition; rotating the world with your hands isn't available yet (use stick turn / Level heading).
- Menu items are shown as icons; text labels are planned.
- In-VR editing, measurement and interpretation tools are not yet available — VR is for viewing and navigating the scene.
Behaviour such as turn direction, speed and grab sensitivity is still being tuned. If something feels off in the headset, note what you were doing so it can be adjusted.