Skip to content

SETUP_GUIDE.md

Latest commit

 

History

History
498 lines (375 loc) · 13.9 KB

SETUP_GUIDE.md

File metadata and controls

498 lines (375 loc) · 13.9 KB
Raw

Unity Quest 3 Gaussian Splat Viewer - Setup Guide

Complete step-by-step guide for configuring the project in Unity Editor.

Phase 1: Open Project in Unity Hub

  1. Open Unity Hub
  2. Click Add → Add project from disk
  3. Navigate to /Users/zd/CascadeProjects/xr-vr/GaussianSplatViewer
  4. Select the folder and click Open
  5. If prompted about Unity version:
    • Select Unity 6 (6000.0.x LTS) - download if needed
    • Click Open with Unity 6
  6. Wait for initial import (packages will download automatically)

Phase 2: Fix Package Import Errors

After opening, you may see console errors. Fix them:

  1. Go to Window → Package Manager
  2. Wait for packages to load
  3. If any packages show errors, click on them and press Update or Repair
  4. Required packages should include:
    • Universal RP (17.0.3+)
    • XR Interaction Toolkit (3.0.7+)
    • OpenXR Plugin (1.14.0+)
    • Meta OpenXR (2.1.0+)
    • Burst (1.8.18+)
    • Input System (1.11.2+)

If Meta OpenXR is missing:

  1. In Package Manager, click + → Add package by name
  2. Enter: com.unity.xr.meta-openxr
  3. Click Add

Phase 3: Configure Build Settings

  1. Go to File → Build Settings
  2. Select Android in the platform list
  3. Click Switch Platform (wait for recompile)
  4. Configure settings:
    • Texture Compression: ASTC
    • ETC2 fallback: 32-bit
  5. Click Player Settings (bottom left)

Phase 4: Configure Player Settings

In Edit → Project Settings → Player:

Other Settings tab:

  1. Rendering:

    • Color Space: Linear
    • Auto Graphics API: Unchecked
    • Graphics APIs: Remove OpenGLES, keep only Vulkan

  2. Identification:

    • Package Name: com.gaussiansplatviewer.quest
    • Minimum API Level: Android 10.0 (API level 29)
    • Target API Level: Automatic (highest installed)

  3. Configuration:

    • Scripting Backend: IL2CPP
    • API Compatibility Level: .NET Standard 2.1
    • Target Architectures: ARM64 only (uncheck ARMv7)
    • Allow unsafe Code: Checked

  4. Optimization:

    • Managed Stripping Level: Low

Phase 5: Configure XR Settings

5.1 XR Plug-in Management

  1. Go to Edit → Project Settings → XR Plug-in Management
  2. Click Install XR Plug-in Management if not installed
  3. Select Android tab (robot icon)
  4. Check OpenXR
  5. A warning will appear - click Fix All if shown

5.2 OpenXR Settings

  1. Under XR Plug-in Management, click OpenXR
  2. Under Android tab:
    • Render Mode: Single Pass Instanced
    • Depth Submission Mode: Depth 16 Bit
  3. Under Interaction Profiles, click + and add:
    • Oculus Touch Controller Profile
    • Meta Quest Touch Pro Controller Profile
  4. Under OpenXR Feature Groups, enable:
    • Meta Quest Support
    • Click the gear icon next to it:
      • Target Devices: Quest 3, Quest 2, Quest Pro
      • Hand Tracking: Enabled
      • System Splash Screen: Enabled

5.3 Fix Any Validation Errors

  1. Still in OpenXR settings, look for red/yellow warnings
  2. Click Fix All to resolve common issues
  3. Common fixes:
    • "Interaction profile not configured" → Add profiles above
    • "Render mode not optimal" → Set to Single Pass Instanced

Phase 6: Configure URP (Universal Render Pipeline)

6.1 Create URP Assets (if not auto-created)

  1. Go to Assets → Settings folder
  2. Right-click → Create → Rendering → URP Asset (with Universal Renderer)
  3. Name it URPAsset
  4. A Renderer will be created alongside it

6.2 Configure URP Asset

  1. Select the URPAsset in Assets/Settings

  2. In Inspector, configure:

    Rendering:

    • Render Scale: 1.0
    • Upscaling Filter: Auto

    Quality:

    • HDR: Unchecked (saves performance on Quest)
    • Anti Aliasing (MSAA): 2x or 4x

    Lighting:

    • Main Light: Per Pixel
    • Additional Lights: Disabled (saves performance)
    • Cast Shadows: Unchecked

    Shadows:

    • Max Distance: 0 (disable shadows for performance)

6.3 Assign URP Asset

  1. Go to Edit → Project Settings → Graphics
  2. Under Scriptable Render Pipeline Settings:
    • Drag your URPAsset into the slot
  3. Go to Edit → Project Settings → Quality
  4. For each quality level, assign the same URPAsset

6.4 Add Gaussian Splat Renderer Feature

  1. Select the URPAsset_Renderer (the Renderer Data asset)
  2. In Inspector, scroll to Renderer Features
  3. Click Add Renderer Feature → Gaussian Splat Renderer Feature
  4. Configure the feature:
    • Render Pass Event: After Rendering Transparents
    • Preprocess Shader: Drag GaussianSplatCompute.compute
    • Sort Shader: Drag RadixSort.compute
    • Splat Material: (create in next step)

6.5 Create Splat Material

  1. Right-click in Assets → Create → Material
  2. Name it GaussianSplatMaterial
  3. In Inspector:
    • Change shader to GaussianSplatViewer/GaussianSplat
    • Alpha Cutoff: 0.004
  4. Drag this material into the Renderer Feature's Splat Material slot

Phase 7: Set Up Input Actions

7.1 Create Input Action Asset

  1. Right-click in Assets → Create → Input Actions
  2. Name it VRInputActions
  3. Double-click to open Input Actions editor

7.2 Configure Actions

Click + next to Action Maps, create XR:

Movement Actions:

Action Name Action Type Control Type Binding
Move Value Vector2 <XRController>{LeftHand}/thumbstick
Turn Value Vector2 <XRController>{RightHand}/thumbstick

UI Actions:

Action Name Action Type Control Type Binding
Menu Button Button <XRController>{LeftHand}/menuButton
Reset Button Button <XRController>{RightHand}/primaryButton (A button)
Select Button Button <XRController>/triggerPressed
  1. Click Save Asset
  2. In the Inspector for VRInputActions, check Generate C# Class
  3. Click Apply

Phase 8: Create Main Scene

8.1 Create New Scene

  1. File → New Scene → Basic (Built-in)
  2. File → Save As → Save to Assets/GaussianSplatViewer/Scenes/MainScene.unity
  3. Delete the default Main Camera and Directional Light

8.2 Run Scene Setup Script

  1. Go to Tools → Gaussian Splat Viewer → Setup Main Scene
  2. This creates the basic hierarchy

8.3 Configure XR Origin (Manual Fixes)

  1. Select XR Origin in Hierarchy
  2. Add Component: XR Origin (XR Rig)
    • Camera Floor Offset Object: Drag Camera Offset here
    • Camera: Drag Main Camera here
    • Origin Base GameObject: Leave as XR Origin itself
    • Tracking Origin Mode: Floor

8.4 Configure Main Camera

  1. Select Main Camera under Camera Offset
  2. Add Component: Tracked Pose Driver
    • Tracking Type: Rotation And Position
    • Position Input: Center Eye Position
    • Rotation Input: Center Eye Rotation
  3. Ensure Camera has:
    • Clear Flags: Solid Color
    • Background: Dark gray (0.1, 0.1, 0.15)
    • Near Clip: 0.01
    • Far Clip: 1000

8.5 Configure Hand Controllers

Left Hand Controller:

  1. Select Left Hand Controller
  2. Add Component: XR Controller (Action-based)
  3. Configure tracking:
    • Position Action: Use Reference → Add binding → <XRController>{LeftHand}/devicePosition
    • Rotation Action: Use Reference → Add binding → <XRController>{LeftHand}/deviceRotation
  4. Add Component: XR Ray Interactor
  5. Add Component: XR Interactor Line Visual
  6. Add Component: Line Renderer (for ray visualization)

Right Hand Controller:

  • Repeat the same steps with {RightHand} bindings

8.6 Add Teleportation Provider

  1. Select XR Origin
  2. Add Component: Teleportation Provider
  3. Add Component: XR Interaction Manager (if not present)

Phase 9: Create File Browser UI

9.1 Create Canvas

  1. Right-click in Hierarchy → UI → Canvas
  2. Rename to File Browser Canvas
  3. Configure Canvas:
    • Render Mode: World Space
    • Event Camera: Drag Main Camera
    • Width: 800, Height: 600
  4. Set Transform:
    • Position: (0, 1.5, 2)
    • Scale: (0.002, 0.002, 0.002)

9.2 Add XR UI Input

  1. Select File Browser Canvas
  2. Add Component: Tracked Device Graphic Raycaster
  3. Remove the default Graphic Raycaster if present

9.3 Create UI Elements

Background Panel:

  1. Right-click Canvas → UI → Panel
  2. Rename to Background
  3. Set color to dark (0.15, 0.15, 0.2, 0.95)

Header:

  1. Right-click Background → UI → Text - TextMeshPro
    • If prompted, click Import TMP Essentials
  2. Rename to PathText
  3. Anchor: Top, Stretch horizontal
  4. Text: "/sdcard/Download"
  5. Font Size: 24
  6. Position: Top of panel

File List (ScrollView):

  1. Right-click Background → UI → Scroll View
  2. Rename to FileScrollView
  3. Anchor: Stretch all
  4. Set padding from edges (20px top for header)
  5. Under Scroll View → Viewport → Content:
    • Add Component: Vertical Layout Group
    • Child Force Expand: Width checked, Height unchecked
    • Spacing: 5

File Entry Prefab:

  1. Right-click Content → UI → Button - TextMeshPro
  2. Rename to FileEntryPrefab
  3. Configure:
    • Height: 50
    • Text: "📁 FolderName"
    • Font Size: 20
    • Alignment: Left
  4. Drag to Assets to create prefab
  5. Delete from scene (it's now a prefab)

Back Button:

  1. Right-click Background → UI → Button - TextMeshPro
  2. Rename to BackButton
  3. Position: Top-left corner
  4. Text: "← Back"

Close Button:

  1. Right-click Background → UI → Button - TextMeshPro
  2. Rename to CloseButton
  3. Position: Top-right corner
  4. Text: "✕"

Loading Panel:

  1. Right-click Background → UI → Panel
  2. Rename to LoadingPanel
  3. Add Slider child for progress
  4. Add Text child for status
  5. Set panel inactive by default

Status Text:

  1. Right-click Background → UI → Text - TextMeshPro
  2. Rename to StatusText
  3. Position: Bottom of panel
  4. Text: "Ready"

9.4 Wire Up VRFileBrowser Component

  1. Select the File Browser Canvas (or a child object)
  2. Add Component: VR File Browser
  3. Assign references:
    • Canvas: File Browser Canvas
    • Splat Renderer: Gaussian Splat Renderer
    • File List Container: Content (under ScrollView)
    • File Entry Prefab: Your FileEntryPrefab
    • Current Path Text: PathText
    • Status Text: StatusText
    • Back Button: BackButton
    • Close Button: CloseButton
    • Loading Slider: The Slider in LoadingPanel
    • Loading Panel: LoadingPanel

Phase 10: Configure Main App Controller

  1. Select GaussianSplatViewerApp in Hierarchy
  2. In Inspector, assign:
    • Splat Renderer: Gaussian Splat Renderer object
    • VR Rig: XR Origin's VRRigController
    • Locomotion: XR Origin's VRLocomotion
    • File Browser: The VRFileBrowser component
    • Menu Action: Create reference to your Menu input action
    • Reset Action: Create reference to your Reset input action

Phase 11: Configure Gaussian Splat Renderer

  1. Select Gaussian Splat Renderer in Hierarchy
  2. Add Component: Gaussian Splat Renderer (if not present)
  3. Assign:
    • Preprocess Shader: GaussianSplatCompute.compute
    • Sort Shader: RadixSort.compute
    • Splat Material: GaussianSplatMaterial
  4. Configure settings:
    • Splat Scale: 1.0
    • Alpha Cutoff: 0.004
    • Max Visible Splats: 400000

Phase 12: Final Scene Setup

12.1 Add Lighting

  1. Right-click Hierarchy → Light → Directional Light
  2. Configure:
    • Rotation: (50, -30, 0)
    • Intensity: 1.0
    • Shadow Type: No Shadows (performance)

12.2 Add Event System

  1. Right-click Hierarchy → UI → Event System
  2. Remove Standalone Input Module if present
  3. Add Component: XR UI Input Module

12.3 Add Teleport Areas (Optional)

  1. Create 3D Object → Plane for floor
  2. Add Component: Teleportation Area
  3. Configure teleport settings

12.4 Save Scene

  1. Ctrl+S / Cmd+S to save
  2. Go to File → Build Settings
  3. Click Add Open Scenes
  4. Ensure MainScene is in the list with index 0

Phase 13: Build and Deploy

13.1 Connect Quest 3

  1. Connect Quest 3 via USB cable
  2. Put on headset and Allow USB debugging when prompted
  3. In Unity, go to File → Build Settings
  4. Under Run Device, select your Quest 3

13.2 Build APK

  1. Click Build (or Build and Run)
  2. Choose output location (e.g., Builds/GaussianSplatViewer.apk)
  3. Wait for build to complete

13.3 Install via ADB (Alternative)

adb install -r Builds/GaussianSplatViewer.apk

Phase 14: Testing

14.1 First Launch

  1. On Quest 3, go to App Library → Unknown Sources
  2. Find and launch Gaussian Splat Viewer
  3. Grant storage permissions when prompted

14.2 Load a PLY File

  1. Copy a PLY file to Quest: 
    adb push /path/to/your/file.ply /sdcard/Download/
  2. In app, navigate to Downloads folder
  3. Select the PLY file
  4. Wait for loading

14.3 Controls

  • Left Thumbstick: Move
  • Right Thumbstick: Turn (snap or smooth)
  • Left Menu Button: Toggle file browser
  • A Button: Reset view
  • Trigger: Select in UI

Troubleshooting

Black Screen on Quest

  • Check OpenXR is enabled for Android
  • Verify Meta Quest Support feature is enabled
  • Check Vulkan is the only Graphics API

Splats Not Rendering

  • Verify Renderer Feature is added to URP Renderer
  • Check compute shaders are assigned
  • Verify material uses correct shader

File Browser Not Working

  • Check Canvas is World Space
  • Verify Tracked Device Graphic Raycaster is added
  • Check XR UI Input Module exists

Poor Performance

  • Reduce Max Visible Splats to 200000
  • Disable MSAA
  • Lower render scale to 0.8

Storage Permission Denied

  • Manually grant in Quest Settings → Apps → Gaussian Splat Viewer → Permissions