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#
- Architecture Overview
- Library Categories
- Getting Started
- Development Setup
- Core Libraries
- Celestial Data
- Orbital Mechanics
- Visualization
- Telescope Control
- User Features
- Configuration
- Testing
- Applications
- 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#
# 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#
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#
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#
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#
# 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#
# 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#
# 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#
# 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#
# 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#
- Create the library directory structure:
mkdir -p libs/nyx/my-feature/src
- Create
project.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"]
}
}
}
}
- Create
package.json:
{
"name": "@nyx/my-feature",
"version": "0.0.1",
"type": "module",
"main": "./src/index.ts",
"types": "./src/index.ts",
"dependencies": {
"@nyx/core": "workspace:*"
}
}
- Add path mapping to
tsconfig.base.json:
{
"compilerOptions": {
"paths": {
"@nyx/my-feature": ["libs/nyx/my-feature/src/index.ts"]
}
}
}
- Create your source files:
# libs/nyx/my-feature/src/index.ts
touch libs/nyx/my-feature/src/index.ts
Type Checking#
# 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:
- Add a launch configuration in
.vscode/launch.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"
}
- Set breakpoints in your test files or source code
- Run the debug configuration
Environment Setup#
Create a .env.local file in the repo root for local development:
# 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#
- Create a feature branch for your changes
- Write tests for all new functionality
- Ensure tests pass:
pnpm nx test <library-name> - Ensure lint passes:
pnpm nx lint <library-name> - Build successfully:
pnpm nx build <library-name> - Update documentation if adding new features
- Commit with conventional commits:
feat(nyx): add new feature - 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.
import {
Observer,
CelestialCoordinates,
HorizontalCoordinates,
EquatorialCoordinates,
GalacticCoordinates,
EclipticCoordinates,
CelestialObject,
Star,
Planet,
DeepSkyObject,
} from '@nyx/core';
@nyx/coordinates#
Coordinate system transformations.
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.
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.
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.
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.
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.
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#
# 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.
# 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#
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:
# 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:
# 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.
# 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#
import { calculatePosition } from '@nyx/ephemeris';
const position = await calculatePosition(objectId, date, observer);
// Returns: { ra, dec, distance, altitude, azimuth, magnitude }
Coordinate Transformation#
import { equatorialToHorizontal } from '@nyx/coordinates';
const { altitude, azimuth } = equatorialToHorizontal(
{ ra: 83.822, dec: -5.391 },
observer,
date
);
Time Conversion#
import { toJulianDate, getLocalSiderealTime } from '@nyx/time';
const jd = toJulianDate(new Date());
const lst = getLocalSiderealTime(jd, longitude);
Star Catalog Query#
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#
import { SkyRenderer } from '@nyx/sky-renderer';
const renderer = new SkyRenderer({ width: 1920, height: 1080 });
const canvas = renderer.render({ observer, datetime, stars });
Eclipse Prediction#
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
- @nyx/ephemeris API
- @nyx/coordinates API
- @nyx/time API
- @nyx/star-catalogs API
- @nyx/sky-renderer API
Related Documentation#
- Astronomical Accuracy - Precision standards and validation
- User Guide - End-user documentation
- API Guide - REST/GraphQL API documentation
- Astronomical Algorithms - Implementation details
- Coordinate Systems - Coordinate system reference
- Time Systems - Time system reference
- Catalog Formats - Supported catalog formats
- Telescope Protocols - ASCOM/INDI protocols