cosmos-lib

Reusable TypeScript library for astronomical data, coordinate math, sky maps, NASA/ESA APIs, media loading, and UI transitions. Zero runtime dependencies — Three.js and React support are optional peer dependencies in separate entry points.

Install

npm install @motioncomplex/cosmos-lib

Optional peer dependencies (only install what you use):

npm install three    # for cosmos-lib/three (3D scene helpers)
npm install react    # for cosmos-lib/react (React hooks & components)

Quick start

import Cosmos from '@motioncomplex/cosmos-lib'

// Search the built-in catalog (300+ stars, 110 Messier, 88 constellations)
const results = Cosmos.Data.search('orion')
const nebulae = Cosmos.Data.getByType('nebula')
const near    = Cosmos.Data.nearby({ ra: 83.8, dec: -5.4 }, 20)

// Coordinate transforms
const { alt, az } = Cosmos.Math.equatorialToHorizontal(
  { ra: 101.287, dec: -16.716 },                // Sirius
  { lat: 47.05,  lng: 8.31, date: new Date() }  // Lucerne
)

// Sun, Moon & eclipses
const sunPos    = Cosmos.Sun.position()
const moonPhase = Cosmos.Moon.phase()
const twilight  = Cosmos.Sun.twilight({ lat: 51.5, lng: -0.1 })

// NASA APIs
const apod = await Cosmos.API.NASA.apod()
const imgs = await Cosmos.API.NASA.searchImages('pillars of creation', { pageSize: 5 })

Tree-shakeable named exports

import { AstroMath, Data, NASA, Units, renderSkyMap, staggerIn } from '@motioncomplex/cosmos-lib'

React hooks (optional)

import { useSkyPosition, useMoonPhase, useWhatsUp, useTwilight, SkyMap } from '@motioncomplex/cosmos-lib/react'

// Reactive sky position — auto-updates every 10s
const pos = useSkyPosition('sirius', { lat: 47.05, lng: 8.31 })

// What's visible tonight?
const visible = useWhatsUp({ lat: 47.05, lng: 8.31 }, { magnitudeLimit: 4 })

Three.js helpers (optional)

import { createPlanet, LODTextureManager, CameraFlight } from '@motioncomplex/cosmos-lib/three'
import * as THREE from 'three'

const { group, dispose } = createPlanet({
  radius: 6.5,
  textureUrl: 'earth-bluemarble-4k.jpg',
  atmosphere: { color: 0x4488ff, intensity: 1.3 },
}, THREE)
scene.add(group)

Features

| Module | Description | Docs | |--------|-------------|------| | Data | 300+ bright stars, 110 Messier objects, 88 constellations, 20 meteor showers, solar system bodies. Fuzzy search, proximity queries, image resolution. | Data | | AstroMath | Julian dates, sidereal time, coordinate transforms (equatorial, horizontal, galactic, ecliptic), Kepler solver, planetary ephemeris, precession, nutation, refraction, rise/transit/set. | Math | | Sun / Moon / Eclipse | Solar & lunar positions, moon phases, twilight times, eclipse prediction. | Sun/Moon/Eclipse | | NASA / ESA / Simbad | NASA Image Library, APOD, ESA Hubble archive, CDS Simbad object resolution. | API Integrations | | Planner | "What's up tonight?" — visible objects, best observation windows, visibility curves, moon interference scoring, airmass, planet oppositions/conjunctions. | Planner | | AstroClock | Simulation clock with speed control, forward/reverse playback, snap-to-event, and requestAnimationFrame support. | Clock | | Sky Map | Stereographic, Mollweide, and gnomonic projections. Interactive canvas sky chart with pan, zoom, click-to-identify, FOV overlays, HUD, and real-time tracking. | Sky Map | | React Hooks | useSkyPosition, useMoonPhase, useAstroClock, useWhatsUp, useTwilight, <SkyMap />. SSR-safe. Optional peer dependency. | React | | Equipment | 160+ cameras, telescopes, lenses, and star trackers. Rig builder with FOV, pixel scale, framing, exposure limits, payload check, and target recommendations. | Astrophoto | | AstroPhoto | Session planner, exposure calculators (NPF, rule of 500, sub-exposure), Milky Way tracker, polar alignment, golden/blue hour, light pollution tools. | Astrophoto | | Events | Upcoming events feed: moon phases, eclipses, meteor showers, oppositions, conjunctions, equinoxes, solstices. iCal export. Observer visibility scoring. | Events | | Media | Progressive image loading with fallback chains, Wikimedia/Cloudinary URL builders, responsive srcset generation. | Media | | Transitions | View Transitions API wrappers: morph, stagger reveal, fade, crossfade, hero expand/collapse. | Transitions | | Three.js | Planet/nebula/starfield factories, LOD texture management, camera flights. Optional peer dependency. | Three.js | | Constants & Units | Astronomical constants (IAU 2012), distance/angle conversions, RA/Dec formatters. | Constants & Units |

Documentation

Full documentation lives in the docs/ folder:

• Getting Started — installation, import patterns, quick start
• API Reference — per-module docs with signatures, parameters, and examples
• Guides — conceptual walkthroughs for coordinate systems, catalog data, and Three.js integration
• Type Reference — quick-reference table of all exported types

Generate HTML API docs from TSDoc comments:

npm run docs

Development

npm install
npm test              # run tests
npm run test:watch    # watch mode
npm run typecheck     # tsc --noEmit
npm run build         # compile to dist/
npm run docs          # generate TypeDoc API reference

License

MIT