Skymap

Skymap is a Ruby library for generating maps of the sky.

Install the gem and add it to the application's Gemfile by executing:

bundle add skymap

If Bundler is not being used to manage dependencies, install the gem by executing:

gem install skymap

Skymap draws the sky seen by an observer at a given instant, and returns it as an SVG string:

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)

chart = Skymap::Chart.new(observer: observer, instant: instant, canvas: canvas)
svg = chart.render(
  Skymap::Catalog::Stars.new,
  lines: Skymap::Catalog::ConstellationLines.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.

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. The cardinal directions (N, E, S, W) are drawn in the padding.

Skymap::Catalog::Stars gives the 9,096 stars of the Yale Bright Star Catalogue (see Data sources), but Chart#render accepts any list of Skymap::Star.

Stars are drawn bigger the brighter they are. 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:

Skymap::Chart.new(
  observer: observer,
  instant: instant,
  canvas: canvas,
  magnitude_limit: 6
)

Skymap::Catalog::ConstellationLines gives the lines of the 88 IAU constellations (see Data sources). Pass them to Chart#render with lines: to draw the constellations; leave them out for a map of stars only.

Figures are drawn whole, even when some of their stars are fainter than the magnitude limit, and lines that cross the horizon stop at the edge of the sky. The stars given to Chart#render must include the stars of the lines: lines to a star that is not given are left out.

data/stars.csv is extracted from the Yale Bright Star Catalogue, 5th Revised Edition (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). The original description of the VizieR service was published in 2000, A&AS 143, 23.

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

After checking out the repo, run bin/setup to install dependencies. Then, run bundle exec rake to run the tests and the linter. You can also run bin/console for an interactive prompt that will allow you to experiment.

• Tests: bundle exec rspec
• Linter (Standard Ruby through RuboCop): bundle exec rubocop (bundle exec rubocop -a to autocorrect)
• Everything CI checks: bin/ci

1. Update the version number in lib/skymap/version.rb and CHANGELOG.md.
2. Commit, then tag and push: git tag vX.Y.Z && git push origin vX.Y.Z.
3. The Release workflow builds and publishes the gem to RubyGems.org using trusted publishing.

Bug reports and pull requests are welcome on GitHub at https://github.com/rhannequin/skymap. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the Skymap project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.