# Nyx User Guide

> Complete guide to using Nyx cosmic observatory applications

Welcome to the Nyx User Guide. This documentation covers all user-facing
features of the Nyx cosmic observatory platform, from basic star map navigation
to advanced VR planetarium experiences.

## Table of Contents

### Getting Started

- [Quick Start](#quick-start)
- [System Requirements](#system-requirements)
- [Installation](#installation)

### Guides

1. [Star Map Navigation](./star-map-navigation.md) - Navigate the night sky
2. [Search and Discovery](./search-discovery.md) - Find celestial objects
3. [Educational Features](./educational-features.md) - Learning tools and tours
4. [VR/AR Usage](./vr-ar-usage.md) - Immersive experiences

### Reference

- [Keyboard Shortcuts](#keyboard-shortcuts)
- [Glossary](#glossary)
- [FAQ](#faq)

---

## Quick Start

### Web Application

1. Navigate to the Nyx star map at `https://nyx.oshun.io/star-map`
2. Allow location access for accurate sky positioning
3. Use mouse/touch to pan and zoom the sky view
4. Click on any object to see its details

### Mobile Application

1. Download Nyx from the App Store or Google Play
2. Grant camera permissions for AR features
3. Point your device at the sky to identify objects
4. Tap objects for detailed information

### Desktop Application

1. Download Nyx Desktop from the releases page
2. Install and launch the application
3. Connect your telescope (optional)
4. Explore the cosmos

---

## System Requirements

### Web Application

| Component | Minimum    | Recommended      |
| --------- | ---------- | ---------------- |
| Browser   | Chrome 90+ | Chrome/Edge 110+ |
| RAM       | 4 GB       | 8 GB             |
| GPU       | WebGL 2.0  | Dedicated GPU    |
| Display   | 1280x720   | 1920x1080        |
| Internet  | 5 Mbps     | 25 Mbps          |

### Mobile Application

| Platform | Minimum Version | Notes                    |
| -------- | --------------- | ------------------------ |
| iOS      | 15.0+           | iPhone 8 or newer        |
| Android  | 10.0+           | ARCore compatible device |

### VR Requirements

| Platform  | Minimum                      |
| --------- | ---------------------------- |
| Quest 2/3 | Native support               |
| PC VR     | SteamVR compatible headset   |
| WebXR     | Chrome/Edge on compatible HW |

---

## Installation

### Web (No Installation Required)

Simply visit [nyx.oshun.io](https://nyx.oshun.io) in a modern browser.

### Progressive Web App (PWA)

1. Visit the Nyx web application
2. Click "Install" in your browser's address bar
3. The app will be available offline

### Desktop (Electron)

```bash
# Download from GitHub releases
# macOS
brew install --cask nyx-observatory

# Windows (via winget)
winget install Oshun.Nyx

# Linux (AppImage)
chmod +x Nyx-x86_64.AppImage
./Nyx-x86_64.AppImage
```

### Mobile

- **iOS**: [App Store Link](https://apps.apple.com/app/nyx-observatory)
- **Android**:
  [Google Play Link](https://play.google.com/store/apps/details?id=io.oshun.nyx)

---

## Keyboard Shortcuts

### Navigation

| Action         | Windows/Linux | macOS         |
| -------------- | ------------- | ------------- |
| Pan up         | `W` or `↑`    | `W` or `↑`    |
| Pan down       | `S` or `↓`    | `S` or `↓`    |
| Pan left       | `A` or `←`    | `A` or `←`    |
| Pan right      | `D` or `→`    | `D` or `→`    |
| Zoom in        | `+` or scroll | `+` or scroll |
| Zoom out       | `-` or scroll | `-` or scroll |
| Reset view     | `Home`        | `Fn` + `←`    |
| Go to location | `G`           | `G`           |

### Time Controls

| Action          | Windows/Linux | macOS         |
| --------------- | ------------- | ------------- |
| Play/pause time | `Space`       | `Space`       |
| Jump to now     | `N`           | `N`           |
| Step forward    | `]`           | `]`           |
| Step backward   | `[`           | `[`           |
| Faster          | `Shift` + `]` | `Shift` + `]` |
| Slower          | `Shift` + `[` | `Shift` + `[` |

### Display Options

| Action                | Windows/Linux | macOS            |
| --------------------- | ------------- | ---------------- |
| Toggle constellations | `C`           | `C`              |
| Toggle grid           | `E`           | `E`              |
| Toggle labels         | `L`           | `L`              |
| Toggle planets        | `P`           | `P`              |
| Toggle deep sky       | `O`           | `O`              |
| Toggle atmosphere     | `T`           | `T`              |
| Night mode            | `Ctrl` + `N`  | `Cmd` + `N`      |
| Full screen           | `F11`         | `Ctrl`+`Cmd`+`F` |

### Search

| Action         | Windows/Linux | macOS       |
| -------------- | ------------- | ----------- |
| Open search    | `Ctrl` + `F`  | `Cmd` + `F` |
| Search by name | `/`           | `/`         |
| Quick find     | `Ctrl` + `K`  | `Cmd` + `K` |

---

## Glossary

### Astronomical Terms

| Term                | Definition                                                  |
| ------------------- | ----------------------------------------------------------- |
| **Altitude**        | Height above horizon in degrees (0° to 90°)                 |
| **Azimuth**         | Compass direction (0° N, 90° E, 180° S, 270° W)             |
| **Declination**     | Celestial latitude (-90° to +90°)                           |
| **Right Ascension** | Celestial longitude (0h to 24h or 0° to 360°)               |
| **Magnitude**       | Brightness scale (lower = brighter, negative = very bright) |
| **Zenith**          | Point directly overhead (altitude 90°)                      |
| **Nadir**           | Point directly below (opposite of zenith)                   |
| **Meridian**        | North-south line through zenith                             |
| **Ecliptic**        | Path of Sun across sky; plane of solar system               |
| **DSO**             | Deep Sky Object (galaxy, nebula, cluster)                   |

### Object Types

| Abbreviation | Full Name            | Symbol |
| ------------ | -------------------- | ------ |
| **Str**      | Star                 | ★      |
| **Pla**      | Planet               | ●      |
| **Moo**      | Moon/Satellite       | ◐      |
| **Gal**      | Galaxy               | ◎      |
| **Neb**      | Nebula               | ☁      |
| **OC**       | Open Cluster         | ⊛      |
| **GC**       | Globular Cluster     | ⊚      |
| **Ast**      | Asteroid             | ⬡      |
| **Com**      | Comet                | ☄      |
| **Sat**      | Artificial Satellite | ▲      |

---

## FAQ

### General

**Q: Is Nyx free to use?** A: The web application is free with basic features.
Premium subscriptions unlock additional catalogs, telescope control, and
advanced features.

**Q: Does Nyx work offline?** A: Yes, the PWA and desktop versions cache star
catalogs for offline use. However, some features like satellite tracking require
internet.

**Q: Can I use Nyx for astrophotography?** A: Yes! Nyx includes tools for
planning imaging sessions, calculating field of view, and controlling ASCOM/INDI
compatible equipment.

### Technical

**Q: Why is my sky position incorrect?** A: Ensure location services are enabled
and accurate. You can manually set coordinates in Settings > Location.

**Q: Objects aren't showing at their correct positions?** A: Check that your
device's date and time are correct. Nyx uses your system time for calculations.

**Q: WebGL is not available?** A: Update your browser and graphics drivers. Some
integrated graphics may need hardware acceleration enabled in browser settings.

### Telescope Control

**Q: What telescopes are supported?** A: Any ASCOM Alpaca or INDI compatible
mount. This includes most modern computerized telescopes from Celestron,
Sky-Watcher, iOptron, and others.

**Q: How do I connect my telescope?** A: Go to Settings > Equipment > Add
Telescope. Enter your ASCOM server address or INDI server details.

**Q: Plate solving isn't working?** A: Ensure you have downloaded the
appropriate index files for your field of view. See Settings > Plate Solving for
configuration.

---

## Getting Help

### Support Channels

- **Documentation**: You're here!
- **Community Forum**: [community.oshun.io/nyx](https://community.oshun.io/nyx)
- **GitHub Issues**:
  [github.com/oshun/nyx/issues](https://github.com/oshun/nyx/issues)
- **Email Support**: nyx-support@oshun.io

### Reporting Bugs

When reporting bugs, please include:

1. Your device/browser information
2. Steps to reproduce the issue
3. Screenshots or screen recordings if applicable
4. Console errors (press F12 to open developer tools)

---

## Next Steps

- [Star Map Navigation](./star-map-navigation.md) - Learn to navigate the sky
- [Search and Discovery](./search-discovery.md) - Find celestial objects
- [Educational Features](./educational-features.md) - Explore learning tools
- [VR/AR Usage](./vr-ar-usage.md) - Experience immersive astronomy
