spacemap 0.1.4 → 0.1.6

package/README.md

@@ -44,7 +44,7 @@ your page:
 ```html
 <div id="map" style="height: 500px"></div>
 <script type="module">
-	import { createMap } from 'https://cdn.jsdelivr.net/npm/spacemap@0.1.4/dist/spacemap.js';
+	import { createMap } from 'https://cdn.jsdelivr.net/npm/spacemap@0.1.6/dist/spacemap.js';
 	const map = await createMap({ container: '#map' });
 </script>
 ```
@@ -166,6 +166,24 @@ anchor there is on the lit side even on a body whose spin is not measured. It
 is null as well until the map has read how the body spins, which it does once
 the camera is on the body or its system.
 
+The same three measures are functions that need no map, for a page that has
+none or that cannot wait for one to reach a date. They take the date and
+resolve when the export has answered for it:
+
+```js
+import { distanceKm, offsetKm, subsolarPoint } from 'spacemap';
+
+const landing = new Date('1971-07-30T22:16:00Z');
+await distanceKm({ body: 'naif-301' }, { body: 'naif-499' }, landing);
+await offsetKm({ body: 'naif-301' }, { body: 'naif-499' }, landing);
+await subsolarPoint('naif-301', landing);
+```
+
+Null means nowhere at that date and never not loaded yet. They place planets,
+moons and small bodies as the map does. Spacecraft are not placed, and a
+satellite of Earth only near the present: those need the map. A failed
+download rejects.
+
 ### Drawing on it
 
 Everything you draw is put somewhere by an **anchor**, and the anchor is what
@@ -235,6 +253,10 @@ 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.
 
+A line, in space or on a surface, takes `dash` as the flat map's does: `'4 3'`
+is four pixels drawn and three left out, counted on screen like the width, so
+the dashes read the same from any distance.
+
 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
@@ -466,6 +488,22 @@ flat.isLayerVisible('clouds');
 flat.on('layerschange', (layers) => redraw(layers));
 ```
 
+### Bodies kept in sight
+
+The map decides what to name by how far the camera is: a planet's halo and
+orbit drop out once its whole orbit is a few pixels across, and a name gives way
+to a bigger neighbour's. `setPinnedBodies` takes that decision for the bodies a
+page is about:
+
+```js
+map.setPinnedBodies(['naif-499', 'spkid-20000433']); // Mars and Eros, from anywhere
+map.setPinnedBodies([]); // back to the map's own judgement
+```
+
+A pinned body keeps its halo, name and orbit from however far, and through a
+hidden layer. A moon is the exception: it is only drawn inside the system the
+camera is in, so pin its planet to mark it from outside.
+
 ## The flat map
 
 One body's surface, drawn flat, with layers you can switch and drawings of your