Eve library

Nyx Domain

Other

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. Core Libraries
  5. Celestial Data
  6. Orbital Mechanics
  7. Visualization
  8. Telescope Control
  9. User Features
  10. Configuration
  11. Testing

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}`);

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);
  });
});