@navaramap/three-plugins 0.0.0

package/src/CesiumIonPlugin.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+
+import { CesiumIonPlugin } from "./CesiumIonPlugin";
+
+// Importing the real @navaramap/three touches WASM/os at module load, which fails
+// in the test environment. CesiumIonPlugin only needs `Plugin` as a runtime base
+// class (everything else it imports is type-only), so stub the module.
+/* eslint-disable @typescript-eslint/no-extraneous-class */
+vi.mock("@navaramap/three", () => ({
+  default: class ThreeView {},
+  Plugin: class Plugin {},
+}));
+/* eslint-enable @typescript-eslint/no-extraneous-class */
+
+// A minimal fake of the pieces of ThreeView / Source / Layer that
+// CesiumIonPlugin.addTerrain touches. It records the descriptions passed to
+// addSource/addLayer and lets a test fire the layer's "deleted" event.
+function makeFakeView() {
+  const source = {
+    id: "src",
+    type: "quantized-mesh",
+    delete: vi.fn(() => true),
+  };
+  let onDeleted: (() => void) | undefined;
+  const layer = {
+    id: "layer",
+    once: vi.fn((event: string, cb: () => void) => {
+      if (event === "deleted") onDeleted = cb;
+    }),
+    // Deleting the layer emits "deleted", mirroring the real Layer.
+    delete: vi.fn(() => onDeleted?.()),
+  };
+  const view = {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    addSource: vi.fn((_desc: any) => source),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    addLayer: vi.fn((_desc: any) => layer),
+  };
+  return { view, source, layer };
+}
+
+async function initPlugin(view: unknown) {
+  const plugin = new CesiumIonPlugin({ assetId: 42, accessToken: "user-tok" });
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () => ({
+      ok: true,
+      json: async () => ({
+        url: "https://tiles.example/",
+        accessToken: "asset-tok",
+      }),
+    })),
+  );
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  await plugin.init(view as any, {} as any);
+  return plugin;
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("CesiumIonPlugin.addTerrain", () => {
+  it("routes fetch options to the source and render options to the layer", async () => {
+    const { view, source } = makeFakeView();
+    const plugin = await initPlugin(view);
+
+    plugin.addTerrain({
+      maxZoom: 14,
+      requestVertexNormals: true,
+      castShadow: true,
+    });
+
+    // Source carries the resolved endpoint URL/token and the fetch options,
+    // but not the render options.
+    expect(view.addSource).toHaveBeenCalledWith({
+      type: "quantized-mesh",
+      url: "https://tiles.example/{z}/{x}/{y}.terrain",
+      token: "asset-tok",
+      maxZoom: 14,
+      requestVertexNormals: true,
+    });
+    const sourceDesc = view.addSource.mock.calls[0][0];
+    expect(sourceDesc).not.toHaveProperty("castShadow");
+
+    // Layer references the source and receives the render options.
+    expect(view.addLayer).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: "terrain",
+        source,
+        terrain: expect.objectContaining({ castShadow: true }),
+      }),
+    );
+    const layerDesc = view.addLayer.mock.calls[0][0];
+    expect(layerDesc.terrain).not.toHaveProperty("maxZoom");
+  });
+
+  it("reclaims the implicit source when the layer is deleted", async () => {
+    const { view, source, layer } = makeFakeView();
+    const plugin = await initPlugin(view);
+
+    plugin.addTerrain();
+
+    expect(source.delete).not.toHaveBeenCalled();
+    layer.delete();
+    expect(source.delete).toHaveBeenCalledTimes(1);
+  });
+
+  it("throws when called before init()", () => {
+    const plugin = new CesiumIonPlugin({ assetId: 1, accessToken: "t" });
+    expect(() => plugin.addTerrain()).toThrow(/after view\.init/);
+  });
+});

package/src/CesiumIonPlugin.ts

@@ -0,0 +1,161 @@
+/**
+ * CesiumIonPlugin — Navara Plugin for Cesium Ion quantized-mesh terrain.
+ *
+ * Resolves a Cesium Ion asset endpoint at `init()` time and exposes
+ * `addTerrain()` to register the asset as a terrain layer on the view.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import ThreeView from "@navaramap/three";
+ * import { DefaultPlugin } from "@navaramap/three-default-plugin";
+ * import { CesiumIonPlugin } from "@navaramap/three-plugins";
+ *
+ * const view = new ThreeView({ container, animation: true });
+ * const cesiumIon = new CesiumIonPlugin({
+ *   assetId: 12345,
+ *   accessToken: "<your cesium ion token>",
+ * });
+ *
+ * view.addPlugin(new DefaultPlugin());
+ * view.addPlugin(cesiumIon);
+ * await view.init();
+ *
+ * cesiumIon.addTerrain({
+ *   maxZoom: 14,
+ *   castShadow: true,
+ *   receiveShadow: true,
+ *   tms: true,
+ *   geographic: true,
+ *   requestVertexNormals: true,
+ *   requestWaterMask: true,
+ * });
+ * ```
+ */
+import ThreeView, {
+  Plugin,
+  type QuantizedMeshSource,
+  type TerrainSourceLayer,
+  type ViewContext,
+} from "@navaramap/three";
+import type { DefaultDescriptions } from "@navaramap/three-default-plugin";
+
+type View = ThreeView<DefaultDescriptions>;
+
+const CESIUM_ION_API = "https://api.cesium.com/v1/assets";
+
+export type CesiumIonConfig = {
+  /** Cesium Ion asset id. */
+  assetId: number | string;
+  /** Cesium Ion access token used to resolve the asset endpoint. */
+  accessToken: string;
+  endpoint?: string;
+};
+
+/**
+ * Quantized-mesh fetch/decode options forwarded to the source.
+ * The `url` and `token` fields are provided by the plugin from the resolved
+ * Cesium Ion endpoint.
+ */
+export type CesiumIonSourceOptions = Omit<
+  QuantizedMeshSource,
+  "type" | "url" | "token" | "id"
+>;
+
+/** Terrain mesh rendering options forwarded to the terrain layer. */
+export type CesiumIonTerrainRenderOptions = NonNullable<
+  TerrainSourceLayer["terrain"]
+>;
+
+/**
+ * Options for {@link CesiumIonPlugin.addTerrain}. A flat object combining the
+ * quantized-mesh source's fetch/decode options with the terrain layer's render
+ * options; the plugin routes each field to the source or the layer.
+ */
+export type CesiumIonTerrainOptions = CesiumIonSourceOptions &
+  CesiumIonTerrainRenderOptions;
+
+type CesiumIonEndpoint = {
+  url: string;
+  accessToken: string;
+};
+
+export class CesiumIonPlugin extends Plugin<View, ViewContext> {
+  private view?: View;
+  private readonly config: CesiumIonConfig;
+  private endpoint?: CesiumIonEndpoint;
+
+  constructor(config: CesiumIonConfig) {
+    super();
+    this.config = config;
+  }
+
+  async init(view: View, _ctx: ViewContext): Promise<void> {
+    this.view = view;
+
+    const { assetId, accessToken, endpoint = CESIUM_ION_API } = this.config;
+    const url = `${endpoint}/${encodeURIComponent(String(assetId))}/endpoint?access_token=${encodeURIComponent(accessToken)}`;
+
+    const res = await fetch(url);
+    if (!res.ok) {
+      throw new Error(
+        `CesiumIonPlugin: failed to fetch asset ${assetId} endpoint (${res.status} ${res.statusText})`,
+      );
+    }
+    const json = (await res.json()) as CesiumIonEndpoint;
+    this.endpoint = { url: json.url, accessToken: json.accessToken };
+  }
+
+  /**
+   * Register the resolved Cesium Ion asset as a quantized-mesh terrain layer.
+   * Must be called after `view.init()`.
+   *
+   * Internally this creates an implicit quantized-mesh source for the asset and
+   * a terrain layer that references it. The source is owned by the returned
+   * layer: deleting the layer reclaims the source too, so callers only manage
+   * the layer handle.
+   */
+  addTerrain(options: CesiumIonTerrainOptions = {}) {
+    if (!this.view || !this.endpoint) {
+      throw new Error(
+        "CesiumIonPlugin: addTerrain() must be called after view.init().",
+      );
+    }
+
+    const {
+      castShadow,
+      receiveShadow,
+      show,
+      showBoundingBox,
+      skirt,
+      skirtExaggeration,
+      ...sourceOptions
+    } = options;
+
+    const source = this.view.addSource({
+      type: "quantized-mesh",
+      url: `${this.endpoint.url}{z}/{x}/{y}.terrain`,
+      token: this.endpoint.accessToken,
+      ...sourceOptions,
+    });
+
+    const layer = this.view.addLayer({
+      type: "terrain",
+      source,
+      terrain: {
+        castShadow,
+        receiveShadow,
+        show,
+        showBoundingBox,
+        skirt,
+        skirtExaggeration,
+      },
+    });
+
+    // The source is implicit — the caller only holds the layer handle — so
+    // reclaim it once the layer is deleted.
+    layer.once("deleted", () => source.delete());
+
+    return layer;
+  }
+}

package/src/OverlayPlugin.ts

@@ -0,0 +1,202 @@
+/**
+ * OverlayPlugin — Navara Plugin for world-to-screen overlay projection.
+ *
+ * Tracks a set of world positions (lat/lng/alt) and projects them to
+ * screen coordinates on every render frame. UI components subscribe via
+ * `onUpdate()` to render HTML overlays at the projected positions.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import ThreeView from "@navaramap/three";
+ * import { DefaultPlugin } from "@navaramap/three-default-plugin";
+ * import { OverlayPlugin, moveOverlayElement } from "@navaramap/three-plugins";
+ *
+ * const view = new ThreeView({ container, animation: true });
+ * const overlayPlugin = new OverlayPlugin({ maxDistance: 100_000 });
+ *
+ * view.addPlugin(overlayPlugin);
+ * await view.init();
+ *
+ * overlayPlugin.setPositions([
+ *   { id: "marker-1", lng: 139.77, lat: 35.68, alt: 0 },
+ * ]);
+ *
+ * const unsub = overlayPlugin.onUpdate(({ projected }) => {
+ *   for (const [id, pos] of projected) {
+ *     const el = document.getElementById(id);
+ *     if (el) moveOverlayElement(el, pos.x, pos.y);
+ *   }
+ * });
+ *
+ * unsub();
+ * overlayPlugin.dispose();
+ * ```
+ */
+import ThreeView, {
+  Plugin,
+  geodeticToVector3,
+  convertWorldToScreen,
+  degreeToRadian,
+  type ViewContext,
+  type Window,
+} from "@navaramap/three";
+import type { DefaultDescriptions } from "@navaramap/three-default-plugin";
+
+type View = ThreeView<DefaultDescriptions>;
+
+export type WorldPosition = {
+  id: string;
+  lng: number;
+  lat: number;
+  alt: number;
+};
+
+export type ProjectedPosition = {
+  x: number;
+  y: number;
+  /** Distance from the camera in meters (ECEF euclidean). */
+  distance: number;
+};
+
+export type CameraPosition = {
+  lng: number;
+  lat: number;
+  height: number;
+  heading: number;
+  pitch: number;
+};
+
+export type OverlayState = {
+  projected: Map<string, ProjectedPosition>;
+};
+
+export type OverlayConfig = {
+  /** Positions farther than this (in meters) are skipped. @defaultValue `100_000` (100 km) */
+  maxDistance?: number;
+};
+
+type UpdateListener = (state: OverlayState) => void;
+
+/**
+ * Position an absolutely-positioned HTML element using a GPU-accelerated
+ * CSS `translate()` transform.
+ */
+export function moveOverlayElement(
+  el: HTMLElement,
+  x: number,
+  y: number,
+): void {
+  el.style.transform = `translate(${x}px, ${y}px)`;
+  el.style.willChange = "transform";
+}
+
+const DEFAULT_MAX_DISTANCE = 100_000;
+
+/**
+ * Projects geographic positions to screen coordinates on every render frame.
+ *
+ * Register via `view.addPlugin(overlayPlugin)` **before** `view.init()`.
+ * The `preRender` hook is attached automatically during initialization.
+ */
+export class OverlayPlugin extends Plugin<View, ViewContext> {
+  private view?: View;
+  private maxDistance: number;
+
+  private positions: WorldPosition[] = [];
+  private projected = new Map<string, ProjectedPosition>();
+
+  private listeners = new Set<UpdateListener>();
+  private boundHandler: () => void;
+
+  constructor(config?: OverlayConfig) {
+    super();
+    this.maxDistance = config?.maxDistance ?? DEFAULT_MAX_DISTANCE;
+    this.boundHandler = this.handlePreRender.bind(this);
+  }
+
+  async init(view: View, _ctx: ViewContext): Promise<void> {
+    this.view = view;
+    view.on("preRender", this.boundHandler);
+  }
+
+  /**
+   * Replace the set of world positions to track.
+   * Positions are re-projected on the next render frame automatically.
+   */
+  setPositions(positions: WorldPosition[]): void {
+    this.positions = positions;
+  }
+
+  onUpdate(fn: UpdateListener): () => void {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  dispose(): void {
+    if (this.view) {
+      this.view.off("preRender", this.boundHandler);
+    }
+    this.listeners.clear();
+    this.positions = [];
+    this.projected.clear();
+  }
+
+  private worldToScreen(
+    lng: number,
+    lat: number,
+    alt: number,
+  ): { x: number; y: number } | null {
+    if (!this.view) return null;
+
+    const ecef = geodeticToVector3({
+      lng: degreeToRadian(lng),
+      lat: degreeToRadian(lat),
+      height: alt,
+    });
+
+    const win: Window = {
+      width: this.view.screenSize.x,
+      height: this.view.screenSize.y,
+      pixelRatio: this.view.pixelRatio,
+    };
+
+    const result = convertWorldToScreen(win, this.view.camera.raw, ecef);
+    if (!result) return null;
+
+    return { x: result.x, y: result.y };
+  }
+
+  private handlePreRender(): void {
+    if (!this.view) return;
+
+    const geo = this.view.camera.positionGeographic;
+    const cameraEcef = geodeticToVector3({
+      lng: degreeToRadian(geo.lng),
+      lat: degreeToRadian(geo.lat),
+      height: geo.height,
+    });
+
+    const next = new Map<string, ProjectedPosition>();
+    for (const pos of this.positions) {
+      const markerEcef = geodeticToVector3({
+        lng: degreeToRadian(pos.lng),
+        lat: degreeToRadian(pos.lat),
+        height: pos.alt,
+      });
+      const distance = cameraEcef.distanceTo(markerEcef);
+      if (distance > this.maxDistance) continue;
+
+      const screen = this.worldToScreen(pos.lng, pos.lat, pos.alt);
+      if (screen) {
+        next.set(pos.id, { ...screen, distance });
+      }
+    }
+    this.projected = next;
+
+    const state: OverlayState = {
+      projected: this.projected,
+    };
+    for (const fn of this.listeners) fn(state);
+  }
+}