celestial-chart 0.8.0

package/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+## 0.8.0 — first release of the fork
+
+Forked from [d3-celestial](https://github.com/ofrohn/d3-celestial) `0.7.35`
+(commit `7e720a3`, 2022-07-05).
+
+Every change below is measured against the pinned upstream build: 67 projections
+× 4 rotations × 413 sky points = 110 684 points, maximum difference **0.000 px**.
+
+### Astronomical fixes
+
+- **[#148](https://github.com/ofrohn/d3-celestial/issues/148)** `horizontal.inverse()`
+  was missing a sign correction. `acos` returns 0–180°, so half the sky above the
+  horizon — exactly the half where `sin(azimuth) > 0` — came back wrong, by up to
+  171°. The forward direction already handled the ambiguity. Round-trip error:
+  50% of points → 0%.
+- **[#130](https://github.com/ofrohn/d3-celestial/issues/130)** *Wrong moon phase?*
+  The phase computation is correct (verified against seven eclipse-anchored
+  syzygies). Two other defects produced the reported symptom:
+  - `moon.js` added Schlyter's **ecliptic** perturbation terms directly to right
+    ascension and declination, where `elements()` already accounts for them.
+    Meeus 13.a: RA error 1.50° → 0.0004°.
+  - The terminator ellipse used `1.6 · |ph − 0.5|` where the geometry is
+    `|2·ph − 1|`, so a full moon was drawn 19% narrow — as a gibbous.
+- **[#157](https://github.com/ofrohn/d3-celestial/issues/157)** The guard written
+  for the 180° centre change (`if (d > 3.14)`) was unreachable: `Round(d, 2)`
+  cannot exceed 3.14. Antipodal endpoints then went through `geoInterpolate`,
+  which divides by `sin(d) = 1.2e-16`. Measured angular error up to 139°.
+- `Celestial.ha()` normalised with `if (ha < 180)` instead of `if (ha < 0)`,
+  returning hour angles such as 460°.
+- `Trig.normalize` / `normalize0` did not normalise inputs below −2π (−3π).
+  Latent: the Moon's position stays sane from 1700 to 2300 either way.
+
+### Rendering fixes
+
+- Star colours: `d3.scaleQuantize` no longer accepts a descending domain, so
+  after the D3 upgrade **every star rendered red**. The scale is now built
+  ascending with a reversed range.
+- Milky Way: d3-geo filled the **complement** of the outline at some
+  orientations — the map greyed out and the Milky Way showed black. Detected by
+  asking the rendered path whether it contains the galactic pole, which is known
+  to lie outside every Milky Way contour. Verified across 44 orientations.
+- Window resize reset the user's zoom: the guard in `resize(set)` never fired,
+  because in D3 v7 the listener's first argument is the event object.
+- SVG export wrote `Infinity` coordinates for mercator (the 179.95° background
+  circle includes the poles); browsers discard such paths.
+- The map failed to render when given neither a container element nor a width —
+  `getWidth()` called `window.getBoundingClientRect()`, which does not exist.
+
+### Projections
+
+- `hatano` and `wagner7` restored: d3-geo-projection v4 no longer exports their
+  raw functions.
+- `healpix` restored to the v3 normalisation: v4 rescales x and y differently,
+  so the configured `scale`/`ratio` would produce a wrongly proportioned map.
+- `twoPointEquidistant`: v4's raw doubles its argument; the configured values are
+  calibrated for v3.
+- `wiechel`: reflecting the projected x is **not** equivalent to flipping the
+  longitude for this projection, because the sign of λ also matters inside
+  `atan2`. The v3 wrapping is kept.
+- `cassini` and `quincuncial` remain unavailable — they are absent from the
+  shipped upstream build as well.
+
+### Architecture
+
+- D3 v7, ES modules, tree-shaken and bundled. Four outputs: IIFE (global
+  `Celestial`, unchanged usage), minified IIFE, ESM and CJS.
+- Class-based instances (`SkyMap`), so several maps can share a page — each with
+  its own configuration, projection, container and settings form
+  ([#96](https://github.com/ofrohn/d3-celestial/issues/96),
+  [#131](https://github.com/ofrohn/d3-celestial/issues/131)).
+- Repeated `Celestial.display()` calls no longer append a duplicate settings form
+  (six calls produced 469 fields instead of 67, sharing ids).
+- TypeScript definitions, with a test that keeps them from drifting from the code.
+- The spherical zoom plugin now uses [`versor`](https://github.com/d3/versor)
+  (ISC) for the quaternion mathematics instead of a vendored copy.
+
+### Privacy
+
+- **No API key is shipped any more.** Upstream's defaults carried the author's
+  TimeZoneDB account id, and `settimezone: true` was also a default — so any page
+  embedding the library sent its visitors' coordinates to a third party, unasked,
+  on a quota shared with every other d3-celestial site, over plain HTTP whenever
+  the page itself was served over HTTP. A key in a client-side bundle cannot be
+  kept secret, so the fix is no key rather than a different one.
+- New `timezoneResolver(lat, lon, whenSeconds) => number | Promise<number>`
+  config option: resolve the offset from your own service. It takes precedence
+  over `timezoneid`, which still works with a key of your own.
+- A test now fails the build if a credential-looking literal reappears in `src/`.
+
+### Breaking changes
+
+Behaviour that differs from upstream — all of them consequences of the fixes above:
+
+- Moon right ascension and declination move by up to 1.50°; the terminator is wider.
+- `horizontal.inverse()` returns the correct hemisphere.
+- `Celestial.ha()` returns `[0, 360)`.
+- SVG export clips paths to the output size.
+- `Celestial.display()` additionally returns the created instance.
+- With no `timezoneid` and no `timezoneResolver`, the UTC offset of a position is
+  estimated from longitude instead of being looked up remotely. Configure one of
+  the two to get exact offsets back.
+
+A global `d3` is no longer required, or used, by the bundle.

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2015, Olaf Frohn
+Copyright (c) 2026, Fekete László
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/NOTICE.md

@@ -0,0 +1,41 @@
+# Notices and attributions
+
+`celestial-chart` is a fork of [d3-celestial](https://github.com/ofrohn/d3-celestial)
+by Olaf Frohn, distributed under the BSD 3-Clause License. See `LICENSE` for the
+full text, which covers both the original work and this fork.
+
+Per clause 3 of that license, the name of the original copyright holder is used
+here **only to identify the origin of the code** — not to endorse or promote this
+fork. This project is not affiliated with, nor endorsed by, Olaf Frohn.
+
+Likewise, this package is not an official D3 module and is not affiliated with
+the D3 project.
+
+## Bundled dependencies
+
+The distributed bundles (`build/celestial.js`, `.min.js`, `.mjs`, `.cjs`) include
+the following packages, all © Mike Bostock, ISC License:
+
+    d3-dispatch   d3-fetch     d3-geo       d3-geo-projection
+    d3-interpolate d3-scale    d3-selection d3-shape
+    d3-time-format d3-transition d3-zoom    versor
+
+ISC License text: https://opensource.org/licenses/ISC
+
+## Algorithm credits
+
+**Spherical drag-to-rotate** (`lib/geo-zoom.js`) implements the approach of
+Jason Davies' `d3.geo.zoom` plugin (2014, http://www.jasondavies.com/maps/rotate/).
+The quaternion mathematics is **not** copied from that plugin: it comes from the
+`versor` package (Mike Bostock, ISC), which provides the same computation under
+clear terms. The D3 v7 glue code is original to this fork.
+
+**Astronomical algorithms** in `src/kepler.js` and `src/moon.js` follow Paul
+Schlyter's *How to compute planetary positions* and Jean Meeus' *Astronomical
+Algorithms*; both are inherited from the upstream project.
+
+## Data files
+
+The star, deep-sky and Milky Way data under `harness/data/` is a minimal subset
+copied from the upstream repository for reproducible testing. The full data sets,
+their sources and licensing are documented upstream.

package/README.md

@@ -0,0 +1,192 @@
+# celestial-chart
+
+Interactive celestial map for the browser: stars, constellations, deep-sky objects,
+the Milky Way and planets, in 67 map projections, rendered to canvas with SVG export.
+
+A modernised fork of [d3-celestial](https://github.com/ofrohn/d3-celestial) by
+Olaf Frohn, whose last release was in 2022 and which is pinned to D3 v3.
+
+**Live demo: [celestial.blackit.hu](https://celestial.blackit.hu)** — pick a
+projection, drag to rotate, scroll to zoom.
+
+```bash
+npm install celestial-chart
+```
+
+```js
+import Celestial from "celestial-chart";
+
+Celestial.display({
+  container: "celestial-map",
+  projection: "aitoff",
+  stars: { limit: 6 },
+  constellations: { names: true, lines: true }
+});
+```
+
+Or a single script tag — **D3 is bundled, no separate `<script>` needed**:
+
+```html
+<link rel="stylesheet" href="node_modules/celestial-chart/celestial.css">
+<div id="celestial-map"></div>
+<script src="node_modules/celestial-chart/build/celestial.min.js"></script>
+```
+
+## What this fork changes
+
+**It runs on current D3.** Upstream is pinned to D3 v3 (2016). This fork uses
+D3 v7 as ES modules, bundled in — which resolves upstream
+[#147](https://github.com/ofrohn/d3-celestial/issues/147) (D3 upgrade),
+[#141](https://github.com/ofrohn/d3-celestial/issues/141) (ES modules),
+[#134](https://github.com/ofrohn/d3-celestial/issues/134) (`d3 is not defined`),
+[#115](https://github.com/ofrohn/d3-celestial/issues/115) (webpack),
+[#86](https://github.com/ofrohn/d3-celestial/issues/86) (React) and
+[#81](https://github.com/ofrohn/d3-celestial/issues/81) (Node).
+
+One file instead of three, and smaller than the original despite a much newer D3:
+
+| | files | minified |
+|---|---:|---:|
+| upstream (d3 + plugin + celestial) | 3 | 316 KB |
+| celestial-chart | **1** | **295 KB** |
+
+**Several maps on one page.** Upstream kept global state, so a page could hold
+one map ([#96](https://github.com/ofrohn/d3-celestial/issues/96),
+[#131](https://github.com/ofrohn/d3-celestial/issues/131)). Each instance now
+owns its state — including its own settings form:
+
+```js
+import { SkyMap } from "celestial-chart";
+
+const a = new SkyMap({ container: "map-a", projection: "orthographic" }, { standalone: true });
+const b = new SkyMap({ container: "map-b", projection: "mollweide" },   { standalone: true });
+```
+
+**TypeScript types ship with the package.** Projection and coordinate-system
+names are union types, so the editor offers all 69.
+
+**Astronomical fixes.**
+
+| | |
+|---|---|
+| [#148](https://github.com/ofrohn/d3-celestial/issues/148) | `horizontal.inverse()` lost the sign: **half** the sky above the horizon came back wrong, by up to 171°. |
+| [#130](https://github.com/ofrohn/d3-celestial/issues/130) | The phase computation was fine; two other things were not. `moon.js` added ecliptic perturbations directly to right ascension — a **1.5° error**, three lunar diameters (Meeus 13.a). And the terminator ellipse used a factor of 1.6 instead of 2, so a **full moon was drawn gibbous**. |
+| [#157](https://github.com/ofrohn/d3-celestial/issues/157) | The guard written for the 180° turn was unreachable (`Round(d,2)` never exceeds 3.14), so antipodal centre changes went through a degenerate great-circle interpolation — measured error up to 139°. |
+
+Plus, found while testing: every star rendered red after the D3 upgrade
+(`scaleQuantize` no longer accepts a descending domain); window resizing reset
+the user's zoom; the settings form was appended again on every `display()` call;
+`Celestial.ha()` returned hour angles outside any sane range; and the map failed
+to render at all when given neither a container element nor a width.
+
+## Time zones, and the key that is not here
+
+The settings form shows the observer's local time, which means turning a
+position into a UTC offset. A browser cannot do that for an arbitrary point on
+Earth — only for the viewer's own zone — so it takes an outside source.
+
+Upstream shipped the author's TimeZoneDB account id as a default, with
+`settimezone: true` also being a default. Every page embedding the library
+therefore sent its visitors' coordinates to a third party, unasked, on a quota
+shared with every other d3-celestial site — and over plain HTTP whenever the
+page itself was served over HTTP.
+
+**This fork ships no key and no endpoint.** With nothing configured, no request
+is made and the offset is estimated from longitude (15° per hour) — the fallback
+the code always had for failed lookups. Accurate enough for most places, wrong
+by up to an hour or two where zones follow politics rather than meridians.
+
+To get exact offsets, configure one of these:
+
+```js
+// Your own service — nothing leaves your infrastructure.
+Celestial.display({
+  timezoneResolver: (lat, lon, when) =>
+    fetch(`https://example.org/timezone?lat=${lat}&lon=${lon}&t=${when}`)
+      .then(r => r.json())
+      .then(j => j.offsetMinutes)
+});
+
+// Or the upstream route, with a key of your own.
+Celestial.display({ timezoneid: "YOUR_OWN_TIMEZONEDB_KEY" });
+```
+
+`timezoneResolver` wins over `timezoneid`; if it rejects, the longitude estimate
+takes over. A key in a client-side bundle is readable by anyone who loads the
+page, so treat `timezoneid` as public, and prefer a resolver you control.
+
+## Backwards compatibility
+
+`Celestial.display(config)` behaves as before, including how successive calls
+accumulate settings. It now also returns the instance it created.
+
+Behaviour that intentionally differs — all of them bug fixes:
+
+- Moon right ascension and declination move by up to 1.5°; the terminator is drawn wider.
+- `horizontal.inverse()` returns the correct hemisphere.
+- `Celestial.ha()` returns `[0, 360)`.
+- SVG export clips paths to the output size (mercator produced `Infinity` coordinates, which browsers discard).
+- `Trig.normalize` / `normalize0` normalise inputs below −2π correctly.
+
+## How it is verified
+
+Projection is a deterministic function — `(RA, Dec, projection, rotation) → (x, y)` —
+so it can be pinned. `harness/` holds the output of the **pinned upstream v3 build**
+and compares the fork against it:
+
+```
+67 projections × 4 rotations × 413 sky points = 110 684 measured points
+maximum difference: 0.000 px
+```
+
+Bit-identical, including the clipping state of every point. The harness checks
+itself too: it fails if two projections — or two rotations — produce the same
+output, because a net that measures nothing passes everything.
+
+```bash
+npm run verify    # build + 71 unit tests + types + 28 browser assertions, ~2 min
+```
+
+The browser run regenerates both references, compares them, captures 12 screenshots
+with a pixel diff, and drives the real UI (zoom, drag-rotate, projection switching,
+forms, SVG export, two independent maps). It runs in CI on every push.
+
+## Trying it locally
+
+The data files are not in the npm package (they are large and they are the
+upstream project's catalogues), so the demos load them from `harness/data/`.
+They need a real HTTP server — in D3 v7 `d3.json` uses `fetch`, which the
+browser refuses on `file://`.
+
+```bash
+npm run serve       # then open http://127.0.0.1:8877/demo/full.html
+```
+
+| page | what it shows |
+|---|---|
+| [`demo/full.html`](demo/full.html) | the whole interface: settings form, controls, location, SVG export |
+| [`demo/module.html`](demo/module.html) | the same as an ES module import |
+| [`demo/two-maps.html`](demo/two-maps.html) | two independent maps on one page |
+| [`demo/two-forms.html`](demo/two-forms.html) | two maps, each with its own settings form |
+
+The landing page behind the live demo lives in its own repository,
+[celestial-demo](https://github.com/Fekete85/celestial-demo) — it consumes this
+package as a dependency, so it is also a standing check that installing and
+using the published library actually works.
+
+## Documentation
+
+The full configuration is documented in the
+[upstream readme](https://github.com/ofrohn/d3-celestial#configuration) — the
+option names are unchanged. Type definitions in `types/celestial.d.ts` list them
+all, and a test keeps them from drifting from the code.
+
+The migration itself is written up in [`docs/`](docs/) — what was measured,
+what broke, and why.
+
+## License
+
+BSD 3-Clause, inherited from d3-celestial. See [`LICENSE`](LICENSE) and
+[`NOTICE.md`](NOTICE.md).
+
+This project is not affiliated with, nor endorsed by, Olaf Frohn or the D3 project.