# Star Map Navigation

> Master the art of navigating Nyx's interactive star map

This guide covers all aspects of navigating the Nyx star map, from basic pan and
zoom to advanced coordinate entry and telescope synchronization.

## Table of Contents

1. [Basic Navigation](#basic-navigation)
2. [View Modes](#view-modes)
3. [Time Control](#time-control)
4. [Location Settings](#location-settings)
5. [Display Layers](#display-layers)
6. [Object Interaction](#object-interaction)
7. [Advanced Navigation](#advanced-navigation)

---

## Basic Navigation

### Mouse Controls (Desktop)

| Action           | Control               |
| ---------------- | --------------------- |
| Pan view         | Click and drag        |
| Zoom in/out      | Scroll wheel          |
| Select object    | Single click          |
| Center on object | Double click          |
| Context menu     | Right click           |
| Rotate view      | Ctrl + drag (3D mode) |

### Touch Controls (Mobile/Tablet)

| Action           | Gesture                     |
| ---------------- | --------------------------- |
| Pan view         | Single finger drag          |
| Zoom in/out      | Pinch to zoom               |
| Select object    | Tap                         |
| Center on object | Double tap                  |
| Rotate view      | Two finger rotate (3D mode) |
| Context menu     | Long press                  |

### Gamepad Controls

| Action      | Control                      |
| ----------- | ---------------------------- |
| Pan view    | Left stick                   |
| Zoom in/out | Right stick Y-axis           |
| Rotate view | Right stick X-axis (3D mode) |
| Select      | A button                     |
| Back        | B button                     |
| Menu        | Start button                 |

---

## View Modes

Nyx offers multiple view modes for different use cases.

### 2D Flat View

The default view showing the sky as a flat projection.

**Projections available:**

| Projection    | Best For                        | Field of View |
| ------------- | ------------------------------- | ------------- |
| Stereographic | General viewing, wide field     | 1° - 180°     |
| Gnomonic      | Telescope planning, small areas | 1° - 120°     |
| Orthographic  | Hemisphere view, artistic       | 1° - 180°     |
| Mercator      | Navigation, equatorial belt     | 1° - 360°     |
| Hammer-Aitoff | Full-sky view, surveys          | Full sky      |
| Mollweide     | Full-sky view, area-accurate    | Full sky      |

**To change projection:**

1. Click the View menu
2. Select "Projection"
3. Choose your preferred projection

### 3D Orbital View

Interactive 3D view of the solar system.

**Controls:**

- Left drag: Orbit camera around Sun
- Right drag: Pan camera
- Scroll: Zoom in/out
- Double-click planet: Focus on that planet

**Scale modes:**

- **Realistic**: True distances (planets appear as dots)
- **Enhanced**: Enlarged planets, compressed distances
- **Schematic**: Diagrammatic view for education

### Planetarium Mode

Full dome simulation for planetarium software.

**Features:**

- Horizon masking based on observer location
- Cardinal direction labels (N, E, S, W)
- Zenith and nadir markers
- Atmosphere gradient rendering
- Light pollution simulation

### VR Immersive View

Full 360° immersive experience.

See [VR/AR Usage](./vr-ar-usage.md) for details.

---

## Time Control

Navigate through time to see how the sky changes.

### Time Controls Interface

Located at the bottom of the screen:

```
[<<] [<] [▶/⏸] [>] [>>]  |  2026-01-21 22:30:00 UTC  |  [Now] [Date Picker]
```

| Button | Function                     |
| ------ | ---------------------------- |
| `<<`   | Fast rewind (1 day/second)   |
| `<`    | Slow rewind (1 hour/second)  |
| `▶/⏸`  | Play/pause time animation    |
| `>`    | Slow forward (1 hour/second) |
| `>>`   | Fast forward (1 day/second)  |
| `Now`  | Jump to current real time    |

### Time Step Options

Customize time steps in Settings > Time:

| Step Size | Use Case                       |
| --------- | ------------------------------ |
| 1 second  | Satellite tracking, ISS passes |
| 1 minute  | Planet/Moon motion             |
| 1 hour    | Daily sky rotation             |
| 1 day     | Planetary position changes     |
| 1 week    | Moon phases                    |
| 1 month   | Seasonal constellation changes |
| 1 year    | Precession, proper motion      |

### Jump to Specific Date

1. Click the date display
2. Use the calendar picker to select a date
3. Optionally enter a specific time
4. Click "Go" to jump to that moment

**Quick date commands:**

- "tonight sunset" - Jump to today's sunset
- "next full moon" - Jump to next full moon
- "mars opposition" - Jump to next Mars opposition
- "2024 eclipse" - Jump to a known eclipse date

### Event Timeline

The timeline strip shows upcoming events:

```
[---o----●----o--------●------]
    ↑    ↑    ↑        ↑
  Sunset Moon Rise   ISS Pass  Sunrise
```

Click any event marker to jump to that time.

---

## Location Settings

Your viewing location affects what you can see.

### Setting Your Location

**Automatic (Recommended):**

1. Allow browser location access when prompted
2. Your GPS coordinates will be used
3. Elevation is estimated from terrain data

**Manual entry:**

1. Go to Settings > Location
2. Enter latitude and longitude
3. Optionally enter elevation
4. Click "Save"

**From map:**

1. Go to Settings > Location > Pick on Map
2. Click your location on the world map
3. Confirm selection

### Saved Locations

Save frequently used locations:

| Name           | Latitude | Longitude  | Elevation |
| -------------- | -------- | ---------- | --------- |
| Home           | 40.7128° | -74.0060°  | 10 m      |
| Cherry Springs | 41.6649° | -77.8224°  | 710 m     |
| Mauna Kea      | 19.8207° | -155.4681° | 4207 m    |
| Death Valley   | 36.5054° | -117.0794° | -86 m     |

### Famous Observatory Locations

Quick-select from world-renowned observatories:

- **Mauna Kea Observatory** - Hawaii, USA
- **Paranal Observatory** - Atacama Desert, Chile
- **Roque de los Muchachos** - La Palma, Canary Islands
- **South African Astronomical Observatory** - Sutherland, SA
- **Siding Spring Observatory** - New South Wales, Australia

---

## Display Layers

Control what appears on the star map.

### Layer Controls Panel

Access via the Layers button (☰) or press `L`:

```
☑ Stars (to magnitude 6.5)         [Slider: 1-12]
☑ Planets
☑ Moon and Sun
☑ Constellation lines
☐ Constellation boundaries
☑ Constellation names
☐ Deep sky objects
☐ Asteroids
☐ Comets
☐ Artificial satellites
☑ Coordinate grid
☐ Ecliptic line
☐ Galactic plane
☑ Horizon
☐ Atmosphere
```

### Stars Layer

| Setting           | Options                        |
| ----------------- | ------------------------------ |
| Magnitude limit   | 1.0 to 12.0 (higher = fainter) |
| Color mode        | Natural, Enhanced, Monochrome  |
| Size scaling      | Linear, Logarithmic, Fixed     |
| Show proper names | Named stars labeled            |
| Show Bayer names  | Greek letter designations      |
| Show HIP numbers  | Hipparcos catalog numbers      |

### Constellation Layer

| Setting         | Options                             |
| --------------- | ----------------------------------- |
| Line style      | IAU Official, Traditional, Artistic |
| Line color      | Various presets                     |
| Fill boundaries | Shade constellation areas           |
| Name position   | Center, Near brightest star         |
| Culture         | Western, Chinese, Arabic, Māori     |

### Deep Sky Objects

| Setting          | Options                  |
| ---------------- | ------------------------ |
| Show galaxies    | ☑                        |
| Show nebulae     | ☑                        |
| Show clusters    | ☑                        |
| Magnitude limit  | Up to magnitude 15       |
| Show images      | Display DSO photographs  |
| Catalog priority | Messier, NGC, IC, Custom |

### Coordinate Grids

| Grid Type  | Description                 |
| ---------- | --------------------------- |
| Equatorial | RA/Dec lines (J2000)        |
| Horizontal | Alt/Az lines                |
| Ecliptic   | Ecliptic latitude/longitude |
| Galactic   | Galactic coordinates        |

---

## Object Interaction

### Selecting Objects

Click or tap any visible object to select it:

```
┌─────────────────────────────────────────┐
│ ★ Betelgeuse (α Orionis)                │
├─────────────────────────────────────────┤
│ Type: Red Supergiant Star               │
│ Magnitude: 0.42 (variable)              │
│ Distance: 700 light years               │
│ Spectral: M1-2 Ia-Iab                   │
├─────────────────────────────────────────┤
│ RA: 05h 55m 10.3s | Dec: +07° 24' 25"   │
│ Alt: 45° 23' | Az: 165° 12'             │
├─────────────────────────────────────────┤
│ [Center] [Track] [Add to List] [More]   │
└─────────────────────────────────────────┘
```

### Object Actions

| Action          | Description                        |
| --------------- | ---------------------------------- |
| **Center**      | Center view on this object         |
| **Track**       | Keep object centered as time moves |
| **Add to List** | Add to observation list            |
| **More Info**   | Open detailed information panel    |
| **Wikipedia**   | Open Wikipedia article             |
| **GoTo**        | Slew telescope to object           |

### Object Information Panel

The expanded info panel shows:

- **Physical properties**: Size, mass, temperature, age
- **Orbital elements**: For solar system objects
- **Observability**: Rise/set times, best viewing time
- **History**: Discovery date, notable observations
- **Media**: Images, videos, audio guides
- **Related objects**: Nearby objects, same type

---

## Advanced Navigation

### Coordinate Entry

Go directly to specific coordinates:

1. Press `G` or click "Go To Coordinates"
2. Enter coordinates in any format:

```
# Equatorial (J2000)
RA: 05h 35m 17.3s  Dec: -05° 23' 28"
RA: 83.822°  Dec: -5.391°

# Horizontal
Alt: 45° Az: 180°

# Object name
M42
NGC 7000
Andromeda Galaxy
```

### Bookmark System

Save and organize sky locations:

**Create a bookmark:**

1. Navigate to desired view
2. Press `Ctrl/Cmd + B` or click bookmark icon
3. Name your bookmark
4. Optionally add to a folder

**Bookmark folders:**

- My Favorites
- Messier Objects
- Summer Targets
- Telescope Sessions

### View History

Navigate through recent views:

- `Alt + Left Arrow` - Go back
- `Alt + Right Arrow` - Go forward
- Click history icon to see list of recent locations

### Telescope Synchronization

If connected to a telescope:

| Action              | Description                          |
| ------------------- | ------------------------------------ |
| **Sync from Scope** | Match star map to telescope position |
| **Sync to Scope**   | Slew telescope to match star map     |
| **Two-Star Align**  | Perform alignment procedure          |
| **Park**            | Park telescope                       |

---

## Tips and Tricks

### Finding Faint Objects

1. Increase the magnitude limit
2. Turn off the atmosphere layer
3. Enable night mode for screen
4. Use the search function with filters

### Planning an Observation Session

1. Set location and date/time
2. Check what's visible tonight (Visibility panel)
3. Create an observation list
4. Sort by transit time
5. Export to telescope control software

### Screenshot and Sharing

- `Ctrl/Cmd + S` - Save screenshot
- `Ctrl/Cmd + Shift + S` - Save high-resolution
- Share button - Generate shareable link

### Keyboard Navigation Tips

- Hold `Shift` while panning for fine control
- Use number keys `1-9` for zoom presets
- Press `0` for full-sky view
- Press `?` for keyboard shortcut reference

---

## Next: [Search and Discovery](./search-discovery.md)
