@navaramap/three 0.0.8 → 0.1.0

package/src/pick/pickHelper.test.ts

@@ -1,7 +1,9 @@
-import { Vector2 } from "three";
-import { describe, expect, it } from "vitest";
+import { PerspectiveCamera, Vector2, type WebGLRenderer } from "three";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { isClickGesture } from "./pickHelper";
+import type { MeshCache } from "../type";
+
+import { isClickGesture, PickHelper } from "./pickHelper";
 
 describe("isClickGesture", () => {
   it("accepts a mouseup at the exact mousedown position", () => {
@@ -42,3 +44,259 @@ describe("isClickGesture", () => {
     expect(isClickGesture(new Vector2(0, 0), new Vector2(4, 4))).toBe(false);
   });
 });
+
+/**
+ * Renderer stub: just enough of the WebGLRenderer surface for PickHelper.
+ * `pixel` is what the next readback returns; `scissors`/`renderCount`
+ * record the GPU work a pick performed.
+ */
+const createRendererStub = () => {
+  const state = {
+    pixel: [0, 0, 0] as [number, number, number],
+    renderCount: 0,
+    scissors: [] as { x: number; y: number; w: number; h: number }[],
+  };
+  const renderer = {
+    getContext: () => ({ drawingBufferWidth: 800, drawingBufferHeight: 600 }),
+    getPixelRatio: () => 1,
+    getClearColor: () => undefined,
+    getClearAlpha: () => 1,
+    getRenderTarget: () => null,
+    setClearColor: () => undefined,
+    setRenderTarget: () => undefined,
+    clear: () => undefined,
+    autoClear: true,
+    render: () => {
+      state.renderCount++;
+    },
+    setScissor: (x: number, y: number, w: number, h: number) => {
+      state.scissors.push({ x, y, w, h });
+    },
+    setScissorTest: () => undefined,
+    readRenderTargetPixels: (
+      _target: unknown,
+      _x: number,
+      _y: number,
+      _w: number,
+      _h: number,
+      buffer: Uint8Array,
+    ) => {
+      [buffer[0], buffer[1], buffer[2]] = state.pixel;
+      buffer[3] = 255;
+    },
+  } as unknown as WebGLRenderer;
+  return { renderer, state };
+};
+
+describe("PickHelper", () => {
+  let rafCallbacks: Map<number, FrameRequestCallback>;
+  let nextRafId: number;
+
+  beforeEach(() => {
+    rafCallbacks = new Map();
+    nextRafId = 0;
+    vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => {
+      rafCallbacks.set(++nextRafId, cb);
+      return nextRafId;
+    });
+    vi.stubGlobal("cancelAnimationFrame", (id: number) => {
+      rafCallbacks.delete(id);
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  /** Runs every rAF callback queued so far (one simulated frame). */
+  const runFrame = () => {
+    const callbacks = [...rafCallbacks.values()];
+    rafCallbacks.clear();
+    for (const cb of callbacks) cb(0);
+  };
+
+  const setup = (opts?: { clickable?: boolean; hoverable?: boolean }) => {
+    const element = document.createElement("div");
+    const { renderer, state } = createRendererStub();
+    const picks: number[][] = [];
+    const hovers: number[][] = [];
+    // Mutable so tests can flip a gate mid-flight (listener removal).
+    const gates = {
+      clickable: opts?.clickable ?? true,
+      hoverable: opts?.hoverable ?? true,
+    };
+    const helper = new PickHelper(
+      element,
+      renderer,
+      new PerspectiveCamera(),
+      new Map() as MeshCache,
+      (arr) => picks.push(arr),
+      (arr) => hovers.push(arr),
+      () => gates.clickable,
+      () => gates.hoverable,
+    );
+    helper.enablePick(true);
+
+    const mouse = (type: string, x: number, y: number, buttons = 0) =>
+      element.dispatchEvent(
+        new MouseEvent(type, { clientX: x, clientY: y, buttons }),
+      );
+    return { helper, element, state, picks, hovers, gates, mouse };
+  };
+
+  describe("click picking", () => {
+    it("decodes the batch id from the pick render", () => {
+      const { state, picks, mouse } = setup();
+      state.pixel = [0, 1, 2]; // (0 << 16) + (1 << 8) + 2
+
+      mouse("mousedown", 100, 100);
+      mouse("mouseup", 100, 100);
+
+      expect(picks).toEqual([[258]]);
+      expect(state.renderCount).toBe(1);
+    });
+
+    it("reports an empty pick for a miss (batch id 0)", () => {
+      const { picks, mouse } = setup();
+
+      mouse("mousedown", 100, 100);
+      mouse("mouseup", 100, 100);
+
+      expect(picks).toEqual([[]]);
+    });
+
+    it("limits GPU work to the clicked pixel via scissor", () => {
+      const { state, mouse } = setup();
+
+      mouse("mousedown", 30, 40);
+      mouse("mouseup", 30, 40);
+
+      // y is flipped into WebGL space: 600 - 1 - 40.
+      expect(state.scissors).toEqual([{ x: 30, y: 559, w: 1, h: 1 }]);
+    });
+
+    it("does not pick when the gesture is a drag", () => {
+      const { state, picks, mouse } = setup();
+
+      mouse("mousedown", 100, 100);
+      mouse("mouseup", 150, 150);
+
+      expect(picks).toEqual([]);
+      expect(state.renderCount).toBe(0);
+    });
+
+    it("skips the pick render entirely when nobody listens", () => {
+      const { state, picks, mouse } = setup({ clickable: false });
+
+      mouse("mousedown", 100, 100);
+      mouse("mouseup", 100, 100);
+
+      expect(picks).toEqual([]);
+      expect(state.renderCount).toBe(0);
+    });
+  });
+
+  describe("hover picking", () => {
+    it("picks at most once per animation frame, at the latest position", () => {
+      const { state, hovers, mouse } = setup();
+      state.pixel = [0, 0, 7];
+
+      mouse("mousemove", 10, 10);
+      mouse("mousemove", 20, 20);
+      mouse("mousemove", 30, 30);
+      expect(hovers).toEqual([]); // nothing until the frame fires
+
+      runFrame();
+
+      expect(hovers).toEqual([[7]]);
+      expect(state.renderCount).toBe(1);
+      expect(state.scissors).toEqual([{ x: 30, y: 569, w: 1, h: 1 }]);
+    });
+
+    it("reports an empty hover for a miss", () => {
+      const { hovers, mouse } = setup();
+
+      mouse("mousemove", 10, 10);
+      runFrame();
+
+      expect(hovers).toEqual([[]]);
+    });
+
+    it("is suppressed while a mouse button is pressed", () => {
+      const { state, hovers, mouse } = setup();
+
+      mouse("mousemove", 10, 10, 1);
+      runFrame();
+
+      expect(hovers).toEqual([]);
+      expect(state.renderCount).toBe(0);
+    });
+
+    it("re-checks the listener gate when the frame fires", () => {
+      const { state, hovers, gates, mouse } = setup();
+      state.pixel = [0, 0, 7];
+
+      mouse("mousemove", 10, 10);
+      // Listeners are removed between the mousemove and the frame.
+      gates.hoverable = false;
+      runFrame();
+
+      expect(hovers).toEqual([]);
+      expect(state.renderCount).toBe(0);
+    });
+
+    it("schedules nothing when no hover listener is registered", () => {
+      const { state, hovers, mouse } = setup({ hoverable: false });
+
+      mouse("mousemove", 10, 10);
+
+      expect(rafCallbacks.size).toBe(0);
+      runFrame();
+      expect(hovers).toEqual([]);
+      expect(state.renderCount).toBe(0);
+    });
+
+    it("mouseleave reports nothing hovered and cancels the pending pick", () => {
+      const { state, hovers, element, mouse } = setup();
+      state.pixel = [0, 0, 7];
+
+      mouse("mousemove", 10, 10);
+      element.dispatchEvent(new MouseEvent("mouseleave"));
+
+      expect(hovers).toEqual([[]]);
+
+      runFrame();
+      // The queued pick was cancelled: no render, no second callback.
+      expect(hovers).toEqual([[]]);
+      expect(state.renderCount).toBe(0);
+    });
+
+    it("mouseleave stays silent without hover listeners", () => {
+      const { hovers, element } = setup({ hoverable: false });
+
+      element.dispatchEvent(new MouseEvent("mouseleave"));
+
+      expect(hovers).toEqual([]);
+    });
+  });
+
+  describe("enablePick(false)", () => {
+    it("detaches every handler and cancels pending hover picks", () => {
+      const { helper, state, picks, hovers, mouse } = setup();
+      state.pixel = [0, 0, 7];
+      mouse("mousemove", 10, 10);
+
+      helper.enablePick(false);
+
+      expect(rafCallbacks.size).toBe(0);
+      mouse("mousedown", 100, 100);
+      mouse("mouseup", 100, 100);
+      mouse("mousemove", 20, 20);
+      runFrame();
+
+      expect(picks).toEqual([]);
+      expect(hovers).toEqual([]);
+      expect(state.renderCount).toBe(0);
+    });
+  });
+});

package/src/pick/pickHelper.ts

@@ -47,6 +47,12 @@ export function isClickGesture(
  * Re-parenting is safe because pass scenes all have identity world
  * transforms, so world matrices of the re-parented objects are
  * unaffected.
+ *
+ * Two gestures trigger a pick: a click (mousedown/mouseup within
+ * {@link CLICK_PIXEL_TOLERANCE}) and hovering, throttled to at most one
+ * pick per animation frame. Both are lazy: a pick runs only while the
+ * matching `shouldClickPick` / `shouldHoverPick` gate returns true
+ * (i.e. someone is listening for the result).
  */
 export class PickHelper {
   private element: HTMLElement;
@@ -64,9 +70,20 @@ export class PickHelper {
   /** Full-size render target used for click picking with scissor restriction. */
   private pickRenderTarget: WebGLRenderTarget;
 
+  private onHoverCallback: (pickArr: number[]) => void;
+  /** Click picks run only while this returns true (e.g. featureClick listeners exist). */
+  private shouldClickPick: () => boolean;
+  /** Hover picks run only while this returns true (e.g. hover listeners exist). */
+  private shouldHoverPick: () => boolean;
+
   private mouseDownPosition?: Vector2;
   private mouseDownHandler: (event: MouseEvent) => void;
   private mouseUpHandler: (event: MouseEvent) => void;
+  private hoverMoveHandler: (event: MouseEvent) => void;
+  private hoverLeaveHandler: () => void;
+  /** Latest mousemove position awaiting a hover pick, in client coords. */
+  private hoverPosition?: Vector2;
+  private hoverRafId?: number;
 
   constructor(
     element: HTMLElement,
@@ -74,6 +91,9 @@ export class PickHelper {
     camera: PerspectiveCamera,
     meshes: MeshCache,
     onPickCallback: (pickArr: number[]) => void,
+    onHoverCallback: (pickArr: number[]) => void,
+    shouldClickPick: () => boolean,
+    shouldHoverPick: () => boolean,
     options?: PickHelperOptions,
   ) {
     this.element = element;
@@ -82,9 +102,14 @@ export class PickHelper {
     this._camera = camera;
     this._meshes = meshes;
     this.onPickCallback = onPickCallback;
+    this.onHoverCallback = onHoverCallback;
+    this.shouldClickPick = shouldClickPick;
+    this.shouldHoverPick = shouldHoverPick;
 
     this.mouseDownHandler = (event: MouseEvent) => this.onMouseDown(event);
     this.mouseUpHandler = (event: MouseEvent) => this.onMouseUp(event);
+    this.hoverMoveHandler = (event: MouseEvent) => this.onHoverMouseMove(event);
+    this.hoverLeaveHandler = () => this.onHoverMouseLeave();
 
     const width = this._renderer.getContext().drawingBufferWidth;
     const height = this._renderer.getContext().drawingBufferHeight;
@@ -114,6 +139,9 @@ export class PickHelper {
     this.mouseDownPosition = undefined;
     if (!downPosition) return;
 
+    // Skip the GPU pick entirely when nobody is listening for the result.
+    if (!this.shouldClickPick()) return;
+
     if (
       isClickGesture(downPosition, new Vector2(event.clientX, event.clientY))
     ) {
@@ -125,10 +153,61 @@ export class PickHelper {
     if (bPick) {
       this.element.addEventListener("mousedown", this.mouseDownHandler);
       this.element.addEventListener("mouseup", this.mouseUpHandler);
+      this.element.addEventListener("mousemove", this.hoverMoveHandler);
+      this.element.addEventListener("mouseleave", this.hoverLeaveHandler);
     } else {
       this.element.removeEventListener("mousedown", this.mouseDownHandler);
       this.element.removeEventListener("mouseup", this.mouseUpHandler);
+      this.element.removeEventListener("mousemove", this.hoverMoveHandler);
+      this.element.removeEventListener("mouseleave", this.hoverLeaveHandler);
+      this.cancelPendingHoverPick();
+    }
+  }
+
+  /**
+   * Hover picking: schedules at most one GPU pick per animation frame from
+   * the latest mousemove position. Suppressed while any mouse button is
+   * pressed (camera drags would otherwise trigger a pick per frame) and
+   * while `shouldHoverPick` returns false, so pages without hover
+   * listeners pay nothing.
+   */
+  private onHoverMouseMove(event: MouseEvent) {
+    if (event.buttons !== 0 || !this.shouldHoverPick()) return;
+
+    if (!this.hoverPosition) this.hoverPosition = new Vector2();
+    this.hoverPosition.set(event.clientX, event.clientY);
+
+    if (this.hoverRafId !== undefined) return;
+    this.hoverRafId = requestAnimationFrame(() => {
+      this.hoverRafId = undefined;
+      const position = this.hoverPosition;
+      if (!position) return;
+      this.hoverPosition = undefined;
+
+      // Listeners may have been removed between the mousemove that
+      // scheduled this frame and now. Re-check so no orphan pick runs.
+      if (!this.shouldHoverPick()) return;
+
+      const batchId = this.pickBatchIdAt(position.x, position.y);
+      this.onHoverCallback(batchId > 0 ? [batchId] : []);
+    });
+  }
+
+  private onHoverMouseLeave() {
+    this.cancelPendingHoverPick();
+    // Report "nothing hovered" so diff-based enter/leave synthesis can
+    // close out the current hover when the cursor exits the canvas.
+    if (this.shouldHoverPick()) {
+      this.onHoverCallback([]);
+    }
+  }
+
+  private cancelPendingHoverPick() {
+    if (this.hoverRafId !== undefined) {
+      cancelAnimationFrame(this.hoverRafId);
+      this.hoverRafId = undefined;
     }
+    this.hoverPosition = undefined;
   }
 
   /**
@@ -225,9 +304,19 @@ export class PickHelper {
   }
 
   private onMouseClick(event: MouseEvent) {
+    const batchId = this.pickBatchIdAt(event.clientX, event.clientY);
+    const pickArr = batchId > 0 ? [batchId] : [];
+    this.onPickCallback(pickArr);
+  }
+
+  /**
+   * Runs the single-pixel pick render at the given client coordinates and
+   * returns the decoded batch ID (0 when nothing pickable is hit).
+   */
+  private pickBatchIdAt(clientX: number, clientY: number): number {
     const rect = this.element.getBoundingClientRect();
-    const x = event.clientX - rect.left;
-    const y = event.clientY - rect.top;
+    const x = clientX - rect.left;
+    const y = clientY - rect.top;
 
     const pixelRatio = this._renderer.getPixelRatio();
     const fullWidth = this._renderer.getContext().drawingBufferWidth;
@@ -267,13 +356,11 @@ export class PickHelper {
 
     this._renderer.setScissorTest(false);
 
-    const batchId =
+    return (
       (this.pixelBuffer[0] << 16) +
       (this.pixelBuffer[1] << 8) +
-      this.pixelBuffer[2];
-
-    const pickArr = batchId > 0 ? [batchId] : [];
-    this.onPickCallback(pickArr);
+      this.pixelBuffer[2]
+    );
   }
 
   public dispose() {

package/src/renderOrder.ts

@@ -1,3 +1,13 @@
 export const FEATURE_RENDER_ORDER = 1;
+/**
+ * Polylines (strokes) must draw after polygon fills. In the per-tile bake
+ * scene, sibling fill/stroke meshes are created asynchronously and land in
+ * the scene in arbitrary order, so a fill baked later paints over the stroke.
+ * In the MRT scene, polyline materials skip the depth test but still write
+ * depth, so a coplanar fill drawn after a stroke z-fights against the
+ * stroke's depth per fragment (mottled boundaries). Encoding the stacking in
+ * renderOrder makes both cases deterministic.
+ */
+export const STROKE_RENDER_ORDER = FEATURE_RENDER_ORDER + 1;
 export const SKY_RENDER_ORDER = 100;
 export const STARS_RENDER_ORDER = SKY_RENDER_ORDER + 1;

package/src/terrain/sampleTerrainMostDetailed.test.ts

@@ -37,6 +37,7 @@ vi.mock("@navaramap/engine-api", () => {
   };
   return {
     default: vi.fn().mockResolvedValue(undefined),
+    angleToRadian: (deg: number) => (deg * Math.PI) / 180,
     terrainPositionsToTiles: vi.fn(
       (geographic: boolean, level: number, positions: Float64Array) => {
         const result = new Uint32Array(positions.length);
@@ -87,12 +88,11 @@ vi.mock("@navaramap/engine-api", () => {
   };
 });
 
-const KARIYA = { lat: (35.0 * Math.PI) / 180, lng: (137.0 * Math.PI) / 180 };
-const NEARBY = {
-  lat: (35.001 * Math.PI) / 180,
-  lng: (137.001 * Math.PI) / 180,
-};
-const TOKYO = { lat: (35.68 * Math.PI) / 180, lng: (139.76 * Math.PI) / 180 };
+// Public inputs are degrees; the mocked engine functions still receive the
+// radians the implementation converts to.
+const KARIYA = { lat: 35.0, lng: 137.0 };
+const NEARBY = { lat: 35.001, lng: 137.001 };
+const TOKYO = { lat: 35.68, lng: 139.76 };
 
 const SOURCE: QuantizedMeshSource = {
   type: "quantized-mesh",

package/src/terrain/sampleTerrainMostDetailed.ts

@@ -1,5 +1,6 @@
 import type { LatLng } from "@navaramap/core";
 import {
+  angleToRadian,
   sampleQuantizedMeshHeights,
   sampleRasterDemHeights,
   terrainPositionsToTiles,
@@ -29,9 +30,9 @@ export type SampleTerrainOptions = {
 };
 
 export type SampledTerrainPosition = {
-  /** Latitude in radians, echoed from the input. */
+  /** Latitude in degrees, echoed from the input. */
   lat: number;
-  /** Longitude in radians, echoed from the input. */
+  /** Longitude in degrees, echoed from the input. */
   lng: number;
   /**
    * Terrain height in meters, or `undefined` when no tile covering the
@@ -104,7 +105,7 @@ type SourceConfig = {
  *
  * @param source - A `quantized-mesh` or `raster-dem` source description (the
  *   same shape `addSource` accepts)
- * @param positions - Geodetic positions (lat/lng in radians)
+ * @param positions - Geodetic positions (lat/lng in degrees)
  * @param options - Optional abort signal and fixed-level sampling
  * @returns One result per input position, in the same order (the input
  *   objects are not mutated)
@@ -123,10 +124,11 @@ export async function sampleTerrainMostDetailed(
   // Fixed-level sampling never falls back to parents.
   const floorLevel = options?.level != null ? startLevel : config.minZoom;
 
+  // The engine samplers work in radians; inputs and echoed outputs are degrees.
   const flat = new Float64Array(positions.length * 2);
   positions.forEach((p, i) => {
-    flat[i * 2] = p.lng;
-    flat[i * 2 + 1] = p.lat;
+    flat[i * 2] = angleToRadian(p.lng);
+    flat[i * 2 + 1] = angleToRadian(p.lat);
   });
 
   // Group positions by their containing tile at the starting level; each

package/src/type/index.ts

@@ -75,6 +75,27 @@ type ConvertColorFields<T> = {
  */
 type WithColorSupport<T> = ConvertColorFields<T>;
 
+/**
+ * Source geometry categories a vector appearance can consume via its
+ * `geometryTypes` option. Each appearance defaults to its native geometry only
+ * (`"point"` for point/billboard/text, `"line"` for polyline); adding entries
+ * derives extra representations, e.g. `polyline: { geometryTypes: ["line",
+ * "polygon"] }` also renders polygon boundary rings as polylines.
+ */
+export type SourceGeometryType = "point" | "line" | "polygon";
+
+/**
+ * Helper type to narrow the generated `geometryTypes?: string[]` material
+ * fields to the {@link SourceGeometryType} literal union.
+ */
+type ConvertGeometryTypeFields<T> = {
+  [K in keyof T]: K extends "geometryTypes"
+    ? SourceGeometryType[] | Extract<T[K], undefined>
+    : T[K] extends object | undefined
+      ? ConvertGeometryTypeFields<T[K]> | Extract<T[K], undefined>
+      : T[K];
+};
+
 /**
  * A reference to a {@link Source}: either the source handle returned by
  * `addSource`, or its `id` string.
@@ -87,7 +108,7 @@ export type SourceLayerBase<Layer extends { source?: string | undefined }> =
   };
 
 type VectorLayerBase = WithColorSupport<
-  Layer<VectorLayerDescription & { type: "vector" }>
+  ConvertGeometryTypeFields<Layer<VectorLayerDescription & { type: "vector" }>>
 >;
 
 /**