skymap 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39b1d636c38cf34bdfc3f5a254d032541d34644f36ccd81a2b7e8e93bb6381c6
-  data.tar.gz: df280a7aa348117b765058bf21238f5612f0c328518bf2db4cb23c9e131267e6
+  metadata.gz: 98d71fa1603df92409f0387d0f7d1d162de5ee8d5c332b8171ce019c2f54d684
+  data.tar.gz: 414e303a6a023f3ad4eb5d0937fd3aefbb5ad20ebb6f3bb095737cb290e17a8c
 SHA512:
-  metadata.gz: 0e91b001e8435a137565f80ec7637bc55105deb03b0dc23cf0bd3cfbb8f7839e92bc52a07f51efdf76d5f629408c6e8da2ff95fa3ea0cbcce6faf9420ff8d6b7
-  data.tar.gz: c8fca052275edce9fdd41b588cdfe303e8bbadc177aca27db77904fc6a9a17596b6bea4fede841961b479980116aa07343f74427338a2d2e3efb6199a0ff1996
+  metadata.gz: 6b00bb7e7fb4ff5d22e8948793fbd7a108fa64c56c0d5724cf9ab8cfc698fd99b5dccd14e5eb1dd6bcc3fbfd650b75574290b7a06db3b9653268f1c183325300
+  data.tar.gz: 12d6fb6e7000639230d6184a80939b1425bee1f3b4de886b19532b1bf23dbcd1b8128ce49f58012628fd1fdf49350bf9eabf9ffb62297a8a55f7b9d20414b5f8

data/CHANGELOG.md

@@ -5,11 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.1.0] - 2026-10-05
+
+### Added
+
+- `Skymap::Chart` draws the sky seen by an [Astronoby] observer at a given
+  instant and returns it as an SVG string, using a stereographic projection
+  with the zenith at the center and the horizon at the edge
+- `Skymap::Canvas` sets the size of the SVG and the padding around the horizon
+- `Chart#render` takes layers, drawn in order on top of the sky
+- `Skymap::Layers::Stars` draws stars sized by their magnitude and scaled with
+  the canvas, down to a `magnitude_limit:` (5 by default)
+- `Skymap::Catalog::Stars` gives the 9,096 stars of the Yale Bright Star
+  Catalogue
+- `Skymap::Layers::ConstellationLines` draws the lines of the constellations,
+  stopping at the horizon
+- `Skymap::Catalog::ConstellationLines` gives the lines of the 88 IAU
+  constellations, each with a `bold`, `normal` or `thin` weight
+- `Skymap::Layers::CardinalDirections` labels the cardinal directions around
+  the horizon
 
 ## [0.0.1] - 2026-09-25
 
 - Initial release to reserve the gem name on RubyGems.org
 
-[Unreleased]: https://github.com/rhannequin/skymap/compare/v0.0.1...HEAD
+[0.1.0]: https://github.com/rhannequin/skymap/compare/v0.0.1...v0.1.0
 [0.0.1]: https://github.com/rhannequin/skymap/releases/tag/v0.0.1
+[Astronoby]: https://github.com/rhannequin/astronoby

data/README.md

@@ -5,6 +5,14 @@
 
 Skymap is a Ruby library for generating maps of the sky.
 
+<p align="center">
+  <img
+    src="https://raw.githubusercontent.com/rhannequin/skymap/main/sky_map.svg"
+    width="480"
+    alt="The sky over Paris on September 24, 2026 at 22:00 UTC, with the stars and the constellation lines"
+  >
+</p>
+
 > [!WARNING]
 > This project is in its very early stages, please expect breaking changes.
 
@@ -25,7 +33,142 @@ gem install skymap
 
 ## Usage
 
-Coming soon.
+Skymap draws the sky seen by an observer at a given instant, and returns it
+as an SVG string:
+
+```ruby
+require "skymap"
+
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(48.8575),
+  longitude: Astronoby::Angle.from_degrees(2.3514)
+)
+instant = Astronoby::Instant.from_time(Time.utc(2026, 9, 24, 22))
+canvas = Skymap::Canvas.new(size: 800, padding: 24)
+stars = Skymap::Catalog::Stars.new.to_a
+
+chart = Skymap::Chart.new(observer: observer, instant: instant, canvas: canvas)
+svg = chart.render(
+  Skymap::Layers::ConstellationLines.new(
+    lines: Skymap::Catalog::ConstellationLines.new,
+    stars: stars
+  ),
+  Skymap::Layers::Stars.new(stars: stars),
+  Skymap::Layers::CardinalDirections.new
+)
+
+File.write("sky_map.svg", svg)
+```
+
+The observer and the instant are [Astronoby] objects. Astronoby computes where
+each star is in the sky and Skymap draws it.
+
+The map is a disk: the zenith is at the center and the horizon is the edge. It
+uses a [stereographic projection], the most common one for sky charts because
+it keeps the shapes of constellations, even near the horizon. North is at the
+top and East is on the left, as on a map you would hold above your head.
+
+### Canvas
+
+The canvas is the square SVG the map is drawn on. `size` is its width and
+height, and `padding` is the space between the horizon and the edge of the
+SVG.
+
+### Layers
+
+A map is the sky, with the layers given to `Chart#render` drawn on top of it,
+in order: each layer is drawn over the previous ones. Without layers,
+`Chart#render` draws an empty sky. Leave a layer out to hide what it draws.
+
+#### Stars
+
+`Skymap::Layers::Stars` draws stars, bigger the brighter they are.
+`Skymap::Catalog::Stars` gives the 9,096 stars of the Yale Bright Star
+Catalogue (see [Data sources](#data-sources)), but the layer accepts any list
+of `Skymap::Star`.
+
+By default, only stars of magnitude 5 or brighter are drawn, which is about
+what you can see from a suburban sky. Use `magnitude_limit:` to draw more or
+fewer stars:
+
+```ruby
+Skymap::Layers::Stars.new(stars: stars, magnitude_limit: 6)
+```
+
+#### Constellation lines
+
+`Skymap::Layers::ConstellationLines` draws the lines of the constellations.
+`Skymap::Catalog::ConstellationLines` gives the lines of the 88 IAU
+constellations (see [Data sources](#data-sources)).
+
+Figures are drawn whole, even when some of their stars are fainter than the
+magnitude limit of the stars layer, and lines that cross the horizon stop at
+the edge of the sky. The stars given to the layer must include the stars of
+the lines: lines to a star that is not given are left out.
+
+Each line has a weight, as drawn on the IAU charts: `bold` for the best-known
+shapes (the asterisms, such as the Big Dipper or the Teapot of Sagittarius),
+`normal` for the rest of the figures and `thin` for the secondary lines. The
+layer draws the lines it's given, so select the ones you want, for example
+only the asterisms:
+
+```ruby
+asterisms = Skymap::Catalog::ConstellationLines.new.select do |line|
+  line.weight == :bold
+end
+
+Skymap::Layers::ConstellationLines.new(lines: asterisms, stars: stars)
+```
+
+#### Cardinal directions
+
+`Skymap::Layers::CardinalDirections` labels the cardinal directions (N, E, S,
+W) in the padding, with a size that follows it: a padding of about 3% of the
+size gives readable labels.
+
+## Data sources
+
+### Stars
+
+`data/stars.csv` is extracted from the [Yale Bright Star Catalogue, 5th
+Revised Edition][bsc5] (VizieR V/50): the 9,096 stars of the catalog with
+their Harvard Revised number (`hr`), J2000 coordinates (`right_ascension` in
+hours, `declination` in degrees) and visual magnitude (`magnitude`). The 14
+non-stellar entries kept only for numbering are left out.
+
+> Hoffleit, D., Warren Jr., W. H., 1991, _The Bright Star Catalogue, 5th
+> Revised Ed. (Preliminary Version)_, Astronomical Data Center, NSSDC/ADC.
+
+The file is generated with `bin/build_catalog`, which downloads the catalog
+from CDS.
+
+This research has made use of the VizieR catalogue access tool, CDS,
+Strasbourg, France ([DOI: 10.26093/cds/vizier][vizier-doi]). The original
+description of the VizieR service was published in 2000, A&AS 143, 23.
+
+### Constellations
+
+`data/constellations/iau.csv` holds the lines of the 88 IAU constellations
+(Mensa and Microscopium have none), one row per segment:
+
+- `constellation`: the IAU abbreviation of the constellation.
+- `from_hr`, `to_hr`: the ends of the segment, as HR numbers of stars of
+  `data/stars.csv`. An end with two HR numbers, such as `5190 5193`, is the
+  midpoint of these two stars: the IAU charts draw some lines to a pair of
+  close stars rather than to one of them.
+- `weight`: `bold` for the lines the charts draw thickest, the best-known
+  shapes such as the Big Dipper or the Teapot of Sagittarius, `normal` for the
+  rest of the main figures, `thin` for the secondary lines.
+
+The lines are transcribed from the [IAU constellation maps][oae-maps] of the
+IAU Office of Astronomy for Education, adapted from the original charts by
+the IAU and Sky & Telescope magazine (Roger Sinnott & Rick Fienberg), with the
+constellation patterns of Alan MacRobert, and released under the [Creative
+Commons Attribution 4.0 International][cc-by-4] license.
+
+The file was transcribed once from the vector PDF of each map, by matching the
+ends of the lines drawn on the maps to the stars of the catalog, and checked
+against the maps. It is not regenerated by a script.
 
 ## Development
 
@@ -62,6 +205,12 @@ Everyone interacting in the Skymap project's codebases, issue trackers, chat
 rooms and mailing lists is expected to follow the
 [code of conduct](CODE_OF_CONDUCT.md).
 
+[Astronoby]: https://github.com/rhannequin/astronoby
+[stereographic projection]: https://en.wikipedia.org/wiki/Stereographic_map_projection
 [Standard Ruby]: https://github.com/standardrb/standard
 [trusted publishing]: https://guides.rubygems.org/trusted-publishing/
 [MIT License]: https://opensource.org/licenses/MIT
+[bsc5]: https://cdsarc.cds.unistra.fr/viz-bin/cat/V/50
+[vizier-doi]: https://doi.org/10.26093/cds/vizier
+[oae-maps]: https://www.astro4edu.org/
+[cc-by-4]: https://creativecommons.org/licenses/by/4.0/