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. You can also measure and annotate the outcrop in the headset — place scale bars, take distance measurements, record dip/azimuth readings and digitise polylines, all saved straight into the project.

Preview feature

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

1. Make sure VRGS is running with the Vulkan renderer (the default — see above).
2. Open a project and a 3D model view, then load a model.
3. 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.

tip

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 · place points with an edit tool
Left menu button	Open / close the radial menu

In an edit tool

While an edit tool is armed the right trigger places points and the left grip finishes a polyline (teleport is paused so the grip is free). Re-open the menu to switch tools or stop.

Controller differences

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.

Comfort

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.

Reset

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 thin, translucent 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. Each option shows an icon and a text label. 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.

Spin the ring with the left thumbstick (push left/right) to bring any option round toward your pointer — handy if an item sits at an awkward angle.

The menu is organised into pages so the ring never gets crowded. The first ring (Root) holds the two most-used actions plus two category buttons that open sub-pages. Every sub-page has a Back ◂ item that returns you to Root.

Root ring

Item	What it does
Display ▸	Open the display & comfort page.
Edit ▸	Open the edit-tools page.
Recenter	Reset position, heading and world scale — back to the starting view at 1:1.
Exit VR	End the VR session and return to the desktop view.

Display page

Item	What it does
Level	Keep your position but straighten your heading.
Speed	Step the free-fly speed through 1× → 2× → 4× → 1×. The icon shows a slow or fast glyph for the current setting.
Vignette ☑	Turn the peripheral comfort vignette on or off.
Mirror ☑	Mirror the headset view to the desktop window so others can watch (on by default).
Back ◂	Return to the Root ring.

Edit page

The edit tools place measurements and annotations directly on the outcrop — see Edit tools for how each one works.

Item	What it does
Scale Bar	Place a scale bar on the surface.
Measure	Measure a distance with a live readout.
Orientation	Record a dip/azimuth from three points.
Polyline	Digitise a multi-point line.
Back ◂	Return to the Root ring.

note

While the menu is open, the thumbsticks and grips drive the menu (the left thumbstick spins the ring) instead of moving you, so you won't fly off while choosing an option. Toggle items (Vignette, Mirror) carry a small checkbox badge — green when on, grey when off.

Edit tools

Open Edit ▸ in the radial menu and pick a tool. The menu closes and the tool arms: the right-controller laser becomes a placement cursor with a coloured preview marker on the surface where you're aiming. Aim the same way you point at the menu, and pull the right trigger to place a point.

Everything you create is saved into the project — it appears in the desktop view and the project tree, and stays visible in the headset. Objects made on the desktop show up in VR too, so you can review existing measurements and interpretation in the headset.

Switching or stopping

Re-open the menu at any time to switch tools or stop — opening the menu cancels whatever you're part-way through placing.

Scale Bar

Aim at the surface and pull the trigger to drop a scale bar at that point. The tool stays armed so you can place several in a row.

Measure

Hold the right trigger: the first point anchors where you pulled, and the second follows your aim as you move it — a stretchy "tape measure". A line and end markers show the span on the outcrop, and a readout floats by your right hand showing the distance, azimuth and inclination, updating live. Release the trigger to finish. Distances are real-world regardless of how far you've scaled the model with grab-the-world.

Orientation

Pull the trigger on three points across a bedding plane (or any planar feature). On the third point VRGS fits a best-fit plane and drops a dip/azimuth disc lying in that plane. The tool re-arms for the next reading, so you can record many in a row.

Polyline

Pull the trigger to drop each node along a feature; a line follows your aim from the last node. Squeeze the left grip to finish the line (you need at least two nodes). The tool re-arms for the next polyline.

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 with Vignette on the radial menu's Display page.
• Teleport instead of free-fly to avoid sliding motion entirely.
• Lower the speed with the Speed item on the Display page.

First-timers

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

"Could not start VR"

Work through these in order:

1. Renderer — VRGS must be using the Vulkan renderer. If you're in OpenGL mode, restart with -vulkan (see Choosing the renderer).
2. OpenXR runtime — make sure SteamVR or the Oculus app is running and the headset is connected and awake.
3. 3D view — open a 3D model view and load a model before connecting the HMD.
4. Logs — check logs/vrgs-debug.log for 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 Speed on the radial menu's Display page, 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).
• The edit tools cover scale bars, measurements, orientations and polylines. Other interpretation types (waypoints, faults, full editing of existing objects) are still desktop-only for now.
• Lineation/plunge orientations from the desktop aren't drawn in the headset yet (planar dip/azimuth discs are).

Feedback

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.