@johnmorrisdotca/wakusei-planets 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.5.0
+
+The bodies for someone else's three.js scene.
+
+- **`@johnmorrisdotca/wakusei-planets/painter`**: `painter.make(three, "Jupiter", { look, invalidate, ratio })` makes the Sun, a planet, Pluto or a moon as an object of radius 1 for a perspective-camera scene of your own, in the realistic or the painted look, lit from any direction in the scene's own axes (equatorial J2000, y up), turned about its real pole at the moment given, with its rings and the Sun's glow. Nothing is drawn by it and it holds no renderer, loop or clock: the caller places, scales and calls `update({ toSun, ms, radiusPx })` at each draw. A painted body shows the shaded look until its map arrives, fetches a sharper map only when it is big on the screen, and lets the big one go a few seconds after it shrinks. `painter.moons("Jupiter", ms)` places a planet's moons in planet radii. Its shape is chikyu-earth's `BodyPainter`, so `setBodyPainter(painter)` is the whole wiring (chikyu-earth 0.11).
+- New shaders for it (`VERTEX_WORLD` and friends): the lighting, the ring's shadow and the limb are worked out from the direction to the camera, not from an orthographic viewer's frame.
+- `orientation(id, ms)` and `moonOffset(id, ms)`: a body's pole and prime meridian, and a moon's place from its planet, in the same axes.
+- A guide, "In your own three.js scene", in English and Japanese.
+
 ## 0.4.0
 
 "Put it in your page" is a configurator.

package/README.md

@@ -11,9 +11,9 @@ A clean line drawing, a shaded realistic drawing, or a painted surface map, with
 
 <p align="center"><a href="https://johnmorrisdotca.github.io/wakusei-planets/"><strong>Open the demo →</strong></a> · <a href="https://johnmorrisdotca.github.io/wakusei-planets/embed.html">Embed page</a> · <a href="https://johnmorrisdotca.github.io/wakusei-planets/docs/">Docs</a></p>
 
-<p align="center"><img alt="Jupiter and Saturn drawn in the realistic look, and Saturn as a line drawing" src="https://raw.githubusercontent.com/johnmorrisdotca/wakusei-planets/v0.4.0/docs/images/hero-desk.png" width="640"></p>
+<p align="center"><img alt="Jupiter and Saturn drawn in the realistic look, and Saturn as a line drawing" src="https://raw.githubusercontent.com/johnmorrisdotca/wakusei-planets/v0.5.0/docs/images/hero-desk.png" width="640"></p>
 
-<p align="center"><img alt="Every body at one scale, the Earth among them: each small body has a magnified picture joined by a line, and the Sun shows only its edge" src="https://raw.githubusercontent.com/johnmorrisdotca/wakusei-planets/v0.4.0/docs/images/lineup-desk.png" width="640"></p>
+<p align="center"><img alt="Every body at one scale, the Earth among them: each small body has a magnified picture joined by a line, and the Sun shows only its edge" src="https://raw.githubusercontent.com/johnmorrisdotca/wakusei-planets/v0.5.0/docs/images/lineup-desk.png" width="640"></p>
 
 ## One minute
 

package/dist/element.d.ts

@@ -25,7 +25,7 @@ export type WakuseiState = "line" | "loading" | "still" | "live" | "lost" | "una
  * console.log(TEXTURE_BASE);
  * ```
  */
-export declare const TEXTURE_BASE = "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/wakusei-planets@0.4.0/dist/textures/";
+export declare const TEXTURE_BASE = "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/wakusei-planets@0.5.0/dist/textures/";
 /**
  * Where the sharpest surface pictures are: the files of this exact version in the repository, on jsDelivr's GitHub address. The npm package holds only the two smaller widths, so a page that
  * never zooms in never fetches them. Set `texture-far-base` on an element to serve them yourself.
@@ -37,7 +37,7 @@ export declare const TEXTURE_BASE = "https://cdn.jsdelivr.net/npm/@johnmorrisdot
  * console.log(TEXTURE_FAR_BASE);
  * ```
  */
-export declare const TEXTURE_FAR_BASE = "https://cdn.jsdelivr.net/gh/johnmorrisdotca/wakusei-planets@v0.4.0/textures/";
+export declare const TEXTURE_FAR_BASE = "https://cdn.jsdelivr.net/gh/johnmorrisdotca/wakusei-planets@v0.5.0/textures/";
 /**
  * The `<wakusei-body>` custom element: a body of the solar system, drawn in a look.
  *

package/dist/scene/glsl.d.ts

@@ -2,11 +2,20 @@ export declare const VERTEX = "\nvarying vec3 vObj;\nvarying vec3 vN;\nvarying v
 /** Noise, craters and the band palette, for the surface code of a body to call. */
 export declare const PRELUDE = "\nfloat hash13(vec3 p) { p = fract(p * 0.1031); p += dot(p, p.zyx + 31.32); return fract((p.x + p.y) * p.z); }\nvec3 hash33(vec3 p) { p = fract(p * vec3(0.1031, 0.1030, 0.0973)); p += dot(p, p.yxz + 33.33); return fract((p.xxy + p.yxx) * p.zyx); }\nfloat vnoise(vec3 p) {\n  vec3 i = floor(p); vec3 f = fract(p); f = f * f * (3.0 - 2.0 * f);\n  return mix(mix(mix(hash13(i), hash13(i + vec3(1,0,0)), f.x), mix(hash13(i + vec3(0,1,0)), hash13(i + vec3(1,1,0)), f.x), f.y),\n             mix(mix(hash13(i + vec3(0,0,1)), hash13(i + vec3(1,0,1)), f.x), mix(hash13(i + vec3(0,1,1)), hash13(i + vec3(1,1,1)), f.x), f.y), f.z);\n}\nfloat fbm(vec3 p) { float a = 0.5; float s = 0.0; for (int i = 0; i < 5; i++) { s += a * vnoise(p); p = p * 2.03 + vec3(1.7, 9.2, 3.1); a *= 0.5; } return s; }\n// Craters: a bowl and a raised rim in each cell that has one. Returns a height, negative in a bowl.\nfloat craters(vec3 p, float freq, float amp, float seed) {\n  vec3 q = p * freq + seed; vec3 ip = floor(q); float h = 0.0;\n  for (int x = -1; x <= 1; x++) for (int y = -1; y <= 1; y++) for (int z = -1; z <= 1; z++) {\n    vec3 c = ip + vec3(float(x), float(y), float(z));\n    float on = step(0.52, hash13(c + 3.7));\n    vec3 ctr = c + hash33(c);\n    float rad = mix(0.12, 0.36, hash13(c + 17.3));\n    float d = length(q - ctr) / rad;\n    float bowl = d < 1.0 ? (d * d - 1.0) : 0.0;\n    float rim = d >= 1.0 ? exp(-pow((d - 1.0) * 5.0, 2.0)) * 0.3 : 0.0;\n    h += on * amp * rad * (bowl + rim);\n  }\n  return h;\n}\nfloat lon(vec3 p) { return atan(p.y, p.x); }\nfloat lat(vec3 p) { return asin(clamp(p.z, -1.0, 1.0)); }\nfloat wrapPi(float a) { return a - 6.2831853 * floor((a + 3.1415927) / 6.2831853); }\nvec3 dirOf(float lonDeg, float latDeg) { float lo = radians(lonDeg); float la = radians(latDeg); return vec3(cos(la) * cos(lo), cos(la) * sin(lo), sin(la)); }\n// One big round bowl with a rim, by longitude, latitude and angular radius in degrees. Negative inside.\nfloat bowl(vec3 p, float lonDeg, float latDeg, float radDeg, float depth) {\n  float d = acos(clamp(dot(p, dirOf(lonDeg, latDeg)), -1.0, 1.0)) / radians(radDeg);\n  return d < 1.0 ? depth * (d * d - 1.0) : depth * exp(-pow((d - 1.0) * 5.0, 2.0)) * 0.3;\n}\n// A soft oval on the body, 1 inside and 0 outside, by longitude and latitude in degrees.\nfloat oval(vec3 p, float lon0, float lat0, float rx, float ry, float soft) {\n  float dx = wrapPi(lon(p) - radians(lon0)) * cos(radians(lat0)) / radians(rx);\n  float dy = (lat(p) - radians(lat0)) / radians(ry);\n  return 1.0 - smoothstep(1.0 - soft, 1.0, sqrt(dx * dx + dy * dy));\n}";
 /** The fragment shader of a body: the surface code goes between the prelude and `main`. */
-export declare function bodyFragment(surface: string, painted: boolean): string;
+export declare function bodyFragment(surface: string, painted: boolean, world?: boolean): string;
 /** A painted body's surface code: the map by longitude and latitude, with the seam at 180 degrees left alone. */
 export declare const PAINTED_SURFACE = "\nvec4 surface(vec3 p) {\n  float u1 = atan(p.y, p.x) / 6.2831853 + 0.5;\n  float u2 = fract(u1 + 0.5) - 0.5;\n  float v = asin(clamp(p.z, -1.0, 1.0)) / 3.1415927 + 0.5;\n  vec2 a = vec2(u1, v); vec2 b = vec2(u2, v);\n  vec2 ax = dFdx(a); vec2 ay = dFdy(a); vec2 bx = dFdx(b); vec2 by = dFdy(b);\n  bool useA = dot(ax, ax) + dot(ay, ay) <= dot(bx, bx) + dot(by, by);\n  vec3 c = textureGrad(uMap, useA ? a : b, useA ? ax : bx, useA ? ay : by).rgb;\n  return vec4(c, dot(c, vec3(0.3, 0.59, 0.11)));\n}";
 export declare const RING_FRAGMENT = "\nprecision highp float;\nuniform sampler2D uRingTex;\nuniform vec2 uRingR;\nuniform vec3 uLight;\nuniform vec3 uRingN;\nvarying vec3 vL;\nvarying vec3 vW;\nvoid main() {\n  float u = (length(vL.xy) - uRingR.x) / (uRingR.y - uRingR.x);\n  if (u < 0.0 || u > 1.0) discard;\n  vec4 t = texture2D(uRingTex, vec2(u, 0.5));\n  float nl = dot(uRingN, uLight);\n  float side = nl * uRingN.z;\n  float bright = 0.16 + 0.84 * clamp(abs(nl) * 2.0, 0.0, 1.0);\n  if (side < 0.0) bright *= 0.38;\n  float b = dot(vW, uLight);\n  float closest = sqrt(max(dot(vW, vW) - b * b, 0.0));\n  float shadow = b < 0.0 ? smoothstep(1.02, 0.97, closest) : 0.0;\n  vec3 c = pow(t.rgb, vec3(2.2)) * bright * (1.0 - 0.93 * shadow);\n  gl_FragColor = vec4(pow(c, vec3(1.0 / 2.2)), t.a);\n}";
 export declare const RING_VERTEX = "\nvarying vec3 vL;\nvarying vec3 vW;\nvoid main() {\n  vL = position;\n  vec4 w = modelMatrix * vec4(position, 1.0);\n  vW = w.xyz;\n  gl_Position = projectionMatrix * viewMatrix * w;\n}";
+/**
+ * The body's vertex shader for a perspective camera and a body anywhere in the scene: the normal and the position are in the scene's axes, the position in body radii from the body's centre
+ * (`uScale` is the body's size in scene units), and `vV` points at the camera.
+ */
+export declare const VERTEX_WORLD = "\nuniform float uScale;\nvarying vec3 vObj;\nvarying vec3 vN;\nvarying vec3 vW;\nvarying vec3 vV;\nvoid main() {\n  vObj = vec3(position.z, position.x, position.y);\n  vec4 w = modelMatrix * vec4(position, 1.0);\n  vN = normalize(transpose(inverse(mat3(modelMatrix))) * normal);\n  vW = mat3(modelMatrix) * position / uScale;\n  vV = cameraPosition - w.xyz;\n  gl_Position = projectionMatrix * viewMatrix * w;\n}";
+/** The ring's vertex shader for a perspective camera, with the same frame as `VERTEX_WORLD`. */
+export declare const RING_VERTEX_WORLD = "\nuniform float uScale;\nvarying vec3 vL;\nvarying vec3 vW;\nvarying vec3 vV;\nvoid main() {\n  vL = position;\n  vec4 w = modelMatrix * vec4(position, 1.0);\n  vW = mat3(modelMatrix) * position / uScale;\n  vV = cameraPosition - w.xyz;\n  gl_Position = projectionMatrix * viewMatrix * w;\n}";
+/** The ring's fragment shader for a perspective camera: which side is seen comes from the direction to the camera. */
+export declare const RING_FRAGMENT_WORLD: string;
 export declare const GLOW_VERTEX = "\nvarying vec2 vP;\nvoid main() { vP = position.xy; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }";
 export declare const GLOW_FRAGMENT = "\nprecision highp float;\nvarying vec2 vP;\nuniform vec3 uColour;\nvoid main() {\n  float r = length(vP);\n  if (r < 0.98) discard;\n  float a = exp(-(r - 1.0) * 2.4) * 0.62;\n  float streak = 0.82 + 0.18 * sin(atan(vP.y, vP.x) * 9.0 + r * 3.0);\n  a *= streak * smoothstep(3.0, 1.6, r);\n  gl_FragColor = vec4(uColour * a, a);\n}";
 /** A cheap lit ball for a moon seen small beside its planet. */

package/dist/scene/glsl.js

@@ -51,7 +51,7 @@ float oval(vec3 p, float lon0, float lat0, float rx, float ry, float soft) {
   return 1.0 - smoothstep(1.0 - soft, 1.0, sqrt(dx * dx + dy * dy));
 }`;
 /** The fragment shader of a body: the surface code goes between the prelude and `main`. */
-export function bodyFragment(surface, painted) {
+export function bodyFragment(surface, painted, world = false) {
     return /* glsl */ `
 precision highp float;
 uniform vec3 uLight;
@@ -70,13 +70,14 @@ ${painted ? "uniform sampler2D uMap;" : ""}
 varying vec3 vObj;
 varying vec3 vN;
 varying vec3 vW;
+${world ? "varying vec3 vV;" : ""}
 ${PRELUDE}
 ${surface}
 void main() {
   vec3 p = normalize(vObj);
   vec4 s = surface(p);
   vec3 n = normalize(vN);
-  float mu = clamp(n.z, 0.0, 1.0);
+  float mu = ${world ? "clamp(dot(n, normalize(vV)), 0.0, 1.0)" : "clamp(n.z, 0.0, 1.0)"};
   if (uEmissive > 0.5) {
     float edge = pow(mu, uLimb);
     vec3 c = s.rgb * mix(vec3(1.0, 0.55, 0.25), vec3(1.0), edge) * (0.55 + 0.45 * edge);
@@ -153,6 +154,39 @@ void main() {
   vW = w.xyz;
   gl_Position = projectionMatrix * viewMatrix * w;
 }`;
+/**
+ * The body's vertex shader for a perspective camera and a body anywhere in the scene: the normal and the position are in the scene's axes, the position in body radii from the body's centre
+ * (`uScale` is the body's size in scene units), and `vV` points at the camera.
+ */
+export const VERTEX_WORLD = /* glsl */ `
+uniform float uScale;
+varying vec3 vObj;
+varying vec3 vN;
+varying vec3 vW;
+varying vec3 vV;
+void main() {
+  vObj = vec3(position.z, position.x, position.y);
+  vec4 w = modelMatrix * vec4(position, 1.0);
+  vN = normalize(transpose(inverse(mat3(modelMatrix))) * normal);
+  vW = mat3(modelMatrix) * position / uScale;
+  vV = cameraPosition - w.xyz;
+  gl_Position = projectionMatrix * viewMatrix * w;
+}`;
+/** The ring's vertex shader for a perspective camera, with the same frame as `VERTEX_WORLD`. */
+export const RING_VERTEX_WORLD = /* glsl */ `
+uniform float uScale;
+varying vec3 vL;
+varying vec3 vW;
+varying vec3 vV;
+void main() {
+  vL = position;
+  vec4 w = modelMatrix * vec4(position, 1.0);
+  vW = mat3(modelMatrix) * position / uScale;
+  vV = cameraPosition - w.xyz;
+  gl_Position = projectionMatrix * viewMatrix * w;
+}`;
+/** The ring's fragment shader for a perspective camera: which side is seen comes from the direction to the camera. */
+export const RING_FRAGMENT_WORLD = RING_FRAGMENT.replace("varying vec3 vW;", "varying vec3 vW;\nvarying vec3 vV;").replace("float side = nl * uRingN.z;", "float side = nl * dot(uRingN, normalize(vV));");
 export const GLOW_VERTEX = /* glsl */ `
 varying vec2 vP;
 void main() { vP = position.xy; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }`;

package/dist/scene/orient.d.ts

@@ -0,0 +1,38 @@
+import { type BodyId, type MoonId } from "../facts.ts";
+import { type Vec3 } from "../vec.ts";
+/**
+ * Where a moon is from its planet's centre, in planet radii, in the scene's axes (x to the vernal equinox, y north).
+ *
+ * @param id - The moon's name.
+ * @param ms - The instant, in milliseconds since 1970.
+ * @returns The offset, in radii of the planet the moon goes round.
+ *
+ * @example
+ * ```ts
+ * import { moonOffset } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const [x, y, z] = moonOffset("io", Date.UTC(2026, 10, 2));
+ * console.log(Math.hypot(x, y, z).toFixed(1));
+ * ```
+ */
+export declare function moonOffset(id: MoonId, ms: number): Vec3;
+/**
+ * The north pole and the prime meridian of a body at a time, as unit vectors in the scene's axes (x to the vernal equinox, y north). A moon that keeps one face to its planet is
+ * given the direction to the planet as its meridian, so its near side faces the planet.
+ *
+ * @param id - The body's name.
+ * @param ms - The instant, in milliseconds since 1970.
+ * @returns The pole and the direction of longitude 0, both unit vectors.
+ *
+ * @example
+ * ```ts
+ * import { orientation } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const { pole } = orientation("mars", Date.UTC(2026, 10, 2));
+ * console.log(pole.map((n) => n.toFixed(2)).join(", "));
+ * ```
+ */
+export declare function orientation(id: BodyId, ms: number): {
+    pole: Vec3;
+    meridian: Vec3;
+};

package/dist/scene/orient.js

@@ -0,0 +1,72 @@
+// How a body is turned in space at a time, in the axes of an equatorial J2000 scene with y up (x to the vernal equinox, y to the celestial north pole, z toward -y of the equator).
+// Pure: no three.js. The painter uses it to turn each body about its real pole, and to find where a moon is round its planet.
+import { moonVector } from "../ephemeris.js";
+import { BODIES } from "../facts.js";
+import { cross, dot, fromRaDec, OBLIQUITY, RAD, unit, wrap360 } from "../vec.js";
+const J2000 = Date.UTC(2000, 0, 1, 12);
+const DAY = 86_400_000;
+/** An equatorial vector (x to the vernal equinox, z to the north pole) in the scene's axes. */
+const toScene = (v) => [v[0], v[2], -v[1]];
+/** An ecliptic J2000 vector in equatorial J2000 axes. */
+const fromEcliptic = (v) => {
+    const c = Math.cos(OBLIQUITY * RAD);
+    const s = Math.sin(OBLIQUITY * RAD);
+    return [v[0], v[1] * c - v[2] * s, v[1] * s + v[2] * c];
+};
+/**
+ * Where a moon is from its planet's centre, in planet radii, in the scene's axes (x to the vernal equinox, y north).
+ *
+ * @param id - The moon's name.
+ * @param ms - The instant, in milliseconds since 1970.
+ * @returns The offset, in radii of the planet the moon goes round.
+ *
+ * @example
+ * ```ts
+ * import { moonOffset } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const [x, y, z] = moonOffset("io", Date.UTC(2026, 10, 2));
+ * console.log(Math.hypot(x, y, z).toFixed(1));
+ * ```
+ */
+export function moonOffset(id, ms) {
+    const facts = BODIES[id];
+    const radius = BODIES[facts.parent ?? "earth"].radiusKm;
+    const v = toScene(fromEcliptic(moonVector(id, ms)));
+    return [v[0] / radius, v[1] / radius, v[2] / radius];
+}
+/**
+ * The north pole and the prime meridian of a body at a time, as unit vectors in the scene's axes (x to the vernal equinox, y north). A moon that keeps one face to its planet is
+ * given the direction to the planet as its meridian, so its near side faces the planet.
+ *
+ * @param id - The body's name.
+ * @param ms - The instant, in milliseconds since 1970.
+ * @returns The pole and the direction of longitude 0, both unit vectors.
+ *
+ * @example
+ * ```ts
+ * import { orientation } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const { pole } = orientation("mars", Date.UTC(2026, 10, 2));
+ * console.log(pole.map((n) => n.toFixed(2)).join(", "));
+ * ```
+ */
+export function orientation(id, ms) {
+    const facts = BODIES[id];
+    const { ra, dec } = facts.pole;
+    const pole = fromRaDec(ra, dec);
+    let meridian;
+    if (facts.synchronous === true && facts.parent !== undefined) {
+        const planetward = unit(fromEcliptic(moonVector(id, ms)).map((n) => -n));
+        const d = dot(planetward, pole);
+        meridian = unit([planetward[0] - pole[0] * d, planetward[1] - pole[1] * d, planetward[2] - pole[2] * d]);
+    }
+    else {
+        const w = wrap360(facts.prime.w0 + facts.prime.rate * ((ms - J2000) / DAY));
+        const node = fromRaDec(ra + 90, 0);
+        const third = cross(pole, node);
+        const c = Math.cos(w * RAD);
+        const s = Math.sin(w * RAD);
+        meridian = [node[0] * c + third[0] * s, node[1] * c + third[1] * s, node[2] * c + third[2] * s];
+    }
+    return { pole: toScene(pole), meridian: toScene(meridian) };
+}

package/dist/scene/painter.d.ts

@@ -0,0 +1,164 @@
+import type * as THREE from "three";
+import "../bodies/all.ts";
+import { type Vec3 } from "../vec.ts";
+import { moonOffset, orientation } from "./orient.ts";
+export { moonOffset, orientation };
+/**
+ * The looks the painter draws: `realistic` (shaded from the body's real colours and features) and `painted` (a public-domain surface map, with the shaded look until it arrives).
+ *
+ * @example
+ * ```ts no-run
+ * import { LOOKS, type PainterLook } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const first: PainterLook = LOOKS[0];
+ * console.log(first);
+ * ```
+ */
+export declare const LOOKS: readonly ["realistic", "painted"];
+/**
+ * One of the looks in `LOOKS`: `realistic` or `painted`.
+ *
+ * @example
+ * ```ts no-run
+ * import type { PainterLook } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const look: PainterLook = "painted";
+ * console.log(look);
+ * ```
+ */
+export type PainterLook = (typeof LOOKS)[number];
+/**
+ * What the caller gives the painter when it makes a body.
+ *
+ * @example
+ * ```ts no-run
+ * import type { PaintContext } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const context: PaintContext = { look: "painted", invalidate: () => undefined, ratio: 2 };
+ * console.log(context.look);
+ * ```
+ */
+export interface PaintContext {
+    /** `realistic` (the default) or `painted`. */
+    look?: string;
+    /** Ask for a new draw: a sharper picture has arrived. */
+    invalidate?(): void;
+    /** Device pixels to a CSS pixel; default 1. */
+    ratio?: number;
+    /** The widest picture the GPU should be given, in pixels; default 2048. */
+    maxTexture?: number;
+}
+/**
+ * What the caller tells a painted body at each draw: the direction to the Sun (a unit vector in the scene's axes), the time, and how many CSS pixels across its radius the body is on the screen.
+ *
+ * @example
+ * ```ts no-run
+ * import type { PaintInfo } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const info: PaintInfo = { toSun: [1, 0, 0], ms: Date.UTC(2026, 10, 2), radiusPx: 80 };
+ * console.log(info.radiusPx);
+ * ```
+ */
+export interface PaintInfo {
+    toSun: Vec3;
+    ms: number;
+    radiusPx: number;
+}
+/**
+ * One body made by the painter: an object of radius 1 at the origin for the caller to move and scale.
+ *
+ * @example
+ * ```ts no-run
+ * import type { Painting } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const stop = (painting: Painting): void => painting.dispose();
+ * console.log(typeof stop);
+ * ```
+ */
+export interface Painting {
+    object: THREE.Object3D;
+    /** True to have the caller turn the object to face the camera (the Sun, which carries a glow). */
+    billboard?: boolean;
+    /** Call at each draw, after the object has been placed and scaled. */
+    update(info: PaintInfo): void;
+    dispose(): void;
+}
+/**
+ * One moon of a planet at a time: where it is from the planet's centre and how big it is, both in radii of the planet, in the scene's axes.
+ *
+ * @example
+ * ```ts no-run
+ * import { painter } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const io = painter.moons("Jupiter", Date.UTC(2026, 10, 2))[0];
+ * console.log(io?.name, io?.radius.toFixed(3));
+ * ```
+ */
+export interface MoonSite {
+    /** The moon's name as `make` takes it, for example `Io`. */
+    name: string;
+    offset: Vec3;
+    radius: number;
+}
+/**
+ * Where the pictures are, if not on jsDelivr: a folder address that ends in a slash. `farBase` holds the widest pictures (2048), which the npm package leaves out.
+ *
+ * @example
+ * ```ts no-run
+ * import { createPainter, type PainterOptions } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const options: PainterOptions = { textureBase: "/textures/", farBase: "/textures/" };
+ * console.log(createPainter(options).looks);
+ * ```
+ */
+export interface PainterOptions {
+    textureBase?: string;
+    farBase?: string;
+}
+/**
+ * A painter: makes the bodies as three.js objects (`make`) and tells where a planet's moons are (`moons`). Its shape is chikyu-earth's `BodyPainter`, so `setBodyPainter(painter)` is all the wiring.
+ *
+ * @example
+ * ```ts no-run
+ * import { createPainter, type WakuseiPainter } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const mine: WakuseiPainter = createPainter({ textureBase: "/pictures/", farBase: "/pictures/" });
+ * console.log(mine.looks.join(", "));
+ * ```
+ */
+export interface WakuseiPainter {
+    /** The looks `make` takes in `context.look`. */
+    readonly looks: readonly PainterLook[];
+    /** Make a body: `Sun`, a planet, `Pluto` or a moon, in any case. Throws for a name it does not know. */
+    /** `three` is the three.js module (or a subset of it holding the parts `PainterThree` names); it is typed loosely so that another package can hand over its own subset. */
+    make(three: object, name: string, context?: PaintContext): Painting;
+    /** The moons the painter draws for a planet (none for the Earth: its Moon is the viewer's own), where they are at a time, nearest first. */
+    moons(planet: string, ms: number): MoonSite[];
+}
+/**
+ * Make a painter that takes its pictures from the given folders (jsDelivr's copy of this version by default).
+ *
+ * @param options - Where the pictures are.
+ * @returns The painter.
+ *
+ * @example
+ * ```ts no-run
+ * import { createPainter } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const painter = createPainter();
+ * console.log(painter.moons("Mars", Date.UTC(2026, 10, 2)).map((m) => m.name));
+ * ```
+ */
+export declare function createPainter(options?: PainterOptions): WakuseiPainter;
+/**
+ * The painter with its default pictures: pass it to chikyu-earth's `setBodyPainter`.
+ *
+ * @example
+ * ```ts no-run
+ * import { painter } from "@johnmorrisdotca/wakusei-planets/painter";
+ * import { setBodyPainter } from "@johnmorrisdotca/chikyu-earth/space/element";
+ *
+ * setBodyPainter(painter);
+ * ```
+ */
+export declare const painter: WakuseiPainter;

package/dist/scene/painter.js

@@ -0,0 +1,355 @@
+import "../bodies/all.js";
+import { BODIES, MOONS_OF } from "../facts.js";
+import { VERSION } from "../version.js";
+import { cross } from "../vec.js";
+import { bodyFragment, GLOW_FRAGMENT, GLOW_VERTEX, PAINTED_SURFACE, RING_FRAGMENT_WORLD, RING_VERTEX_WORLD, VERTEX_WORLD } from "./glsl.js";
+import { lookOf } from "./look.js";
+import { moonOffset, orientation } from "./orient.js";
+import { ringStrip } from "./rings.js";
+export { moonOffset, orientation };
+/**
+ * The looks the painter draws: `realistic` (shaded from the body's real colours and features) and `painted` (a public-domain surface map, with the shaded look until it arrives).
+ *
+ * @example
+ * ```ts no-run
+ * import { LOOKS, type PainterLook } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const first: PainterLook = LOOKS[0];
+ * console.log(first);
+ * ```
+ */
+export const LOOKS = ["realistic", "painted"];
+const TEXTURE_BASE = `https://cdn.jsdelivr.net/npm/@johnmorrisdotca/wakusei-planets@${VERSION}/dist/textures/`;
+const TEXTURE_FAR_BASE = `https://cdn.jsdelivr.net/gh/johnmorrisdotca/wakusei-planets@v${VERSION}/textures/`;
+const slash = (base) => (base.endsWith("/") ? base : `${base}/`);
+const titled = (id) => id.charAt(0).toUpperCase() + id.slice(1);
+const pools = new WeakMap();
+function acquire(three, key, make) {
+    let pool = pools.get(three);
+    if (pool === undefined)
+        pools.set(three, (pool = new Map()));
+    let held = pool.get(key);
+    if (held === undefined)
+        pool.set(key, (held = { value: make(), users: 0 }));
+    held.users += 1;
+    const mine = held;
+    const owner = pool;
+    let released = false;
+    return {
+        value: mine.value,
+        release() {
+            if (released)
+                return;
+            released = true;
+            mine.users -= 1;
+            if (mine.users <= 0) {
+                mine.value.dispose();
+                owner.delete(key);
+            }
+        },
+    };
+}
+const fallbackLook = (id) => {
+    const c = [1, 3, 5].map((i) => (parseInt(BODIES[id].colour.slice(i, i + 2), 16) / 255).toFixed(3)).join(", ");
+    return { id, surface: `vec4 surface(vec3 p) { float n = fbm(p * 5.0); return vec4(vec3(${c}) * (0.85 + 0.3 * n), 0.0); }` };
+};
+/** The name of a body as the painter takes it: any case, `Sun`, a planet or Pluto, or a moon such as `Io`. */
+function idOf(name) {
+    const id = name.toLowerCase();
+    if (!(id in BODIES))
+        throw new Error(`wakusei-planets: no body called ${name}`);
+    return id;
+}
+const moonsOf = (planet) => {
+    const id = planet.toLowerCase();
+    return id === "earth" ? [] : id in MOONS_OF ? MOONS_OF[id] : [];
+};
+function paint(T, id, context, bases) {
+    const facts = BODIES[id];
+    const look = lookOf(id) ?? fallbackLook(id);
+    const wantPainted = (context.look === "painted" || look.mapped === true) && look.painted !== undefined;
+    const ratio = context.ratio ?? 1;
+    const maxWidth = context.maxTexture ?? 2048;
+    const redraw = () => context.invalidate?.();
+    const releases = [];
+    const disposables = [];
+    const sphere = acquire(T, "sphere", () => new T.SphereGeometry(1, 96, 48));
+    releases.push(sphere.release);
+    const group = new T.Group();
+    group.name = facts.name.en;
+    const uniforms = (painted) => {
+        const a = look.atmosphere;
+        return {
+            uLight: { value: new T.Vector3(1, 0, 0) },
+            uRelief: { value: painted ? (look.painted?.relief ?? 0) : (look.relief ?? 0.6) },
+            uAmbient: { value: look.ambient ?? 0.04 },
+            uLimb: { value: look.limb ?? 0 },
+            uWrap: { value: look.wrap ?? (a === undefined ? 0.04 : 0.3) },
+            uAtmos: { value: new T.Vector3(...(a?.colour ?? [0, 0, 0])) },
+            uAtmosPow: { value: a?.power ?? 3 },
+            uEmissive: { value: look.emissive === true ? 1 : 0 },
+            uRingN: { value: new T.Vector3(0, 1, 0) },
+            uRingR: { value: new T.Vector2(1, 2) },
+            uRingOn: { value: 0 },
+            uRingTex: { value: null },
+            uMap: { value: null },
+            uScale: { value: 1 },
+        };
+    };
+    const material = (painted) => {
+        const m = new T.ShaderMaterial({ vertexShader: VERTEX_WORLD, fragmentShader: bodyFragment(painted ? PAINTED_SURFACE : look.surface, painted, true), uniforms: uniforms(painted) });
+        disposables.push(m);
+        return m;
+    };
+    const shader = material(false);
+    const paintedMaterial = wantPainted ? material(true) : undefined;
+    const materials = [shader, ...(paintedMaterial ? [paintedMaterial] : [])];
+    const mesh = new T.Mesh(sphere.value, shader);
+    mesh.matrixAutoUpdate = false;
+    group.add(mesh);
+    // rings: the table's strip at once, the picture of them (painted) when it arrives
+    let ringMesh;
+    let ringMaterial;
+    let ringTexture;
+    let ringInner = 1;
+    let ringOuter = 2;
+    const table = look.emissive === true ? null : ringStrip(facts, 1024);
+    const loadImage = (url) => new Promise((resolve, reject) => {
+        const loader = new T.TextureLoader();
+        loader.setCrossOrigin("anonymous");
+        loader.load(url, resolve, undefined, (e) => reject(e instanceof Error ? e : new Error("texture failed")));
+    });
+    let gone = false;
+    if (table !== null) {
+        ringInner = table.inner;
+        ringOuter = table.outer;
+        const strip = new T.DataTexture(table.data, table.width, 1, T.RGBAFormat);
+        strip.magFilter = T.LinearFilter;
+        strip.minFilter = T.LinearFilter;
+        strip.wrapS = T.ClampToEdgeWrapping;
+        strip.needsUpdate = true;
+        ringTexture = strip;
+        const ringGeometry = new T.RingGeometry(ringInner, ringOuter, 256, 1);
+        disposables.push(ringGeometry);
+        ringMaterial = new T.ShaderMaterial({
+            vertexShader: RING_VERTEX_WORLD,
+            fragmentShader: RING_FRAGMENT_WORLD,
+            side: T.DoubleSide,
+            transparent: true,
+            depthWrite: false,
+            uniforms: { uRingTex: { value: strip }, uRingR: { value: new T.Vector2(ringInner, ringOuter) }, uLight: { value: new T.Vector3(1, 0, 0) }, uRingN: { value: new T.Vector3(0, 1, 0) }, uScale: { value: 1 } },
+        });
+        disposables.push(ringMaterial);
+        ringMesh = new T.Mesh(ringGeometry, ringMaterial);
+        ringMesh.matrixAutoUpdate = false;
+        ringMesh.renderOrder = 1;
+        group.add(ringMesh);
+        const photo = wantPainted ? look.painted?.rings : undefined;
+        if (photo !== undefined) {
+            void loadImage(`${bases.near}${photo.map}-${photo.width}.webp`).then((t) => {
+                if (gone) {
+                    t.dispose();
+                    return;
+                }
+                t.magFilter = T.LinearFilter;
+                t.minFilter = T.LinearFilter;
+                t.generateMipmaps = false;
+                t.wrapS = T.ClampToEdgeWrapping;
+                t.colorSpace = T.NoColorSpace;
+                ringTexture?.dispose();
+                ringTexture = t;
+                ringInner = photo.from / facts.radiusKm;
+                ringOuter = photo.to / facts.radiusKm;
+                ringMesh.geometry.dispose();
+                ringMesh.geometry = new T.RingGeometry(ringInner, ringOuter, 256, 1);
+                disposables.push(ringMesh.geometry);
+                ringMaterial.uniforms.uRingTex.value = t;
+                ringMaterial.uniforms.uRingR.value.set(ringInner, ringOuter);
+                for (const m of materials) {
+                    m.uniforms.uRingTex.value = t;
+                    m.uniforms.uRingR.value.set(ringInner, ringOuter);
+                }
+                redraw();
+            }, () => undefined);
+        }
+        for (const m of materials) {
+            m.uniforms.uRingOn.value = 1;
+            m.uniforms.uRingTex.value = strip;
+            m.uniforms.uRingR.value.set(ringInner, ringOuter);
+        }
+    }
+    // the glow of a star: a plane through its centre that the caller turns to the camera
+    if (look.emissive === true) {
+        const glowGeometry = acquire(T, "glow", () => new T.PlaneGeometry(6, 6));
+        releases.push(glowGeometry.release);
+        const glowMaterial = new T.ShaderMaterial({ vertexShader: GLOW_VERTEX, fragmentShader: GLOW_FRAGMENT, transparent: true, depthWrite: false, blending: T.AdditiveBlending, uniforms: { uColour: { value: new T.Vector3(1, 0.7, 0.3) } } });
+        disposables.push(glowMaterial);
+        const glow = new T.Mesh(glowGeometry.value, glowMaterial);
+        glow.renderOrder = 4;
+        glow.frustumCulled = false;
+        group.add(glow);
+    }
+    // the painted map: the smallest width at once, a sharper one when the body is big on the screen, back to the small one when it is not
+    const widths = (look.painted?.widths ?? []).filter((w, i) => i === 0 || w <= maxWidth);
+    let small;
+    let sharp;
+    let sharpWidth = 0;
+    let loading = false;
+    let failed = false;
+    let tooBigSince = 0;
+    const tried = new Set();
+    const urlOf = (w) => `${look.painted.far !== undefined && w >= look.painted.far ? bases.far : bases.near}${look.painted.map}-${w}.webp`;
+    const prepare = (t) => {
+        t.anisotropy = 4;
+        t.wrapS = T.RepeatWrapping;
+        t.colorSpace = T.NoColorSpace;
+        return t;
+    };
+    const show = (t) => {
+        paintedMaterial.uniforms.uMap.value = t;
+        mesh.material = paintedMaterial;
+        redraw();
+    };
+    if (wantPainted && paintedMaterial !== undefined && widths[0] !== undefined) {
+        void loadImage(urlOf(widths[0])).then((t) => {
+            if (gone) {
+                t.dispose();
+                return;
+            }
+            small = prepare(t);
+            if (sharp === undefined)
+                show(small);
+        }, () => {
+            failed = true;
+        });
+    }
+    const keepSized = (radiusPx) => {
+        if (!wantPainted || failed || small === undefined || loading)
+            return;
+        const wanted = radiusPx * 2 * ratio * 1.6;
+        const next = widths.find((w) => w >= wanted) ?? widths[widths.length - 1];
+        if (next > sharpWidth && next > widths[0] && !tried.has(next)) {
+            tried.add(next);
+            loading = true;
+            void loadImage(urlOf(next)).then((t) => {
+                loading = false;
+                if (gone) {
+                    t.dispose();
+                    return;
+                }
+                const old = sharp;
+                sharp = prepare(t);
+                sharpWidth = next;
+                show(sharp);
+                old?.dispose();
+            }, () => {
+                loading = false;
+            });
+        }
+        else if (sharp !== undefined && wanted * 2 < sharpWidth) {
+            // much smaller on the screen than the picture it holds: after a few seconds, let the big picture go
+            const now = Date.now();
+            if (tooBigSince === 0)
+                tooBigSince = now;
+            else if (now - tooBigSince > 4000) {
+                show(small);
+                sharp.dispose();
+                sharp = undefined;
+                sharpWidth = 0;
+                tried.clear();
+                tooBigSince = 0;
+            }
+        }
+        else
+            tooBigSince = 0;
+    };
+    const axes = facts.axesKm;
+    const scaleX = axes ? axes[1] / facts.radiusKm : 1;
+    const scaleY = axes ? axes[2] / facts.radiusKm : 1 - facts.flattening;
+    const scaleZ = axes ? axes[0] / facts.radiusKm : 1;
+    const basis = (object, x, y, z, sx = 1, sy = 1, sz = 1) => {
+        object.matrix.makeBasis(new T.Vector3(x[0] * sx, x[1] * sx, x[2] * sx), new T.Vector3(y[0] * sy, y[1] * sy, y[2] * sy), new T.Vector3(z[0] * sz, z[1] * sz, z[2] * sz));
+    };
+    const light = new T.Vector3();
+    const poleVec = new T.Vector3();
+    return {
+        object: group,
+        ...(look.emissive === true ? { billboard: true } : {}),
+        update(info) {
+            light.set(info.toSun[0], info.toSun[1], info.toSun[2]);
+            const scale = group.scale.x || 1;
+            if (look.emissive !== true) {
+                const { pole, meridian } = orientation(id, info.ms);
+                const east = cross(pole, meridian);
+                basis(mesh, east, pole, meridian, scaleX, scaleY, scaleZ);
+                if (ringMesh !== undefined)
+                    basis(ringMesh, meridian, east, pole);
+                poleVec.set(pole[0], pole[1], pole[2]);
+            }
+            for (const m of materials) {
+                m.uniforms.uLight.value.copy(light);
+                m.uniforms.uScale.value = scale;
+                m.uniforms.uRingN.value.copy(poleVec);
+            }
+            if (ringMaterial !== undefined) {
+                ringMaterial.uniforms.uLight.value.copy(light);
+                ringMaterial.uniforms.uRingN.value.copy(poleVec);
+                ringMaterial.uniforms.uScale.value = scale;
+            }
+            keepSized(info.radiusPx);
+        },
+        dispose() {
+            gone = true;
+            small?.dispose();
+            sharp?.dispose();
+            ringTexture?.dispose();
+            for (const d of disposables)
+                d.dispose();
+            for (const r of releases)
+                r();
+            group.clear();
+        },
+    };
+}
+/**
+ * Make a painter that takes its pictures from the given folders (jsDelivr's copy of this version by default).
+ *
+ * @param options - Where the pictures are.
+ * @returns The painter.
+ *
+ * @example
+ * ```ts no-run
+ * import { createPainter } from "@johnmorrisdotca/wakusei-planets/painter";
+ *
+ * const painter = createPainter();
+ * console.log(painter.moons("Mars", Date.UTC(2026, 10, 2)).map((m) => m.name));
+ * ```
+ */
+export function createPainter(options = {}) {
+    const near = slash(options.textureBase ?? TEXTURE_BASE);
+    const far = slash(options.farBase ?? (options.textureBase !== undefined ? options.textureBase : TEXTURE_FAR_BASE));
+    return {
+        looks: LOOKS,
+        make: (three, name, context = {}) => paint(three, idOf(name), context, { near, far }),
+        moons(planet, ms) {
+            const radius = BODIES[idOf(planet)]?.radiusKm;
+            if (radius === undefined)
+                return [];
+            return moonsOf(planet)
+                .map((moon) => ({ name: titled(moon), offset: moonOffset(moon, ms), radius: BODIES[moon].radiusKm / radius }))
+                .sort((a, b) => Math.hypot(...a.offset) - Math.hypot(...b.offset));
+        },
+    };
+}
+/**
+ * The painter with its default pictures: pass it to chikyu-earth's `setBodyPainter`.
+ *
+ * @example
+ * ```ts no-run
+ * import { painter } from "@johnmorrisdotca/wakusei-planets/painter";
+ * import { setBodyPainter } from "@johnmorrisdotca/chikyu-earth/space/element";
+ *
+ * setBodyPainter(painter);
+ * ```
+ */
+export const painter = createPainter();

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.5.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.4.0";
+export const VERSION = "0.5.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnmorrisdotca/wakusei-planets",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Wakusei Planets 惑星 — The Sun, planets and moons for the web: each as a clean line drawing, a shaded realistic drawing or a painted surface map, with real sizes, axial tilt and rotation as data, and positions of the moons for any date and time. SVG for the lines, three.js (optional) for the rest.",
   "keywords": [
     "planets",
@@ -57,6 +57,11 @@
       "import": "./dist/scene/look.js",
       "default": "./dist/scene/look.js"
     },
+    "./painter": {
+      "types": "./dist/scene/painter.d.ts",
+      "import": "./dist/scene/painter.js",
+      "default": "./dist/scene/painter.js"
+    },
     "./all": {
       "types": "./dist/bodies/all.d.ts",
       "import": "./dist/bodies/all.js",