Eve library

Nyx Domain

Guide

Revision 1

On this page

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
  2. Library Categories
  3. Getting Started
  4. Development Setup
  5. Core Libraries
  6. Celestial Data
  7. Orbital Mechanics
  8. Visualization
  9. Telescope Control
  10. User Features
  11. Configuration
  12. Testing
  13. Applications
  14. 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.

text
┌──────────────────────────────────────────────────────────────────────────┐
│                           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:

text
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
  1. 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"]
      }
    }
  }
}
  1. 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:*"
  }
}
  1. Add path mapping to tsconfig.base.json:
json
{
  "compilerOptions": {
    "paths": {
      "@nyx/my-feature": ["libs/nyx/my-feature/src/index.ts"]
    }
  }
}
  1. 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"
}
  1. Set breakpoints in your test files or source code
  2. 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: