@navaramap/three 0.0.8 → 0.1.1

package/src/pick/pickHelper.ts

@@ -19,22 +19,40 @@ export type PickHelperOptions = {
 };
 
 /**
- * Travel tolerance in CSS pixels between mousedown and mouseup to count as a click.
+ * Travel tolerance in CSS pixels between pointerdown and pointerup to count as a click.
  * Follows Cesium's `_clickPixelTolerance` (MapLibre uses 3px).
  * ref: https://github.com/CesiumGS/cesium/blob/9fda7ab97a762e40c74b1d0e1814c98a2de43337/packages/engine/Source/Core/ScreenSpaceEventHandler.js#L1012
  * ref: https://github.com/maplibre/maplibre-gl-js/blob/3a0a4f795fef5b2a29034d71833475589c344eaf/src/ui/map.ts#L542
  */
-const CLICK_PIXEL_TOLERANCE = 5;
+export const CLICK_PIXEL_TOLERANCE = 5;
+
+/**
+ * Travel tolerance for touch taps. Finger contact jitters far more than a
+ * mouse, so follows MapLibre's tap `MAX_DIST` instead.
+ * ref: https://github.com/maplibre/maplibre-gl-js/blob/3a0a4f795fef5b2a29034d71833475589c344eaf/src/ui/handler/tap_recognizer.ts
+ */
+export const TAP_PIXEL_TOLERANCE = 30;
 
 export function isClickGesture(
   downPosition: Vector2,
   upPosition: Vector2,
+  tolerance: number = CLICK_PIXEL_TOLERANCE,
 ): boolean {
-  return downPosition.distanceTo(upPosition) < CLICK_PIXEL_TOLERANCE;
+  return downPosition.distanceTo(upPosition) < tolerance;
 }
 
 /**
- * GPU picking using a dedicated single-pixel render pass.
+ * Pick search radius in CSS pixels around the pointer. The pick reads a
+ * (2r+1)² window and takes the non-zero batch id closest to its center, so
+ * small features (points, thin lines) don't demand pixel-perfect aim.
+ */
+export const PICK_RADIUS = 3;
+
+/** Pick search radius for touch: fingertips land less precisely than a cursor. */
+export const TOUCH_PICK_RADIUS = 10;
+
+/**
+ * GPU picking using a dedicated render pass over a small search window.
  *
  * The pick pass does NOT reuse the main render pipeline (globe / MRT /
  * draped / copy passes). Instead, every pickable raw — regardless of
@@ -47,6 +65,15 @@ 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 or touch tap (pointerdown/pointerup
+ * within {@link CLICK_PIXEL_TOLERANCE} / {@link TAP_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). The gestures are detected from pointer events, which fire for
+ * touch as well. The camera-input handlers call `preventDefault()` on
+ * touch events, so the compatibility mouse events never do.
  */
 export class PickHelper {
   private element: HTMLElement;
@@ -64,9 +91,21 @@ export class PickHelper {
   /** Full-size render target used for click picking with scissor restriction. */
   private pickRenderTarget: WebGLRenderTarget;
 
-  private mouseDownPosition?: Vector2;
-  private mouseDownHandler: (event: MouseEvent) => void;
-  private mouseUpHandler: (event: MouseEvent) => void;
+  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 pointerDownPosition?: Vector2;
+  private pointerDownHandler: (event: PointerEvent) => void;
+  private pointerUpHandler: (event: PointerEvent) => void;
+  private pointerCancelHandler: () => void;
+  private hoverMoveHandler: (event: PointerEvent) => void;
+  private hoverLeaveHandler: () => void;
+  /** Latest pointermove position awaiting a hover pick, in client coords. */
+  private hoverPosition?: Vector2;
+  private hoverRafId?: number;
 
   constructor(
     element: HTMLElement,
@@ -74,6 +113,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 +124,17 @@ export class PickHelper {
     this._camera = camera;
     this._meshes = meshes;
     this.onPickCallback = onPickCallback;
-
-    this.mouseDownHandler = (event: MouseEvent) => this.onMouseDown(event);
-    this.mouseUpHandler = (event: MouseEvent) => this.onMouseUp(event);
+    this.onHoverCallback = onHoverCallback;
+    this.shouldClickPick = shouldClickPick;
+    this.shouldHoverPick = shouldHoverPick;
+
+    this.pointerDownHandler = (event: PointerEvent) =>
+      this.onPointerDown(event);
+    this.pointerUpHandler = (event: PointerEvent) => this.onPointerUp(event);
+    this.pointerCancelHandler = () => this.onPointerCancel();
+    this.hoverMoveHandler = (event: PointerEvent) =>
+      this.onHoverPointerMove(event);
+    this.hoverLeaveHandler = () => this.onHoverPointerLeave();
 
     const width = this._renderer.getContext().drawingBufferWidth;
     const height = this._renderer.getContext().drawingBufferHeight;
@@ -105,32 +155,113 @@ export class PickHelper {
     }
   }
 
-  private onMouseDown(event: MouseEvent) {
-    this.mouseDownPosition = new Vector2(event.clientX, event.clientY);
+  private onPointerDown(event: PointerEvent) {
+    // A second concurrent pointer (e.g. the pinch-zoom finger) turns the
+    // gesture into something other than a tap; abandon the pending click.
+    if (!event.isPrimary) {
+      this.pointerDownPosition = undefined;
+      return;
+    }
+    this.pointerDownPosition = new Vector2(event.clientX, event.clientY);
   }
 
-  private onMouseUp(event: MouseEvent) {
-    const downPosition = this.mouseDownPosition;
-    this.mouseDownPosition = undefined;
+  private onPointerUp(event: PointerEvent) {
+    if (!event.isPrimary) return;
+
+    const downPosition = this.pointerDownPosition;
+    this.pointerDownPosition = undefined;
     if (!downPosition) return;
 
+    // Skip the GPU pick entirely when nobody is listening for the result.
+    if (!this.shouldClickPick()) return;
+
+    const tolerance =
+      event.pointerType === "touch"
+        ? TAP_PIXEL_TOLERANCE
+        : CLICK_PIXEL_TOLERANCE;
     if (
-      isClickGesture(downPosition, new Vector2(event.clientX, event.clientY))
+      isClickGesture(
+        downPosition,
+        new Vector2(event.clientX, event.clientY),
+        tolerance,
+      )
     ) {
-      this.onMouseClick(event);
+      this.onClickPick(event);
     }
   }
 
+  /** The browser took over the gesture (scroll, app switch): not a click. */
+  private onPointerCancel() {
+    this.pointerDownPosition = undefined;
+  }
+
   enablePick(bPick: boolean) {
     if (bPick) {
-      this.element.addEventListener("mousedown", this.mouseDownHandler);
-      this.element.addEventListener("mouseup", this.mouseUpHandler);
+      this.element.addEventListener("pointerdown", this.pointerDownHandler);
+      this.element.addEventListener("pointerup", this.pointerUpHandler);
+      this.element.addEventListener("pointercancel", this.pointerCancelHandler);
+      this.element.addEventListener("pointermove", this.hoverMoveHandler);
+      this.element.addEventListener("pointerleave", this.hoverLeaveHandler);
     } else {
-      this.element.removeEventListener("mousedown", this.mouseDownHandler);
-      this.element.removeEventListener("mouseup", this.mouseUpHandler);
+      this.element.removeEventListener("pointerdown", this.pointerDownHandler);
+      this.element.removeEventListener("pointerup", this.pointerUpHandler);
+      this.element.removeEventListener(
+        "pointercancel",
+        this.pointerCancelHandler,
+      );
+      this.element.removeEventListener("pointermove", this.hoverMoveHandler);
+      this.element.removeEventListener("pointerleave", this.hoverLeaveHandler);
+      this.cancelPendingHoverPick();
     }
   }
 
+  /**
+   * Hover picking: schedules at most one GPU pick per animation frame from
+   * the latest pointermove position. Suppressed while any button is pressed
+   * (Camera drags would otherwise trigger a pick per frame. For touch,
+   * contact itself sets `buttons`, so touch never hover-picks) and while
+   * `shouldHoverPick` returns false, so pages without hover listeners pay
+   * nothing.
+   */
+  private onHoverPointerMove(event: PointerEvent) {
+    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 pointermove 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 onHoverPointerLeave() {
+    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;
+  }
+
   /**
    * Moves every pickable raw (visible, currently parented) into the
    * dedicated `pickScene` and activates the picking uniforms on its
@@ -224,10 +355,27 @@ export class PickHelper {
     this.debugBufferView.render(this._renderer, this.debugRenderTarget);
   }
 
-  private onMouseClick(event: MouseEvent) {
+  private onClickPick(event: PointerEvent) {
+    const radius =
+      event.pointerType === "touch" ? TOUCH_PICK_RADIUS : PICK_RADIUS;
+    const batchId = this.pickBatchIdAt(event.clientX, event.clientY, radius);
+    const pickArr = batchId > 0 ? [batchId] : [];
+    this.onPickCallback(pickArr);
+  }
+
+  /**
+   * Runs the pick render in a search window around the given client
+   * coordinates and returns the non-zero batch ID closest to its center
+   * (0 when nothing pickable is inside the window).
+   */
+  private pickBatchIdAt(
+    clientX: number,
+    clientY: number,
+    radiusCss: number = PICK_RADIUS,
+  ): 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;
@@ -249,31 +397,58 @@ export class PickHelper {
     );
     const readY = fullHeight - 1 - pixelY;
 
+    // The search window in device pixels, clamped to the viewport.
+    const radius = Math.max(0, Math.round(radiusCss * pixelRatio));
+    const minX = Math.max(0, pixelX - radius);
+    const maxX = Math.min(fullWidth - 1, pixelX + radius);
+    const minY = Math.max(0, readY - radius);
+    const maxY = Math.min(fullHeight - 1, readY + radius);
+    const width = maxX - minX + 1;
+    const height = maxY - minY + 1;
+
     // Keep the camera projection unchanged for wide lines / screen-space
-    // expanded shaders, and limit fragment work to one pixel via scissor.
-    this._renderer.setScissor(pixelX, readY, 1, 1);
+    // expanded shaders, and limit fragment work to the window via scissor.
+    this._renderer.setScissor(minX, minY, width, height);
     this._renderer.setScissorTest(true);
 
     this.processRender(this.pickRenderTarget, pickingCoord);
 
+    if (this.pixelBuffer.length < width * height * 4) {
+      this.pixelBuffer = new Uint8Array(width * height * 4);
+    }
     this._renderer.readRenderTargetPixels(
       this.pickRenderTarget,
-      pixelX,
-      readY,
-      1,
-      1,
+      minX,
+      minY,
+      width,
+      height,
       this.pixelBuffer,
     );
 
     this._renderer.setScissorTest(false);
 
-    const batchId =
-      (this.pixelBuffer[0] << 16) +
-      (this.pixelBuffer[1] << 8) +
-      this.pixelBuffer[2];
-
-    const pickArr = batchId > 0 ? [batchId] : [];
-    this.onPickCallback(pickArr);
+    // The non-zero batch id nearest to the pointer wins, so a small feature
+    // beside a large one is still pickable by aiming at it.
+    let bestId = 0;
+    let bestDistSq = Infinity;
+    for (let row = 0; row < height; row++) {
+      for (let col = 0; col < width; col++) {
+        const i = (row * width + col) * 4;
+        const id =
+          (this.pixelBuffer[i] << 16) +
+          (this.pixelBuffer[i + 1] << 8) +
+          this.pixelBuffer[i + 2];
+        if (id === 0) continue;
+        const dx = minX + col - pixelX;
+        const dy = minY + row - readY;
+        const distSq = dx * dx + dy * dy;
+        if (distSq < bestDistSq) {
+          bestDistSq = distSq;
+          bestId = id;
+        }
+      }
+    }
+    return bestId;
   }
 
   public dispose() {

package/src/plugins/AttributionPlugin/index.ts

@@ -125,7 +125,7 @@ let styleRefCount = 0;
  */
 const NAVARA_CREDIT: AttributionItem = {
   attribution: "Navara",
-  attributionUrl: "https://navara-docs.reearth.workers.dev//",
+  attributionUrl: "https://navara.world/",
 };
 
 /**

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" }>>
 >;
 
 /**