@navaramap/three 0.0.7 → 0.1.0

package/src/index.ts

@@ -23,7 +23,7 @@ import {
   type FontWorkerMemoryStats,
 } from "@navaramap/font";
 import FontWorkerURL from "@navaramap/font/fontWorker?worker&url";
-import { initNavaraApi } from "@navaramap/three-api";
+import { initNavaraApi, degreeToRadian } from "@navaramap/three-api";
 import {
   initializeWorkerPool,
   probeWorkerPoolHeap,
@@ -131,6 +131,7 @@ import {
   type SampledTerrainPosition,
   type TerrainSampleSource,
 } from "./terrain/sampleTerrainMostDetailed";
+import { hasObservedTerrainHeight } from "./terrain/terrainHeightEvent";
 import type { TextureOptions } from "./textures";
 import { TileTextureCompositor } from "./tileTexture";
 import {
@@ -156,6 +157,30 @@ import WorkerURL from "./worker?url&worker";
 
 export type { CameraOptions, CameraEvent } from "./camera";
 
+/** Easing presets applied to a `flyTo` flight's normalized time. */
+export type FlyToEasing =
+  "linear" | "quadInOut" | "cubicInOut" | "cubicOut" | "quinticInOut";
+
+export type FlyToOptions = {
+  /** Animation duration in milliseconds. Defaults to a duration derived from
+   * the flight distance (2–3 s). Pass `0` to jump instantly. */
+  duration?: number;
+  /** Maximum height during the flight arc in meters. */
+  maxHeight?: number;
+  /** Easing preset. Defaults to `"quinticInOut"`, or `"cubicOut"` when
+   * descending from above 11,500 m. */
+  easing?: FlyToEasing;
+};
+
+// Must mirror `FlyToEasing`'s `TryFrom<u8>` mapping on the Rust side.
+const FLY_TO_EASING_CODE: Record<FlyToEasing, number> = {
+  linear: 0,
+  quadInOut: 1,
+  cubicInOut: 2,
+  cubicOut: 3,
+  quinticInOut: 4,
+};
+
 export { ColorMap, EventHandler, Plugin } from "@navaramap/core";
 export type {
   Nullable,
@@ -284,7 +309,11 @@ export type Options = {
   atmosphere?: AtmosphereOptions;
   /** Background color of the scene. Defaults to dark color (0x0a0a0f). */
   backgroundColor?: CoreColor;
-  /** Feature picking configuration. */
+  /**
+   * Feature picking configuration (default: true). Enables the `featureClick`
+   * event (click) and the `featureHover` / `featureEnter` / `featureLeave`
+   * events (mousemove).
+   */
   picking?: boolean;
   /** When true, renders every frame. When false, renders only on changes or when forceUpdate() is called. */
   animation?: boolean;
@@ -388,8 +417,24 @@ export type MapMouseEvent = {
 export type ViewEvents = {
   /** Emitted when the view is resized. Receives width and height in pixels. */
   resize: (w: number, h: number) => void;
-  /** Emitted when a feature is picked. Receives picked feature info or null. */
-  pick: (info: Nullable<PickedFeature>) => void;
+  /**
+   * Emitted when a feature is clicked (click-gesture GPU pick). Receives the
+   * clicked feature, or null when empty space was clicked. For raw click
+   * coordinates use the `click` event instead.
+   */
+  featureClick: (info: Nullable<PickedFeature>) => void;
+  /**
+   * Emitted when the hovered feature changes (mousemove picking). Receives
+   * the newly hovered feature, or null when the pointer leaves all pickable
+   * features. Hover picking runs a GPU pick per frame while the pointer
+   * moves, and is active only while at least one `featureHover` /
+   * `featureEnter` / `featureLeave` listener is registered.
+   */
+  featureHover: (info: Nullable<PickedFeature>) => void;
+  /** Emitted when the pointer starts hovering a pickable feature. See `featureHover` for activation. */
+  featureEnter: (info: PickedFeature) => void;
+  /** Emitted when the pointer stops hovering the previously hovered feature. See `featureHover` for activation. */
+  featureLeave: (info: PickedFeature) => void;
   /** Emitted when a layer event occurs. Receives event type, layer ID, and event arguments. */
   layer: <K extends keyof LayerEvent>(
     k: K,
@@ -474,6 +519,12 @@ export default class ThreeView<
   private _declutterRetryDelay = 0;
   private _isIdle = false;
   private _uniforms: CommonUniforms;
+  /** Pending `flyTo` promises keyed by flight id, settled by
+   *  `camera_flight_ended` events from the engine. */
+  private _pendingFlights = new Map<number, (completed: boolean) => void>();
+
+  /** Currently hovered feature, used to diff-synthesize hover events. */
+  private _hoveredFeature: Nullable<PickedFeature> = null;
 
   private _meshes: MeshCache = new Map();
   private _abortControllers: AbortControllers = new Map();
@@ -1055,7 +1106,9 @@ export default class ThreeView<
       tGlobeNormal: { value: null },
       tSkyEnvMap: { value: null },
       inverseProjectionMatrix: { value: null },
-      // TODO: Need to sync `fov` with WASM side
+      // Vertical fov in radians; synced with the engine on each frustum event.
+      // Plain arithmetic: the WASM-backed degreeToRadian is not available
+      // until init().
       fov: { value: (this._camera.raw.fov * Math.PI) / 180 },
       screenHeightPx: { value: height },
       time: { value: 0 },
@@ -1493,6 +1546,13 @@ export default class ThreeView<
       viewEvents: this,
       layersManager: this.layersManager,
       viewContext: this.viewContext,
+      flightHandler: (id, completed) => {
+        const resolve = this._pendingFlights.get(id);
+        if (resolve) {
+          this._pendingFlights.delete(id);
+          resolve(completed);
+        }
+      },
       layerHandler: this._layerHandler,
       fontManager: this._fontManager,
       textureFragmentIndex: this._textureFragmentIndex,
@@ -1525,6 +1585,17 @@ export default class ThreeView<
         this._camera.raw,
         this._meshes,
         this.onPick.bind(this),
+        this.onHoverPick.bind(this),
+        // Picks cost a GPU render (plus a re-render to restore draped
+        // atlases), so both gestures stay off until someone actually
+        // listens for the result.
+        () => !!this.size("featureClick"),
+        () =>
+          !!(
+            this.size("featureHover") ||
+            this.size("featureEnter") ||
+            this.size("featureLeave")
+          ),
         // {
         //   debug: true,
         // },
@@ -1603,6 +1674,11 @@ export default class ThreeView<
   dispose() {
     this._disposed = true;
     this._initialized = false;
+    // Settle pending flyTo promises so callers never hang on a disposed view.
+    for (const resolve of this._pendingFlights.values()) {
+      resolve(false);
+    }
+    this._pendingFlights.clear();
     if (this._declutterRetry !== undefined) {
       clearTimeout(this._declutterRetry);
       this._declutterRetry = undefined;
@@ -1768,7 +1844,10 @@ export default class ThreeView<
     const pixelRatio = this._renderer.getPixelRatio();
 
     // Ref: https://github.com/CesiumGS/cesium/blob/2cf09cb06e4f7ea767da39befabcfc3444b02c49/packages/engine/Source/Core/PerspectiveFrustum.js#L208-L218
-    const fovY = this._camera.fovy ?? 1;
+    // raw.fov mirrors the engine's vertical fov (degrees) via the frustum
+    // event pump. Plain arithmetic: this must not depend on the WASM-backed
+    // degreeToRadian helper.
+    const fovY = (this._camera.raw.fov * Math.PI) / 180;
     const top = this._camera.raw.near * Math.tan(0.5 * fovY);
     const bottom = -top;
     const right = this._camera.raw.aspect * top;
@@ -1793,8 +1872,8 @@ export default class ThreeView<
     this._uniforms.inverseProjectionMatrix.value =
       this._camera.raw.projectionMatrixInverse;
 
-    // TODO: Need to sync `fov` with WASM side
-    this._uniforms.fov.value = (this._camera.raw.fov * Math.PI) / 180;
+    // Vertical fov in radians (raw.fov is kept in sync with the engine).
+    this._uniforms.fov.value = fovY;
     this._uniforms.screenHeightPx.value = viewport?.height ?? 0;
   }
 
@@ -2486,30 +2565,48 @@ export default class ThreeView<
 
   /**
    * Animates the camera to fly to a target position.
+   *
+   * The flight follows an arced path: the default duration is derived from
+   * the flight distance (2–3 s), the default easing is `quinticInOut`
+   * (`cubicOut` when descending from high altitude), and longitudes take the
+   * short way across the antimeridian.
+   *
    * @param camPos - Target position with required lng/lat (degrees). Provide either `height` (meters above the ellipsoid)
    *   or `distance` (meters from the target point along the camera forward direction). Optional pitch, heading, roll (degrees).
-   * @param duration - Animation duration in milliseconds
-   * @param maxHeight - Maximum height during the flight arc in meters
+   * @param options - Flight options (`duration`, `maxHeight`, `easing`)
+   * @returns A promise resolving to `true` when the flight completes, or
+   *   `false` when it is interrupted by another camera operation, such as a
+   *   newer `flyTo` or a `setCamera` call.
    */
   flyTo(
     camPos: CameraPosition &
       Required<Pick<CameraPosition, "lng" | "lat">> &
       ({ height: number } | { distance: number }),
-    duration?: number,
-    maxHeight?: number,
-  ) {
+    options: FlyToOptions = {},
+  ): Promise<boolean> {
     const pos = camPos as CameraPosition & { lng: number; lat: number };
     const position = new Float64Array([pos.lng, pos.lat, pos.height ?? 0]);
 
-    this._core?.flyTo(
+    const id = this._core?.flyTo(
       position,
       pos.pitch,
       pos.heading,
       pos.roll,
-      duration,
-      maxHeight,
+      options.duration,
+      options.maxHeight,
       pos.distance,
+      options.easing === undefined
+        ? undefined
+        : FLY_TO_EASING_CODE[options.easing],
     );
+
+    if (id === undefined) {
+      return Promise.resolve(false);
+    }
+
+    return new Promise<boolean>((resolve) => {
+      this._pendingFlights.set(id, resolve);
+    });
   }
 
   /**
@@ -2558,11 +2655,11 @@ export default class ThreeView<
 
   /**
    * Samples the terrain height at a given geodetic position synchronously.
-   * @param pos - Geodetic position (lat in radians, lng in radians)
+   * @param pos - Geodetic position (lat in degrees, lng in degrees)
    * @returns Terrain height in meters, or undefined if terrain data not loaded
    */
   sampleTerrainHeight(pos: LatLng): number | undefined {
-    const lle = new LLE(pos.lat, pos.lng, 0);
+    const lle = new LLE(degreeToRadian(pos.lat), degreeToRadian(pos.lng), 0);
     return this._core?.sampleTerrainHeight(lle);
   }
 
@@ -2580,7 +2677,7 @@ export default class ThreeView<
    * sampled.
    *
    * @param source - A registered terrain source (handle or id)
-   * @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
    */
@@ -2606,7 +2703,7 @@ export default class ThreeView<
 
   /**
    * Observes terrain height changes at a position. Callback is invoked each time terrain data updates.
-   * @param pos - Geodetic position to observe (lat in radians, lng in radians)
+   * @param pos - Geodetic position to observe (lat in degrees, lng in degrees)
    * @param cb - Callback function receiving the terrain height in meters
    * @returns Cleanup function to stop observing
    */
@@ -2618,11 +2715,11 @@ export default class ThreeView<
       return () => {};
     }
 
-    const lle = new LLE(pos.lat, pos.lng, 0);
+    const lle = new LLE(degreeToRadian(pos.lat), degreeToRadian(pos.lng), 0);
     const entityBits = this._core.registerSampleTerrainHeightEvent(lle);
 
     const callFunc = (ev: TerrainHeightUpdatedEvent) => {
-      if (ev.bits === entityBits && ev.height) {
+      if (hasObservedTerrainHeight(ev, entityBits)) {
         cb(ev.height);
       }
     };
@@ -2715,6 +2812,29 @@ export default class ThreeView<
     this.resize(width, height, pixelRatio);
   };
 
+  /**
+   * Resolves a picked batch ID into feature information via the engine's
+   * property store.
+   */
+  private resolvePickedFeature(batchId: number): PickedFeature {
+    const prop = this._core?.readPropertyByGlobalBatchId(batchId);
+    if (prop) {
+      return {
+        properties: prop.properties,
+        // The GPU pick returns the clicked instance's id; report the
+        // feature's canonical batch id instead so it matches the id the
+        // evaluator exposes (a MultiPoint feature spans many instances).
+        batchId: prop.batchId ?? batchId,
+        layerId: prop.layerId,
+      };
+    }
+    return {
+      properties: {},
+      batchId,
+      layerId: undefined,
+    };
+  }
+
   /**
    * Handles pick events and emits the picked feature information.
    * @param pickArr - Array of picked batch IDs
@@ -2723,28 +2843,34 @@ export default class ThreeView<
     this._renderFlag.forceUpdate = true;
 
     if (pickArr.length > 0) {
-      const batchId = pickArr[0];
-      const prop = this._core?.readPropertyByGlobalBatchId(batchId);
-      if (prop) {
-        const pickedFeature: PickedFeature = {
-          properties: prop.properties,
-          batchId,
-          layerId: prop.layerId,
-        };
-        this.emit("pick", pickedFeature);
-      } else {
-        const emptyFeature: PickedFeature = {
-          properties: {},
-          batchId,
-          layerId: undefined,
-        };
-        this.emit("pick", emptyFeature);
-      }
+      this.emit("featureClick", this.resolvePickedFeature(pickArr[0]));
     } else {
-      this.emit("pick", null);
+      this.emit("featureClick", null);
     }
   }
 
+  /**
+   * Handles hover pick results and synthesizes `featureHover` / `featureEnter` /
+   * `featureLeave` events by diffing against the previously hovered feature.
+   * @param pickArr - Array of picked batch IDs
+   */
+  private onHoverPick(pickArr: number[]) {
+    // The pick render re-bakes draped vector atlases in pick mode; a main
+    // render is needed to restore their normal colors.
+    this._renderFlag.forceUpdate = true;
+
+    const batchId = pickArr.length > 0 ? pickArr[0] : 0;
+    const prev = this._hoveredFeature;
+    if ((prev?.batchId ?? 0) === batchId) return;
+
+    const feature = batchId > 0 ? this.resolvePickedFeature(batchId) : null;
+    this._hoveredFeature = feature;
+
+    if (prev) this.emit("featureLeave", prev);
+    if (feature) this.emit("featureEnter", feature);
+    this.emit("featureHover", feature);
+  }
+
   /**
    * Gets whether continuous animation mode is enabled.
    */
@@ -2758,6 +2884,14 @@ export default class ThreeView<
     this._renderFlag.animation = v;
   }
 
+  /**
+   * Gets the canvas element the view renders into. Useful for styling,
+   * e.g. switching the cursor from a `featureHover` event listener.
+   */
+  get canvas(): HTMLCanvasElement {
+    return this._renderer.domElement;
+  }
+
   /**
    * Gets the current screen size in pixels.
    */

package/src/material/macro/tileShader.ts

@@ -97,8 +97,18 @@ export function generateTileMapFragment(
   }`
     : "";
   return `
-  vec4 atlasColor = texture2D(uColorAtlas, vOrigUv);
-  vec4 atlasAttr  = texture2D(uAttrAtlas,  vOrigUv);
+  // The atlases are linear-filtered for display, but the pick pass reads
+  // encoded batch ids out of atlasColor: interpolating id colors at feature
+  // edges decodes to batch ids that don't exist (a thin draped polyline is
+  // almost all edge pixels). Snap to the texel center (nearest sampling)
+  // while picking.
+  vec2 nvr_atlasUv = vOrigUv;
+  if (uPickable > 0.) {
+    vec2 nvr_atlasSize = vec2(textureSize(uColorAtlas, 0));
+    nvr_atlasUv = (floor(vOrigUv * nvr_atlasSize) + 0.5) / nvr_atlasSize;
+  }
+  vec4 atlasColor = texture2D(uColorAtlas, nvr_atlasUv);
+  vec4 atlasAttr  = texture2D(uAttrAtlas,  nvr_atlasUv);
 
   // attr.a encodes (winningSlot + 1) / 255 — 0 means no contributing slot.
   int winIdx = int(round(atlasAttr.a * 255.0)) - 1;

package/src/mesh/polyline.ts

@@ -32,6 +32,16 @@ import { setupRTECallback } from "./rtcRteHelper";
 // Sentinel value for picking coordinate when not picking (reused to avoid allocations)
 const PICKING_COORD_SENTINEL = new Vector2(-1, -1);
 
+/**
+ * Minimum stroke width used while rendering the pick pass. A hairline stroke
+ * covers too few pick-buffer texels to click reliably — on the draped path the
+ * 512px tile atlas resolves a thin line to scattered partial texels, so the
+ * decoded batch id is background almost everywhere the line is visible.
+ * Fattening the stroke only for the pick render gives lines the same "click
+ * tolerance" pointing devices get elsewhere; the visible width is untouched.
+ */
+const MIN_PICK_WIDTH = 10;
+
 type Attributes = BatchedFeatureAttributes<{
   position: BufferAttribute;
   // RTE mode attributes (only present when useRTE=true)
@@ -490,11 +500,21 @@ export class PolylineMesh extends BatchedFeatureMesh<
     return this.getEnhancer().states().effectIdsMask;
   }
 
+  /** Visible stroke width to restore after a pick-pass width bump. */
+  private _pickSavedWidth?: number;
+
   onBeforePicking(pickingCoord?: Vector2) {
-    this.getEnhancer().update({ base: { pickable: true } });
+    const enhancer = this.getEnhancer();
+    const width = enhancer.states().width;
+    if (width < MIN_PICK_WIDTH) {
+      this._pickSavedWidth = width;
+      enhancer.update({ base: { pickable: true, width: MIN_PICK_WIDTH } });
+    } else {
+      enhancer.update({ base: { pickable: true } });
+    }
     this.needsUpdate();
 
-    const mutates = this.getEnhancer().mutates();
+    const mutates = enhancer.mutates();
     if (pickingCoord) {
       mutates.setPickingCoord(pickingCoord);
     } else {
@@ -503,9 +523,17 @@ export class PolylineMesh extends BatchedFeatureMesh<
   }
 
   onAfterPicking() {
-    this.getEnhancer().update({ base: { pickable: false } });
+    const enhancer = this.getEnhancer();
+    if (this._pickSavedWidth !== undefined) {
+      enhancer.update({
+        base: { pickable: false, width: this._pickSavedWidth },
+      });
+      this._pickSavedWidth = undefined;
+    } else {
+      enhancer.update({ base: { pickable: false } });
+    }
     this.needsUpdate();
-    this.getEnhancer().mutates().setPickingCoord(PICKING_COORD_SENTINEL);
+    enhancer.mutates().setPickingCoord(PICKING_COORD_SENTINEL);
   }
 
   _getDefaultBatchAttributeValues(): DefaultBatchAttributeValues {

package/src/mesh/sdfText/batchedSdfText.test.ts

@@ -212,6 +212,71 @@ describe("BatchedSdfTextMesh material updates vs per-feature values", () => {
   });
 });
 
+// A feature owns several anchors for MultiPoint geometry and for labels
+// derived from line/polygon vertices via `geometryTypes`. Per-feature setters
+// address features (batch indices), so they must fan out to every anchor the
+// feature owns via the geometry's per-anchor `batch_index` buffer.
+describe("BatchedSdfTextMesh multi-instance fan-out", () => {
+  /** Feature 0 owns anchors 0 and 1 (MultiPoint); feature 1 owns anchor 2. */
+  function multiInstanceMeshEvent(mat: NavaraTextMaterial): NavaraTextMesh {
+    return {
+      material: mat,
+      transform: { tx: 0, ty: 0, tz: 0 },
+      geometry: {
+        batch_ids: { data: new Float32Array([7, 8, 9]), size: 1 },
+        batch_index: { data: new Uint32Array([0, 0, 1]), size: 1 },
+        position: {
+          data: new Float32Array([0, 0, 0, 10, 0, 0, 20, 0, 0]),
+          size: 3,
+        },
+      },
+    } as unknown as NavaraTextMesh;
+  }
+
+  function makeMultiInstanceMesh() {
+    const fontManager = makeFontManager();
+    const ctx = {
+      buf: {
+        removeF32: (d: Float32Array) => d,
+        u32: (d: Uint32Array) => d,
+      },
+      fontManager,
+      renderFlag: { forceUpdate: false },
+    } as unknown as EventContext;
+    const mesh = new BatchedSdfTextMesh(
+      ctx,
+      multiInstanceMeshEvent(material()),
+      "font",
+      { layerId: "layer" },
+    );
+    return { mesh, fontManager };
+  }
+
+  it("applies text and styles to every anchor the feature owns", () => {
+    const { mesh } = makeMultiInstanceMesh();
+    mesh.setTextByBatchIndex(0, "AB");
+    mesh.setFeatureSizeByBatchIndex(0, 32);
+
+    // Feature 0's two anchors got labels (slots 0 and 1), both styled.
+    expect(showOf(mesh, 0)).toBe(1);
+    expect(showOf(mesh, 1)).toBe(1);
+    expect(sizeOf(mesh, 0)).toBe(32);
+    expect(sizeOf(mesh, 1)).toBe(32);
+  });
+
+  it("does not leak styling into other features' anchors", () => {
+    const { mesh } = makeMultiInstanceMesh();
+    mesh.setTextByBatchIndex(0, "AB");
+    mesh.setTextByBatchIndex(1, "CD");
+    mesh.setFeatureShowByBatchIndex(1, false);
+
+    expect(showOf(mesh, 0)).toBe(1);
+    expect(showOf(mesh, 1)).toBe(1);
+    // Feature 1 = anchor 2 = the third label slot.
+    expect(showOf(mesh, 2)).toBe(0);
+  });
+});
+
 // Unprepared text costs a worker round-trip and font-face fetches, and a
 // low-zoom tile spans far more world than the screen shows. With declutter on,
 // `setTextByBatchIndex` therefore parks preparation until a placement pass