Metadata-Version: 2.4
Name: sidereal-canvas
Version: 0.1.0
Summary: Generate circular star charts for a location and time.
License-Expression: MIT
Project-URL: Homepage, https://github.com/rivak7/sidereal-canvas
Project-URL: Repository, https://github.com/rivak7/sidereal-canvas
Project-URL: Issues, https://github.com/rivak7/sidereal-canvas/issues
Keywords: astronomy,astropy,star-chart,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: data/LICENSE.md
License-File: licenses/starhue-BSD-3-Clause.txt
Requires-Dist: astropy<9,>=8.0
Requires-Dist: matplotlib<4,>=3.10
Requires-Dist: numpy<3,>=2.2
Requires-Dist: pandas<3,>=2.2
Provides-Extra: catalog
Requires-Dist: starhue==1.1.1; extra == "catalog"
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: ruff~=0.15.21; extra == "dev"
Requires-Dist: starhue==1.1.1; extra == "dev"
Provides-Extra: web
Requires-Dist: streamlit<2,>=1.50; extra == "web"
Dynamic: license-file

# 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.

![Example chart](https://raw.githubusercontent.com/rivak7/sidereal-canvas/main/docs/demo.png)

## 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:

```bash
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:

```bash
pytest
ruff check .
git diff --check
```

See
[`CONTRIBUTING.md`](https://github.com/rivak7/sidereal-canvas/blob/main/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`](https://github.com/rivak7/sidereal-canvas/blob/main/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`](https://github.com/rivak7/sidereal-canvas/blob/main/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`](https://github.com/rivak7/sidereal-canvas/blob/main/docs/cli.md),
and planned additions are in
[`docs/roadmap.md`](https://github.com/rivak7/sidereal-canvas/blob/main/docs/roadmap.md).

## Documentation

- [`docs/design.md`](https://github.com/rivak7/sidereal-canvas/blob/main/docs/design.md):
  architecture and product decisions
- [`docs/scientific-notes.md`](https://github.com/rivak7/sidereal-canvas/blob/main/docs/scientific-notes.md):
  astronomy assumptions and interpretation
- [`docs/engineering-notes.md`](https://github.com/rivak7/sidereal-canvas/blob/main/docs/engineering-notes.md):
  implemented decisions and measured evidence
- [`docs/releasing.md`](https://github.com/rivak7/sidereal-canvas/blob/main/docs/releasing.md):
  package release procedure
- [`docs/constellations.md`](https://github.com/rivak7/sidereal-canvas/blob/main/docs/constellations.md):
  constellation membership design
- [`CONTRIBUTING.md`](https://github.com/rivak7/sidereal-canvas/blob/main/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`](https://github.com/devesh-aggarwal/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`](https://github.com/rivak7/sidereal-canvas/blob/main/THIRD_PARTY_NOTICES.md)
for details.
