skymap 0.4.0 → 0.5.0

data/README.md

@@ -48,7 +48,7 @@ observer = Astronoby::Observer.new(
 )
 instant = Astronoby::Instant.from_time(Time.utc(2026, 9, 23, 20))
 canvas = Skymap::Canvas.new(size: 800, padding: 24)
-stars = Skymap::Catalog::Stars.new.to_a
+stars = Skymap::Catalog::Stars.new
 lines = Skymap::Catalog::ConstellationLines.new.to_a
 
 chart = Skymap::Chart.new(observer: observer, instant: instant, canvas: canvas)
@@ -87,6 +87,145 @@ 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.
 
+#### Print size
+
+The SVG is written in pixels by default. To print it at a known size, give the
+canvas a `print_size:`: the length of the side of the square, in millimeters
+(`:mm`), centimeters (`:cm`) or inches (`:in`):
+
+```ruby
+canvas = Skymap::Canvas.new(
+  size: 800,
+  padding: 24,
+  print_size: Skymap::PrintSize.new(length: 190, unit: :mm)
+)
+```
+
+The SVG gets `width="190mm"` and `height="190mm"`, and its `viewBox` stays in
+the units of the canvas, so the map is the same and a browser or a print dialog
+prints it at 190 mm.
+
+`Skymap::PrintSize.paper` gives the largest square that fits in the width of a
+sheet of paper, minus a margin of 10 mm on each side by default (`margin:`, in
+millimeters). The papers are `:a5`, `:a4`, `:a3`, `:letter` and `:tabloid`:
+
+```ruby
+Skymap::PrintSize.paper(:a4)                # 190 mm
+Skymap::PrintSize.paper(:letter, margin: 5) # 205.9 mm
+```
+
+Add a [scale](#scale) to the map to read angles on the printed chart.
+
+### View
+
+By default, the map is the whole sky. Pass a `view:` to zoom on an area of it:
+the center of the area, as the equatorial coordinates of a point of the sky, at
+J2000 or at the date of the chart (or horizontal coordinates), and the field of
+view, the angle between the opposite sides of the map:
+
+```ruby
+view = Skymap::View.new(
+  center: Astronoby::Coordinates::Equatorial.new(
+    right_ascension: Astronoby::Angle.from_hours(5.6),
+    declination: Astronoby::Angle.zero,
+    epoch: Astronoby::JulianDate::J2000
+  ),
+  field_of_view: Astronoby::Angle.from_degrees(50)
+)
+
+chart = Skymap::Chart.new(
+  observer: observer,
+  instant: instant,
+  canvas: canvas,
+  view: view
+)
+```
+
+Equatorial coordinates at any other epoch raise an `ArgumentError`. With
+horizontal coordinates, only the altitude and the azimuth are used, as seen by
+the observer of the chart. The field of view is an `Astronoby::Angle` of more
+than 0 and up to 180 degrees.
+
+The sky is still seen from the observer. By default, the zenith is at the top of
+the map, except when the zenith is in the view: the north is at the top then, as
+in the whole sky. The next section changes that. The layers draw what is in the
+view only. The horizon is drawn as a line when it is in the view, and the edge
+of the map is a thin outline. It is no longer the horizon, so the cardinal
+directions are not drawn. The Sun and the Moon are drawn at their size in the
+sky once it is larger than their usual size on the map. The stars come from a
+catalog that goes down to magnitude 9: draw them with `magnitude_limit: 9` in a
+zoomed view to fill it.
+
+#### Orientation
+
+A map in a telescope is turned in a way that depends on the telescope and on
+its mount. Three options of `View` give the map the same orientation:
+
+- `orientation: :zenith_up` (the default) keeps the zenith at the top, like an
+  alt-az mount does at the meridian.
+- `orientation: :equatorial` puts the north celestial pole at the top and the
+  east on the left, like the sky seen through an equatorial mount.
+- `rotation:` turns the map clockwise, by an `Astronoby::Angle`.
+- `mirrored: true` swaps the left and the right, before the rotation.
+
+On an equatorial mount, a refractor or a catadioptric telescope with a
+diagonal shows a mirrored image, and a Newtonian shows the sky turned by half a
+turn:
+
+```ruby
+field_of_view = Astronoby::Angle.from_degrees(4)
+
+Skymap::View.new(
+  center: center,
+  field_of_view: field_of_view,
+  orientation: :equatorial
+)
+Skymap::View.new(
+  center: center,
+  field_of_view: field_of_view,
+  orientation: :equatorial,
+  mirrored: true
+)
+Skymap::View.new(
+  center: center,
+  field_of_view: field_of_view,
+  orientation: :equatorial,
+  rotation: Astronoby::Angle.from_degrees(180)
+)
+```
+
+The north is the one of the celestial pole of the date, in both hemispheres.
+The lit side of the Moon follows the orientation too.
+
+### Accuracy
+
+Stars are drawn where they are at the date of the chart, not at their catalog
+position: their proper motion is applied from J2000 to the instant of the chart,
+then the position is precessed and nutated to the true equator and equinox of
+date, and seen from the observer. `Skymap::Star#coordinates_at(instant)` gives
+the first step, as `Astronoby::Coordinates::Equatorial` at J2000. A star without
+a proper motion stays where it is, at any epoch; with a proper motion, its
+coordinates must be at J2000, or `Skymap::Star` raises an `ArgumentError`. For a
+star that has a proper motion but no parallax or no radial velocity, which is
+the case of two thirds of the stars of the Bright Star Catalogue for the
+parallax and of a fifth of the others for the radial velocity, a parallax of 1
+milliarcsecond and a radial velocity of 0 are assumed: the position changes by
+less than 0.1 arcsecond. To keep the charts fast, the proper motion is left out
+of a star that it moves by less than 0.005 pixel on the chart, so a star is
+drawn within 0.005 pixel of where the full propagation puts it.
+
+These are not applied:
+
+- the annual aberration of light, up to about 20 arcseconds
+- the annual parallax, under 1 arcsecond
+- the atmospheric refraction, which lifts a star near the horizon by up to half
+  a degree
+- the rounding of the positions of the Bright Star Catalogue, about 1 arcsecond
+
+The proper motion is visible in charts with a field of view under a degree:
+Arcturus moves by 1 arcminute in 27 years. In a larger field, it is smaller
+than a pixel for most stars.
+
 ### Themes
 
 A theme gives the colors of the map. `Chart` draws the dark theme by default,
@@ -134,30 +273,41 @@ theme = Skymap::Theme.dark.with(
 )
 ```
 
-The colors are `background` (the square behind the sky, which the cardinal
-directions are written on), `sky`, `horizon`, `star`, `constellation_line`, `boundary`,
-`ecliptic`, `planet`, `sun`, `moon`, `moon_shadow` (with its
-`moon_shadow_opacity`, between 0 and 1), `constellation_name`, `star_name`,
-`planet_name` and `label` (the cardinal directions). `font` is the font family
-of every text.
-
 Use `"none"` as a color to leave something out. The dark theme has
 `background: "none"`, so the SVG is transparent around the sky, and with
 `sky: "none"` the sky is transparent too, to put the map on a background of
 your own. With `horizon: "none"`, the edge of the sky is not outlined.
 
+The [theme reference][themes-reference] lists every color and shows how to
+build a theme from scratch.
+
 ### 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.
 
+Labels never overlap. A label is written above or below its object, and moves
+to another side of it when that place is taken by another label, a deep-sky
+symbol, a planet, the Sun, the Moon or a bright star. A label with no room
+around its object is left out, so a crowded field shows fewer labels, and a
+larger map or a smaller field shows more. Labels of fields, planets, stars and
+deep-sky objects are placed in this order, and the brighter objects come first
+among deep-sky objects. The names of the constellations, the scale and the
+cardinal directions stay where they are.
+
 #### 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`.
+`Skymap::Catalog::Stars` gives the 130,556 stars down to magnitude 9 (see
+[Data sources](#data-sources)), but the layer accepts any list of
+`Skymap::Star`. Pass the catalog itself rather than `to_a`: it builds only the
+stars the layer asks for, the ones brighter than `magnitude_limit:` and, in a
+zoomed view, near the view. Building the 130,556 of them takes seconds and
+hundreds of megabytes.
+
+Stars are drawn at their position at the date of the chart, with their proper
+motion applied (see [Accuracy](#accuracy)).
 
 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
@@ -276,12 +426,78 @@ Skymap::Layers::ConstellationNames.new(
 )
 ```
 
+#### Deep-sky objects
+
+`Skymap::Layers::DeepSkyObjects` draws galaxies, clusters, nebulae and other
+deep-sky objects. `Skymap::Catalog::DeepSkyObjects` gives the 109 Messier
+objects and the NGC and IC objects of magnitude 12 or brighter, 1,741 in all
+(see [Data sources](#data-sources)), but the layer accepts any list of
+`Skymap::DeepSkyObject`, such as the objects you pick from the catalog:
+
+```ruby
+objects = Skymap::Catalog::DeepSkyObjects.new
+
+Skymap::Layers::DeepSkyObjects.new(objects: objects)
+```
+
+`messier?` tells the Messier objects from the others, so you can draw only
+those:
+
+```ruby
+Skymap::Layers::DeepSkyObjects.new(objects: objects.select(&:messier?))
+```
+
+Each type of object has its own symbol, drawn as an outline in the `deep_sky`
+color of the [theme](#themes), as in most atlases:
+
+| `type`              | Symbol                                    |
+| ------------------- | ----------------------------------------- |
+| `galaxy`            | an ellipse                                |
+| `globular_cluster`  | a circle with a cross                     |
+| `open_cluster`      | a dashed circle                           |
+| `planetary_nebula`  | a circle with four ticks around it        |
+| `nebula`            | a dashed square with rounded corners      |
+| `supernova_remnant` | a dashed circle with a dot at its center  |
+| `asterism`          | a dotted circle                           |
+| `double_star`       | a small circle with a bar through it      |
+| `other`             | a small cross                             |
+
+By default, objects of magnitude 11 or brighter are drawn, which keeps every
+Messier object, and an object without a magnitude is always drawn. Use
+`magnitude_limit:` to draw fewer objects, or up to 12 to draw all of the
+catalog, or select the objects you want. The `magnitude` of an object is a
+visual one unless its `magnitude_band` is `:blue`, as for 65 faint NGC and IC
+objects that only have a blue magnitude, which is about a magnitude fainter for
+most objects:
+
+```ruby
+galaxies = objects.select { |object| object.type == :galaxy }
+
+Skymap::Layers::DeepSkyObjects.new(objects: galaxies, magnitude_limit: 9.5)
+```
+
+An object has the size of the symbol on the map, which is small, until its
+size in the sky is larger: it is then drawn at its real size, which you see
+when you zoom in with a [view](#view). A small object keeps its proportions in
+the symbol, and an object with no known size, such as M40, is drawn with the
+smallest symbol. A round object is a circle. An elongated object is an ellipse
+turned the way the object is, as `position_angle` gives it, from the north
+through the east: the layer follows the [orientation](#orientation) of the
+view, its rotation and its mirror, and the whole sky. An elongated object
+without a position angle (M1, M8, M16, M42 and M43) is not turned, as nothing
+says which way: it is drawn as a circle with the same area as the ellipse,
+whose diameter is the square root of the product of its axes.
+
+With `labels: true`, the designation of each object (such as `M31`) is written
+next to its symbol, in the `deep_sky` color too. Objects below the horizon or
+outside the view are left out. Give the layer after the stars to draw its
+symbols over them.
+
 #### 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.
+The lit side of the Moon faces the Sun on the map: the Moon is turned with the
+projection, wherever it is on the map and whatever the orientation of the view.
 
 Astronoby needs an ephemeris to compute where the Moon is: download one once,
 load it and give it to the layer (see the
@@ -362,11 +578,184 @@ data, and it stops at the horizon:
 Skymap::Layers::Ecliptic.new
 ```
 
+#### Grid
+
+`Skymap::Layers::Grid` draws the celestial coordinate grid: the lines of right
+ascension and the circles of declination, including the celestial equator. They
+are the coordinates of the stars in a catalog, and the grid shows where the
+sky turns around the celestial pole. It needs no data, and it stops at the
+horizon:
+
+```ruby
+Skymap::Layers::Grid.new
+```
+
+The lines are 30 degrees apart (2 hours of right ascension) by default. Use
+`step:`, an `Astronoby::Angle`, to draw them closer or further apart. It is
+between 1 and 90 degrees and divides 360 degrees. For a line of right ascension
+every hour:
+
+```ruby
+Skymap::Layers::Grid.new(step: Astronoby::Angle.from_hours(1))
+```
+
+By default the grid is in the equator and equinox of J2000, like the
+coordinates of atlases and catalogs. Use `epoch: :of_date` to draw it in the
+true equator and equinox of the date of the chart instead. The declination
+circles are then centered on the true celestial pole of that date, which is
+what a polar-aligned equatorial mount shows:
+
+```ruby
+Skymap::Layers::Grid.new(epoch: :of_date)
+```
+
+The two grids differ by a fraction of a degree today, which only shows when the
+map is zoomed on a small area of the sky. For a view that follows a
+polar-aligned equatorial mount, use `:of_date`, which pairs with
+`orientation: :equatorial` (north celestial pole at the top). Keep `:j2000` to
+read coordinates off the grid and look them up in an atlas or a catalog.
+
+Give the grid first to `Chart#render` to draw the stars and the other layers
+over it.
+
+#### Field circles
+
+`Skymap::Layers::FieldCircles` draws circles that show what a finder scope or an
+eyepiece covers in the sky. Give it the fields to draw, as `Skymap::Field` or
+`Skymap::Setup` objects (see
+[Telescope, eyepiece and fields](#telescope-eyepiece-and-fields)):
+
+```ruby
+Skymap::Layers::FieldCircles.new(fields: [finder, setup], labels: true)
+```
+
+The circles are centered on the center of the [view](#view), so the layer needs
+a view, and nothing is drawn without one. Use `center:` to draw them around
+another point, as the equatorial or horizontal coordinates of a point of the
+sky, such as a target when the view is wider than the circles:
+
+```ruby
+Skymap::Layers::FieldCircles.new(fields: [setup], center: target)
+```
+
+A circle has the size of its field on the sphere, then it is projected, so it
+keeps its size and its shape anywhere in the map. Each circle and its label are
+drawn in the `field_circle` color of the [theme](#themes). In a view, a circle
+is drawn whole, even below the horizon, and a circle that does not reach the
+view is left out. In the whole sky, which has no center unless you give a `center:`,
+a circle stops at the horizon.
+
+With `labels: true`, the label of each field is written next to its circle.
+A label that would fall outside the view is left out. Give the layer last to
+`Chart#render` to draw the circles over the 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.
+size gives readable labels. It draws nothing when the map has a [view](#view).
+
+#### Scale
+
+`Skymap::Layers::Scale` draws a scale bar with its length as a label, such as
+`1°`, `30′` or `10″`, in the lower left of a map with a [view](#view). It draws
+nothing on the whole sky, where the scale changes from one place to another:
+
+```ruby
+Skymap::Layers::Scale.new
+```
+
+The bar is the longest of 1, 2, 5, 10, 20 and 30 arc-seconds, arc-minutes or
+degrees that is at most a fifth of the width of the map. It stays horizontal
+and the same in every [orientation](#orientation) of the view. The scale of the
+map changes from the center to the edge, and the bar follows it: its length is
+the angle it says at the place where it is drawn. A straight bar on the map is a
+small circle on the sky, not the shortest path between its ends, so the angle
+between the ends is a little smaller than the label on wide fields. The
+difference is below 0.01% up to a field of view of 90 degrees, which covers
+finder charts, and at most 0.1% at 120 degrees and 0.3% at 180 degrees. Nothing
+is drawn when even 1 arc-second is too long, for a field of view below about
+0.0014 degrees (5 arc-seconds). The bar and its label use the `scale`
+color of the theme. With a [print size](#print-size), the bar is as long on
+paper as the angle it says.
+
+### Telescope, eyepiece and fields
+
+An eyepiece in a telescope shows a small part of the sky, often less than a
+degree wide. These classes describe the equipment, compute that part of the
+sky, and give it to a [view](#view) or to the [field circles](#field-circles).
+
+`Skymap::Telescope` has a focal length and an aperture, in millimeters, as
+`focal_length_mm` and `aperture_mm`. `Skymap::Eyepiece` has a focal length in
+millimeters, as `focal_length_mm`, and the apparent field of view that its
+maker gives, as an `Astronoby::Angle`. All the numbers must be above 0, and
+the apparent field of view up to 180 degrees:
+
+```ruby
+telescope = Skymap::Telescope.new(focal_length_mm: 1200, aperture_mm: 200)
+eyepiece = Skymap::Eyepiece.new(
+  focal_length_mm: 25,
+  apparent_field_of_view: Astronoby::Angle.from_degrees(52)
+)
+```
+
+`Skymap::Setup` pairs a telescope with an eyepiece, and computes what you see
+with them:
+
+```ruby
+setup = Skymap::Setup.new(telescope: telescope, eyepiece: eyepiece)
+
+setup.magnification # => 48.0
+setup.true_field    # => an Astronoby::Angle of 1.083 degrees
+setup.label         # => "25 mm, 48×, 1.1°"
+```
+
+- `magnification` is the focal length of the telescope divided by the one of
+  the eyepiece, as a `Float`.
+- `true_field` is the part of the sky you see, as an `Astronoby::Angle`: the
+  apparent field of view divided by the magnification, the usual first-order
+  formula. With a Barlow lens or a focal reducer, give the effective focal
+  length of the telescope. It is what `field_of_view:` of a view takes, to draw
+  a map as wide as the eyepiece.
+- `label` is a short text for the circle: the focal length of the eyepiece,
+  the magnification and the true field, in degrees (with at most one decimal)
+  from 1 degree, in arcminutes (`15′`) below, and in arcseconds (`30″`) below
+  one arcminute.
+
+`Skymap::Field` is a field that does not come from a setup, such as a finder
+scope, a Telrad ring or the frame of a camera: its `true_field` as an
+`Astronoby::Angle`, and the `label` you choose:
+
+```ruby
+finder = Skymap::Field.new(
+  true_field: Astronoby::Angle.from_degrees(5),
+  label: "Finder 5°"
+)
+```
+
+`FieldCircles` takes anything with a `true_field` and a `label`, so a list of
+fields and setups draws them together around a target, on a map twice as wide
+as the eyepiece:
+
+```ruby
+view = Skymap::View.new(
+  center: target,
+  field_of_view: Astronoby::Angle.from_degrees(
+    setup.true_field.degrees * 2
+  )
+)
+
+chart = Skymap::Chart.new(
+  observer: observer,
+  instant: instant,
+  canvas: canvas,
+  view: view
+)
+svg = chart.render(
+  Skymap::Layers::Stars.new(stars: stars, magnitude_limit: 7),
+  Skymap::Layers::FieldCircles.new(fields: [finder, setup], labels: true)
+)
+```
 
 ## Examples
 
@@ -374,24 +763,77 @@ The [examples](https://github.com/rhannequin/skymap/tree/main/examples)
 folder has scripts and the maps they draw, for
 different combinations of layers, themes and observers: the naked-eye sky, a
 printable map of the constellations, the planets, a night vision map for
-outdoors, the southern sky and more. Start from the one closest to what you
-want to draw.
+outdoors, the southern sky, the galaxies of Virgo and more. Start from the one
+closest to what you want to draw.
 
 ## 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.
+`data/stars.bin` is the star catalog of `Skymap::Catalog::Stars`: 130,556
+stars down to magnitude 9, in a binary file of 2.6 MB that the catalog reads
+by magnitude and by area of the sky, so that a view of a few degrees reads a few
+hundred stars out of the file. Each star has its J2000 coordinates, its visual
+magnitude and its astrometry, blank when unknown: the proper motion in right
+ascension (`proper_motion_ra`, which includes the cosine of the declination) and
+in declination (`proper_motion_dec`) in mas/yr, the `parallax` in mas and the
+`radial_velocity` in km/s. `Skymap::Catalog::Stars` loads them as an
+`Astronoby::AngularVelocity`, an `Astronoby::Angle` and an
+`Astronoby::Velocity` on `Skymap::Star`. They are all optional, so a list of
+your own stars can leave them out: the proper motions are given together, and
+the parallax and the radial velocity are `nil` when unknown.
+
+The file merges the stars of two sources:
+
+- the 9,096 stars of the [Yale Bright Star Catalogue, 5th Revised Edition][bsc5]
+  (VizieR V/50), with their Harvard Revised number (`hr`), extracted in
+  `data/stars.csv`. They keep their values: a proper motion for each of them, a
+  parallax for 3,100 (387 of them are dynamical parallaxes, not trigonometric
+  ones) and a radial velocity for 9,090. The 14 non-stellar entries kept only
+  for numbering are left out
+- the 121,460 other stars of [Tycho-2][tycho2] down to magnitude 9, with no
+  Harvard Revised number. The visual magnitude is computed from the Tycho
+  magnitudes with V = VT - 0.090 (BT - VT), which gives the magnitude of the
+  Bright Star Catalogue to 0.001 at the median. The proper motion is the one of
+  Tycho-2, and the parallax and the radial velocity are the ones of [Gaia
+  DR3][gaia], or the parallax of the new reduction of [Hipparcos][hipparcos]
+  when Gaia has none: all but 6 of the stars have a proper motion, 97% a
+  parallax and 79% a radial velocity. The position of the few hundred stars for
+  which Tycho-2 only gives the position observed around 1991 comes from Gaia or
+  Hipparcos, brought to J2000 with their proper motion. A star of Tycho-2 is
+  left out when it is already in the Bright Star Catalogue: within 5
+  arcseconds, plus 5 years of its proper motion, and 0.5 magnitude
+
+The file is generated with `bin/build_stars`, which reads `data/stars.csv` and
+queries the [ESA Gaia archive][esa-archive], where ESA also serves Tycho-2 and
+Hipparcos. `bin/build_catalog` generates `data/stars.csv` from the Bright Star
+Catalogue, which it downloads from CDS. `data/stars.csv` is not part of the
+gem: the gem has `data/stars.bin` only.
+
+The data of Gaia, Hipparcos and Tycho come from ESA, which distributes them
+under [CC BY-NC 3.0 IGO][cc-by-nc-igo]: the file is released under the same
+license, with the credits "Credit: ESA, Gaia DPAC" and "Credit: ESA", and ESA
+asks to be contacted before any use that generates a financial gain. The
+license and the terms are in `data/LICENSE-stars.txt`, shipped with the gem. The
+code stays under the MIT license.
 
 > 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.
+> Høg, E. et al., 2000, _The Tycho-2 catalogue of the 2.5 million brightest
+> stars_, A&A 355, L27.
+
+> van Leeuwen, F., 2007, _Validation of the new Hipparcos reduction_, A&A 474,
+> 653.
+
+> Gaia Collaboration, 2016, _The Gaia mission_, A&A 595, A1; Gaia
+> Collaboration, 2023, _Gaia Data Release 3: Summary of the content and survey
+> properties_, A&A 674, A1.
+
+This work has made use of data from the European Space Agency (ESA) mission
+Gaia (<https://www.cosmos.esa.int/gaia>), processed by the Gaia Data Processing
+and Analysis Consortium (DPAC,
+<https://www.cosmos.esa.int/web/gaia/dpac/consortium>).
 
 This research has made use of the VizieR catalogue access tool, CDS,
 Strasbourg, France ([DOI: 10.26093/cds/vizier][vizier-doi]). The original
@@ -466,12 +908,90 @@ 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.
 
+### Deep-sky objects
+
+`data/deep_sky_objects.csv` holds 1,741 deep-sky objects, from
+[OpenNGC][openngc] (release v20260501, commit `36cb178`), one row per object:
+the 109 Messier objects, then the 1,496 NGC and 136 IC objects of magnitude 12
+or brighter that are not Messier objects.
+
+- `designation`: `M31` for a Messier object, `NGC 7000` or `IC 434` for the
+  others, without zero padding.
+- `name`: the first common name of OpenNGC, blank when it has none.
+- `type`: one of the types below.
+- `right_ascension` (hours) and `declination` (degrees): J2000 coordinates.
+- `magnitude`: the visual (V) magnitude, or the blue (B) one when there is no
+  V magnitude. Every object has one, and every Messier object has a V magnitude.
+- `magnitude_band`: `V` or `B`, the band of the `magnitude`.
+- `major_axis` and `minor_axis`: the size in arcminutes, blank when unknown.
+- `position_angle`: the angle of the major axis in degrees, from the north
+  through the east, blank when unknown. OpenNGC only gives it to galaxies, M24
+  and the Pleiades.
+
+The OpenNGC types become these ones:
+
+| OpenNGC                                | `type`              |
+| -------------------------------------- | ------------------- |
+| `G`, `GPair`, `GTrpl`, `GGroup`        | `galaxy`            |
+| `OCl`                                  | `open_cluster`      |
+| `GCl`                                  | `globular_cluster`  |
+| `PN`                                   | `planetary_nebula`  |
+| `Neb`, `HII`, `EmN`, `RfN`, `Cl+N`     | `nebula`            |
+| `SNR`                                  | `supernova_remnant` |
+| `*Ass`                                 | `asterism`          |
+| `**`                                   | `double_star`       |
+| `Other`                                | `other`             |
+
+M42 is the only Messier object of OpenNGC type `Cl+N`, a cluster with
+nebulosity: it is a `nebula`, as its nebulosity is far larger than the
+Trapezium cluster at its center. M24 (a star cloud) is an `asterism`, M73 is
+`other`, and M40 is a `double_star`: OpenNGC lists it with no size. Any other
+OpenNGC type stops the build.
+
+`Skymap::Catalog::DeepSkyObjects` loads them as `Skymap::DeepSkyObject`, with
+the sizes as `Astronoby::Angle`. A `minor_axis` is blank for most clusters and
+some nebulae: `Skymap::DeepSkyObject` takes it as a round object, with a
+`minor_axis` equal to its `major_axis`. Both are `nil` when the size is unknown
+(M40, M73).
+
+OpenNGC identifies M102 as a duplicate of M101 (its identity is controversial
+and it follows the assumption of NED), so M102 is left out and the file has no
+`M102`. M40 and M45 are not in the NGC and IC catalogs: they come from the
+addendum of OpenNGC, where the Pleiades are listed as Melotte 22.
+
+The file leaves out the objects of OpenNGC that are not in the sky or not
+objects (duplicates, non-existent objects, stars, novae and dark nebulae), the
+components of a galaxy listed apart (such as `NGC 520 NED01`), the objects of
+the addendum other than M40 and M45, and every NGC and IC object without a
+magnitude or fainter than magnitude 12. This keeps the objects you can look
+for in an amateur telescope, without the thousands of faint galaxies.
+
+The file is generated with `bin/build_deep_sky_objects`, which downloads
+`NGC.csv` and `addendum.csv` from the pinned commit of OpenNGC and keeps these
+objects. Pass the path of a local directory holding the two files to build from
+it. The output must not change when you run it again.
+
+OpenNGC is released under the [Creative Commons Attribution-ShareAlike 4.0
+International][cc-by-sa-4] license, and so is `data/deep_sky_objects.csv`: the
+license, with the credits and changes, is in
+`data/LICENSE-deep_sky_objects.txt`, shipped with the gem. If you share this
+file or data adapted from it, you must release your version under the same
+license. The code of Skymap stays under the MIT license.
+
+OpenNGC merges the data of the NASA/IPAC Extragalactic Database (NED),
+HyperLEDA, SIMBAD, the HEASARC archive and Harold Corwin's NGC/IC Positions and
+Notes. This research has made use of the NASA/IPAC Extragalactic Database
+(NED), which is operated by the Jet Propulsion Laboratory, California Institute
+of Technology, under contract with the National Aeronautics and Space
+Administration, of the HyperLEDA database, and of the SIMBAD database, operated
+at CDS, Strasbourg, France.
+
 ### Ephemeris of the tests
 
 The tests of the Sun, the Moon and the planets use
 `spec/fixtures/de440s_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 barycenters of the planets, the
+planetary and lunar ephemeris of the
+[Jet Propulsion Laboratory][jpl-ephemerides], distributed by [NAIF][naif]. It only keeps the barycenters of the planets, 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.
@@ -489,14 +1009,19 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 - Tests: `bundle exec rspec`
 - Linter ([Standard Ruby] through RuboCop): `bundle exec rubocop`
   (`bundle exec rubocop -a` to autocorrect)
+- Render times of representative charts: `bin/benchmark` (`RUNS=10` to change
+  the number of runs it keeps the best of)
 - Everything CI checks: `bin/ci`
 
 ### Releasing
 
-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](.github/workflows/release.yml) builds and publishes
-   the gem to RubyGems.org using [trusted publishing].
+1. Update the version number in `lib/skymap/version.rb`, date the section of
+   the version in `CHANGELOG.md` and run `bundle install` to update
+   `Gemfile.lock`.
+2. Merge it, then tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z`.
+3. The [Release workflow](.github/workflows/release.yml) checks that the tag
+   matches the version, then builds and publishes the gem to RubyGems.org using
+   [trusted publishing].
 
 ## Contributing
 
@@ -507,7 +1032,13 @@ the [code of conduct](CODE_OF_CONDUCT.md).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License].
+The gem is available as open source under the terms of the [MIT License]. The
+data file `data/deep_sky_objects.csv` is adapted from OpenNGC and released under
+[CC BY-SA 4.0][cc-by-sa-4] (see [Data sources](#deep-sky-objects-1)). The data
+file `data/stars.bin` merges data of ESA missions and is released under
+[CC BY-NC 3.0 IGO][cc-by-nc-igo]: it is free to use with credit, and a use that
+generates a financial gain needs the authorization of ESA (see [Data
+sources](#stars-1)).
 
 ## Code of Conduct
 
@@ -521,11 +1052,19 @@ rooms and mailing lists is expected to follow the
 [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
+[tycho2]: https://cdsarc.cds.unistra.fr/viz-bin/cat/I/259
+[hipparcos]: https://cdsarc.cds.unistra.fr/viz-bin/cat/I/311
+[gaia]: https://www.cosmos.esa.int/web/gaia/dr3
+[esa-archive]: https://gea.esac.esa.int/archive/
 [vizier-doi]: https://doi.org/10.26093/cds/vizier
+[themes-reference]: https://github.com/rhannequin/skymap/blob/main/docs/themes.md
 [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/
+[cc-by-sa-4]: https://creativecommons.org/licenses/by-sa/4.0/
+[cc-by-nc-igo]: https://creativecommons.org/licenses/by-nc/3.0/igo/
+[openngc]: https://github.com/mattiaverga/OpenNGC
 [iau-csn]: https://www.pas.rochester.edu/~emamajek/WGSN/IAU-CSN.txt