@navaramap/three 0.0.0

package/src/bufferView.ts

@@ -0,0 +1,90 @@
+import type { WebGLRenderer, WebGLRenderTarget } from "three";
+
+export class BufferView {
+  canvas: HTMLCanvasElement;
+  canvasForImage: HTMLCanvasElement;
+  constructor(
+    width: number,
+    height: number,
+    {
+      styleWidth = "300px",
+      styleHeight = "auto",
+    }: { styleWidth?: string; styleHeight?: string } = {},
+  ) {
+    this.canvas = document.createElement("canvas");
+    this.canvas.width = width;
+    this.canvas.height = height;
+    this.canvas.style.width = styleWidth;
+    this.canvas.style.height = styleHeight;
+    this.canvas.style.position = "absolute";
+    this.canvas.style.top = "0px";
+    this.canvas.style.left = "0px";
+    this.canvas.style.zIndex = "1000";
+    this.canvas.style.pointerEvents = "none";
+    document.body.appendChild(this.canvas);
+
+    this.canvasForImage = document.createElement("canvas");
+    this.canvasForImage.width = width;
+    this.canvasForImage.height = height;
+  }
+
+  render(renderer: WebGLRenderer, renderTarget: WebGLRenderTarget) {
+    const width = renderTarget.width;
+    const height = renderTarget.height;
+    const pixelBuffer = new Uint8Array(width * height * 4);
+    renderer.readRenderTargetPixels(
+      renderTarget,
+      0,
+      0,
+      width,
+      height,
+      pixelBuffer,
+    );
+    this.drawPixels(pixelBuffer, width, height);
+  }
+
+  /**
+   * Render from raw pixel data (Uint8Array RGBA).
+   * Use this for HalfFloat MRT attachments where readRenderTargetPixels doesn't work.
+   */
+  renderFromPixels(pixels: Uint8Array, width: number, height: number) {
+    this.drawPixels(pixels, width, height);
+  }
+
+  private drawPixels(pixelBuffer: Uint8Array, width: number, height: number) {
+    const ctx = this.canvas.getContext("2d");
+    if (!ctx) return;
+
+    // Clear canvas before drawing (fix for stale content from previous frames)
+    ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+
+    // Resize temp canvas to match source data
+    if (
+      this.canvasForImage.width !== width ||
+      this.canvasForImage.height !== height
+    ) {
+      this.canvasForImage.width = width;
+      this.canvasForImage.height = height;
+    }
+
+    const imageData = ctx.createImageData(width, height);
+    imageData.data.set(pixelBuffer);
+
+    const tempCtx = this.canvasForImage.getContext("2d");
+    if (!tempCtx) return;
+    tempCtx.putImageData(imageData, 0, 0);
+
+    // Flip Y and scale from source size to display canvas size
+    const cw = this.canvas.width;
+    const ch = this.canvas.height;
+    ctx.translate(0, ch);
+    ctx.scale(1, -1);
+    ctx.drawImage(this.canvasForImage, 0, 0, cw, ch);
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+  }
+
+  dispose() {
+    this.canvas.remove();
+    this.canvasForImage.remove();
+  }
+}

package/src/camera.ts

@@ -0,0 +1,182 @@
+import {
+  EventHandler,
+  type CameraOrientation,
+  type LatLngHeight,
+  type NormalizeWASMClass,
+  type XYZ,
+} from "@navaramap/core";
+import {
+  Core,
+  CameraStatus,
+  CameraStatusType,
+  CameraControlUpdateEvent,
+} from "@navaramap/engine";
+import { PerspectiveCamera } from "three";
+import invariant from "tiny-invariant";
+
+export type CameraEvent = {
+  movestart: () => void;
+  move: () => void;
+  moveend: () => void;
+  frustumChanged: () => void;
+};
+
+export type CameraOptions = NormalizeWASMClass<CameraControlUpdateEvent>;
+
+export class ThreeViewCamera extends EventHandler<CameraEvent> {
+  raw: PerspectiveCamera;
+
+  private _core: Core | undefined;
+  private _status: CameraStatus | undefined;
+
+  constructor(cam?: PerspectiveCamera) {
+    super();
+    if (cam instanceof PerspectiveCamera) {
+      this.raw = cam;
+    } else {
+      this.raw = new PerspectiveCamera();
+    }
+  }
+
+  set core(core: Core | undefined) {
+    this._core = core;
+  }
+
+  updateStatus() {
+    this._status = this._core?.getCameraStatus();
+    if (!this._status) {
+      return;
+    }
+
+    for (const val of this._status.status) {
+      switch (val) {
+        case CameraStatusType.MoveStart:
+          this.emit("movestart");
+          break;
+        case CameraStatusType.Moving:
+          this.emit("move");
+          break;
+        case CameraStatusType.MoveEnd:
+        case CameraStatusType.LookAt:
+        case CameraStatusType.Rotate:
+          this.emit("moveend");
+          break;
+        default:
+          break;
+      }
+    }
+  }
+
+  get positionECEF(): XYZ {
+    const pos = this._core?.getCameraPositionECEF();
+    invariant(pos);
+    return {
+      x: pos[0],
+      y: pos[1],
+      z: pos[2],
+    };
+  }
+
+  get positionGeographic(): LatLngHeight {
+    const pos = this._core?.getCameraPositionLLE();
+    invariant(pos);
+    return {
+      lng: pos[0],
+      lat: pos[1],
+      height: pos[2],
+    };
+  }
+
+  get orientation(): CameraOrientation {
+    const orientation = this._core?.getCameraOrientation();
+    invariant(orientation);
+    return {
+      heading: orientation.heading,
+      pitch: orientation.pitch,
+      roll: orientation.roll,
+    };
+  }
+
+  get fovy(): number | undefined {
+    return this._core?.getCameraFOVY();
+  }
+
+  /**
+   * Effective Web Mercator zoom level the camera is viewing the surface at
+   * (fractional). Computed engine-side from the camera's ellipsoid height (not
+   * terrain), FOV and viewport.
+   */
+  get zoom(): number | undefined {
+    return this._core?.getZoomLevel();
+  }
+
+  set fov(val: number) {
+    if (val < 1 || val > 180) {
+      return;
+    }
+
+    this._core?.setFrustum(val, undefined, undefined);
+  }
+
+  set near(val: number) {
+    if (val <= 0) {
+      return;
+    }
+
+    this._core?.setFrustum(undefined, val, undefined);
+  }
+
+  get near() {
+    return this.raw.near;
+  }
+
+  set far(val: number) {
+    if (val <= this.raw.near) {
+      return;
+    }
+
+    this._core?.setFrustum(undefined, undefined, val);
+  }
+
+  get far() {
+    return this.raw.far;
+  }
+
+  set options(options: CameraOptions) {
+    const event = new CameraControlUpdateEvent();
+    if (options.autoAdjustNearFar !== undefined) {
+      event.autoAdjustNearFar = options.autoAdjustNearFar;
+    }
+    if (options.minimumZoomDistance !== undefined) {
+      event.minimumZoomDistance = options.minimumZoomDistance;
+    }
+    if (options.maximumZoomDistance !== undefined) {
+      event.maximumZoomDistance = options.maximumZoomDistance;
+    }
+    if (options.spinSpeed !== undefined) {
+      event.spinSpeed = options.spinSpeed;
+    }
+    if (options.zoomSpeed !== undefined) {
+      event.zoomSpeed = options.zoomSpeed;
+    }
+    if (options.spinDuration !== undefined) {
+      event.spinDuration = options.spinDuration;
+    }
+    if (options.zoomDuration !== undefined) {
+      event.zoomDuration = options.zoomDuration;
+    }
+    if (options.translateDuration !== undefined) {
+      event.translateDuration = options.translateDuration;
+    }
+    if (options.enableSpin !== undefined) {
+      event.enableSpin = options.enableSpin;
+    }
+    if (options.enableZoom !== undefined) {
+      event.enableZoom = options.enableZoom;
+    }
+    if (options.enableTilt !== undefined) {
+      event.enableTilt = options.enableTilt;
+    }
+    this._core?.setCameraControl(event);
+  }
+}

package/src/concurrency.ts

@@ -0,0 +1,15 @@
+import { createConcurrencyManager } from "@navaramap/worker";
+
+/** Maximum workers on mobile: limits thermal throttling AND peak memory —
+ * every busy worker's WASM heap ratchets to its decode working set, so a
+ * camera-move burst costs up to `workers × maxWorkerHeapBytes`. Two workers
+ * halve that peak versus four at the cost of decode throughput. */
+const MOBILE_MAX_WORKERS = 2;
+
+export const createDefaultConcurrencyManager = (mobileOptimized: boolean) => {
+  const hardwareConcurrency = Math.max(navigator.hardwareConcurrency, 1);
+  const totalConcurrency = mobileOptimized
+    ? Math.min(hardwareConcurrency, MOBILE_MAX_WORKERS)
+    : hardwareConcurrency;
+  return createConcurrencyManager(totalConcurrency);
+};

package/src/constants/assets.ts

@@ -0,0 +1,30 @@
+export const ATMOSPHERE_ASSETS_URL = new URL(
+  `${import.meta.env.BASE_URL}assets/atmosphere`,
+  import.meta.url,
+).toString();
+
+export const CLOUD_ASSETS_URL = new URL(
+  `${import.meta.env.BASE_URL}assets/cloud`,
+  import.meta.url,
+).toString();
+
+export const NOISE_ASSETS_URL = new URL(
+  `${import.meta.env.BASE_URL}assets/noise`,
+  import.meta.url,
+).toString();
+
+export const RAIN_ASSETS_URL = new URL(
+  `${import.meta.env.BASE_URL}assets/rain`,
+  import.meta.url,
+).toString();
+
+export const WATER_ASSETS_URL = new URL(
+  `${import.meta.env.BASE_URL}assets/water`,
+  import.meta.url,
+).toString();
+
+export const STARS_ASSETS_URL = `${ATMOSPHERE_ASSETS_URL}/stars.bin`;
+
+export const STBN_URL = `${NOISE_ASSETS_URL}/stbn.bin`;
+
+export const WATER_NORMAL_URL = `${WATER_ASSETS_URL}/waternormals.jpg`;

package/src/constants/decoder.ts

@@ -0,0 +1,7 @@
+import { ElevationDecoder } from "@navaramap/engine";
+
+// Evaluate them lazily because we need to wait until WASM module is ready.
+// If we can use top-level-await, we don't need to do it.
+export const JAPAN_GSI_ELEVATION_DECODER = () => ElevationDecoder.japanGSI();
+export const MAPBOX_ELEVATION_DECODER = () => ElevationDecoder.mapbox();
+export const TERRARIUM_ELEVATION_DECODER = () => ElevationDecoder.terrarium();

package/src/constants/index.ts

@@ -0,0 +1,2 @@
+export * from "./assets";
+export * from "./decoder";

package/src/core/BaseDesc.ts

@@ -0,0 +1,142 @@
+import { EventHandler, type BaseEventMap } from "@navaramap/core";
+import { generateId } from "@navaramap/engine";
+
+import type ThreeView from "../index";
+
+import type { ViewContext } from "./ViewContext";
+
+/**
+ * Base configuration options common to all descriptors.
+ */
+export type BaseDescConfig = {
+  /** Optional custom ID. Auto-generated if not provided. */
+  id?: string;
+  /** Whether the descriptor is visible. Defaults to true. */
+  visible?: boolean;
+};
+
+/**
+ * Configuration properties that can be updated after creation.
+ */
+export type BaseDescConfigUpdate = Pick<BaseDescConfig, "visible">;
+
+/**
+ * Base interface for the underlying Three.js instance created by a descriptor.
+ */
+export type BaseInstance = { visible: boolean };
+
+/**
+ * Internal events emitted by BaseDesc.
+ */
+export type BaseDescEvents = {
+  /** @internal Emitted when the descriptor needs to trigger a re-render. */
+  needsUpdate: () => void;
+};
+
+/**
+ * Abstract base class for descriptors (mesh, light, and effect descriptors).
+ * Extend this class to create custom descriptor types.
+ *
+ * Descriptors differ from resource layers in that they are purely client-side
+ * and don't load data from external sources. They create Three.js objects directly.
+ *
+ * @typeParam Config - Configuration type for the descriptor (extends BaseDescConfig)
+ * @typeParam UpdateConfig - Configuration properties that can be updated (extends BaseDescConfigUpdate)
+ * @typeParam Instance - The underlying Three.js object type created by the descriptor
+ * @typeParam CustomEvent - Additional custom events the descriptor can emit
+ *
+ * @example
+ * ```typescript
+ * // Creating a custom mesh desc
+ * class MyCustomMeshDesc extends BaseDesc<MyConfig, MyUpdateConfig, Mesh> {
+ *   onCreate() {
+ *     const geometry = new BoxGeometry(1, 1, 1);
+ *     const material = new MeshBasicMaterial();
+ *     this._instance = new Mesh(geometry, material);
+ *     this.ctx.scenes.opaque.add(this._instance);
+ *   }
+ * }
+ * ```
+ */
+export abstract class BaseDesc<
+  Config extends BaseDescConfig = BaseDescConfig,
+  UpdateConfig extends BaseDescConfigUpdate = BaseDescConfigUpdate,
+  Instance extends BaseInstance = BaseInstance,
+  CustomEvent extends BaseEventMap = BaseEventMap,
+> extends EventHandler<BaseDescEvents & CustomEvent> {
+  /** The unique identifier. */
+  public readonly id: string;
+
+  /** The ThreeView instance providing access to camera, atmosphere, globe, and other view state. */
+  protected view: ThreeView;
+  /** The view context providing access to scenes, passes, and rendering internals. */
+  protected ctx: ViewContext;
+  /** The underlying Three.js instance. */
+  protected _instance: Instance | undefined;
+
+  private _visible?: boolean;
+
+  constructor(
+    view: ThreeView,
+    ctx: ViewContext,
+    config: Config = {} as Config,
+  ) {
+    super();
+
+    this.id = config.id || generateId();
+    this._visible = config.visible ?? true;
+    this.view = view;
+    this.ctx = ctx;
+  }
+
+  /**
+   * Called when the this class is added to the scene. Override this to create the Three.js objects.
+   * This is where you should initialize `this._instance` and add it to the appropriate scene.
+   */
+  abstract onCreate(): void;
+
+  /**
+   * Called when the configuration is updated via `BaseHandle.update()`.
+   * Override this to handle custom configuration updates.
+   * @param updates - The configuration properties being updated
+   */
+  onUpdateConfig(updates: UpdateConfig) {
+    if (updates.visible !== undefined) {
+      this._visible = updates.visible;
+      if (this._instance) {
+        this._instance.visible = updates.visible;
+      }
+    }
+
+    this.requestUpdate();
+  }
+
+  protected requestUpdate(): void {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    this.emit("needsUpdate");
+  }
+
+  /**
+   * Called when deleted via `BaseHandle.delete()`.
+   * Override this to clean up resources. Remember to call `super.onDestroy()`.
+   */
+  onDestroy(): void {
+    this._instance = undefined;
+  }
+
+  /**
+   * Gets whether this is currently visible.
+   */
+  get visible() {
+    return !!this._visible;
+  }
+
+  /**
+   * Sets whether this should be visible.
+   */
+  set visible(v: boolean) {
+    this._visible = v;
+    this.onUpdateConfig({ visible: v } as UpdateConfig);
+  }
+}

package/src/core/BaseHandle.ts

@@ -0,0 +1,126 @@
+import { EventHandler } from "@navaramap/core";
+
+import { BaseDesc, type BaseDescConfigUpdate } from "./BaseDesc";
+import type { EffectDesc } from "./EffectDesc";
+import type { LightDesc } from "./LightDesc";
+import type { MeshDesc } from "./MeshDesc";
+
+/** The mesh descriptor hierarchy. */
+export type AnyMeshDesc = MeshDesc;
+
+/**
+ * Events emitted by handles.
+ */
+export type HandleEvent = {
+  /** Emitted when the descriptor is deleted. */
+  deleted: () => void;
+};
+
+/**
+ * Abstract base handle to control a descriptor after it has been added to the scene.
+ *
+ * Use the typed subclasses instead:
+ * - {@link MeshHandle} - returned by `ThreeView.addMesh()`
+ * - {@link LightHandle} - returned by `ThreeView.addLight()`
+ * - {@link EffectHandle} - returned by `ThreeView.addEffect()`
+ *
+ * @typeParam T - The specific descriptor type
+ */
+export class BaseHandle<
+  T extends BaseDesc = BaseDesc,
+> extends EventHandler<HandleEvent> {
+  constructor(private desc: T) {
+    super();
+  }
+
+  /**
+   * Updates the descriptor configuration with partial updates.
+   * Only the specified properties will be changed; others remain unchanged.
+   * @param updates - Partial configuration object with properties to update
+   */
+  update(
+    updates: T extends BaseDesc<infer _A, infer B> ? B : BaseDescConfigUpdate,
+  ): void {
+    this.desc.onUpdateConfig(updates);
+  }
+
+  /**
+   * Gets direct access to the underlying descriptor instance.
+   * Use this to access descriptor-specific methods and properties not exposed through the handle.
+   */
+  get ref(): T {
+    return this.desc;
+  }
+
+  /**
+   * Removes the descriptor from the scene and disposes its resources.
+   * After calling this, the handle should no longer be used.
+   */
+  delete(): void {
+    if (this._deleted) return;
+    this._deleted = true;
+    this.desc.onDestroy();
+    this.emit("deleted");
+  }
+
+  private _deleted = false;
+
+  /**
+   * Gets the unique identifier.
+   */
+  get id(): string {
+    return this.desc.id;
+  }
+
+  /**
+   * Gets whether the descriptor is currently visible in the scene.
+   */
+  get visible(): boolean {
+    return this.desc.visible;
+  }
+
+  /**
+   * Sets whether the descriptor should be visible in the scene.
+   * @param visible - True to show, false to hide
+   */
+  set visible(visible: boolean) {
+    this.desc.visible = visible;
+  }
+}
+
+/**
+ * A handle to control a mesh descriptor after it has been added to the scene.
+ * Returned by `ThreeView.addMesh()`.
+ *
+ * @typeParam T - The specific mesh descriptor type (e.g., BoxMeshDesc)
+ *
+ * @example
+ * ```typescript
+ * const handle = view.addMesh<BoxMeshDesc>({ box: { width: 100 } });
+ * handle.update({ box: { width: 200 } });
+ * handle.delete();
+ * ```
+ */
+export class MeshHandle<
+  T extends AnyMeshDesc = AnyMeshDesc,
+> extends BaseHandle<T> {}
+
+/**
+ * A handle to control a light descriptor after it has been added to the scene.
+ * Returned by `ThreeView.addLight()`.
+ *
+ * @typeParam T - The specific light descriptor type (e.g., SunLightDesc)
+ */
+export class LightHandle<
+  T extends LightDesc = LightDesc,
+> extends BaseHandle<T> {}
+
+/**
+ * A handle to control an effect descriptor after it has been added to the scene.
+ * Returned by `ThreeView.addEffect()`.
+ *
+ * @typeParam T - The specific effect descriptor type (e.g., SSAOEffectDesc)
+ */
+export class EffectHandle<
+  T extends EffectDesc = EffectDesc,
+> extends BaseHandle<T> {}

package/src/core/DescRegistry.ts

@@ -0,0 +1,88 @@
+import type ThreeView from "../index";
+
+import type { ViewContext } from "./ViewContext";
+
+/**
+ * Base abstract class for all registry types in the Navara system.
+ * Provides common functionality for registering, creating, and managing different types of components.
+ */
+export abstract class DescRegistry<
+  TConstructor,
+  TInstance,
+  TConfig extends Record<string, unknown> = Record<string, unknown>,
+> {
+  protected registry = new Map<string, TConstructor>();
+
+  constructor(
+    public view: ThreeView,
+    public ctx: ViewContext,
+  ) {}
+
+  /**
+   * Register a new type with the given name and constructor
+   */
+  register(name: string, constructor: TConstructor): void {
+    this.registry.set(name, constructor);
+  }
+
+  /**
+   * Unregister a type by name
+   */
+  unregister(name: string): boolean {
+    return this.registry.delete(name);
+  }
+
+  /**
+   * Check if a type is registered
+   */
+  has(name: string): boolean {
+    return this.registry.has(name);
+  }
+
+  /**
+   * Get all registered type names
+   */
+  getRegisteredTypes(): string[] {
+    return Array.from(this.registry.keys());
+  }
+
+  /**
+   * Get the number of registered types
+   */
+  size(): number {
+    return this.registry.size;
+  }
+
+  /**
+   * Clear all registered types
+   */
+  clear(): void {
+    this.registry.clear();
+  }
+
+  /**
+   * Create an instance of the specified type with the given configuration
+   * Must be implemented by subclasses
+   */
+  abstract create(name: string, config: TConfig): TInstance;
+
+  /**
+   * Find a type name from a configuration object
+   * Useful for auto-detecting type from config keys
+   */
+  findTypeFromConfig(config: Record<string, unknown>): string | null {
+    for (const key of Object.keys(config)) {
+      if (this.registry.has(key)) {
+        return key;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Get constructor by name (protected method for subclasses)
+   */
+  protected getConstructor(name: string): TConstructor | undefined {
+    return this.registry.get(name);
+  }
+}