skymap 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39b1d636c38cf34bdfc3f5a254d032541d34644f36ccd81a2b7e8e93bb6381c6
-  data.tar.gz: df280a7aa348117b765058bf21238f5612f0c328518bf2db4cb23c9e131267e6
+  metadata.gz: 2a51ef1b61aec62bb35240049a14adc40f006027f59fc30178eb973791901094
+  data.tar.gz: 1f8a1488c057a526bf1eaa7f36cb24fa78fc903e0a957fd6c946a1189ddebad6
 SHA512:
-  metadata.gz: 0e91b001e8435a137565f80ec7637bc55105deb03b0dc23cf0bd3cfbb8f7839e92bc52a07f51efdf76d5f629408c6e8da2ff95fa3ea0cbcce6faf9420ff8d6b7
-  data.tar.gz: c8fca052275edce9fdd41b588cdfe303e8bbadc177aca27db77904fc6a9a17596b6bea4fede841961b479980116aa07343f74427338a2d2e3efb6199a0ff1996
+  metadata.gz: 3151561266fea54c8845be6747e32d511da079ff8f0616bed97d359e39cadeddcb72d46e79f9f94a3dd8bbd27f00dd7598db65ef2a008ee68366978c1993537d
+  data.tar.gz: 205fab1dc18044a3117bc7cdd291ff18aaf5c07e47cc77e72f306acbaf1166b2b34b0b0edacc8676340d6df8b6afe96e5e09f1ad6ed9d8e96966ab38a7b51ab4

data/CHANGELOG.md

@@ -7,9 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-27
+
+### Added
+
+- `Skymap::Layers::ConstellationBoundaries` draws the boundaries between the
+  constellations as thin dashed lines, stopping at the horizon
+- `Skymap::Catalog::ConstellationBoundaries` gives the borders of the 88 IAU
+  constellations, in J2000 coordinates
+- `Skymap::Layers::Moon` draws the Moon with its phase, where it is in the sky,
+  from an ephemeris given with `ephem:`
+
+### Changed
+
+- The data of the constellations lives in `data/constellations/iau/`:
+  `data/constellations/iau.csv` is now `data/constellations/iau/lines.csv`
+
+## [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
+[Unreleased]: https://github.com/rhannequin/skymap/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/rhannequin/skymap/compare/v0.1.0...v0.2.0
+[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, the constellation lines, the constellation boundaries and the Moon"
+  >
+</p>
+
 > [!WARNING]
 > This project is in its very early stages, please expect breaking changes.
 
@@ -25,7 +33,217 @@ 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::ConstellationBoundaries.new(
+    boundaries: Skymap::Catalog::ConstellationBoundaries.new
+  ),
+  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 boundaries
+
+`Skymap::Layers::ConstellationBoundaries` draws the boundaries between the
+constellations as thin dashed lines, and stops the ones that cross the horizon
+at the edge of the sky. `Skymap::Catalog::ConstellationBoundaries` gives the
+borders of the 88 IAU constellations (see [Data sources](#data-sources)).
+
+Layers are drawn in the order they are given: put the boundaries first to draw
+them below the lines and the stars.
+
+#### 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)
+```
+
+#### Moon
+
+`Skymap::Layers::Moon` draws the Moon where it is in the sky, with its phase.
+The Moon is drawn upright, as the observer sees it from the ground, so a
+crescent over the western horizon is tilted as it is in the real sky. On the
+chart, this means the lit side does not always face the Sun's position.
+
+Astronoby needs an ephemeris to compute where the Moon is: download one once,
+load it and give it to the layer (see the
+[Astronoby documentation][astronoby-ephem] to pick one):
+
+```ruby
+Astronoby::Ephem.download(name: "inpop19a.bsp", target: "inpop19a.bsp")
+ephem = Astronoby::Ephem.load("inpop19a.bsp")
+
+Skymap::Layers::Moon.new(ephem: ephem)
+```
+
+The Moon is drawn larger than it is, as on most sky maps: at its true size it
+would be a dot as small as the faintest stars. Its radius is 3% of the radius
+of the sky. When the center of the Moon is below the horizon, it is left out.
+
+#### 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/lines.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.
+
+### Constellation boundaries
+
+`data/constellations/iau/boundaries.csv` holds the borders between the 88 IAU
+constellations, one row per point of a border, in order:
+
+- `border`: the number of the border. Each border between two constellations
+  is listed once.
+- `constellations`: the IAU abbreviations of the two constellations the border
+  separates.
+- `right_ascension` (hours) and `declination` (degrees): the coordinates of
+  the point, in J2000. The borders of the constellations are straight lines of
+  right ascension and declination in B1875, and curves in J2000: there is a
+  point about every degree to follow them.
+
+The borders come from the [Catalogue of Constellation Boundary Data][vi49] by
+Davenhall and Leggett (VizieR VI/49), in the version of Bill J. Gray that
+lists the constellation on each side of a border. They are the boundaries
+defined by Delporte in 1930, in B1875 coordinates.
+
+> Davenhall, A. C., Leggett, S. K., 1989, _Catalogue of Constellation Boundary
+> Data_, Royal Observatory Edinburgh.
+
+The file is generated with `bin/build_boundaries`, which downloads the
+catalog from CDS, keeps each shared border once, adds the points along the
+borders and precesses them to J2000 with Astronoby.
+
+### Ephemeris of the tests
+
+The tests of the Moon use `spec/fixtures/de440s_moon_2025_2030_excerpt.bsp`, an
+excerpt of DE440s, the planetary and lunar ephemeris of the [Jet Propulsion
+Laboratory][jpl-ephemerides], distributed by [NAIF][naif]. It only keeps the
+Earth-Moon barycenter, the Sun, the Moon and the Earth, from 2025 to 2030. As
+NAIF asks for modified kernels, its comment area names this project as the
+last to modify it, and points to the original kernel. It is not part of the
+gem.
+
+> Park, R. S., Folkner, W. M., Williams, J. G., Boggs, D. H., 2021, _The JPL
+> Planetary and Lunar Ephemerides DE440 and DE441_, The Astronomical Journal,
+> 161, 105.
 
 ## Development
 
@@ -62,6 +280,16 @@ 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
+[astronoby-ephem]: https://github.com/rhannequin/astronoby/blob/main/docs/ephem.md
+[oae-maps]: https://www.astro4edu.org/
+[vi49]: https://cdsarc.cds.unistra.fr/viz-bin/cat/VI/49
+[jpl-ephemerides]: https://ssd.jpl.nasa.gov/planets/eph_export.html
+[naif]: https://naif.jpl.nasa.gov/naif/rules.html
+[cc-by-4]: https://creativecommons.org/licenses/by/4.0/