@blcklab/siriusx

v1.0.4

Published

13 days ago

Zero-dependency TypeScript astronomy platform for real catalogs, astrometry, observation planning, Solar System ephemerides, and optional renderers

A zero-runtime-dependency TypeScript astronomy platform for real star catalogs, observer-based astrometry, observation planning, Solar System ephemerides, and optional renderers.

Stable 1.0: 1.0.0 is the first production release of the frozen SiriusX API. It is designed for web planetariums, education, catalog exploration, and observation planning. It does not claim SOFA-equivalent sub-arcsecond certification.

SiriusX never generates random decorative stars. Every stellar result comes from catalog coordinates supplied by the application.

Install

npm install @blcklab/siriusx

Real-sky calculation

import { createSky } from "@blcklab/siriusx";
import { BRIGHT_STAR_CATALOG } from "@blcklab/siriusx/catalog/bright";

const sky = createSky({
  catalog: BRIGHT_STAR_CATALOG,
  observer: {
    latitudeDegrees: 14.5995,
    longitudeDegrees: 120.9842,
    elevationMeters: 10,
  },
  date: new Date(),
  accuracy: "visual",
  magnitudeLimit: 2,
  horizonLimitDegrees: 0,
});

for (const star of sky.getFrame().stars) {
  console.log(star.source.name, star.altitudeDegrees, star.azimuthDegrees);
}

Inspect the astrometric pipeline

import { observeStar } from "@blcklab/siriusx";

const observed = observeStar(star, observer, {
  date: new Date(),
  accuracy: "observational",
  earthOrientation: {
    dut1Seconds: 0.08,
    xPolarMotionArcseconds: 0.12,
    yPolarMotionArcseconds: 0.31,
  },
});

observed.stages.icrs;
observed.stages.propagated;
observed.stages.meanOfDate;
observed.stages.apparent;
observed.stages.topocentric;
observed.correctionsApplied;

Accuracy modes

| Mode | Intended use | Default corrections | |---|---|---| | fast | large interactive catalogs | proper motion, mean precession | | visual | web planetariums | fast + compact nutation, annual aberration, stellar parallax, refraction | | observational | observation planning | visual + solar deflection and supplied polar motion/EOP | | precision | reference-comparison workflows | fullest built-in pipeline, with explicit non-certification caveat |

Use ACCURACY_PROFILES to display these boundaries in developer tools or application settings.

Catalogs

import {
  createMemoryCatalog,
  packCatalog,
  unpackCatalog,
  validateCatalog,
} from "@blcklab/siriusx/catalog";

const catalog = createMemoryCatalog(myStars);
const sirius = catalog.get("Sirius");
const nearby = catalog.query({
  center: sirius,
  radiusDegrees: 10,
  magnitudeLimit: 6,
});

Catalog functionality includes:

identifier, name, alias, Bayer, and constellation lookup
magnitude and text filtering
cone search
validation and duplicate detection
JSON parsing
typed-array packed representation
synchronous and asynchronous catalog interfaces
streaming collection through AsyncIterable

The bundled bright catalog is intentionally small. Large Hipparcos, Tycho-2, Gaia, or application-specific subsets stay outside the core package.

Observation planning

import {
  calculateRiseSetTransit,
  calculateVisibilityWindows,
  airmassFromAltitude,
  angularSeparationDegrees,
} from "@blcklab/siriusx/observation";

const events = calculateRiseSetTransit({
  star: sirius,
  observer,
  date: new Date("2026-08-01T00:00:00Z"),
});

const windows = calculateVisibilityWindows({
  star: sirius,
  observer,
  start: new Date("2026-08-01T00:00:00Z"),
  end: new Date("2026-08-02T00:00:00Z"),
  minimumAltitudeDegrees: 25,
});

Utilities also include position angle, coordinate formatting/parsing, and airmass.

Solar System

import {
  sunPosition,
  moonPosition,
  planetPosition,
  observeSolarSystemBody,
  calculateTwilight,
} from "@blcklab/siriusx/solar-system";

const jupiter = planetPosition("jupiter", new Date());
const observedMoon = observeSolarSystemBody("moon", observer, new Date());
const twilight = calculateTwilight(observer, new Date());

Solar System observations apply full 3D topocentric parallax by default. This is especially important for the Moon, whose apparent position can shift by nearly one degree between the Earth's center and a surface observer.

import { calculateSolarSystemEvents } from "@blcklab/siriusx/solar-system";

const moonEvents = calculateSolarSystemEvents({
  body: "moon",
  observer,
  date: new Date("2026-08-01T00:00:00Z"),
  limb: "upper",
  refraction: "standard",
});

Event calculations explicitly distinguish center crossings from upper-limb contact and make the standard horizon-refraction assumption visible in the API.

Planet positions use JPL's published approximate Keplerian elements and expose their 1800–2050 validity range. The corrected compact Moon model is intended for visual maps and planning, not occultation or eclipse prediction. Elliptical minor-body propagation is available for user-supplied comet or asteroid elements.

Constellations

import {
  IAU_CONSTELLATIONS,
  createConstellationBoundaryResolver,
  parseConstellationBoundaryText,
} from "@blcklab/siriusx/constellations";

SiriusX ships all 88 IAU constellation identities, a conventional line-figure interface, and a generic boundary parser/resolver. Official boundary datasets remain external so applications can select and acknowledge the exact catalog revision they use.

Canvas renderer

import { createCanvasSky } from "@blcklab/siriusx/canvas";
import { BRIGHT_STAR_CATALOG } from "@blcklab/siriusx/catalog/bright";

const map = createCanvasSky(document.body, {
  catalog: BRIGHT_STAR_CATALOG,
  observer,
  accuracy: "visual",
  projection: "stereographic",
  showStarLabels: true,
  labelMagnitudeLimit: 1.5,
});

map.start();
map.setView({ zoom: 1.2, rotationDegrees: 15 });
const hit = map.hitTest(pointerX, pointerY);

Canvas handles DPR scaling, resize observation, lifecycle cleanup, labels, constellation lines, projection selection, view rotation, zoom, and hit testing. It remains isolated from root and core imports.

SVG and WebGL

import { renderSkySvg } from "@blcklab/siriusx/svg";
import { buildWebGlPointCloud } from "@blcklab/siriusx/webgl";

const svg = renderSkySvg(frame, { width: 800, height: 800 });
const points = buildWebGlPointCloud(frame, { width: 800, height: 800 });

The WebGL entry creates normalized point buffers without owning a WebGL context, making it suitable for custom engines.

React and Vue

Framework packages are not runtime dependencies. Inject the framework runtime to create a thin component wrapper:

import React from "react";
import { createReactSkyComponent } from "@blcklab/siriusx/adapters/react";

export const SiriusXSky = createReactSkyComponent(React);

import * as Vue from "vue";
import { createVueSkyComponent } from "@blcklab/siriusx/adapters/vue";

export const SiriusXSky = createVueSkyComponent(Vue);

Public entry points

@blcklab/siriusx
@blcklab/siriusx/core
@blcklab/siriusx/catalog
@blcklab/siriusx/catalog/bright
@blcklab/siriusx/observation
@blcklab/siriusx/constellations
@blcklab/siriusx/solar-system
@blcklab/siriusx/canvas
@blcklab/siriusx/svg
@blcklab/siriusx/webgl
@blcklab/siriusx/adapters/react
@blcklab/siriusx/adapters/vue

Scientific boundaries

SiriusX implements and tests IAU 2000 Earth Rotation Angle, IAU 2006 GMST, and IAU 2006 mean precession against SOFA reference fixtures. Its compact nutation, aberration, solar-deflection, lunar, and refraction models prioritize a small zero-dependency package. SiriusX 1.0.0 includes full topocentric Solar System vectors, corrected lunar distance and phase geometry, and independent reference fixtures for Sun/Moon observer positions and lunar events.

For spacecraft navigation, professional astrometric reduction, eclipse/occultation prediction, or telescope pointing that requires certified sub-arcsecond error budgets, use SOFA/JPL-grade systems and current IERS Earth-orientation data as the authority.

Documentation

Production documentation is organized from docs/index.md:

Development

npm ci
npm run check
npm run benchmark
npm pack

License

MIT. SOFA-derived coefficient implementations are covered by the attribution and derived-work notice in SOFA-NOTICE.md. Dataset provenance and scientific accuracy boundaries are documented in docs/accuracy-and-data.md.