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
- Core Libraries
- Celestial Data
- Orbital Mechanics
- Visualization
- Telescope Control
- User Features
- Configuration
- 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.
┌──────────────────────────────────────────────────────────────────────────┐
│ 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}`);
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);
});
});