spacemap 0.1.0

package/LICENSE

@@ -0,0 +1,373 @@
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+*                                                                      *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
+*                                                                      *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or  *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
+*                                                                      *
+************************************************************************
+
+************************************************************************
+*                                                                      *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
+*                                                                      *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
+*                                                                      *
+************************************************************************
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.

package/README.md

@@ -0,0 +1,590 @@
+# spacemap
+
+The map of the Solar System from [spacemap.co](https://spacemap.co), on your
+website! There are flat maps too, and 360 panoramas from the surface.
+
+Distances are kilometres and angles are degrees throughout. Objects are named
+by their export id — `naif-399` for Earth, `spkid-20000004` for Vesta,
+`norad_satcat-25544` for the ISS.
+
+Licensed MPL-2.0. No key, no quota for now. The credit line the map draws is
+not removable: the imagery it shows requires attribution. Some body textures
+are licensed for non-commercial use only.
+
+## Getting it
+
+As one script that carries everything it needs — `spacemap.js`, an ES module,
+next to `spacemap.iife.js` for pages that want a global instead:
+
+```html
+<div id="map" style="height: 500px"></div>
+<script type="module">
+	import { createMap } from './spacemap.js';
+	const map = await createMap({ container: '#map' });
+</script>
+```
+
+Or from npm, where three.js is yours to provide:
+
+```sh
+npm install spacemap three
+```
+
+```js
+import { createMap } from 'spacemap';
+```
+
+## The Solar System map
+
+`createMap` resolves once the map is worth looking at: the opening body placed,
+and the one-off quality benchmark done. Small bodies go on streaming in behind
+the map it hands back.
+
+```js
+const map = await createMap({
+	container: '#map',
+	view: { body: 'naif-499', lat: 20, lon: 0, distanceKm: 40000 },
+	date: new Date('2030-01-01'),
+	locale: 'fr'
+});
+```
+
+### Moving the camera
+
+```js
+await map.flyTo({ body: 'naif-599' }); // fly, framing it for you
+map.jumpTo({ body: 'naif-599', distanceKm: 2e6 }); // no flight
+map.jumpTo({ body: 'naif-399', facing: 'naif-10', elevationDeg: 30 });
+map.getCamera(); // { body, lat, lon, distanceKm }
+```
+
+`flyTo` resolves when the flight lands. What a target leaves out the map frames
+itself, so `{ body }` alone is the ordinary way to move.
+
+Clicking a named surface feature reports it; `panTo` turns to one without
+travelling:
+
+```js
+map.on('featureselect', (feature) => map.panTo({ body: feature.bodyId, feature }));
+```
+
+To place the camera yourself, frame by frame, take it off the map's own
+controls:
+
+```js
+const hold = map.holdCamera();
+map.on('frame', () =>
+	hold.set({ position: { body: 'naif-499', offsetKm: [x, y, z] }, target: { body: 'naif-499' } })
+);
+hold.release();
+```
+
+### Events
+
+`on` returns a function that stops listening; `once` and `off` do what they say.
+
+| event                             | when                                               |
+| --------------------------------- | -------------------------------------------------- |
+| `focuschange`                     | the camera settled on another object               |
+| `camera`                          | the camera came to rest                            |
+| `featureselect`                   | a nomenclature label was clicked                   |
+| `clock`                           | the date, play state, rate or direction changed    |
+| `loading` / `progress`            | data is coming in                                  |
+| `error`                           | the data could not be loaded                       |
+| `notice` / `noticedismiss`        | a condition worth telling the reader about         |
+| `layerschange`                    | a layer was switched                               |
+| `frame`                           | once per drawn frame                               |
+| `contextlost` / `contextrestored` | the GPU context dropped and came back              |
+| `datastale`                       | the export was republished while this map was open |
+| `userpromoted`                    | how many reader-promoted bodies can be cleared     |
+
+### The clock
+
+`map.clock` is the simulation clock. It starts on wall-clock time unless the
+map was opened on a date.
+
+```js
+map.clock.pause();
+map.clock.setTimeScale(86400); // a day a second
+map.clock.toggleDirection();
+map.clock.setDate(new Date('2035-06-01'));
+map.clock.now();
+```
+
+### Drawing on it
+
+Everything you draw is put somewhere by an **anchor**, and the anchor is what
+keeps it there as the map moves under it. There are two kinds. A surface anchor
+is a longitude, a latitude and a height on a body, and turns with the body as
+it spins; an inertial anchor is a body and an offset in kilometres on ecliptic
+axes, which travels with the body but does not turn. Either way the drawing
+follows what it is drawn on, over any distance and any date.
+
+Six things sit **in space**, measured from an anchor in kilometres:
+
+```js
+// Your own element, pinned to a place.
+const marker = map.addMarker({
+	anchor: { body: 'naif-499', latitude: 18.4, longitude: 77.5, altitudeKm: 0 },
+	element: pin,
+	align: [0.5, 1],
+	occlude: true
+});
+
+// A line. Points are kilometres from the anchor, on ecliptic axes.
+map.addPolyline({ anchor: { body: 'naif-499' }, points, color: '#66aaff', closed: true });
+
+// An area, filled in its own colour unless you name another.
+map.addPolygon({ anchor: { body: 'naif-499' }, points, color: '#ffcc55', fillOpacity: 0.3 });
+
+// A circle round a place, in a plane you turn where you like. It is a ring
+// rather than a disc unless you give it a fill: what it is drawn round is
+// usually the point.
+const ring = map.addCircle({
+	anchor: { body: 'naif-499' },
+	radiusKm: 20000,
+	normal: [0.4, 0, 1],
+	widthPx: 3
+});
+ring.setRadiusKm(30000);
+
+// Text at a place, without an element of your own to build and style.
+map.addLabel({ anchor: { body: 'naif-499', latitude: 18.4, longitude: 77.5 }, text: 'Elysium' });
+
+// A picture at a place. It holds its size on screen wherever the camera goes.
+map.addIcon({ anchor: { body: 'naif-499' }, url: badge, widthPx: 28, occlude: true });
+```
+
+Three more are drawn **on a body**, following its curve and turning with it.
+These take longitude and latitude rather than kilometres — the same places the
+flat map's shapes take, so one list of points draws on both maps:
+
+```js
+map.addSurfacePolyline({ body: 'naif-499', points: track, interpolate: 'geodesic' });
+map.addSurfacePolygon({ body: 'naif-499', points: quadrangle, color: '#88ddff' });
+map.addSurfaceCircle({ body: 'naif-499', center: { lon: 77.5, lat: 18.4 }, radiusKm: 800 });
+```
+
+`boxRing`, `smallCircle` and `graticule`, the flat map's helpers, make point
+lists these take; `circlePoints` does the same for a circle in space.
+
+Every drawing answers `remove()` and `setVisible()`, a shape answers
+`setAnchor()` and `setPoints()`, and `map.clearDrawings()` takes them all away
+at once, leaving the map itself alone.
+
+`ShapeStyle` is shared by the shapes: `color`, `widthPx` in screen pixels,
+`opacity`, `fill` and `fillOpacity`. A width of zero leaves the outline out, for
+an area drawn as a fill alone. The flat map says the same things with the same
+words — its version is `FlatShapeStyle`, named apart because a page can hold
+both maps at once — so a drawing described once can be handed to either.
+
+Two rules fall out of the scene rather than out of taste. Widths are pixels
+because the map spans metres to astronomical units, and a line a kilometre wide
+is a wall from low orbit and nothing at all from the next planet out. And a body
+hides what is behind it: a shape in space is drawn with the orbit trails and is
+cut off at a body's edge exactly as they are, and a shape on a surface stops at
+the limb. Markers, labels and icons are HTML rather than geometry and would
+otherwise show through the body they sit on, so they take `occlude` to be hidden
+when the place they mark turns away.
+
+A shape on a surface floats a little above it by default — half a percent of the
+body's radius, which is 17 km at Mars. That clears the relief the map draws, so
+the shape reads as lying on the ground rather than sinking into it, and ground
+higher than that still comes through, as it should. Give it an `altitudeKm` of
+its own for a track flown rather than walked.
+
+Labels and icons are elements, so listen to them directly through their
+`element`; they take pointer events only once you pass `interactive: true`,
+since the camera is dragged through the layer they sit in. Shapes drawn as
+geometry are not clickable.
+
+### Objects of your own
+
+A spacecraft, a station, a body the export has never heard of: your own thing on
+the map, moving under its own trajectory and drawn with your own model.
+
+```js
+const sat = map.objects.add({
+	id: 'my-sat',
+	name: 'My Satellite',
+	position: tle(line1, line2),
+	model: { object3d: myMesh, scaleM: 12, minPx: 24 },
+	label: true
+});
+
+map.objects.get('my-sat');
+map.objects.all();
+sat.remove();
+map.objects.clear();
+```
+
+**The map ships no model loader.** `object3d` is a three.js `Object3D` you have
+already built or loaded — a mesh of your own, or a GLB you put through your own
+`GLTFLoader`. That keeps a loader, its Draco and KTX2 decoders and their WASM out
+of a bundle every reader downloads, for a feature most embeds never use, and it
+leaves you the loader you already have rather than one this package chose for
+you. From npm, three.js is a peer dependency: your copy is the map's copy, and
+there is nothing to reconcile. From the CDN script the map's three.js is bundled
+inside it and private, so a page that builds a model loads its own copy; that
+works, since all the map does with the object is put it in a scene and place it,
+but the package is the way to do this without two copies of three.js on the page.
+
+`scaleM` is how big the model is drawn, in metres across its longest dimension
+— the real size, arrays and booms deployed. Left out, it is drawn at the size it
+was built. A twelve-metre satellite is nothing at all from a planetary view, so
+`minPx` gives it a floor in pixels: below that it is drawn bigger than life,
+above it, true to size.
+
+Four constructors say where an object is, and any of them can be used anywhere
+an anchor can — a marker, a drawing, a camera pose:
+
+```js
+import { elements, fixed, kmToAu, samples, tle } from 'spacemap';
+
+// Parked: on the ground, or at an offset from a body's centre.
+fixed({ body: 'naif-499', latitude: 18.4, longitude: 77.5, altitudeKm: 0 });
+fixed({ body: 'naif-499', offsetKm: [0, 20000, 0] });
+
+// A list of states, read between.
+samples({ body: 'naif-399', samples: [{ jd, km: [x, y, z] }, ...] });
+
+// A Keplerian orbit, propagated from its epoch.
+elements({
+	body: 'naif-399',
+	elements: {
+		a: kmToAu(6878), // semi-major axis, in AU
+		e: 0.001,
+		i: 51.6, // inclination, degrees
+		om: 247, // longitude of the ascending node
+		w: 130, // argument of pericentre
+		ma: 325, // mean anomaly at the epoch
+		n: 5658, // mean motion, degrees a day
+		epoch: 2460584.5, // Julian date
+		equatorial: true // referenced to Earth's equator, not the ecliptic
+	}
+});
+
+// Two lines of a NORAD element set, propagated with SGP4 round Earth.
+tle(line1, line2);
+```
+
+Offsets and states are kilometres on ecliptic J2000 axes, measured from the body
+they name — the Sun when they name none. Orbital elements are the export's own,
+which means the semi-major axis is in astronomical units: the one distance on
+this surface that is not in kilometres, because that is how elements are quoted
+everywhere the map reads them. `kmToAu` is there for that line alone. Set
+`equatorial` when the angles are referenced to Earth's equator, as a TLE's are.
+
+Between two states the path is a cubic through both of them, tangent to the
+slope their neighbours imply, which is the curve a coasting object actually
+follows — a straight line between states would cut every corner of an orbit.
+States may be given in any order and at any spacing; they are read at their own
+dates. **Outside the dates the states cover, the object is not drawn.** A list
+that has run out is not evidence of where anything is, and the map would rather
+show nothing than park a probe at its last known place. A TLE is the same the
+other way: SGP4 propagates it as far as you ask, accuracy falling away from the
+element set's epoch, and a date it cannot be propagated to — a decayed satellite
+— leaves the object undrawn. Keplerian elements are defined at every date, so an
+object on them is always somewhere.
+
+What an object takes part in, and what it does not, is worth saying plainly. It
+is drawn in the scene beside the bodies, so **a body in front of it hides it and
+it hides what is behind it**, and it holds its place as the map's origin moves
+from body to body. `label: true` writes its name beside it in the map's own
+label style, `occludeLabel` hiding that while the object is round the far side.
+
+It is **not** a body. `getBody` does not know it, `flyTo` cannot reach it, a
+click does not select it — the map resolves a click through a pass over its own
+objects, which a host object has no id in — and it draws no orbit trail of its
+own. Those all read the published catalogue, and an object of yours is not in
+it. What you get instead is its position, at any date you like, which is enough
+to do the rest yourself:
+
+```js
+sat.positionKm(map.clock.jd); // [x, y, z] km from the body it is measured from
+
+// Following it: its position is an anchor, so a held camera takes it as a
+// target, and a standoff behind it as its own place.
+const hold = map.holdCamera();
+map.on('frame', ({ jd }) => {
+	const km = sat.positionKm(jd);
+	if (!km) return;
+	hold.set({
+		position: { body: sat.position.body, offsetKm: [km[0] + 500, km[1], km[2] + 200] },
+		target: sat.position
+	});
+});
+
+// A trail: sample the trajectory and hand the points to a polyline.
+const points = [];
+for (let i = -60; i <= 0; i++) points.push(sat.positionKm(map.clock.jd + i / 1440));
+map.addPolyline({ anchor: { body: 'naif-399' }, points: points.filter(Boolean), fade: true });
+```
+
+`clearDrawings()` leaves objects alone — they are not drawings — and
+`map.objects.clear()` takes only them.
+
+### Its own imagery on a body
+
+A body the map already knows can wear your pictures instead of the export's:
+
+```js
+map.setBodyAppearance('naif-499', { surface: url, night: url, clouds: url });
+map.setBodyAppearance('naif-499', {}); // back to the map's own
+```
+
+Each is a URL the browser can load — an equirectangular map, east to the right,
+longitude 0 in the middle, which is how every body's imagery is drawn. `night`
+is the lights on the unlit side, `clouds` a layer over the surface whose alpha
+is the cover; a body with neither of its own gets one built for it. The set is
+replaced whole, so what a call leaves out goes back to the map's own picture.
+
+**A picture given here is what the body wears at every distance.** The map picks
+its own imagery by how much of the screen the body fills, stepping up a tier as
+you approach; there is nothing to pick once a host has said what the body looks
+like, so that pass stops fetching for it and, every frame, checks that what is on
+the body is still yours — a system reload, a defocus or a lost GPU context puts
+it straight back.
+
+The flat map needs nothing of its own for this: its pictures are layers already,
+and `addRasterLayer` puts one of yours over or in place of them.
+
+### Layers
+
+What the map draws is a set of layers, each switched by id — the kinds of
+object first, then the chrome drawn around them:
+
+`planets`, `dwarfPlanets`, `moons`, `asteroids`, `comets`, `spacecraft`,
+`satellites` (the ones round Earth), `debris`, `orbits`, `labels` (the names of
+objects), `nomenclature` (the names of places on them) and `stars` (the sky
+behind everything).
+
+```js
+const map = await createMap({
+	container: '#map',
+	layers: { asteroids: false, comets: false, debris: false }
+});
+
+map.setLayerVisible('moons', false);
+map.isLayerVisible('moons'); // false
+map.getLayers(); // every id, so a switcher need not spell them out
+```
+
+**A layer switched off in the options is never downloaded; a layer switched off
+later is only hidden.** The two are different asks and the map answers them
+differently on purpose. `layers` at open time is what an embed about Mars
+wants: the belts, the comets and the thirty thousand Earth satellites are not
+fetched at all, and the map opens on a fraction of the data. `setLayerVisible`
+is what a reader's checkbox wants: it lands on the next frame and never asks
+the network for anything, whichever way it is switched.
+
+The corollary is worth saying plainly: **switching on a layer that was off at
+open time shows nothing**, because there is nothing to show. Switch off in the
+options what the map is not for; switch at runtime what the reader is to have a
+say in.
+
+Two groups are hidden rather than skipped. `planets` and `dwarfPlanets` share
+one file with the Sun, so leaving them out saves no download. `satellites` and
+`debris` share one file with each other, so the download is only skipped when
+neither is wanted.
+
+The asteroids are one layer, not five. The export files them by orbit class,
+and those classes do not divide cleanly into the dynamical families
+`Body.orbitClass` reports — two of them belong to no family at all — so a
+family switch would leave objects answering to nothing. Read `orbitClass` off a
+body to tell the families apart.
+
+Hiding is a drawing decision and nothing else. The Sun lights the scene
+whatever is off, `flyTo` reaches a hidden body, and `getBody` still knows it.
+
+The flat map has layers too, of its own: the pictures wrapped round a body and
+the lines drawn over them. Those depend on the body on screen and carry their
+own names, so it reads them out whole:
+
+```js
+flat.getLayers(); // ['surface', 'clouds', 'night', 'graticule', 'nomenclature']
+flat.layers; // the same, with a label, a kind and a credit each
+flat.setLayerVisible('clouds', false);
+flat.isLayerVisible('clouds');
+flat.on('layerschange', (layers) => redraw(layers));
+```
+
+## The flat map
+
+One body's surface, drawn flat, with layers you can switch and drawings of your
+own on top.
+
+```js
+const flat = await createFlatMap({
+	container: '#flat',
+	body: 'naif-399',
+	projection: 'orthographic',
+	centerLon: 10,
+	zoom: 2
+});
+
+flat.setLayerVisible('clouds', false);
+flat.setProjection('equirectangular');
+flat.addCircle({ at: { lon: 12.5, lat: 41.9 }, radiusDeg: 5, stroke: '#f80' });
+flat.on('click', (at) => at && console.log(at.lon, at.lat));
+```
+
+## Panoramas
+
+A rover's panorama from the inside, with arrows along its traverse. The
+three-dimensional part is all the SDK draws; the date, the place, a list to
+pick from or a map of the traverse are the page's to build.
+
+```js
+const view = await createPanorama({
+	container: '#panorama',
+	body: 'naif-499',
+	// A panorama's id, or its `time,lat,lon` key; the body's first when omitted.
+	at: 'curiosity-n_l000_0016_edr003cyltsm0078_drivem3'
+});
+
+view.getPanoramas(); // every panorama of the body, mission by mission in time order
+view.getNeighbours(); // the previous and next one on this traverse, with bearing and distance
+view.on('load', (entry) => console.log(entry.sol, entry.time, entry.lat, entry.lon));
+view.on('viewchange', ({ heading, pitch, fov }) => {});
+view.setView({ heading: 90 });
+await view.open(view.getPanoramas()[3]);
+await view.step('next');
+```
+
+Pressing an arrow opens the panorama it points at, unless `followArrows` is
+false: then only the `step` event fires, for a page that keeps the panorama in
+its own URL. The `arrows` event says where each arrow landed on screen, for a
+label beside it. `interactive: false` turns the drag, pinch, wheel and arrow
+keys off; `arrows: false` and `setArrowsVisible` hide the arrows.
+
+Limits keep the reader inside part of the sweep, or at one zoom. Headings run
+clockwise from the first to the second, so `[300, 60]` is the arc across
+north; a pair of equal values locks that axis.
+
+```js
+createPanorama({ container: '#panorama', body: 'naif-499', limits: { pitch: [-20, 20] } });
+view.setLimits({ heading: [300, 60], fov: [60, 60] }); // ±60° of north, no zoom
+view.setLimits({}); // free again
+```
+
+## Restricting the map
+
+Both maps take restrictions on what the reader may do. Each gesture is a
+handler of its own, the way Mapbox has them:
+
+```js
+map.scrollZoom.disable();
+map.scrollZoom.isEnabled(); // false
+map.dragRotate.enable();
+```
+
+The Solar System map has `dragRotate`, `scrollZoom`, `keyboard`, `bodySelect`
+and `featureSelect`; the flat map has `dragPan` and `scrollZoom`. They can be
+set as the map opens, either one at a time or all at once:
+
+```js
+createMap({ container: '#map', interactive: false }); // every gesture off
+createMap({ container: '#map', interactions: { scrollZoom: false } }); // one
+```
+
+`limits` says how far the reader may go. On the Solar System map that is a
+distance from the focused body, a band of it to look down from, and the objects
+a click may focus:
+
+```js
+const map = await createMap({
+	container: '#map',
+	limits: {
+		minDistanceKm: 8000,
+		maxDistanceKm: 400000,
+		minLat: -40,
+		maxLat: 40,
+		minLon: -60,
+		maxLon: 60,
+		bodies: ['naif-399', 'naif-301']
+	}
+});
+
+map.setLimits({ maxDistanceKm: 1e6 }); // replaced whole, not merged
+map.getLimits();
+```
+
+On the flat map it is a zoom range and a band the middle of the frame stays in:
+
+```js
+flat.setLimits({ minZoom: 2, maxZoom: 8, minLon: -30, maxLon: 30 });
+flat.getLimits();
+```
+
+**Limits gate reader input and nothing else.** `flyTo`, `jumpTo`, `panTo`,
+`setView` and a held camera go where they are told, outside the limits
+included; the reader's next gesture brings the map back inside. This is a
+deliberate departure from Mapbox, where `maxBounds` holds the map whatever
+moved it. Restrict what the reader may reach, and drive the map yourself to
+anywhere you like.
+
+A longitude band may run through the antimeridian: 170 to −170 is the twenty
+degrees across it. One edge alone leaves the other at the antimeridian.
+
+`setLimits` replaces the whole set, so `setLimits({})` lifts the restrictions
+again. Angles are degrees and distances kilometres, as everywhere else.
+
+### Cooperative gestures
+
+A map inside a page the reader scrolls past can hand the plain gestures back to
+the page:
+
+```js
+createMap({ container: '#map', cooperativeGestures: true });
+```
+
+The wheel then scrolls the page unless ctrl (⌘ on a Mac) is held, and one
+finger drags the page rather than the map — two fingers still move it. A hint
+says so whenever the plain gesture is tried; `messages` rewords it through
+`cooperative_wheel`, `cooperative_wheel_mac` and `cooperative_touch`. The
+handler is `map.cooperativeGestures`, on and off like any other.
+
+## Controls
+
+A control is anything that builds an element when it is added:
+
+```js
+map.addControl(
+	{
+		onAdd() {
+			const button = document.createElement('button');
+			button.textContent = 'Home';
+			button.onclick = () => map.flyTo({ body: 'naif-399' });
+			return button;
+		}
+	},
+	'top-left'
+);
+```
+
+Corners are `top-left`, `top-right`, `bottom-left` and `bottom-right`;
+top-right unless the control or the caller names another. `removeControl` takes
+one back off — except the credit line, which throws.
+
+The panorama view takes controls the same way. The credit line is the only control the SDK ships. Zoom buttons, a layer
+switcher or a clock are the page's to build, in its own look, from the calls
+this document describes: `flyTo` and `jumpTo`, `getLayers` and
+`setLayerVisible` with the `layerschange` event, and `map.clock` with the
+`clock` event.
+
+## Where the data comes from
+
+Both maps read the published export. `dataUrl` and `imagesUrl` point them
+somewhere else — your own mirror, or a local copy while you develop. They are
+page-wide: the last map created sets them, and data already fetched keeps the
+origin it came from.
+
+`locale` picks localized names; `messages` replaces the English wording the map
+renders itself, one key at a time.
+
+## Finishing with a map
+
+```js
+map.remove();
+```

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "spacemap",
+	"version": "0.1.0",
+	"description": "The map of the Solar System from spacemap.co, on your website!",
+	"keywords": [
+		"solar system",
+		"spacecraft",
+		"orbits",
+		"map",
+		"three.js"
+	],
+	"homepage": "https://spacemap.co",
+	"bugs": {
+		"url": "https://github.com/julie-dujardin/space-map/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/julie-dujardin/space-map.git",
+		"directory": "frontend"
+	},
+	"license": "MPL-2.0",
+	"author": "Julie Dujardin",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"default": "./index.js"
+		}
+	},
+	"main": "index.js",
+	"peerDependencies": {
+		"@types/three": "^0.183.0",
+		"three": "^0.183.0"
+	},
+	"peerDependenciesMeta": {
+		"@types/three": {
+			"optional": true
+		}
+	}
+}