# VR/AR Usage Guide

> Immersive astronomy experiences in virtual and augmented reality

Nyx provides cutting-edge VR and AR features that transform how you experience
the cosmos. This guide covers setup, usage, and best practices for immersive
astronomical exploration.

## Table of Contents

1. [Overview](#overview)
2. [Supported Devices](#supported-devices)
3. [VR Planetarium](#vr-planetarium)
4. [AR Star Finder](#ar-star-finder)
5. [Mixed Reality Features](#mixed-reality-features)
6. [Controls and Navigation](#controls-and-navigation)
7. [Best Practices](#best-practices)
8. [Troubleshooting](#troubleshooting)

---

## Overview

### VR Features

- **Immersive Planetarium**: Full 360° sky experience
- **Solar System Explorer**: Walk among the planets
- **Scale Demonstrations**: Feel the vastness of space
- **Guided VR Tours**: Narrated cosmic journeys
- **Multiplayer Viewing**: Share experiences with others

### AR Features

- **Live Sky Overlay**: See star names in your camera view
- **Object Identification**: Point and discover
- **Constellation Drawing**: AR constellation lines
- **Planet Finder**: Locate planets in daylight
- **Time Lapse**: See the sky change over time

---

## Supported Devices

### VR Headsets

| Device           | Support Level | Notes                     |
| ---------------- | ------------- | ------------------------- |
| Meta Quest 3     | Full          | Native app, hand tracking |
| Meta Quest 2     | Full          | Native app                |
| Meta Quest Pro   | Full          | Enhanced passthrough      |
| Apple Vision Pro | Full          | visionOS native           |
| Valve Index      | Full          | Via SteamVR               |
| HTC Vive Pro 2   | Full          | Via SteamVR               |
| PlayStation VR2  | Partial       | Limited features          |
| Pico 4           | Full          | Native app                |

### AR Devices

| Device           | Support Level | Notes                     |
| ---------------- | ------------- | ------------------------- |
| iPhone (12+)     | Full          | ARKit, LiDAR recommended  |
| iPhone (8-11)    | Good          | ARKit without LiDAR       |
| iPad Pro         | Full          | Best tablet AR experience |
| Android (ARCore) | Full          | Requires ARCore support   |
| Magic Leap 2     | Full          | Enterprise AR             |
| HoloLens 2       | Experimental  | Enterprise features       |

### WebXR Support

Any WebXR-compatible browser and device:

- Chrome 79+ with WebXR
- Edge 79+ with WebXR
- Firefox Reality
- Oculus Browser

---

## VR Planetarium

### Getting Started

**Quest/Pico (Standalone):**

1. Install Nyx from Meta Store / Pico Store
2. Launch the app
3. Allow required permissions
4. Select "VR Planetarium" from menu

**PC VR (SteamVR):**

1. Install Nyx Desktop with VR support
2. Launch SteamVR
3. Start Nyx and click "Enter VR"
4. Put on your headset

**WebXR:**

1. Visit nyx.oshun.io in a WebXR browser
2. Click the VR headset icon
3. Grant WebXR permissions
4. Enter immersive mode

### Planetarium Modes

#### Standard Planetarium

Stand under a realistic night sky:

```
┌─────────────────────────────────────────────────────────────┐
│                         ★    ★                               │
│            ★      ★                    ★                    │
│     ★               ★    ★        ★                        │
│          ★                     ★            ★               │
│   ★           ★       ★                                     │
│════════════════════════════════════════════════════════════│
│                     HORIZON                                  │
│         N           E           S           W               │
└─────────────────────────────────────────────────────────────┘

Features:
├── Realistic star rendering (millions of stars)
├── Constellation overlays
├── Horizon with compass directions
├── Ground/landscape options
└── Atmospheric effects (optional)
```

#### Dome Theater

Classic planetarium dome experience:

- Reclined viewing position
- Presenter pointer tools
- Show scheduling
- Multi-user sessions

#### Zero-G Observatory

Float in space without a horizon:

- 360° spherical view
- No up/down orientation
- Galactic plane visible
- Deep space zoom

### VR Solar System Explorer

Walk through a scale model of the solar system:

**Scale Options:**

| Scale       | Sun Size | Earth Size | Neptune Distance |
| ----------- | -------- | ---------- | ---------------- |
| Classroom   | 2m       | 1.8cm      | 90m              |
| Museum      | 10m      | 9cm        | 450m             |
| Realistic\* | 1.39Mm   | 12,742km   | 4.5B km          |

\*Realistic scale uses teleportation for navigation

**Interactions:**

- Walk around planets
- Resize planets with gestures
- View real-time positions
- Time-lapse orbital motion
- Land on planet surfaces

### VR Tours

Pre-built immersive experiences:

| Tour                 | Duration | Description                                       |
| -------------------- | -------- | ------------------------------------------------- |
| Cosmic Voyage        | 15 min   | Journey from Earth to edge of observable universe |
| Life of a Star       | 20 min   | Watch stellar evolution                           |
| Mars Landing         | 10 min   | Experience Perseverance landing                   |
| Black Hole Dive      | 12 min   | Approach event horizon                            |
| Apollo 11 Recreation | 25 min   | Relive the Moon landing                           |
| Exoplanet Discovery  | 18 min   | Visit confirmed exoplanets                        |

---

## AR Star Finder

### Setup

1. Open Nyx mobile app
2. Tap "AR Mode" button
3. Grant camera permissions
4. Point device at sky

### AR Interface

```
┌─────────────────────────────────────────────────────────────┐
│ ○ Camera View with AR Overlay                               │
│                                                              │
│         Polaris ★                                           │
│              ╲                                               │
│               ╲  Ursa Minor                                  │
│                ╲_____★                                       │
│                      ╲                                       │
│                       ★                                      │
│                                                              │
│    Vega ★                              ★ Deneb              │
│                                                              │
│               ★ Altair                                       │
│                                                              │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ Looking: NE ↗ | Alt: 45° | Accuracy: High                   │
│ [Constellations: ON] [Labels: ON] [Info: OFF]               │
└─────────────────────────────────────────────────────────────┘
```

### AR Features

#### Object Identification

1. Point at any bright star or planet
2. Tap the object or wait for auto-identify
3. View information overlay

```
┌─────────────────────────────┐
│ ★ Sirius (α Canis Majoris) │
│ Distance: 8.6 light years   │
│ Magnitude: -1.46            │
│ Type: A1V (white dwarf)     │
│ [More Info] [Track]         │
└─────────────────────────────┘
```

#### Constellation Drawing

Enable constellation lines overlaid on the real sky:

- Official IAU constellation lines
- Mythology-based artistic figures
- Cultural variants (Greek, Chinese, etc.)

#### Planet Finder

Find planets even during daytime:

1. Enable "Planet Finder" mode
2. Follow the on-screen arrow
3. Planet location shown through camera

#### Time Lapse AR

See the sky change over time:

- Speed: 1x to 1000x
- Show star trails
- Predict positions hours ahead
- Rewind to see past sky

### Compass Calibration

For accurate AR positioning:

1. Go to Settings > AR > Calibrate
2. Move device in figure-8 pattern
3. Point at known star to fine-tune
4. Verify accuracy with second star

---

## Mixed Reality Features

### Passthrough Planetarium

See the real world with virtual sky overlay:

**Available on:**

- Meta Quest 3 / Pro
- Apple Vision Pro
- Other passthrough-capable devices

**Features:**

- Real room visible beneath virtual sky
- Walk around your space
- Anchor virtual objects to real surfaces
- Day-to-night transition effects

### AR Telescope Preview

See what your telescope will show:

1. Connect Nyx to your telescope
2. Enable "Telescope FOV" in AR mode
3. Point phone where telescope points
4. See magnified view preview

### Shared AR Experience

Multiple users see the same AR content:

1. One user creates a session
2. Others join via QR code
3. Everyone sees synchronized overlays
4. Perfect for teaching groups

---

## Controls and Navigation

### VR Controllers

**Universal Controls (Quest, Index, Vive):**

| Action       | Control                            |
| ------------ | ---------------------------------- |
| Select/click | Trigger                            |
| Menu         | Menu button                        |
| Teleport     | Thumbstick forward + release       |
| Rotate view  | Thumbstick left/right              |
| Zoom         | Grip buttons (pinch gesture)       |
| Time control | Left controller thumbstick up/down |
| Info panel   | Point at object + trigger          |

### Hand Tracking

**Quest hand tracking gestures:**

| Gesture        | Action                  |
| -------------- | ----------------------- |
| Point          | Select/highlight object |
| Pinch          | Confirm selection       |
| Pinch + drag   | Move/rotate view        |
| Two-hand pinch | Zoom in/out             |
| Palm up        | Show menu               |
| Fist           | Dismiss                 |

### Eye Tracking

**Quest Pro / Vision Pro:**

| Feature       | Description                   |
| ------------- | ----------------------------- |
| Gaze select   | Look at object to highlight   |
| Foveated info | Details appear where you look |
| Natural zoom  | Look + pinch to zoom          |

### AR Touch Controls

| Gesture           | Action               |
| ----------------- | -------------------- |
| Tap object        | Select and show info |
| Double tap        | Center on object     |
| Two-finger rotate | Adjust time          |
| Pinch             | Zoom overlay scale   |
| Long press        | Options menu         |
| Swipe down        | Exit AR mode         |

---

## Best Practices

### VR Comfort

**Reducing motion sickness:**

1. **Use teleport locomotion** instead of smooth movement
2. **Enable vignette** during motion
3. **Take breaks** every 20-30 minutes
4. **Start with stationary** experiences
5. **Adjust IPD** for your eyes

**Room setup:**

- Clear 2m × 2m minimum play space
- Set guardian/boundary
- Sit for extended sessions
- Keep water nearby

### AR Best Practices

**For best tracking:**

1. **Dark location** - Less light pollution
2. **Steady hands** - Use tripod if needed
3. **Calibrate compass** - Critical for accuracy
4. **Allow GPS lock** - Wait for accuracy
5. **Update device** - Latest ARKit/ARCore

**Battery management:**

- AR mode uses significant battery
- Keep device cool (don't cover camera)
- Use external battery for long sessions
- Reduce screen brightness

### Educational VR Sessions

**For classroom use:**

1. Pre-plan the experience route
2. Test all content beforehand
3. Have hygiene wipes for shared headsets
4. Provide seated experiences for all
5. Have non-VR backup activities
6. Monitor students for discomfort

---

## Troubleshooting

### VR Issues

**Headset won't enter VR mode:**

- Ensure SteamVR/Oculus software is running
- Check that headset is detected
- Restart Nyx application
- Update graphics drivers

**Poor performance/low frame rate:**

- Lower star density setting
- Disable atmospheric effects
- Reduce render resolution
- Close background applications

**Tracking issues:**

- Clean tracking cameras
- Improve room lighting
- Redraw guardian boundary
- Reset headset orientation

**No sound:**

- Check VR audio routing
- Ensure headphones connected
- Check in-app volume
- Verify system audio settings

### AR Issues

**Objects in wrong positions:**

- Recalibrate compass
- Verify GPS accuracy
- Check date/time settings
- Perform manual star alignment

**Camera not working:**

- Grant camera permissions
- Restart the app
- Check for other apps using camera
- Clear app cache

**AR drifts over time:**

- Recalibrate periodically
- Keep device steady
- Ensure good GPS signal
- Use reference point correction

**Labels not appearing:**

- Check label settings enabled
- Increase magnitude limit
- Point more directly at sky
- Wait for scene to stabilize

### Performance Optimization

**Mobile AR:**

```
Settings > AR > Performance
├── Star limit: [1000 ▼] (reduce for older devices)
├── Constellation detail: [Simple ▼]
├── Label distance: [Near only ▼]
└── Frame rate target: [30 FPS ▼]
```

**VR:**

```
Settings > VR > Performance
├── Render scale: [1.0 ▼] (reduce to 0.8 for better performance)
├── Star count: [100k ▼]
├── Shadow quality: [Off ▼]
├── Anti-aliasing: [2x ▼]
└── Atmospheric scattering: [Off ▼]
```

---

## Additional Resources

### VR Demo Videos

- [Nyx VR Walkthrough](https://youtube.com/nyx-vr-demo)
- [Classroom VR Guide](https://youtube.com/nyx-edu-vr)
- [Setting Up Quest for Nyx](https://youtube.com/nyx-quest-setup)

### AR Tutorials

- [Getting Started with AR Star Finding](https://youtube.com/nyx-ar-intro)
- [Advanced AR Calibration](https://youtube.com/nyx-ar-calibration)
- [Night Photography with AR Assist](https://youtube.com/nyx-ar-photo)

### Community

- VR astronomy Discord: discord.gg/nyx-vr
- AR feature requests: github.com/oshun/nyx/discussions
- VR content creators: #NyxVR on social media

---

## Back to [User Guide Home](./README.md)
