Documentation:26-1001 Vestibulearn: An Interactive XR Guide to Vestibular Anatomy

Emerging Media Lab
About EML
A collaborative space for UBC faculty, students and staff for exploration of emerging technologies and development of innovative tools and solutions. This wiki is for public-facing documentation for our projects and procedures.
Subpages
	Main EML wiki page Public EML website EML Projects

Introduction

VestibuLearn is a virtual-reality educational prototype built to teach the anatomy and physiology behind Benign Paroxysmal Positional Vertigo (BPPV), one of the most common causes of vertigo. BPPV is caused by displaced calcium-carbonate crystals (otoconia / "canaliths") migrating into the semicircular canals of the inner ear. Clinicians treat it with canalith-repositioning maneuvers such as the Epley Maneuver, a precise sequence of head and body rotations that guides the crystals back out of the affected canal.

Understanding why these maneuvers work requires visualizing the 3D anatomy of the vestibular apparatus and the fluid (endolymph) / cupula mechanics the maneuvers exploit, something that is difficult to teach with 2D diagrams alone. VestibuLearn solves this by letting a learner wear a VR headset while their real head rotation drives a virtual inner-ear model in real time. A procedural fluid simulation shows endolymph flow and cupula deflection responding to head motion, so the learner can directly see how each semicircular canal responds to head rotation.

The current focus of the prototype is the fluid-simulation explorer. In the build's current state, the primary experience (the Play button) is a free-form, head-driven vestibular fluid-simulation sandbox. Pressing Play hides the menu and reveals both inner-ear models (left and right), each driven by its own system that captures the user's head movement and visualizes endolymph flow and cupula deflection per canal in real time, with tunable simulation parameters (flow speed, display speed, short/long time constants). The story VestibuLearn tells is one of turning an invisible internal process, fluid sloshing in microscopic canals, into something a learner can watch happen in real time, in response to their own movement.

Primary Features

• Head-driven vestibular fluid simulation (Play): Pressing Play (`MainMenuController.OnPlayPressed()`) hides the menu, enables input, and scale-in-reveals both inner-ear models, each running a real-time simulation of endolymph flow and cupula deflection driven by the user's own head rotation.
• Correct-canal isolation: Fixed anatomical sensitivity axes and dominance suppression ensure only the anatomically correct canal responds to a given head movement, keeping the visual feedback readable.
• In-world simulation parameter controls: Adjustable flow speed, maximum display speed, and short/long time constants, with live m/s and s readouts inside the VR environment.
• Interactive ear manipulation: Mutually exclusive Move, Rotate, and Scale gizmos let the user manipulate the ear models via pinch or ray interactions.
• Interactive anatomy labels: Billboarded leader-line labels identify the semicircular canals, ampullae, utricle, saccule, and cochlea, always facing the user and avoiding overlap.
• User Interface: A uGUI (Canvas) based menu system with Play, Interact, Questionnaire, Options, and About panels, plus a wrist-mounted options canvas.
• Quiz / questionnaire: A multiple-choice module (`QuizManager` / `QuizCanvas`) covering BPPV and vestibular anatomy, with scoring and audio feedback.
• Accessibility / comfort options: Dark mode, comfort/smooth turning, volume adjustment, and left/right controller selection, synced across menus.
• Guided maneuver sequencer (legacy): A dormant system that walks a user through the Epley maneuver step by step (head-angle targets, hold timers, audio cues). Present in the code and assets but not currently wired into the Play flow.

Methods

VestibuLearn is a single self-contained Unity VR application; there is no separate web or server component. All content (anatomy models, fluid simulation, UI, and quiz) lives in the Unity project and runs on-device on a standalone VR headset.

The core simulation models the cupula-endolymph system as a simplified first-order (leaky-integrator) approximation of the true damped second-order pendulum system. The true system is a damped second-order pendulum, but because its fast time constant (T2, milliseconds) is negligible next to its slow one (T1, seconds), the model collapses to a cheap first-order approximation: each frame, cupula deflection is nudged toward the current sensed angular velocity by an amount scaled by dt/T1, and "leaks" back toward zero once the head stops rotating, mimicking how inner-ear fluid keeps sloshing briefly after motion ends. This is computed per canal on a scene-root master simulator object (`VestibularFluidSimulator`) and pushed to a custom flow-overlay shader (`VestibularFluidOverlay.shader`) for visualization. Fixed anatomical sensitivity axes (calibrated once from mesh geometry via an editor-only tool) and dominance suppression logic ensure only the correct canal reacts to a given rotation.

UI, quiz, accessibility settings, and anatomy labels are built as parallel systems layered on top of the core simulation, coordinated through a main menu controller (`MainMenuController`) that manages panel switching and enables/disables input and visuals.

Discussion

The project's central design tension was balancing physical plausibility against real-time performance and interpretability in VR. A full second-order pendulum model of the cupula-endolymph system was judged unnecessary given the negligible fast time constant, so the team adopted a first-order approximation that is both computationally cheap and visually convincing for teaching purposes.

A recurring technical risk was that anatomical sensitivity axes were originally derived directly from mesh vertices, which broke silently whenever the model was moved or re-imported. This was resolved by calibrating and fixing the axes once via an editor-only tool (`CanalSensitivityAxisSolver`), decoupling simulation correctness from live mesh geometry, with `CanalAxisDiagnostic` flagging suspiciously non-orthogonal axis pairs.

The guided-maneuver system (angles, hold times, audio cues, step types) was deliberately built as data-driven ScriptableObject assets rather than hardcoded per-maneuver logic, so that future maneuvers (for example, Semont or the BBQ roll) can be authored without new code. This decision trades a small amount of upfront complexity for long-term extensibility.

Findings

• Coupling a user's real head rotation to a physically plausible, real-time fluid simulation was achievable with a first-order leaky-integrator approximation rather than a full second-order physical model, keeping the simulation performant on standalone VR hardware.
• Canal cross-talk (multiple canals reacting to the same head movement) was resolved through fixed anatomical axes plus dominance suppression logic.
• Mesh-derived anatomical axes were fragile against model re-imports; calibrating and freezing them via a dedicated editor tool fixed this permanently.
• Authoring maneuvers as ScriptableObject data (rather than hardcoded sequences) made the maneuver system reusable, though this system is currently dormant and not part of the active Play flow.
• Billboarded, overlap-avoiding leader-line labels were necessary to keep anatomy labels legible in 3D space as the user moved around the models.

Challenges

New users getting started with the project should be aware of the following:

• The current build's primary experience is the free-form fluid-simulation sandbox (Play button). The guided Epley maneuver walkthrough exists in the codebase but is not active by default; the calls that launch it in `OnPlayPressed()` are commented out, and it should be wired into its own trigger rather than the existing Play button.
• Anatomical sensitivity axes are fixed/calibrated values, not derived live from mesh geometry. If ear models are replaced or re-imported, axes must be recalibrated using the included editor diagnostic tools before the simulation will behave correctly.
• The project targets standalone Android VR headsets (for example, Meta Quest); testing should be done on-device or via XR Simulation in-editor, not assumed correct from Play Mode alone.

Code

• Unity version required: Unity 6 (6000.4.6f1), using the Universal Render Pipeline (URP). The active render pipeline asset is `PC_RPAsset` (with `PC_Renderer`); a mobile config (`Mobile_RPAsset` / `Mobile_Renderer`) is also present for the Android/standalone-headset target.
• Target platform: Android (standalone VR headset, e.g. Meta Quest).
• Repository: Source is maintained on the lab's Perforce server.

Unity packages (via Package Manager):

• XR Interaction Toolkit (3.4.1): Provides interactors (poke, near-far, teleport), locomotion (snap/continuous turn, teleport, grab-move, climb), and UI interaction for XR. Needed for all VR input and movement.
• XR Hands (1.7.3): Provides hand-tracking skeleton/mesh visualization and pinch/poke gesture detection. Needed for hand-tracked interaction as an alternative to controllers.
• OpenXR Plugin (1.15.1) and Meta OpenXR (2.5.0): Cross-vendor XR runtime and Meta-specific extensions. Needed as the primary runtime loader for headset tracking and rendering.
• Input System (1.17.0): Handles all input, with custom action assets `RightControllerInput` and `RightHandInput`.
• Universal Render Pipeline (17.3.0): The project's rendering pipeline.
• uGUI (2.0.0): Canvas UI system. TextMeshPro is bundled inside this package (it is not a separate Package Manager dependency in Unity 6) and provides all in-scene text, including anatomy labels and UI.

Art Assets

• Inner-ear anatomy models: Primary vestibule model (`ear_just_canals.fbx`) with all semicircular canals shown transparently; used in the active EarsScene. A secondary model (`ear.fbx`) with the posterior canal transparent and otoconia visible in the canal is retained but dormant.
• Epley maneuver character: A rigged humanoid character (`epley_RIGHT (NOT LEFT).fbx`) used to demonstrate body-repositioning steps of the Epley maneuver; part of the currently dormant guided-maneuver system.
• Scenes: `EarsScene` is the primary, shipping scene (in build settings). `Questionnaire` is a standalone quiz/interaction test scene at the Assets/ root. `SampleScene`, `HandsDemoScene`, `PlayScene`, and `AlexsScene` are template or sandbox scenes disabled in the build.
• Shaders/materials: The custom `VestibularFluidOverlay.shader` (with `M_FlowOverlay.mat`) drives the visible endolymph flow effect on the ear meshes. `AnatomySurfaceHighlight.shader` handles anatomy selection highlight, and supporting shaders (`LineOnTop`, `UIOnTop`, `UIOverlayDefault`, `AnchorGlow`) keep UI and label lines correctly layered over 3D geometry in VR.
• Audio: Pre-recorded maneuver voiceovers (`lay_down.mp3`, `rotate_body`, `sit_upright`, `next_step`), countdown clips (`one` through `five`, `ten_seconds`, `twenty_seconds`, `thirty_seconds`, `sixty_seconds`), and UI SFX (`ui-click-soft`, `ui-click-deep`, `pop_sound`, `pop_sound_2`).
• UI reference images: Figma-exported reference images in `Assets/UI/` guide in-editor UI layout; these are visual references only and are not required at runtime.

Dependencies

The project runs entirely on first-party Unity packages; there are no third-party runtime libraries. Core packages:

• Unity XR Interaction Toolkit 3.4.1
• Unity XR Hands 1.7.3
• Unity OpenXR Plugin 1.15.1
• Meta OpenXR 2.5.0
• Unity Input System 1.17.0
• Universal Render Pipeline 17.3.0
• Unity uGUI 2.0.0 (includes TextMeshPro)

(The only non-Unity entry in the manifest is `UniGitHistoryViewer`, an editor-only Git history viewer used during development; it is not a runtime dependency.)

Prefab / GameObject component notes:

• Ear model GameObjects require a mesh renderer, the canal sensitivity solver component, and the fluid simulator component parented correctly under the camera rig to receive live head-rotation data; without the fixed sensitivity axis calibration, the simulation will not isolate canals correctly.
• XR Origin Hands (XR Rig) must include the Main Camera as the head tracker, with poke/near-far/teleport interactors and skinned hand visualizers attached for both controller and hand-tracked interaction to function.
• UI Poke Components prefab is required on any canvas that needs to support VR hand-poke interaction (used in EarsScene and the Questionnaire scene).
• No special tags or layers are required beyond Unity/XRI defaults; standard XR Interactable layers should be preserved for interactors to detect the ear models and UI correctly.

First Time Setup Guide

• Install Unity 6 (6000.4.6f1) and open the project with the Android build target selected.
• Confirm the XR Plug-in Management settings have OpenXR (with the Meta OpenXR feature group) enabled as the active loader.
• Load `EarsScene` (the primary scene) and press Play to enter the head-driven fluid-simulation sandbox.
• For headset testing, deploy to a standalone Android VR headset (for example, Meta Quest); in-editor testing can use XR Simulation.
• If ear models are replaced, re-run the canal-axis calibration tool (`CanalSensitivityAxisSolver`) before relying on the fluid simulation, otherwise canal isolation will be incorrect.

Development Team

• Principal Investigator: Dr. George Medvedev
• Project Lead: Nishant Molleti
• Design: Doruk On
• Development: Nishant Molleti
• Staff: Dante Cerron, Alex Day, Maryann Kempthorne, Phoebe Titus, Avni Kant, Saeed Dyanatkar
• Project duration: May 2026 to August 2026

FAQ

Is the guided Epley maneuver walkthrough active in the current build? No. The code and ScriptableObject-based maneuver data (`EpleyLeft.asset`, `EpleyRight.asset`) still exist, but the calls that launch it are commented out of the current Play flow. `ManeuverSequencer.RestartSequence()` only runs when returning to the menu. To restore guided maneuvers, re-enable those calls, but they should be wired into their own trigger rather than the existing Play button.

What headset does this run on? The project targets standalone Android VR headsets, such as the Meta Quest line, and supports both controller and hand-tracked interaction. Hand-tracked interaction requires the headset's hand-tracking (and, where applicable, passthrough) to be enabled.

Why is the fluid simulation simplified instead of fully physically accurate? The true cupula-endolymph system behaves like a damped second-order pendulum, but its fast time constant is negligible compared to its slow one, so a first-order approximation gives visually accurate behavior at a fraction of the computational cost.

Bibliography

• X Bot 3D Character Model, Mixamo
• Sleeping Idle (Description: Restless Sleeping) by Mixamo
• Lying Down Animation by Mixamo
• Anatomy of the Inner Ear 3D Model, University of Dundee School of Medicine
• Bed, Sample 3D Model, Mifu Saja

Reference links

• Anatomy | Physiology of the Utricle & Saccule [Otolithic Organs] by Catalyst University [1]
• Anatomy | Physiology of the Semicircular Canals by Catalyst University [2]
• The Vestibular System Endolymph Motion Demonstration by sixesfullofnines [3]
• How the Inner Ear Balance System Works, Labyrinth Semicircular Canals by Fauquier ENT [4]
• The Vestibular System, Animation by Alila Medical Media [5]
• The vestibular system, balance, and dizziness | MCAT by khanacademymedicine [6]

License

MIT License

Copyright (c) 2026 University of British Columbia

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Last edit: August 14, 2026 by Doruk On