@navaramap/three 0.0.0

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@navaramap/three",
+  "type": "module",
+  "version": "0.0.0",
+  "main": "dist/index.umd.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eukarya-inc/navara.git",
+    "directory": "web/navara_three"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "postprocessing": ">=6.38.0",
+    "three": ">=0.183.0"
+  },
+  "dependencies": {
+    "@takram/three-atmosphere": "0.19.1",
+    "@takram/three-clouds": "0.7.6",
+    "@takram/three-geospatial": "0.9.1",
+    "@takram/three-geospatial-effects": "0.6.4",
+    "astronomy-engine": "2.1.19",
+    "stats.js": "0.17.0",
+    "three-stdlib": "2.36.1",
+    "@navaramap/core": "0.0.0",
+    "@navaramap/worker": "0.0.0",
+    "@navaramap/engine": "0.0.0",
+    "@navaramap/font": "0.0.0",
+    "@navaramap/engine-api": "0.0.0",
+    "@navaramap/three_csm": "0.0.0",
+    "@navaramap/three_api": "0.0.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.59.1",
+    "@radix-ui/react-collapsible": "1.1.12",
+    "@radix-ui/react-label": "2.1.8",
+    "@radix-ui/react-select": "2.2.6",
+    "@radix-ui/react-separator": "1.1.8",
+    "@radix-ui/react-slider": "1.3.6",
+    "@radix-ui/react-slot": "1.2.4",
+    "@radix-ui/react-switch": "1.2.6",
+    "@tailwindcss/postcss": "4.2.2",
+    "@tweakpane/core": "2.0.5",
+    "@types/geojson": "7946.0.16",
+    "@types/stats.js": "0.17.4",
+    "@types/three": "0.184.0",
+    "ajv": "8.20.0",
+    "class-variance-authority": "0.7.1",
+    "clsx": "2.1.1",
+    "dayjs": "1.11.20",
+    "lucide-react": "1.14.0",
+    "playwright": "1.59.1",
+    "postcss": "8.5.9",
+    "postprocessing": "6.38.3",
+    "sharp": "0.34.5",
+    "shiki": "4.3.1",
+    "tailwind-merge": "3.5.0",
+    "tailwindcss": "4.2.2",
+    "tailwindcss-animate": "1.0.7",
+    "three": "0.184.0",
+    "tsx": "4.21.0",
+    "tweakpane": "4.0.5",
+    "vite-plugin-glsl": "1.6.0",
+    "vite-plugin-static-copy": "4.1.0",
+    "@navaramap/three_default_descs": "0.0.0",
+    "@navaramap/three_default_plugin": "0.0.0",
+    "@navaramap/three_plugins": "0.0.0",
+    "@navaramap/three_react": "0.0.0"
+  },
+  "scripts": {
+    "start": "vite",
+    "dev": "vite -c vite.config.example.ts --host",
+    "type-check": "tsc && tsc -p tsconfig.node.json",
+    "build": "pnpm type-check && vite build -c vite.config.ts",
+    "build:dev": "vite build --mode development",
+    "build:dev:watch": "pnpm build:dev --watch",
+    "build:iife": "vite build -c vite.config.iife.ts",
+    "build:example": "tsc && vite build -c vite.config.example.ts",
+    "preview": "vite preview",
+    "test": "vitest --passWithNoTests --watch=false",
+    "lint": "eslint . --fix",
+    "lint:check": "eslint .",
+    "format": "prettier --write --ignore-path ../../.gitignore --ignore-path ../../.prettierignore .",
+    "format:check": "prettier --check --ignore-path ../../.gitignore --ignore-path ../../.prettierignore .",
+    "screenshots": "tsx scripts/generate-screenshots.ts"
+  }
+}

package/src/Color.ts

@@ -0,0 +1,111 @@
+import { Color as CoreColor } from "@navaramap/core";
+import { NoColorSpace, SRGBColorSpace, Color as ThreeColor } from "three";
+
+/**
+ * Class representing a color.
+ * This class assumes that the specified color represents the sRGB color space.
+ *
+ * ```
+ * const red = new Color().setRGB(1.0, 0.0, 0.0);
+ * const green = new Color().setHex(0x00ff00);
+ * const blue = new Color().setStyle("#0000ff");
+ * ```
+ */
+export class Color implements CoreColor {
+  #color = new ThreeColor();
+
+  /**
+   * Sets the color using RGB values in sRGB color space.
+   * @param r - Red component (0.0 to 1.0)
+   * @param g - Green component (0.0 to 1.0)
+   * @param b - Blue component (0.0 to 1.0)
+   * @returns This color instance for chaining
+   */
+  setRGB(r: number, g: number, b: number) {
+    this.#color.setRGB(r, g, b, SRGBColorSpace);
+    return this;
+  }
+
+  /**
+   * Sets the color using RGB values in linear color space (no gamma correction).
+   * @param r - Red component (0.0 to 1.0)
+   * @param g - Green component (0.0 to 1.0)
+   * @param b - Blue component (0.0 to 1.0)
+   * @returns This color instance for chaining
+   */
+  setRGBLinear(r: number, g: number, b: number) {
+    this.#color.setRGB(r, g, b, NoColorSpace);
+    return this;
+  }
+
+  /**
+   * Sets the color from a hexadecimal value in sRGB color space.
+   * @param hex - Hexadecimal color value (e.g., 0xff0000 for red)
+   * @returns This color instance for chaining
+   */
+  setHex(hex: number) {
+    this.#color.setHex(hex, SRGBColorSpace);
+    return this;
+  }
+
+  /**
+   * Sets the color from a CSS style string in sRGB color space.
+   * @param style - CSS color string (e.g., "#ff0000", "rgb(255, 0, 0)", "red")
+   * @returns This color instance for chaining
+   */
+  setStyle(style: string) {
+    this.#color.setStyle(style, SRGBColorSpace);
+    return this;
+  }
+
+  /**
+   * Copies this color's values to another Color instance.
+   * @param color - Target color to copy values into
+   * @returns The target color with copied values
+   */
+  copy(color: Color) {
+    color.#color = this.#color.clone();
+    return color as this;
+  }
+
+  /**
+   * Creates a new Color instance with the same values.
+   * @returns A new Color instance
+   */
+  clone() {
+    return this.copy(new Color());
+  }
+
+  /**
+   * Returns the color as an RGB array.
+   * @returns Tuple of [red, green, blue] values (0.0 to 1.0)
+   */
+  toArray(): [r: number, g: number, b: number] {
+    return this.#color.toArray() as [r: number, g: number, b: number];
+  }
+
+  /**
+   * Converts the color from linear to sRGB color space.
+   * @returns A new Color instance in sRGB color space
+   */
+  srgb() {
+    const copy = new Color();
+    copy.#color = new ThreeColor().copyLinearToSRGB(this.#color);
+    return copy as this;
+  }
+
+  /**
+   * Returns the color as a hexadecimal number.
+   * @returns Hexadecimal color value (e.g., 0xff0000 for red)
+   */
+  toHex(): number {
+    return this.#color.getHex();
+  }
+
+  /**
+   * Gets the underlying Three.js Color instance.
+   */
+  get raw() {
+    return this.#color;
+  }
+}

package/src/ShadowMapViewers.ts

@@ -0,0 +1,49 @@
+import { CascadedDirectionalLights } from "@navaramap/three_csm";
+import type { WebGLRenderer } from "three";
+import { ShadowMapViewer } from "three-stdlib";
+
+import type { Scenes } from "./scene";
+
+export class ShadowMapViewers {
+  viewers: ShadowMapViewer[] = [];
+  lights: Scenes["light"];
+  enabled = false;
+
+  constructor(lights: Scenes["light"]) {
+    this.lights = lights;
+  }
+
+  render(renderer: WebGLRenderer) {
+    if (!this.enabled || !renderer.shadowMap.enabled) return;
+
+    // Create shadow map viewers for debugging
+    const csm = this.lights.children.find(
+      (c) => c instanceof CascadedDirectionalLights,
+    );
+
+    if (
+      this.viewers.length &&
+      csm?.cascadedLights.length === this.viewers.length
+    ) {
+      this.viewers.forEach((viewer) => {
+        if (viewer) {
+          viewer.render(renderer);
+        }
+      });
+      return;
+    }
+
+    this.viewers.length = 0;
+
+    if (!csm) return;
+    const lights = csm.cascadedLights;
+    lights.forEach((light, i) => {
+      if (light.shadow.map && light.shadow.map.texture) {
+        const viewer = new ShadowMapViewer(light);
+        viewer.position.set(0, 100 * i);
+        viewer.size.set(100, 100);
+        this.viewers.push(viewer);
+      }
+    });
+  }
+}

package/src/atmosphere.test.ts

@@ -0,0 +1,76 @@
+import type { WebGLRenderer } from "three";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { Atmosphere } from "./atmosphere";
+
+const { loadAsyncMock } = vi.hoisted(() => ({
+  loadAsyncMock: vi.fn(),
+}));
+
+vi.mock("@takram/three-atmosphere", () => ({
+  PrecomputedTexturesLoader: class {
+    setType() {
+      return this;
+    }
+    loadAsync = loadAsyncMock;
+  },
+  getSunDirectionECEF: vi.fn(),
+  getMoonDirectionECEF: vi.fn(),
+  getECIToECEFRotationMatrix: vi.fn(),
+}));
+
+const createAtmosphere = () =>
+  new Atmosphere({} as unknown as WebGLRenderer, { date: new Date(0) });
+
+const fakeTextures = () => ({}) as never;
+
+describe("Atmosphere.initTextures", () => {
+  beforeEach(() => {
+    loadAsyncMock.mockReset();
+  });
+
+  it("shares a single load across concurrent calls", async () => {
+    loadAsyncMock.mockResolvedValue(fakeTextures());
+    const atmosphere = createAtmosphere();
+
+    await Promise.all([atmosphere.initTextures(), atmosphere.initTextures()]);
+
+    expect(loadAsyncMock).toHaveBeenCalledTimes(1);
+    expect(atmosphere.textures).toBeDefined();
+  });
+
+  it("returns immediately once textures are loaded", async () => {
+    loadAsyncMock.mockResolvedValue(fakeTextures());
+    const atmosphere = createAtmosphere();
+
+    await atmosphere.initTextures();
+    await atmosphere.initTextures();
+
+    expect(loadAsyncMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("emits textureLoaded exactly once", async () => {
+    loadAsyncMock.mockResolvedValue(fakeTextures());
+    const atmosphere = createAtmosphere();
+    const onLoaded = vi.fn();
+    atmosphere.on("textureLoaded", onLoaded);
+
+    await Promise.all([atmosphere.initTextures(), atmosphere.initTextures()]);
+
+    expect(onLoaded).toHaveBeenCalledTimes(1);
+  });
+
+  it("allows retrying after a failed load", async () => {
+    loadAsyncMock.mockRejectedValueOnce(new Error("network error"));
+    loadAsyncMock.mockResolvedValueOnce(fakeTextures());
+    const atmosphere = createAtmosphere();
+
+    await expect(atmosphere.initTextures()).rejects.toThrow("network error");
+    expect(atmosphere.textures).toBeUndefined();
+
+    await atmosphere.initTextures();
+
+    expect(loadAsyncMock).toHaveBeenCalledTimes(2);
+    expect(atmosphere.textures).toBeDefined();
+  });
+});

package/src/atmosphere.ts

@@ -0,0 +1,364 @@
+import { EventHandler, Observed, type XYZ } from "@navaramap/core";
+import {
+  getECIToECEFRotationMatrix,
+  getMoonDirectionECEF,
+  getSunDirectionECEF,
+  PrecomputedTexturesLoader,
+  type AtmosphereOverlay,
+  type AtmosphereShadow,
+  type AtmosphereShadowLength,
+  type PrecomputedTextures,
+} from "@takram/three-atmosphere";
+import { Vector3, Matrix4, type WebGLRenderer } from "three";
+import invariant from "tiny-invariant";
+
+import { type ThreeViewCamera } from "./camera";
+import { ATMOSPHERE_ASSETS_URL, STBN_URL } from "./constants";
+import { shiftDateToElevation, shiftDateToHourAngle } from "./solar";
+
+/**
+ * Events emitted by the {@link Atmosphere} class.
+ */
+export type AtmosphereEvents = {
+  /** Emitted when the atmosphere needs to trigger a re-render. */
+  needsUpdate: () => void;
+  /** Emitted when precomputed atmosphere textures have been loaded. */
+  textureLoaded: () => void;
+  /** Emitted when the atmosphere is disposed. */
+  disposed: () => void;
+  /** Emitted when the sun direction changes. */
+  sunChanged: (sunDirection: Vector3) => void;
+};
+
+/**
+ * Configuration options for the {@link Atmosphere} class.
+ */
+export type AtmosphereOptions = {
+  /** URL to load precomputed atmosphere textures from. */
+  atmosphereAssetsUrl?: string;
+  /** URL to load STBN (Spatio-Temporal Blue Noise) textures from. */
+  stbnUrl?: string;
+  /** Date used for calculating sun/moon positions. Defaults to current date. */
+  date?: Date;
+};
+
+/**
+ * Default values for {@link AtmosphereOptions}.
+ */
+export const DEFAULT_ATMOSPHERE_OPTIONS: Required<AtmosphereOptions> = {
+  atmosphereAssetsUrl: ATMOSPHERE_ASSETS_URL,
+  stbnUrl: STBN_URL,
+  date: new Date(),
+};
+
+/**
+ * Context for atmosphere rendering.
+ *
+ * Manages sun/moon positions, precomputed atmosphere textures, and related state.
+ * Some variables are shared with Clouds and AerialPerspective.
+ */
+export class Atmosphere extends EventHandler<AtmosphereEvents> {
+  /**
+   * @private
+   */
+  private renderer: WebGLRenderer;
+
+  /**
+   * Current sun direction in ECEF coordinates.
+   */
+  sunDirection = new Vector3();
+
+  /**
+   * Current moon direction in ECEF coordinates.
+   */
+  moonDirection = new Vector3();
+
+  /**
+   * @private
+   */
+  private rotationMatrix = new Matrix4();
+
+  /**
+   * Precomputed atmosphere textures used for rendering.
+   * Loaded asynchronously via {@link initTextures}.
+   */
+  textures?: PrecomputedTextures;
+
+  // Variables that come from Clouds.
+  overlay = new Observed<AtmosphereOverlay | null>(null);
+  shadow = new Observed<AtmosphereShadow | null>(null);
+  shadowLength = new Observed<AtmosphereShadowLength | null>(null);
+  enableShadows = new Observed<boolean>(true);
+
+  /**
+   * @private
+   */
+  private needsUpdate = false;
+
+  /**
+   * @private
+   */
+  private options: AtmosphereOptions;
+
+  /**
+   * @private
+   */
+  private _camera: ThreeViewCamera | undefined;
+
+  /**
+   * In-flight texture loading promise, shared across concurrent
+   * {@link initTextures} calls so the assets are fetched only once.
+   * @private
+   */
+  private texturesPromise: Promise<void> | undefined;
+
+  /**
+   * Creates a new Atmosphere instance.
+   * @param renderer - The WebGL renderer used for texture type detection.
+   * @param options - Configuration options for the atmosphere.
+   * @param camera - Camera reference used by {@link setDateAt}.
+   */
+  constructor(
+    renderer: WebGLRenderer,
+    options: AtmosphereOptions = {},
+    camera?: ThreeViewCamera,
+  ) {
+    super();
+
+    this.renderer = renderer;
+    this.options = { ...DEFAULT_ATMOSPHERE_OPTIONS, ...options };
+    this._camera = camera;
+
+    this.onUpdate();
+  }
+
+  /**
+   * Marks the atmosphere as needing an update.
+   * @private
+   */
+  onUpdate = () => {
+    this.needsUpdate = true;
+    this.emit("needsUpdate");
+  };
+
+  /**
+   * Loads precomputed atmosphere textures asynchronously.
+   * If textures are already loaded, this method returns immediately.
+   * @returns A promise that resolves when textures are loaded.
+   */
+  // TODO: Add an option to disable loading textures.
+  async initTextures() {
+    if (this.textures) return;
+
+    this.texturesPromise ??= new PrecomputedTexturesLoader()
+      .setType(this.renderer)
+      .loadAsync(
+        this.options.atmosphereAssetsUrl ??
+          DEFAULT_ATMOSPHERE_OPTIONS.atmosphereAssetsUrl,
+      )
+      .then((textures) => {
+        this.textures = textures;
+        this.emit("textureLoaded");
+      })
+      .finally(() => {
+        // Allow retrying after a failed load instead of caching the rejection.
+        this.texturesPromise = undefined;
+      });
+
+    await this.texturesPromise;
+  }
+
+  /**
+   * @private
+   */
+  async _init() {
+    await this.initTextures();
+  }
+
+  /**
+   * @private
+   */
+  _dispose() {
+    if (this.textures) {
+      this.textures.irradianceTexture.dispose();
+      this.textures.scatteringTexture.dispose();
+      this.textures.transmittanceTexture.dispose();
+      this.textures.singleMieScatteringTexture?.dispose();
+      this.textures.higherOrderScatteringTexture?.dispose();
+      this.textures = undefined;
+    }
+    this.emit("disposed");
+  }
+
+  /**
+   * Invokes the callback with precomputed textures immediately if already loaded,
+   * or registers a one-time listener to invoke it once textures are ready.
+   */
+  onTexturesReady(callback: (textures: PrecomputedTextures) => void): void {
+    if (this.textures) {
+      callback(this.textures);
+    } else {
+      this.once("textureLoaded", () => {
+        invariant(this.textures);
+        callback(this.textures);
+      });
+    }
+  }
+
+  /**
+   * Returns a clone of the current sun direction vector.
+   * @returns A new Vector3 representing the sun direction in ECEF coordinates.
+   */
+  getSunDirection(): Vector3 {
+    return this.sunDirection.clone();
+  }
+
+  /**
+   * Returns a clone of the current moon direction vector.
+   * @returns A new Vector3 representing the moon direction in ECEF coordinates.
+   */
+  getMoonDirection(): Vector3 {
+    return this.moonDirection.clone();
+  }
+
+  /**
+   * Returns a clone of the ECI to ECEF rotation matrix.
+   * @returns A new Matrix4 representing the rotation from ECI to ECEF coordinates.
+   */
+  getRotationMatrix(): Matrix4 {
+    return this.rotationMatrix.clone();
+  }
+
+  /**
+   * Updates sun/moon directions and rotation matrix if needed.
+   * @private
+   */
+  _update() {
+    if (this.needsUpdate) {
+      getSunDirectionECEF(this.date, this.sunDirection);
+      getMoonDirectionECEF(this.date, this.moonDirection);
+      getECIToECEFRotationMatrix(this.date, this.rotationMatrix);
+
+      this.emit("sunChanged", this.sunDirection.clone());
+    }
+
+    this.needsUpdate = false;
+  }
+
+  /**
+   * Determines whether a given position is on the night side of the Earth.
+   * @param position - The position in ECEF coordinates to check.
+   * @returns `true` if the position is on the night side, `false` otherwise.
+   */
+  isAtNight(position: XYZ): boolean {
+    const normalizedPosition = new Vector3(position.x, position.y, position.z)
+      .clone()
+      .normalize();
+    const dotProduct = normalizedPosition.dot(this.sunDirection);
+    return dotProduct < 0;
+  }
+
+  /**
+   * Gets the current date used for calculating sun/moon positions.
+   */
+  get date() {
+    return this.options.date ?? DEFAULT_ATMOSPHERE_OPTIONS.date;
+  }
+
+  /**
+   * Sets the date used for calculating sun/moon positions.
+   * Triggers an update to recalculate celestial body directions.
+   */
+  set date(v: Date) {
+    this.options.date = v;
+    this.onUpdate();
+  }
+
+  /**
+   * Adjusts `atmosphere.date` so that the local solar time at `to` matches the
+   * local solar time at `from`.
+   *
+   * The calculation is based on the sun's hour angle, which increases
+   * monotonically over a solar day, giving exactly one solution per day with no
+   * morning/afternoon ambiguity. The equation of time is accounted for
+   * automatically.
+   *
+   * @example
+   * // atmosphere.date shows 08:00 local solar time at Tokyo.
+   * view.atmosphere.setDateAt({ lng: 139.69 }, { lng: 0 });
+   * // → atmosphere.date is now 08:00 local solar time at London
+   *
+   * @param from - Source location. Only `lng` (degrees) affects the result.
+   * @param to   - Target location. Only `lng` (degrees) affects the result.
+   */
+  setDateAt(
+    from: { lng: number; lat?: number },
+    to: { lng: number; lat?: number },
+  ): void {
+    this.date = shiftDateToHourAngle(this.date, from.lng, to.lng, to.lat);
+  }
+
+  /**
+   * Adjusts `atmosphere.date` so that the sun elevation at `to` matches the
+   * sun elevation at `from`.
+   *
+   * Morning/afternoon context is preserved. If the target elevation cannot be
+   * reached at `to` (e.g. polar night), the date is clamped to solar noon
+   * there.
+   *
+   * @example
+   * // atmosphere.date shows sun at 30° elevation over Tokyo.
+   * view.atmosphere.setElevationAt({ lat: 35.68, lng: 139.69 }, { lat: 51.5, lng: -0.12 });
+   * // → atmosphere.date adjusted so sun is also at 30° elevation over London
+   *
+   * @param from - Source location (both `lat` and `lng` required).
+   * @param to   - Target location (both `lat` and `lng` required).
+   */
+  setElevationAt(
+    from: { lat: number; lng: number },
+    to: { lat: number; lng: number },
+  ): void {
+    this.date = shiftDateToElevation(
+      this.date,
+      from.lat,
+      from.lng,
+      to.lat,
+      to.lng,
+    );
+  }
+
+  /**
+   * Convenience wrapper for {@link setDateAt} that uses the camera position as
+   * `from`.
+   *
+   * @example
+   * // Camera is over Tokyo showing 08:00 local solar time.
+   * view.atmosphere.setDateFromCameraAt({ lng: 0 }); // adjust to London
+   * // → atmosphere.date is now 08:00 local solar time at London
+   *
+   * @param to - Target location. Only `lng` (degrees) affects the result.
+   */
+  setDateFromCameraAt(to: { lng: number; lat?: number }): void {
+    const { lng: fromLng } = this._camera?.positionGeographic ?? { lng: 0 };
+    this.setDateAt({ lng: fromLng }, to);
+  }
+
+  /**
+   * Convenience wrapper for {@link setElevationAt} that uses the camera
+   * position as `from`.
+   *
+   * @example
+   * // Camera is over Tokyo with sun at 30° elevation.
+   * view.atmosphere.setElevationFromCameraAt({ lat: 51.5, lng: -0.12 }); // adjust to London
+   * // → atmosphere.date adjusted so sun is also at 30° elevation over London
+   *
+   * @param to - Target location (both `lat` and `lng` required).
+   */
+  setElevationFromCameraAt(to: { lat: number; lng: number }): void {
+    const { lng: fromLng, lat: fromLat } = this._camera?.positionGeographic ?? {
+      lng: 0,
+      lat: 0,
+    };
+    this.setElevationAt({ lat: fromLat, lng: fromLng }, to);
+  }
+}