sidereal-canvas 0.1.0

Generate circular star charts for a location and time.

Sidereal Canvas

Sidereal Canvas turns an observer location and UTC time into a circular chart of the stars above the horizon.

Astropy places catalog stars in the local sky. Matplotlib renders them on a black, zenith-centered projection, with apparent magnitude controlling visual prominence and B-V-derived colors giving each star an approximate hue.

What it does

• transforms fixed HYG catalog coordinates into local altitude and azimuth;
• plots the geometric above-horizon sky with north at the top, east on the left, and west on the right;
• scales marker area and opacity from apparent magnitude;
• adds a restrained glow, horizon fade, cardinal directions, title, and Sidereal Canvas footer;
• combines exact-name labels with a requested number of the brightest named stars;
• exports PNG, SVG, and PDF with explicit dimensions and overwrite protection;
• runs from a committed catalog with no catalog download during rendering.

The core is an installable src/-layout Python package. Its coordinate, catalog, and rendering functions are covered by an offline test suite.

Install and render

Sidereal Canvas requires Python 3.14 or newer. Install and render with:

python -m pip install sidereal-canvas

sidereal-canvas render \
  --lat 47.6101 \
  --lon -122.2015 \
  --title "Bellevue, WA" \
  --time "2025-01-01T08:00:00Z" \
  --mag-limit 6.0 \
  --label-brightest 10 \
  --output bellevue.png

Use sidereal-canvas info to inspect the installed version, catalog checksum, row count, magnitude cutoff, and supported formats.

For visual development, python -m scripts.render_static_sky writes a deterministic matrix of Bellevue charts to artifacts/.

Run the checks with:

pytest
ruff check .
git diff --check

See CONTRIBUTING.md for a source checkout and development environment.

How a chart is built

1. Load and validate the packaged HYG-derived catalog.
2. Apply the limiting-magnitude filter.
3. Transform the remaining ICRS-like catalog directions to local AltAz coordinates for an EarthLocation and UTC Time.
4. Keep stars above the geometric horizon.
5. Select labels from the plotted rows.
6. Convert altitude to zenith distance with radius = 90° - altitude.
7. Draw glow and core marker layers, then labels and chart text.
8. Save the finished figure as PNG, SVG, or PDF.

The observer-looking-up projection puts the zenith at the center and the horizon at the outer circle. A star keeps the same marker styling when the magnitude cutoff changes, making charts directly comparable.

Scientific interpretation

The chart uses geometric, unrefracted coordinates. Real observing conditions also depend on sky brightness, weather, atmospheric extinction, terrain, and the observer or instrument. Catalog directions remain fixed at their J2000.0/ICRS-like positions, so proper motion is not propagated. Stellar colors are display approximations derived from B−V rather than direct temperature measurements.

The detailed conventions and accuracy boundaries are documented in docs/scientific-notes.md.

Data

The packaged catalog is derived from HYG Database v4.1 and contains 108,071 stars through apparent magnitude 10.0. Preprocessing verifies a pinned source checksum, preserves HYG identifiers, converts right ascension from hours to degrees, estimates display temperatures, and writes deterministic CSV bytes.

Catalog provenance, measurements, regeneration instructions, and licensing are in data/README.md.

Command reference

Version 0.1.0 renders from custom latitude and longitude, an offset-aware UTC timestamp, and a limiting magnitude. It supports exact-name and brightest-star labels plus PNG, SVG, and PDF output. The full command contract is in docs/cli.md, and planned additions are in docs/roadmap.md.

Documentation

• docs/design.md: architecture and product decisions
• docs/scientific-notes.md: astronomy assumptions and interpretation
• docs/engineering-notes.md: implemented decisions and measured evidence
• docs/releasing.md: package release procedure
• docs/constellations.md: constellation membership design
• CONTRIBUTING.md: development workflow

Data and acknowledgments

Data: HYG Database v4.1 by Astronexus, licensed under CC BY-SA 4.0. Stellar display colors are generated during preprocessing with starhue, distributed under the BSD 3-Clause License.

License

Original Sidereal Canvas code is licensed under the MIT License. The packaged derived catalog at src/sidereal_canvas/data/stars_mag100.csv is licensed separately under CC BY-SA 4.0. See THIRD_PARTY_NOTICES.md for details.