spacemap 0.1.21 → 0.1.24

package/index.d.ts

@@ -4,6 +4,18 @@ export declare type Anchor = InertialAnchor | SurfaceAnchor;
 
 export declare type ArrowKey = 'previous' | 'next';
 
+/**
+ * A body drawn as a sphere wears an artist's impression, not a picture of it.
+ * Sent again when the body it speaks of changes, and dismissed once no such
+ * sphere is in view.
+ */
+export declare interface ArtistImpressionNotice {
+    topic: 'artist-impression';
+    /** The body: the focused one when it wears an impression, else the
+     *  nearest that does. */
+    id: string;
+}
+
 /** Boot-time benchmark result (see perf/atmosphere-calibration.ts). */
 declare interface AtmosphereCalibration {
     /** GPU + resolution identity the run is valid for — a mismatch re-calibrates. */
@@ -95,6 +107,18 @@ export declare type BodyType = 'barycenter' | 'lagrange-point' | 'star' | 'plane
  *  the edges are walked and left for {@link pathFor} to fill in. */
 export declare function boxRing(latMin: number, latMax: number, lonMin: number, lonSpan: number): LonLat[];
 
+/**
+ * How the view is turned off looking straight down at the place, in degrees.
+ * Close to a surface only: from half a radius up the turn the map allows
+ * shrinks, and from one radius up the view is level.
+ */
+export declare interface CameraAngles {
+    /** Off the vertical toward the horizon: 0 looks straight down. */
+    pitch?: number;
+    /** Clockwise from the north the map keeps up. */
+    bearing?: number;
+}
+
 /** A suspension of the map's own camera control, for as long as it is held. */
 export declare interface CameraHold {
     /** Put the camera at `pose` from the next frame on. Call it from the map's
@@ -155,7 +179,9 @@ export declare interface CameraPose {
 
 /** The camera as it stands. `body` is what it orbits, which is also what the
  *  map draws in most detail. */
-export declare interface CameraState {
+export declare interface CameraState extends Required<CameraAngles> {
+    /** What `lat`, `lon` and `distanceKm` are measured from: the focused body,
+     *  or the one a landed probe in focus stands on. */
     body: string;
     lat: number;
     lon: number;
@@ -165,7 +191,7 @@ export declare interface CameraState {
 /** Somewhere to move the camera to. What is left out is left as it is. */
 export declare interface CameraTarget extends CameraOptions {
     /** A feature on `body` to look at, rather than the body as a whole. Its
-     *  size frames the view, so `distanceKm` is not needed. */
+     *  size frames the view: `lat`, `lon` and `distanceKm` are not read. */
     feature?: FeatureRef;
 }
 
@@ -292,6 +318,8 @@ export declare interface CoreMessages {
     attribution_imagery: () => string;
     attribution_stars: () => string;
     attribution_constellations: () => string;
+    attribution_galaxy: () => string;
+    attribution_galaxy_model: () => string;
     credits_see_all: () => string;
     layer_surface: () => string;
     layer_clouds: () => string;
@@ -316,9 +344,10 @@ export declare interface CoreMessages {
 }
 
 /**
- * Conditions the scene reports while it runs: the clock has left the data, or
- * it stopped at a probe's data wall. Raw dates and ids, never sentences — the
- * page around the map words them and decides how they are shown.
+ * Conditions the scene reports while it runs: the clock has left the data, it
+ * stopped at a probe's data wall, or a sphere in view wears an artist's
+ * impression. A notice holds raw dates and ids, not sentences. The page
+ * around the map words them and decides how to show them.
  */
 /** A coverage edge the clock has crossed, and where it lies. */
 export declare interface CoverageEdge {
@@ -414,6 +443,7 @@ export declare interface FeatureRef {
     /** Planetographic degrees, IAU convention. */
     lat: number;
     lon: number;
+    /** IAU diameter in metres; 0 when it gives none. */
     diameterM: number;
 }
 
@@ -903,7 +933,7 @@ export declare interface FocusChange {
     body: Body_2 | undefined;
     /** The first settle after boot. */
     initial: boolean;
-    /** The camera orbits a surface feature; `body` is its host. */
+    /** The camera moved onto a surface feature of `body`. */
     feature: boolean;
 }
 
@@ -1032,7 +1062,7 @@ export declare function jdToDate(jd: number): Date;
 
 /** The same, for a move that does not animate: framing a body against another
  *  one only makes sense as a placement, never as a flight. */
-export declare interface JumpTarget extends CameraTarget {
+export declare interface JumpTarget extends CameraTarget, CameraAngles {
     /** Put this other body — the Sun, usually — behind the one being framed. */
     facing?: string;
     /** How far above the ecliptic to look from, in degrees. */
@@ -1268,7 +1298,7 @@ export declare interface Neighbours {
  *  the same spot. */
 export declare function neighboursOf(entries: PanoramaEntry[], current: PanoramaEntry, radiusKm: number): Neighbours;
 
-export declare type Notice = OutOfRangeNotice | CoveragePauseNotice;
+export declare type Notice = OutOfRangeNotice | CoveragePauseNotice | ArtistImpressionNotice;
 
 export declare type NoticeTopic = Notice['topic'];
 
@@ -1328,9 +1358,12 @@ export declare interface OutOfRangeNotice {
     } | {
         side: 'gap';
     } | null;
-    majorBodies: CoverageEdge | {
-        side: 'outside';
-    } | null;
+    /** The edge of the ephemeris itself, once the date is past it: no planet or
+     *  moon has data. */
+    majorBodies: CoverageEdge | null;
+    /** One entry per edge crossed, by date. Bodies on the side of a crossed
+     *  `majorBodies` edge are left out: that edge already says why. */
+    bodies: UncoveredBodies[];
 }
 
 /** The sky of a page. It leaves the reader's own layer settings alone. */
@@ -1414,7 +1447,14 @@ export declare interface PanoramaEntry {
     /** Image azimuth where the observed span begins, with its width; absent
      *  when the archive label carried no coverage geometry. */
     azimuth_start_deg?: number;
+    /** Width of the mosaic's frame, which can hold far less than it spans:
+     *  read `horizon_deg` for what the sphere shows. */
     hfov_deg?: number;
+    /** Degrees of azimuth where the sphere's pixels hold the horizon. Zero for
+     *  a ring of ground. A mosaic with no real gap in its horizon reads 340 or
+     *  more. Tilt is taken out on most of a turn only, so a tilted arc reads
+     *  short. */
+    horizon_deg?: number;
     /** Solid-angle share of the sphere the mosaic covers, percent. */
     sphere_percent?: number;
     color?: string;
@@ -1831,6 +1871,9 @@ export declare interface SceneSettings {
     highAmbient: boolean;
     realisticLighting: boolean;
     overexposeRings: boolean;
+    /** The glow reads the grid's coarse copies where a sample is wider than a
+     *  cell. Debug only. */
+    glowCoarseReads?: boolean;
     showShapeMesh: boolean;
     showSurfaceTexture: boolean;
     showDisplacement: boolean;
@@ -1953,6 +1996,10 @@ export declare class SpaceMap {
     /* Excluded from this release type: webglError */
     /* Excluded from this release type: contextLost */
     /* Excluded from this release type: focusedBody */
+    /* Excluded from this release type: cameraBody */
+    /** A move onto a surface feature is under way: the focus it hands the
+     *  host is that move's. */
+    private movingToFeature;
     /* Excluded from this release type: attribution */
     /** Objects of the host's own: a spacecraft, a station, a body the export
      *  has never heard of. */
@@ -1989,6 +2036,9 @@ export declare class SpaceMap {
     private pendingFocusId;
     /** The first load, started once. */
     private opening;
+    /** The camera is on the opening view; the map shows once it stops moving. */
+    private openingPlaced;
+    private openingShown;
     /** Counts navigations: a later one supersedes an earlier one still on its way. */
     private navigation;
     /** Retires the host's hold on the camera. Kept so that a second hold, or
@@ -2006,7 +2056,8 @@ export declare class SpaceMap {
     /** What the map knows about an object it has loaded; undefined for one it
      *  has not, which for a small body may simply mean not yet. */
     getBody(id: string): Body_2 | undefined;
-    /** The object the camera orbits. A surface feature reports its host body. */
+    /** The object in view. For a landed probe this is the probe, and the
+     *  camera orbits the body it stands on. */
     getFocusedBody(): Body_2 | undefined;
     /** Ids of the objects orbiting `id` that this map has loaded. Loading is
      *  driven by focus and by the clock, so the list grows as the reader moves. */
@@ -2045,6 +2096,8 @@ export declare class SpaceMap {
     /* Excluded from this release type: open */
     private openOnce;
     /* Excluded from this release type: applyInitialView */
+    /* Excluded from this release type: showOpeningView */
+    private revealWhenSettled;
     /* Excluded from this release type: mount */
     /** Hang a control in one of the map's corners; top-right unless the control
      *  or the caller names another. Adding the same control twice does nothing. */
@@ -2077,9 +2130,10 @@ export declare class SpaceMap {
     private placedAncestor;
     /** The renderer, once the map draws. Null when it never will. */
     private rendering;
-    /** Turn to a feature on the body already framed, without travelling to it —
-     *  the move a click on its label makes. Resolves when the camera comes
-     *  round. */
+    /** Turn to a feature on the body already framed, without travelling to it.
+     *  This is the move a click on its label makes. On another body the camera
+     *  flies to the feature, as {@link SpaceMap.flyTo} does. Resolves when the
+     *  camera comes round. */
     panTo(target: FeatureTarget): Promise<void>;
     /**
      * Put the camera at a place at once, with no flight. Use it to restore a
@@ -2243,7 +2297,7 @@ export declare interface SpaceMapOptions {
     date?: Date;
     live?: boolean;
     /** Where the map opens. */
-    view?: CameraOptions;
+    view?: CameraOptions & CameraAngles;
     /** Whether the reader may move the map at all. True unless it is said
      *  otherwise; false switches every gesture off. */
     interactive?: boolean;
@@ -2524,6 +2578,16 @@ export declare interface TrajectorySample {
     km: OffsetKm;
 }
 
+/** Planets and moons past their own kernels, which end before the ephemeris
+ *  does. `outside`: the date is in a hole between two of their spans. */
+export declare type UncoveredBodies = (CoverageEdge | {
+    side: 'outside';
+}) & {
+    ids: string[];
+    /** Their names, in the order of `ids`. */
+    names: string[];
+};
+
 export declare interface VectorLayer {
     readonly kind: 'vector';
     id: string;