@johnmorrisdotca/wakusei-planets 0.6.0 → 0.11.0

package/dist/portrait/model.d.ts

@@ -0,0 +1,297 @@
+import { type BodyId, type Look } from "../facts.ts";
+/** How the automatic layout arranges the bodies. */
+export type Arrange = "row" | "arc" | "grid" | "orbit";
+/** `true`: every size to scale. `readable`: sizes squeezed together so a small body can still be seen. */
+export type ScaleMode = "true" | "readable";
+export type Background = "black" | "stars" | "gradient" | "transparent";
+/**
+ * One body in the scene: which body, where it is and how big, how it is turned and how fast it turns by itself.
+ *
+ * @example
+ * ```ts
+ * import { addBody, defaultPortrait, type PortraitItem } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * const saturn: PortraitItem = addBody(defaultPortrait(), "saturn").items[0]!;
+ * console.log(saturn.body, saturn.turn);
+ * ```
+ */
+export interface Item {
+    body: BodyId;
+    x: number;
+    y: number;
+    /** The radius, in scene units. */
+    r: number;
+    /** The longitude at the middle of the disc, degrees east (with a date: turned this much from the real one). */
+    spin: number;
+    /** The pole's lean on the page, degrees; the body's own tilt when left out. */
+    tilt?: number;
+    /** How far the viewer looks over the pole, degrees; the usual for the body when left out. */
+    pitch?: number;
+    /** Degrees a second it turns by itself, eastward. */
+    turn: number;
+}
+/**
+ * A portrait scene: the bodies, back to front, and how they are arranged, sized, lit and drawn. Plain data: keep it, change it by making a new one, and `encodeScene` it for an address.
+ *
+ * @example
+ * ```ts
+ * import { addBody, defaultPortrait, type Portrait } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * const scene: Portrait = addBody(addBody(defaultPortrait(), "jupiter"), "io");
+ * console.log(scene.items.length, scene.layout, scene.scale);
+ * ```
+ */
+export interface Portrait {
+    /** Back to front. */
+    items: Item[];
+    /** `auto`: the layout places and sizes every body. `manual`: the positions and sizes below are used as they are. */
+    layout: "auto" | "manual";
+    arrange: Arrange;
+    scale: ScaleMode;
+    /** `auto`: a planet's moons that are in the scene go round it in orbit order. `manual`: each body is placed by itself. */
+    moons: "auto" | "manual";
+    look: Look;
+    bg: Background;
+    /** Width over height. */
+    aspect: number;
+    /** Where the Sun is: `az` clockwise from the top of the picture, `el` toward the viewer (0 along the page, 90 straight at it), degrees. */
+    light: {
+        az: number;
+        el: number;
+    };
+    labels: boolean;
+    orbits: boolean;
+    shadows: boolean;
+    /** The body as the Earth sees it on this date (ISO), or `undefined` for a portrait. */
+    date: string | undefined;
+    /** The view in a manual layout: the centre and the half-height, in scene units. An automatic layout always fits. */
+    camera: {
+        x: number;
+        y: number;
+        h: number;
+    };
+}
+/**
+ * A body of a scene as the layout puts it: its place and size now (stored, or worked out by an automatic layout), and how far its picture reaches past the disc.
+ *
+ * @example
+ * ```ts
+ * import { addBody, defaultPortrait, layoutPortrait, type PlacedItem } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * const placed: PlacedItem[] = layoutPortrait(addBody(defaultPortrait(), "saturn")).placed;
+ * console.log(placed[0]?.reach, placed[0]?.r);
+ * ```
+ */
+export interface Placed extends Item {
+    index: number;
+    /** How far the picture of the body reaches from its centre (rings, the Sun's glow), in scene units. */
+    reach: number;
+}
+/**
+ * What a layout works out for a scene: every body placed, and the camera that holds them (its centre and half-height, in the scene's units).
+ *
+ * @example
+ * ```ts
+ * import { addBody, defaultPortrait, layoutPortrait, type PortraitLayout } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * const layout: PortraitLayout = layoutPortrait(addBody(defaultPortrait(), "mars"));
+ * console.log(layout.camera.h);
+ * ```
+ */
+export interface Resolved {
+    placed: Placed[];
+    camera: {
+        x: number;
+        y: number;
+        h: number;
+    };
+}
+export declare const ASPECTS: readonly (readonly [string, number])[];
+export declare const MAX_ITEMS = 40;
+/** The Sun, then each planet and dwarf planet followed by its moons nearest first: the order a layout and a row of buttons use. */
+export declare const ORDER: readonly BodyId[];
+export declare const rankOf: (id: BodyId) => number;
+/**
+ * An empty scene with the usual settings: an automatic row, readable sizes, the stars behind, the Sun upper left.
+ *
+ * @returns A new scene with no bodies.
+ *
+ * @example
+ * ```ts
+ * import { defaultPortrait } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(defaultPortrait().bg);
+ * ```
+ */
+export declare function defaultPortrait(): Portrait;
+/** How far the picture of a body reaches past its disc, in its radii: Saturn's rings, the Sun's glow. */
+export declare const reachOf: (id: BodyId) => number;
+/** Raw sizes for the bodies, in any unit, in proportion: true to scale, or squeezed (a root of the radius) with the smallest lifted to a tenth of the largest so every body can be seen. */
+export declare function sizesFor(ids: readonly BodyId[], mode: ScaleMode): number[];
+/** The camera that holds every body with a margin: its centre and half-height. */
+export declare function fitCamera(placed: readonly Pick<Placed, "x" | "y" | "reach">[], aspect: number, margin?: number, labels?: boolean): {
+    x: number;
+    y: number;
+    h: number;
+};
+/**
+ * Where every body is and how big, and the camera that holds them. A manual scene gives what it stores. An automatic one works it out (a row, an arc or a grid, a planet's moons round it in orbit
+ * order) and fits the camera, so its units are the camera's half-height.
+ *
+ * @param scene - The scene.
+ * @returns Every body placed, back to front, and the camera.
+ *
+ * @example
+ * ```ts
+ * import { addBody, defaultPortrait, layoutPortrait } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * const { placed } = layoutPortrait(addBody(addBody(defaultPortrait(), "earth"), "moon"));
+ * console.log(placed.map((item) => `${item.body} ${item.x.toFixed(2)}`).join(", "));
+ * ```
+ */
+export declare function resolve(scene: Portrait): Resolved;
+/** A manual layout with every body where the automatic one has it now. */
+export declare function freeze(p: Portrait): Portrait;
+/** The automatic layout again. */
+export declare function auto(p: Portrait): Portrait;
+/**
+ * Add a body to a scene (once), in its place in the order of the sky for an automatic layout, or at the front and to the right of the others for a manual one.
+ *
+ * @param scene - The scene to add to; it is not changed.
+ * @param body - The body's name.
+ * @returns A new scene with the body, or the same one when it is already there.
+ *
+ * @example
+ * ```ts
+ * import { addBody, defaultPortrait } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * const scene = addBody(addBody(defaultPortrait(), "saturn"), "earth");
+ * console.log(scene.items.map((item) => item.body).join(", "));
+ * ```
+ */
+export declare function addBody(scene: Portrait, body: BodyId): Portrait;
+export declare function removeBody(p: Portrait, body: BodyId): Portrait;
+/** Add the moons of a planet that are not in the scene yet, in orbit order. */
+export declare function addMoons(p: Portrait, planet: BodyId): Portrait;
+/** Move one body to a new place in the list: the front is the end. */
+export declare function moveInOrder(p: Portrait, from: number, to: number): Portrait;
+/** Change one body's fields. */
+export declare function setItem(p: Portrait, index: number, change: Partial<Item>): Portrait;
+/** Change the portrait's own settings. A change to manual layout keeps every body where it is on the page. */
+export declare function setPortrait(p: Portrait, change: Partial<Omit<Portrait, "items">>): Portrait;
+/** Every body sized by a scale, keeping the largest as it is (a manual layout's way to go back to true or readable sizes). */
+export declare function rescale(p: Portrait, mode: ScaleMode): Portrait;
+/** Move the camera to the middle of the bodies, keeping its zoom. */
+export declare function centreCamera(p: Portrait): Portrait;
+/** Zoom out or in so every body is in the picture. */
+export declare function fitAll(p: Portrait): Portrait;
+/** The scene's units to pixels: a body at the camera's centre is in the middle of a picture `width` by `height`. */
+export declare function toScreen(camera: Resolved["camera"], width: number, height: number): {
+    px(x: number): number;
+    py(y: number): number;
+    scale: number;
+};
+/** The inverse: a pixel to the scene's units. */
+export declare function fromScreen(camera: Resolved["camera"], width: number, height: number, x: number, y: number): {
+    x: number;
+    y: number;
+};
+/** The index of the body under a point (scene units), front first; a body smaller than `slop` is still hit within it. */
+export declare function hitTest(placed: readonly Placed[], x: number, y: number, slop?: number): number;
+export interface Guide {
+    axis: "x" | "y";
+    at: number;
+}
+/** Where a body being dragged snaps: its middle and edges to the middle and edges of the others and to the middle of the picture, within `tolerance` (scene units). */
+export declare function snap(moving: {
+    x: number;
+    y: number;
+    r: number;
+}, others: readonly {
+    x: number;
+    y: number;
+    r: number;
+}[], centre: {
+    x: number;
+    y: number;
+}, tolerance: number): {
+    x: number;
+    y: number;
+    guides: Guide[];
+};
+/** The Sun's direction as a unit vector in the picture's frame (x right, y up, z toward the viewer). */
+export declare function lightVector(light: {
+    az: number;
+    el: number;
+}): [number, number, number];
+export interface History {
+    readonly current: Portrait;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    /** Remember a new state (a finished change). */
+    push(next: Portrait): void;
+    /** Make the newest step this state instead of a new step (a change that goes on: a key held, a slider dragged). */
+    replace(next: Portrait): void;
+    undo(): Portrait;
+    redo(): Portrait;
+}
+/** The states a scene has been through, to step back and forward over. A state is never changed, so each is kept as it is. */
+export declare function createHistory(initial: Portrait, limit?: number): History;
+/**
+ * The scene as one short piece of text that is safe in an address: fields joined by `~`, each `name:value`, then one `body_x_y_r_spin_tilt_pitch_turn` for each body, back to front. An empty scene is an empty string.
+ *
+ * @param scene - The scene.
+ * @returns The text.
+ *
+ * @example
+ * ```ts
+ * import { addBody, defaultPortrait, encodeScene } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(encodeScene(addBody(defaultPortrait(), "mars")));
+ * ```
+ */
+export declare function encodeScene(scene: Portrait): string;
+/**
+ * The scene from its text. Anything it does not understand is left at its default and a body it does not know is dropped, so any text gives a scene.
+ *
+ * @param text - Text from `encodeScene`, or anything.
+ * @returns The scene.
+ *
+ * @example
+ * ```ts
+ * import { decodeScene } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(decodeScene("look:painted~jupiter_0_0_0.3_0").items[0]?.body);
+ * ```
+ */
+export declare function decodeScene(text: string): Portrait;
+/**
+ * A ready-made scene with its name in English and Japanese.
+ *
+ * @example
+ * ```ts
+ * import { PORTRAIT_PRESETS, type PortraitPreset } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * const first: PortraitPreset = PORTRAIT_PRESETS[0]!;
+ * console.log(first.id, first.name.en);
+ * ```
+ */
+export interface Preset {
+    id: string;
+    name: {
+        en: string;
+        ja: string;
+    };
+    scene: Portrait;
+}
+/**
+ * Ready-made scenes to start from: a family photo of the Sun and the planets, the gas giants to scale, Jupiter and the Galileans, the Earth and the Moon to scale (size and distance), Mars and its moons at their true distance, and the inner planets round the Sun.
+ *
+ * @example
+ * ```ts
+ * import { PORTRAIT_PRESETS } from "@johnmorrisdotca/wakusei-planets";
+ *
+ * console.log(PORTRAIT_PRESETS.map((preset) => preset.id).join(", "));
+ * ```
+ */
+export declare const PRESETS: readonly Preset[];