Starwatcher

Starwatcher is an open-source prototype for creating premium star-map poster compositions from a date, time, and location.

The app calculates a local sky snapshot, renders it as an interactive Three.js scene, and mirrors the same moment into a print-style poster preview. It also includes a heliocentric mode that shows approximate Mercury-through-Neptune positions around the Sun.

Status

This is a product and rendering prototype, not a production-grade astronomy engine. The current calculations are useful for validating the interaction model, visual direction, and print workflow. Before using it for sellable astronomy prints, the engine should be backed by a larger verified star catalog and higher-precision ephemeris handling.

Features

• Date and time based sky rendering
• Location presets plus custom latitude and longitude
• Curated MVP star catalog with constellation linework
• Local sidereal-time based sky rotation
• Heliocentric solar-system variant
• Interactive 3D scene with orbit controls
• Poster preview generated from the same render inputs
• PNG export for the active 3D canvas
• Unit tests for the astronomy and solar-system helpers

Tech Stack

• React
• TypeScript
• Vite
• Three.js with @react-three/fiber and @react-three/drei
• Vitest
• ESLint

Getting Started

Clone the repo and install dependencies:

git clone https://github.com/jokiatgithub/starwatcher.git
cd starwatcher
npm install

Start the local dev server:

npm run dev

Then open the local Vite URL printed in your terminal.

Environment

No secrets are required for the current prototype.

If you want local-only app settings, copy the example file:

cp .env.example .env

Real .env files are ignored by git and should stay local.

Scripts

npm run dev      # Start the Vite dev server
npm run lint     # Run ESLint
npm run test     # Run Vitest once
npm run build    # Type-check and create a production build
npm run preview  # Preview the production build locally

Project Structure

src/
  components/          3D scenes and poster preview
  data/                Curated MVP star catalog
  lib/                 Astronomy, render-mode, and solar-system helpers
tests/                 Unit tests for calculation helpers
docs/                  Engine notes and accuracy context
scripts/               Reserved for project automation

Accuracy Notes

The sky renderer uses a small curated star catalog and rotates stars into a local horizon view with Greenwich Mean Sidereal Time. The heliocentric variant uses approximate NASA/JPL Keplerian orbital elements for a readable product prototype.

For more detail, see docs/engine-notes.md.

Roadmap

The next major direction is a dedicated 3D solar-system engine with clear accuracy tiers, ephemeris adapters, rich camera modes, validation fixtures, and export workflows.

See docs/solar-system-engine-roadmap.md for the full roadmap.

Near-term priorities:

• Introduce a reusable engine boundary around time, coordinates, body states, and ephemeris adapters
• Validate planetary positions against JPL Horizons fixtures
• Refactor the heliocentric scene to consume normalized engine snapshots
• Add body picking, camera focus modes, and shareable scene URLs
• Expand export workflows for posters and animations

Contributing

Issues and pull requests are welcome. Please keep changes focused, include tests for calculation changes, and run the checks before opening a PR:

npm run lint
npm run test
npm run build

See CONTRIBUTING.md for more detail.

Security

Please do not open public issues for sensitive security reports. See SECURITY.md.

License

MIT. See LICENSE.