# Nyx Domain

> Cosmic Observatory Platform Libraries

Nyx is the comprehensive astronomy and space exploration domain within the Oshun
monorepo. It provides all the building blocks needed to build a full-featured
cosmic observatory platform, including celestial object databases, orbital
mechanics calculations, sky visualization, ephemeris computation, and telescope
control integration.

## Table of Contents

1. [Architecture Overview](#architecture-overview)
2. [Library Categories](#library-categories)
3. [Getting Started](#getting-started)
4. [Development Setup](#development-setup)
5. [Core Libraries](#core-libraries)
6. [Celestial Data](#celestial-data)
7. [Orbital Mechanics](#orbital-mechanics)
8. [Visualization](#visualization)
9. [Telescope Control](#telescope-control)
10. [User Features](#user-features)
11. [Configuration](#configuration)
12. [Testing](#testing)
13. [Applications](#applications)
14. [API Reference](#api-reference)

---

## Architecture Overview

The Nyx domain follows a modular architecture where each library handles a
specific astronomical concern. Libraries are designed to be composable and can
be used independently or together.

```
┌──────────────────────────────────────────────────────────────────────────┐
│                           APPLICATION LAYER                               │
│  (Web/Mobile apps, planetarium software, observation planning tools)     │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼────────────────────────────────────────┐
│                             NYX SDK                                       │
│  @nyx/sdk - Unified entry point for all cosmic observatory features      │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │
        ┌─────────────────────────┼─────────────────────────────────────┐
        │                         │                                     │
        ▼                         ▼                                     ▼
┌───────────────┐    ┌────────────────────┐    ┌────────────────────────┐
│  CELESTIAL    │    │   ORBITAL          │    │    VISUALIZATION       │
│  DATA         │    │   MECHANICS        │    │                        │
├───────────────┤    ├────────────────────┤    ├────────────────────────┤
│ star-catalogs │    │ ephemeris          │    │ sky-renderer           │
│ planet-data   │    │ orbital-elements   │    │ constellation-renderer │
│ galaxy-data   │    │ eclipse-predictor  │    │ object-annotations     │
│ dso-catalogs  │    │ conjunction-finder │    │ 3d-visualization       │
│ asteroid-data │    │ transit-calculator │    │ vr-planetarium         │
└───────────────┘    └────────────────────┘    └────────────────────────┘
        │                         │                                     │
        └─────────────────────────┼─────────────────────────────────────┘
                                  │
        ┌─────────────────────────┼─────────────────────────────────────┐
        │                         │                                     │
        ▼                         ▼                                     ▼
┌───────────────┐    ┌────────────────────┐    ┌────────────────────────┐
│  TELESCOPE    │    │   USER             │    │    OBSERVATION         │
│  CONTROL      │    │   FEATURES         │    │    PLANNING            │
├───────────────┤    ├────────────────────┤    ├────────────────────────┤
│ ascom         │    │ observation-log    │    │ visibility-calculator  │
│ indi          │    │ equipment-manager  │    │ session-planner        │
│ goto-control  │    │ imaging-workflow   │    │ weather-integration    │
│ autoguider    │    │ gamification       │    │ light-pollution        │
│ plate-solver  │    │ social-features    │    │ rise-set-times         │
└───────────────┘    └────────────────────┘    └────────────────────────┘
                                  │
                                  ▼
        ┌────────────────────────────────────────────────────┐
        │                   CORE LAYER                        │
        ├────────────────────────────────────────────────────┤
        │ @nyx/core - Types, validation, utilities           │
        │ @nyx/database - Celestial object storage           │
        │ @nyx/coordinates - Coordinate transformations      │
        │ @nyx/time - Time systems (UTC, JD, TDB, sidereal)  │
        │ @nyx/constants - Astronomical constants            │
        └────────────────────────────────────────────────────┘
                                  │
                                  ▼
        ┌────────────────────────────────────────────────────┐
        │              OSHUN SHARED LIBRARIES                 │
        │ @oshun/logging, @oshun/config, @oshun/database...  │
        └────────────────────────────────────────────────────┘
```

---

## Library Categories

### Core Infrastructure (7 libraries)

| Library       | Description                                        |
| ------------- | -------------------------------------------------- |
| `core`        | Base types, validation, and utilities              |
| `database`    | Celestial object database abstractions             |
| `coordinates` | Coordinate systems and transformations             |
| `time`        | Time systems (Julian dates, sidereal time, epochs) |
| `constants`   | Astronomical constants and physical values         |
| `utils`       | Common utility functions                           |
| `types`       | TypeScript type definitions                        |

### Celestial Data (8 libraries)

| Library         | Description                             |
| --------------- | --------------------------------------- |
| `star-catalogs` | Star catalog integrations (Gaia, Tycho) |
| `planet-data`   | Solar system and exoplanet data         |
| `galaxy-data`   | Galaxy catalogs and properties          |
| `dso-catalogs`  | Deep sky object catalogs (NGC, Messier) |
| `asteroid-data` | Asteroid and comet databases            |
| `satellite-tle` | Artificial satellite TLE tracking       |
| `meteor-data`   | Meteor shower predictions               |
| `variable-star` | Variable star monitoring                |

### Orbital Mechanics (6 libraries)

| Library             | Description                          |
| ------------------- | ------------------------------------ |
| `ephemeris`         | High-precision position calculations |
| `orbital-elements`  | Keplerian orbital element handling   |
| `eclipse-predictor` | Solar and lunar eclipse predictions  |
| `conjunction`       | Planetary conjunction finder         |
| `transit`           | Planetary transit calculations       |
| `perturbations`     | Gravitational perturbation modeling  |

### Visualization (7 libraries)

| Library             | Description                              |
| ------------------- | ---------------------------------------- |
| `sky-renderer`      | 2D sky chart rendering                   |
| `3d-visualization`  | 3D solar system visualization            |
| `constellation`     | Constellation rendering and boundaries   |
| `object-annotation` | Object labeling and information overlays |
| `vr-planetarium`    | VR planetarium experience                |
| `ar-starfinder`     | AR-based object identification           |
| `timeline`          | Time-based animation and playback        |

### Telescope Control (6 libraries)

| Library       | Description                  |
| ------------- | ---------------------------- |
| `ascom`       | ASCOM telescope protocol     |
| `indi`        | INDI protocol implementation |
| `goto`        | GoTo mount control           |
| `autoguider`  | Autoguiding interface        |
| `plate-solve` | Astrometric plate solving    |
| `camera`      | Astronomical camera control  |

### Observation Planning (5 libraries)

| Library      | Description                          |
| ------------ | ------------------------------------ |
| `visibility` | Object visibility calculations       |
| `planner`    | Observation session planning         |
| `weather`    | Weather forecast integration         |
| `light-poll` | Light pollution mapping              |
| `rise-set`   | Rise, transit, set time calculations |

### User Features (5 libraries)

| Library           | Description                      |
| ----------------- | -------------------------------- |
| `observation-log` | Personal observation logging     |
| `equipment`       | Equipment inventory management   |
| `imaging`         | Astrophotography workflow        |
| `gamification`    | Achievement and challenge system |
| `social`          | Community features and sharing   |

---

## Getting Started

### Installation

```bash
# Install the Nyx SDK (includes all essential features)
pnpm add @nyx/sdk

# Or install individual libraries
pnpm add @nyx/core @nyx/ephemeris @nyx/sky-renderer
```

### Basic Usage

```typescript
import { Nyx } from '@nyx/sdk';
import { Observer, CelestialCoordinates } from '@nyx/core';
import { calculatePosition } from '@nyx/ephemeris';

// Create an observer location
const observer: Observer = {
  latitude: 40.7128, // New York City
  longitude: -74.006,
  elevation: 10, // meters
  timezone: 'America/New_York',
};

// Get current position of Mars
const marsPosition = await calculatePosition('mars', new Date(), observer);

console.log(`Mars is at RA: ${marsPosition.ra}, Dec: ${marsPosition.dec}`);
console.log(
  `Altitude: ${marsPosition.altitude}°, Azimuth: ${marsPosition.azimuth}°`
);
```

### Render a Star Chart

```typescript
import { SkyRenderer } from '@nyx/sky-renderer';
import { StarCatalog } from '@nyx/star-catalogs';

const renderer = new SkyRenderer({
  width: 1920,
  height: 1080,
  projection: 'stereographic',
  limitingMagnitude: 6.5,
});

// Load star catalog
const stars = await StarCatalog.loadBrightStars();

// Render the current sky
const canvas = renderer.render({
  observer,
  datetime: new Date(),
  stars,
  showConstellations: true,
  showGrid: true,
});
```

### Calculate Eclipse

```typescript
import { EclipsePredictor } from '@nyx/eclipse-predictor';

const predictor = new EclipsePredictor();

// Find next solar eclipse visible from observer
const nextEclipse = await predictor.findNextSolarEclipse({
  observer,
  after: new Date(),
  type: 'any', // 'total', 'partial', 'annular', 'any'
});

console.log(`Next eclipse: ${nextEclipse.date}`);
console.log(`Type: ${nextEclipse.type}`);
console.log(`Maximum magnitude: ${nextEclipse.magnitude}`);
```

---

## Development Setup

This section covers setting up a development environment for contributing to Nyx
libraries.

### Prerequisites

- **Node.js**: v20.x or later
- **pnpm**: v10.x or later (package manager)
- **Git**: For version control
- **Docker**: For local database and services (optional but recommended)

### Clone and Install

```bash
# Clone the Oshun monorepo
git clone git@github.com:GreyChimp/oshun.git
cd oshun

# Install dependencies
pnpm install

# Start development infrastructure (PostgreSQL, Redis, etc.)
docker compose -f docker/docker-compose.dev.yml up -d
```

### Project Structure

Nyx libraries are organized under `libs/nyx/` in the monorepo:

```
oshun/
├── apps/
│   └── nyx/                          # Nyx applications
│       ├── api/                      # REST/GraphQL API server
│       ├── star-map/                 # Interactive star map web app
│       ├── planetarium/              # Planetarium experience
│       ├── observatory/              # Observatory control panel
│       ├── cli/                      # Command-line tools
│       ├── mobile/                   # Mobile app
│       └── electron/                 # Desktop application
│
├── libs/nyx/                         # Nyx libraries (66 total)
│   ├── core/                         # Core types and utilities
│   ├── coordinates/                  # Coordinate transformations
│   ├── time/                         # Time systems (JD, sidereal, etc.)
│   ├── constants/                    # Astronomical constants
│   ├── ephemeris/                    # Position calculations
│   ├── orbital-elements/             # Keplerian elements
│   ├── star-catalogs/                # Star database integrations
│   ├── sky-renderer/                 # 2D sky chart rendering
│   ├── 3d-visualization/             # 3D WebGL rendering
│   └── ...                           # Additional domain libraries
│
├── testing/e2e/tests/nyx/            # End-to-end tests
│   ├── star-map.visual.e2e.ts        # Visual regression tests
│   ├── star-map.browser.e2e.ts       # Cross-browser tests
│   └── star-map.performance.e2e.ts   # Performance tests
│
└── docs/domains/nyx/                 # Documentation
    ├── README.md                     # This file
    ├── accuracy.md                   # Astronomical accuracy docs
    └── api-guide.md                  # API documentation
```

### Building Libraries

```bash
# Build all Nyx libraries
pnpm nx run-many -t build --projects=tag:scope:nyx

# Build a specific library
pnpm nx build nyx-core
pnpm nx build nyx-ephemeris
pnpm nx build nyx-sky-renderer

# Build with watch mode for development
pnpm nx build nyx-core --watch
```

### Running Applications

```bash
# Start the Nyx API server
pnpm nx serve nyx-api

# Start the star map development server
pnpm nx dev nyx-star-map

# Start multiple apps in parallel
pnpm nx run-many -t serve --projects=nyx-api,nyx-star-map
```

### Linting and Formatting

```bash
# Lint all Nyx projects
pnpm nx run-many -t lint --projects=tag:scope:nyx

# Lint a specific library
pnpm nx lint nyx-core

# Fix lint issues automatically
pnpm nx lint nyx-core --fix

# Format code with Prettier
pnpm prettier --write "libs/nyx/**/*.ts"
```

### Running Tests

```bash
# Run all Nyx unit tests
pnpm nx run-many -t test --projects=tag:scope:nyx

# Run tests for a specific library
pnpm nx test nyx-ephemeris

# Run tests with coverage
pnpm nx test nyx-core --coverage

# Run tests in watch mode
pnpm nx test nyx-coordinates --watch

# Run E2E tests (requires running apps)
pnpm nx e2e testing-e2e --project=nyx-visual
pnpm nx e2e testing-e2e --project=nyx-performance
pnpm nx e2e testing-e2e --project=nyx-browser-chromium
```

### Creating a New Library

1. **Create the library directory structure**:

```bash
mkdir -p libs/nyx/my-feature/src
```

2. **Create `project.json`**:

```json
{
  "name": "nyx-my-feature",
  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
  "sourceRoot": "libs/nyx/my-feature/src",
  "projectType": "library",
  "tags": ["scope:nyx", "type:library"],
  "targets": {
    "build": {
      "executor": "@nx/esbuild:esbuild",
      "options": {
        "outputPath": "dist/libs/nyx/my-feature",
        "main": "libs/nyx/my-feature/src/index.ts",
        "tsConfig": "libs/nyx/my-feature/tsconfig.lib.json",
        "format": ["cjs", "esm"]
      }
    },
    "test": {
      "executor": "@nx/vite:test",
      "options": {
        "config": "libs/nyx/my-feature/vite.config.ts"
      }
    },
    "lint": {
      "executor": "@nx/eslint:lint",
      "options": {
        "lintFilePatterns": ["libs/nyx/my-feature/**/*.ts"]
      }
    }
  }
}
```

3. **Create `package.json`**:

```json
{
  "name": "@nyx/my-feature",
  "version": "0.0.1",
  "type": "module",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "dependencies": {
    "@nyx/core": "workspace:*"
  }
}
```

4. **Add path mapping to `tsconfig.base.json`**:

```json
{
  "compilerOptions": {
    "paths": {
      "@nyx/my-feature": ["libs/nyx/my-feature/src/index.ts"]
    }
  }
}
```

5. **Create your source files**:

```bash
# libs/nyx/my-feature/src/index.ts
touch libs/nyx/my-feature/src/index.ts
```

### Type Checking

```bash
# Type check all Nyx projects
pnpm nx run-many -t typecheck --projects=tag:scope:nyx

# Type check a specific library
pnpm tsc --noEmit -p libs/nyx/ephemeris/tsconfig.lib.json
```

### Debugging

For debugging Nyx libraries in VS Code:

1. Add a launch configuration in `.vscode/launch.json`:

```json
{
  "type": "node",
  "request": "launch",
  "name": "Debug Nyx Tests",
  "program": "${workspaceFolder}/node_modules/vitest/vitest.mjs",
  "args": ["run", "--reporter=verbose", "--no-coverage"],
  "cwd": "${workspaceFolder}/libs/nyx/ephemeris",
  "console": "integratedTerminal"
}
```

2. Set breakpoints in your test files or source code
3. Run the debug configuration

### Environment Setup

Create a `.env.local` file in the repo root for local development:

```bash
# Database
NYX_DATABASE_URL=postgresql://oshun:oshun_dev@localhost:5432/nyx

# External data paths (optional, for full catalog access)
NYX_GAIA_CATALOG_PATH=/data/catalogs/gaia_dr3
NYX_HIPPARCOS_PATH=/data/catalogs/hipparcos

# JPL ephemeris files (optional, uses bundled data by default)
NYX_EPHEMERIS_PATH=/data/ephemeris/de440.bsp

# API keys for external services
NYX_WEATHER_API_KEY=your_weather_api_key
```

### Contributing Guidelines

1. **Create a feature branch** for your changes
2. **Write tests** for all new functionality
3. **Ensure tests pass**: `pnpm nx test <library-name>`
4. **Ensure lint passes**: `pnpm nx lint <library-name>`
5. **Build successfully**: `pnpm nx build <library-name>`
6. **Update documentation** if adding new features
7. **Commit with conventional commits**: `feat(nyx): add new feature`
8. **Push and create a PR**

### Common Development Tasks

| Task                      | Command                                              |
| ------------------------- | ---------------------------------------------------- |
| Build all Nyx             | `pnpm nx run-many -t build --projects=tag:scope:nyx` |
| Test all Nyx              | `pnpm nx run-many -t test --projects=tag:scope:nyx`  |
| Lint all Nyx              | `pnpm nx run-many -t lint --projects=tag:scope:nyx`  |
| Start API server          | `pnpm nx serve nyx-api`                              |
| Start star map            | `pnpm nx dev nyx-star-map`                           |
| Run E2E tests             | `pnpm nx e2e testing-e2e --project=nyx-visual`       |
| Generate API types        | `pnpm nx generate-types nyx-api`                     |
| View dependency graph     | `pnpm nx graph --focus=nyx-core`                     |
| Check affected by changes | `pnpm nx affected -t test`                           |
| Reset local Nx cache      | `pnpm nx reset`                                      |
| View project details      | `pnpm nx show project nyx-ephemeris`                 |

---

## Core Libraries

### @nyx/core

The foundation library providing base types and utilities.

```typescript
import {
  Observer,
  CelestialCoordinates,
  HorizontalCoordinates,
  EquatorialCoordinates,
  GalacticCoordinates,
  EclipticCoordinates,
  CelestialObject,
  Star,
  Planet,
  DeepSkyObject,
} from '@nyx/core';
```

### @nyx/coordinates

Coordinate system transformations.

```typescript
import {
  equatorialToHorizontal,
  horizontalToEquatorial,
  equatorialToGalactic,
  equatorialToEcliptic,
  precessCoordinates,
  aberrationCorrection,
  refractedAltitude,
} from '@nyx/coordinates';

// Convert RA/Dec to Alt/Az
const horizontal = equatorialToHorizontal(
  { ra: 83.822, dec: -5.391 }, // Orion Nebula
  observer,
  new Date()
);
```

### @nyx/time

Astronomical time systems.

```typescript
import {
  toJulianDate,
  fromJulianDate,
  getModifiedJulianDate,
  getLocalSiderealTime,
  getGreenwichSiderealTime,
  deltaT,
  tdbToTt,
  besselianYear,
} from '@nyx/time';

const jd = toJulianDate(new Date());
const lst = getLocalSiderealTime(jd, observer.longitude);
```

### @nyx/constants

Astronomical constants.

```typescript
import {
  AU, // Astronomical Unit in km
  LIGHT_YEAR, // Light year in km
  PARSEC, // Parsec in km
  SPEED_OF_LIGHT, // Speed of light in km/s
  GRAVITATIONAL_CONST, // Gravitational constant
  SOLAR_MASS, // Solar mass in kg
  EARTH_RADIUS, // Earth equatorial radius
  OBLIQUITY_J2000, // Earth's obliquity at J2000
  J2000, // J2000 epoch as Julian Date
} from '@nyx/constants';
```

---

## Celestial Data

### @nyx/star-catalogs

Comprehensive star catalog access.

```typescript
import {
  StarCatalog,
  GaiaQuery,
  HipparcosCatalog,
  YaleBrightStarCatalog,
} from '@nyx/star-catalogs';

// Query nearby stars from Gaia DR3
const nearbyStars = await GaiaQuery.findNearbyStars({
  centerRa: 100,
  centerDec: 20,
  radius: 5, // degrees
  maxMagnitude: 10,
  limit: 1000,
});

// Get a specific star by catalog ID
const vega = await StarCatalog.getByHip(91262);
console.log(vega.name); // "Vega"
console.log(vega.magnitude); // 0.03
console.log(vega.spectralType); // "A0V"
```

### @nyx/planet-data

Solar system and exoplanet information.

```typescript
import {
  SolarSystemPlanet,
  ExoplanetCatalog,
  PlanetaryMoon,
} from '@nyx/planet-data';

// Get Jupiter data
const jupiter = SolarSystemPlanet.get('jupiter');
console.log(jupiter.mass); // In Earth masses
console.log(jupiter.orbitalPeriod); // In days
console.log(jupiter.moons); // Array of moons

// Query exoplanets
const habitableZone = await ExoplanetCatalog.findInHabitableZone({
  minRadius: 0.5, // Earth radii
  maxRadius: 2.0,
});
```

---

## Telescope Control

### @nyx/ascom

ASCOM Alpaca protocol for telescope control.

```typescript
import { AscomTelescope, AscomCamera } from '@nyx/ascom';

// Connect to telescope
const telescope = new AscomTelescope({
  host: '192.168.1.100',
  port: 11111,
  deviceNumber: 0,
});

await telescope.connect();

// Slew to target
await telescope.slewToCoordinatesAsync({
  ra: 5.5334, // hours
  dec: -5.391, // degrees
});

// Get current position
const position = await telescope.getPosition();
console.log(`Pointing at RA: ${position.ra}h, Dec: ${position.dec}°`);
```

---

## Configuration

### Environment Variables

```bash
# Database
NYX_DATABASE_URL=postgresql://user:pass@localhost:5432/nyx

# Star catalog paths
NYX_GAIA_CATALOG_PATH=/data/catalogs/gaia_dr3
NYX_HIPPARCOS_PATH=/data/catalogs/hipparcos

# Ephemeris data
NYX_EPHEMERIS_PATH=/data/ephemeris/de440.bsp

# External APIs
NYX_WEATHER_API_KEY=your_api_key
NYX_LIGHT_POLLUTION_API=https://api.lightpollutionmap.info

# Telescope
NYX_ASCOM_HOST=localhost
NYX_ASCOM_PORT=11111
```

---

## Testing

All Nyx libraries include comprehensive test suites.

```bash
# Run all Nyx tests
pnpm nx run-many -t test --projects=tag:scope:nyx

# Run specific library tests
pnpm nx test nyx-ephemeris
pnpm nx test nyx-coordinates

# Run with coverage
pnpm nx test nyx-core --coverage
```

### Test Utilities

```typescript
import {
  createMockObserver,
  createMockStar,
  createMockPlanet,
  KNOWN_POSITIONS, // Verified celestial positions for testing
} from '@nyx/testing';

describe('Ephemeris', () => {
  it('should calculate Mars position within tolerance', async () => {
    const observer = createMockObserver();
    const position = await calculatePosition('mars', KNOWN_POSITIONS.mars.date);

    expect(position.ra).toBeCloseTo(KNOWN_POSITIONS.mars.ra, 4);
    expect(position.dec).toBeCloseTo(KNOWN_POSITIONS.mars.dec, 4);
  });
});
```

---

## Applications

Nyx includes several ready-to-use applications built on top of the library
ecosystem.

### Star Map (`apps/nyx/star-map`)

An interactive web-based star map visualization application.

**Features:**

- Real-time WebGL sky rendering with millions of stars
- Interactive pan, zoom, and rotation
- Constellation overlays with mythology information
- Deep sky object markers and info panels
- Time slider for viewing sky at any date/time
- Location-based horizon masking
- Mobile touch support

**Running the Star Map:**

```bash
# Development mode with hot reload
pnpm nx dev nyx-star-map

# Build for production
pnpm nx build nyx-star-map

# Preview production build
pnpm nx preview nyx-star-map
```

### API Server (`apps/nyx/api`)

REST and GraphQL API server for astronomical calculations.

**Endpoints:**

| Endpoint                     | Description                         |
| ---------------------------- | ----------------------------------- |
| `GET /api/v1/ephemeris`      | Calculate celestial object position |
| `GET /api/v1/stars`          | Query star catalog                  |
| `GET /api/v1/constellations` | List constellations                 |
| `GET /api/v1/events`         | Upcoming astronomical events        |
| `GET /api/v1/visibility`     | Object visibility calculation       |
| `POST /api/v1/observation`   | Log an observation                  |

**Running the API:**

```bash
# Development mode
pnpm nx serve nyx-api

# With hot reload
pnpm nx serve nyx-api --watch
```

### Planetarium (`apps/nyx/planetarium`)

Immersive 3D planetarium experience with VR support.

**Features:**

- Full dome projection simulation
- Solar system exploration mode
- Educational guided tours
- VR headset support (WebXR)
- Multi-language narration

### Observatory (`apps/nyx/observatory`)

Control panel for remote observatory management.

**Features:**

- Telescope mount control (ASCOM/INDI)
- Camera and imaging control
- Weather monitoring integration
- Scheduling and automation
- Real-time status dashboard

### CLI Tools (`apps/nyx/cli`)

Command-line utilities for astronomical calculations.

```bash
# Calculate object position
nyx ephemeris mars --date "2026-01-21T00:00:00Z" --observer "40.7,-74.0"

# Find conjunctions
nyx conjunctions --start 2026-01-01 --end 2026-12-31 --separation 5

# Generate star chart
nyx chart --ra 83.82 --dec -5.39 --fov 10 --output m42.png

# List tonight's visible objects
nyx tonight --lat 40.7 --lon -74.0 --mag-limit 6
```

---

## API Reference

### Quick Reference

#### Ephemeris Calculation

```typescript
import { calculatePosition } from '@nyx/ephemeris';

const position = await calculatePosition(objectId, date, observer);
// Returns: { ra, dec, distance, altitude, azimuth, magnitude }
```

#### Coordinate Transformation

```typescript
import { equatorialToHorizontal } from '@nyx/coordinates';

const { altitude, azimuth } = equatorialToHorizontal(
  { ra: 83.822, dec: -5.391 },
  observer,
  date
);
```

#### Time Conversion

```typescript
import { toJulianDate, getLocalSiderealTime } from '@nyx/time';

const jd = toJulianDate(new Date());
const lst = getLocalSiderealTime(jd, longitude);
```

#### Star Catalog Query

```typescript
import { StarCatalog } from '@nyx/star-catalogs';

const stars = await StarCatalog.query({
  ra: { min: 80, max: 90 },
  dec: { min: -10, max: 0 },
  magnitude: { max: 8 },
  limit: 1000,
});
```

#### Sky Rendering

```typescript
import { SkyRenderer } from '@nyx/sky-renderer';

const renderer = new SkyRenderer({ width: 1920, height: 1080 });
const canvas = renderer.render({ observer, datetime, stars });
```

#### Eclipse Prediction

```typescript
import { EclipsePredictor } from '@nyx/eclipse-predictor';

const eclipses = await EclipsePredictor.findSolarEclipses({
  startDate: new Date('2026-01-01'),
  endDate: new Date('2030-12-31'),
  type: 'total',
});
```

### Full API Documentation

For complete API documentation, see:

- [@nyx/core API](./api/core.md)
- [@nyx/ephemeris API](./api/ephemeris.md)
- [@nyx/coordinates API](./api/coordinates.md)
- [@nyx/time API](./api/time.md)
- [@nyx/star-catalogs API](./api/star-catalogs.md)
- [@nyx/sky-renderer API](./api/sky-renderer.md)

---

## Related Documentation

- [Astronomical Accuracy](./accuracy.md) - Precision standards and validation
- [User Guide](./user-guide.md) - End-user documentation
- [API Guide](./api-guide.md) - REST/GraphQL API documentation
- [Astronomical Algorithms](./algorithms.md) - Implementation details
- [Coordinate Systems](./coordinates.md) - Coordinate system reference
- [Time Systems](./time.md) - Time system reference
- [Catalog Formats](./catalogs.md) - Supported catalog formats
- [Telescope Protocols](./telescope-protocols.md) - ASCOM/INDI protocols
