@navaramap/three 0.0.6 → 0.0.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@navaramap/three",
   "type": "module",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "main": "dist/index.umd.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -30,13 +30,13 @@
     "astronomy-engine": "2.1.19",
     "stats.js": "0.17.0",
     "three-stdlib": "2.36.1",
-    "@navaramap/engine-api": "0.0.6",
-    "@navaramap/engine": "0.0.6",
-    "@navaramap/font": "0.0.6",
-    "@navaramap/three-api": "0.0.6",
-    "@navaramap/three-csm": "0.0.6",
-    "@navaramap/core": "0.0.6",
-    "@navaramap/worker": "0.0.6"
+    "@navaramap/core": "0.0.7",
+    "@navaramap/engine": "0.0.7",
+    "@navaramap/engine-api": "0.0.7",
+    "@navaramap/three-api": "0.0.7",
+    "@navaramap/font": "0.0.7",
+    "@navaramap/three-csm": "0.0.7",
+    "@navaramap/worker": "0.0.7"
   },
   "devDependencies": {
     "@playwright/test": "1.61.1",
@@ -71,10 +71,10 @@
     "tweakpane": "4.0.5",
     "vite-plugin-glsl": "1.6.0",
     "vite-plugin-static-copy": "4.1.1",
-    "@navaramap/three-default-descs": "0.0.6",
-    "@navaramap/three-default-plugin": "0.0.6",
-    "@navaramap/three-react": "0.0.6",
-    "@navaramap/three-plugins": "0.0.6"
+    "@navaramap/three-default-descs": "0.0.7",
+    "@navaramap/three-plugins": "0.0.7",
+    "@navaramap/three-default-plugin": "0.0.7",
+    "@navaramap/three-react": "0.0.7"
   },
   "scripts": {
     "start": "vite",

package/src/declutter/DeclutterManager.test.ts

@@ -232,4 +232,69 @@ describe("DeclutterManager", () => {
     manager.dispose();
     expect(manager.update(camera, 800, 600, 1000)).toBe("idle");
   });
+
+  // Tile swaps replace a batch wholesale; the new batch's labels start hidden
+  // and would re-earn placement from scratch (throttled pass + fade-in) while
+  // the old batch vanished instantly — a tile-shaped blink. The registry lets
+  // the new batch seed a label as already-granted when the previous pass
+  // showed the same content at (nearly) the same anchor.
+  describe("shown-content registry (tile-swap handoff)", () => {
+    it("answers lookups for content shown by the last pass, within tolerance", () => {
+      const manager = new DeclutterManager(new StubKernel());
+      const p = new FakeParticipant([label({ handle: 0, contentKey: "東京" })]);
+      manager.register(p);
+
+      // Nothing recorded before any pass ran.
+      expect(manager.wasRecentlyShown("東京", R, 0, 0)).toBe(false);
+
+      manager.update(makeCamera(), 800, 600, 0);
+
+      expect(manager.wasRecentlyShown("東京", R, 0, 0)).toBe(true);
+      // Same content, slightly offset anchor (a coarser tile's quantization).
+      expect(manager.wasRecentlyShown("東京", R + 500, 200, -300)).toBe(true);
+      // Same content but far away (an unrelated same-name label).
+      expect(manager.wasRecentlyShown("東京", R + 50_000, 0, 0)).toBe(false);
+      // Different content at the same anchor.
+      expect(manager.wasRecentlyShown("大阪", R, 0, 0)).toBe(false);
+    });
+
+    it("does not record candidates the pass hid", () => {
+      const kernel = new StubKernel();
+      kernel.hiddenFor = (n) => new Uint8Array(n).fill(1);
+      const manager = new DeclutterManager(kernel);
+      const p = new FakeParticipant([label({ handle: 0, contentKey: "東京" })]);
+      manager.register(p);
+
+      manager.update(makeCamera(), 800, 600, 0);
+
+      expect(manager.wasRecentlyShown("東京", R, 0, 0)).toBe(false);
+    });
+
+    it("reflects the latest pass only", () => {
+      const kernel = new StubKernel();
+      const manager = new DeclutterManager(kernel);
+      const p = new FakeParticipant([label({ handle: 0, contentKey: "東京" })]);
+      manager.register(p);
+      const camera = makeCamera();
+
+      manager.update(camera, 800, 600, 0);
+      expect(manager.wasRecentlyShown("東京", R, 0, 0)).toBe(true);
+
+      // The next pass hides it; the registry must forget it.
+      kernel.hiddenFor = (n) => new Uint8Array(n).fill(1);
+      manager.markDirty();
+      manager.update(camera, 800, 600, DeclutterManager.MIN_INTERVAL_MS);
+      expect(manager.wasRecentlyShown("東京", R, 0, 0)).toBe(false);
+    });
+
+    it("ignores candidates without a contentKey", () => {
+      const manager = new DeclutterManager(new StubKernel());
+      const p = new FakeParticipant([label({ handle: 0 })]);
+      manager.register(p);
+
+      manager.update(makeCamera(), 800, 600, 0);
+
+      expect(manager.wasRecentlyShown("", R, 0, 0)).toBe(false);
+    });
+  });
 });

package/src/declutter/DeclutterManager.ts

@@ -49,6 +49,11 @@ export class DeclutterManager {
    *  drift toggles frame to frame instead of flickering. Its full box is
    *  still claimed against competitors. */
   static readonly HYSTERESIS_PX = 6;
+  /** Anchor distance (m) within which two same-content candidates count as
+   *  the same label for the tile-swap handoff. Covers the anchor drift a
+   *  zoom level's tile-grid quantization (and per-tile terrain heights)
+   *  introduces, while staying far below distinct same-name places. */
+  static readonly HANDOFF_TOLERANCE_M = 2000;
 
   private _participants = new Set<DeclutterParticipant>();
   /** Set when the label set changed (register/update/text change) so the next
@@ -60,6 +65,11 @@ export class DeclutterManager {
   private _lastRunAt = Number.NEGATIVE_INFINITY;
   private _lastStepAt = Number.NaN;
 
+  /** Shown candidates of the most recent pass, keyed by content, as flat xyz
+   *  anchor triplets. Read by {@link wasRecentlyShown} when a tile swap
+   *  activates a replacement batch. */
+  private _shownByContent = new Map<string, number[]>();
+
   // Reused per-pass scratch to keep steady-state allocations low.
   private _candidates: DeclutterCandidate[] = [];
   /** Packed candidate input for the kernel; grows as the label count does. */
@@ -100,6 +110,33 @@ export class DeclutterManager {
     this._dirty = true;
   }
 
+  /**
+   * Whether the most recent pass showed `contentKey` anchored within
+   * {@link DeclutterManager.HANDOFF_TOLERANCE_M} of (x, y, z) — i.e. an
+   * equivalent label (typically the swapped-out tile's copy) already holds
+   * this screen space. A batch activating in a tile swap uses this to seed
+   * such labels as granted instead of fading them in from hidden, which
+   * would blink the whole tile's labels out for a pass-plus-fade.
+   */
+  wasRecentlyShown(
+    contentKey: string,
+    x: number,
+    y: number,
+    z: number,
+  ): boolean {
+    const anchors = this._shownByContent.get(contentKey);
+    if (!anchors) return false;
+    const tol = DeclutterManager.HANDOFF_TOLERANCE_M;
+    const tolSq = tol * tol;
+    for (let i = 0; i < anchors.length; i += 3) {
+      const dx = anchors[i] - x;
+      const dy = anchors[i + 1] - y;
+      const dz = anchors[i + 2] - z;
+      if (dx * dx + dy * dy + dz * dz <= tolSq) return true;
+    }
+    return false;
+  }
+
   /**
    * Run a placement pass if one is due, then advance any active show/hide
    * fades. `widthPx`/`heightPx` are the viewport in CSS pixels (matching the
@@ -153,6 +190,16 @@ export class DeclutterManager {
     widthPx: number,
     heightPx: number,
   ): void {
+    // Let participants start font/shape preparation for labels whose anchors
+    // became potentially visible (text batches park preparation while an
+    // anchor is out of view, so world-spanning low-zoom tiles don't fetch
+    // fonts for labels the camera can't see). Results land asynchronously and
+    // mark the pass dirty again, so this pass places only already-shaped
+    // labels.
+    for (const p of this._participants) {
+      p.prepareDeferredLabels?.(camera);
+    }
+
     const candidates = this._candidates;
     candidates.length = 0;
     for (const p of this._participants) {
@@ -212,9 +259,20 @@ export class DeclutterManager {
 
     // Apply results as fade targets. Order is irrelevant — applyDeclutter is
     // idempotent per handle — so iterate in candidate order, not sorted order.
+    // Rebuild the shown-content registry from the same results.
+    this._shownByContent.clear();
     for (let i = 0; i < n; i++) {
       const c = candidates[i];
-      c.owner.applyDeclutter(c.handle, hidden[i] !== 0);
+      const isHidden = hidden[i] !== 0;
+      c.owner.applyDeclutter(c.handle, isHidden);
+      if (!isHidden && c.contentKey) {
+        let anchors = this._shownByContent.get(c.contentKey);
+        if (!anchors) {
+          anchors = [];
+          this._shownByContent.set(c.contentKey, anchors);
+        }
+        anchors.push(c.anchorX, c.anchorY, c.anchorZ);
+      }
     }
 
     candidates.length = 0;
@@ -226,6 +284,7 @@ export class DeclutterManager {
   dispose(): void {
     this._participants.clear();
     this._candidates.length = 0;
+    this._shownByContent.clear();
   }
 
   private _snapshotChanged(

package/src/declutter/types.ts

@@ -1,3 +1,5 @@
+import type { PerspectiveCamera } from "three";
+
 /**
  * One label/sprite competing for screen space in a declutter pass.
  *
@@ -34,6 +36,13 @@ export type DeclutterCandidate = {
   /** Participant-defined id (label slot for text batches, instance index for
    *  sprites) passed back to `applyDeclutter`. */
   handle: number;
+  /**
+   * Stable identity of what the candidate displays (label text for text
+   * batches). Feeds the manager's shown-content registry so a tile swap can
+   * hand placement over to the replacing batch's identical label without a
+   * hide/fade-in blink. Omit for candidates that don't participate.
+   */
+  contentKey?: string;
 };
 
 /** Duration of the show/hide fade applied to placement results (ms). */
@@ -58,4 +67,12 @@ export type DeclutterParticipant = {
    * anything is fading; returns true while any label is still mid-fade.
    */
   stepDeclutterFade: (deltaMs: number) => boolean;
+  /**
+   * Optional: start preparation (font loading, shaping) for labels that
+   * parked it while their anchor was out of view. Called at the start of
+   * every placement pass with the camera the pass will use — the cadence at
+   * which visibility can actually change. Preparation is asynchronous, so
+   * promoted labels join a *later* pass once their text is applied.
+   */
+  prepareDeferredLabels?: (camera: PerspectiveCamera) => void;
 };

package/src/event/feature.ts

@@ -37,6 +37,14 @@ import { renderText, processTextChanged } from "./features/text";
 
 import { setTransform } from ".";
 
+/**
+ * Upper bound on how long a text batch's render-completion report waits for
+ * label shaping (see processRenderableFeatureAdded). Settling normally takes
+ * tens of milliseconds; the cap exists so a hung font fetch cannot stall the
+ * tile LOD indefinitely.
+ */
+const TEXT_LABELS_SETTLE_TIMEOUT_MS = 2000;
+
 /**
  * Choose the render scene for a non-draped feature based on its material.
  *
@@ -232,7 +240,16 @@ export async function processRenderableFeatureAdded(
   // terrain tile's vector source to this tile once its features report rendered,
   // so reporting before the offscreen scene existed left the terrain tile's
   // vector drape blank until a camera-move re-traverse.
-  if (renderedType) featureHandler.markFeatureIsRendered(renderedType, bits);
+  //
+  // Text batches are the exception: the report drives the Rust tile-LOD swap,
+  // and a text batch draws nothing until its labels finish async font shaping,
+  // which the evaluator only kicks off further down. Reporting here swapped
+  // the parent tile out for a child that couldn't draw yet — a tile-shaped
+  // blank on every LOD refinement. Their report is deferred below.
+  const isTextBatch = obj instanceof BatchedSdfTextMesh;
+  if (renderedType && !isTextBatch) {
+    featureHandler.markFeatureIsRendered(renderedType, bits);
+  }
 
   if (obj instanceof PolygonMesh && polygon && polygon.outline_geometry) {
     const outline = await renderPolygonOutline(ctx, polygon);
@@ -255,7 +272,13 @@ export async function processRenderableFeatureAdded(
     featureLayerId,
     ev.bits,
   );
-  if (obj.visible) {
+  // Text batches also get their initial `featureUpdated` while still
+  // invisible: tiles spawn inactive, and apps that style text through
+  // `featureUpdated` must be able to populate label texts *before* the
+  // tile-LOD swap flips this batch visible (per-label writes persist in the
+  // label data texture, so styling hidden batches is safe). Otherwise labels
+  // could not exist until after the swap, guaranteeing a blank activation.
+  if (obj.visible || isTextBatch) {
     handleFeatureUpdatedEventByLayerId(
       viewEvents,
       layersManager,
@@ -264,6 +287,26 @@ export async function processRenderableFeatureAdded(
       updatedAt,
     );
   }
+
+  // The evaluator runs synchronously inside the emits above, so any font
+  // preparation it *started* is in flight now. Report the text batch rendered
+  // only once those land, so the Rust swap waits until this batch can draw.
+  // The timeout only bounds a hung font fetch — a late or post-removal report
+  // is a safe no-op on the Rust side.
+  //
+  // With declutter on, the evaluator's setters park unprepared text on anchor
+  // visibility instead of preparing it (BatchedSdfTextMesh.setTextByBatchIndex),
+  // so nothing is in flight here and this resolves immediately. That is
+  // deliberate and must stay that way: promotion needs the batch visible,
+  // visibility needs this report, so waiting on parked labels would deadlock
+  // the cycle until the timeout and stall every text tile's swap. Continuity
+  // across decluttered swaps comes from the placement handoff in `setActive`.
+  if (renderedType && obj instanceof BatchedSdfTextMesh) {
+    void obj.whenLabelsSettled(TEXT_LABELS_SETTLE_TIMEOUT_MS).then(() => {
+      featureHandler.markFeatureIsRendered(renderedType, bits);
+      ctx.renderFlag.forceUpdate = true;
+    });
+  }
 }
 
 export async function processRenderableFeatureChanged(

package/src/event/worker.ts

@@ -598,6 +598,12 @@ async function processConstructPolygonBatchedFeature(
       let outlineGeometry: TransferablePolygonOutlineGeometry | undefined;
       if (result.outline_position) {
         const outlinePosition = bufHandler.adoptF32(result.outline_position);
+        const outlinePosition3dHigh = result.outline_position_3d_high
+          ? bufHandler.adoptF32(result.outline_position_3d_high)
+          : undefined;
+        const outlinePosition3dLow = result.outline_position_3d_low
+          ? bufHandler.adoptF32(result.outline_position_3d_low)
+          : undefined;
         const outlineScaleNormalAndCap = result.outline_scale_normal_and_cap
           ? bufHandler.adoptF32(result.outline_scale_normal_and_cap)
           : undefined;
@@ -616,6 +622,18 @@ async function processConstructPolygonBatchedFeature(
                 result.outline_position_size ?? 3,
               )
             : undefined,
+          outlinePosition3dHigh
+            ? new TransferableFloatAttribute(
+                outlinePosition3dHigh,
+                result.outline_position_3d_high_size ?? 3,
+              )
+            : undefined,
+          outlinePosition3dLow
+            ? new TransferableFloatAttribute(
+                outlinePosition3dLow,
+                result.outline_position_3d_low_size ?? 3,
+              )
+            : undefined,
           outlineScaleNormalAndCap
             ? new TransferableFloatAttribute(
                 outlineScaleNormalAndCap,

package/src/index.ts

@@ -125,6 +125,12 @@ import { TexturizedSceneByTileCoordinates, type Scenes } from "./scene";
 import { ShadowMapViewers } from "./ShadowMapViewers";
 import { Source } from "./source";
 import { RendererStats } from "./stats";
+import {
+  sampleTerrainMostDetailed,
+  type SampleTerrainOptions,
+  type SampledTerrainPosition,
+  type TerrainSampleSource,
+} from "./terrain/sampleTerrainMostDetailed";
 import type { TextureOptions } from "./textures";
 import { TileTextureCompositor } from "./tileTexture";
 import {
@@ -140,6 +146,7 @@ import {
   type WorkerPoolPromises,
   type RenderFlag,
   type TileMapByHandle,
+  type SourceRef,
 } from "./type";
 import type { CommonUniforms } from "./uniforms";
 import { isWorker, convertScreenPos, type TextureSlot } from "./utils";
@@ -168,6 +175,10 @@ export { CameraDirection } from "@navaramap/engine";
 export { CascadedShadowMaps, CSMHelper } from "@navaramap/three-csm";
 
 export * from "./type";
+export type {
+  SampleTerrainOptions,
+  SampledTerrainPosition,
+} from "./terrain/sampleTerrainMostDetailed";
 export * from "./constants";
 export * from "./light";
 export * from "./mesh";
@@ -2547,14 +2558,52 @@ export default class ThreeView<
 
   /**
    * Samples the terrain height at a given geodetic position synchronously.
-   * @param pos - Geodetic position (lat in radians, lng in radians; height is ignored)
+   * @param pos - Geodetic position (lat in radians, lng in radians)
    * @returns Terrain height in meters, or undefined if terrain data not loaded
    */
-  sampleTerrainHeight(pos: LatLngHeight): number | undefined {
+  sampleTerrainHeight(pos: LatLng): number | undefined {
     const lle = new LLE(pos.lat, pos.lng, 0);
     return this._core?.sampleTerrainHeight(lle);
   }
 
+  /**
+   * Samples terrain heights at the most detailed zoom level the terrain
+   * source provides, fetching the needed tiles over the network — unlike
+   * {@link sampleTerrainHeight}, which reads only tiles already resident for
+   * rendering and returns coarse-LOD heights (or nothing) when the camera is
+   * far away. Use this to place objects on the ground before the camera has
+   * streamed the area in.
+   *
+   * `source` is a registered `quantized-mesh` / `raster-dem` source: the
+   * {@link Source} handle returned by `addSource`, or its id. The stored
+   * config (including engine defaults and partial-update merges) is what gets
+   * sampled.
+   *
+   * @param source - A registered terrain source (handle or id)
+   * @param positions - Geodetic positions (lat/lng in radians)
+   * @param options - Optional abort signal and fixed-level sampling
+   * @returns One result per input position, in the same order
+   */
+  async sampleTerrainMostDetailed(
+    source: SourceRef,
+    positions: LatLng[],
+    options?: SampleTerrainOptions,
+  ): Promise<SampledTerrainPosition[]> {
+    invariant(this._core);
+    const sourceId = source instanceof Source ? source.id : source;
+    const description = this._core.getSourceDescription(sourceId) as
+      TerrainSampleSource | undefined;
+    if (
+      description?.type !== "quantized-mesh" &&
+      description?.type !== "raster-dem"
+    ) {
+      throw new Error(
+        `sampleTerrainMostDetailed: source "${sourceId}" is not a registered quantized-mesh or raster-dem source`,
+      );
+    }
+    return sampleTerrainMostDetailed(description, positions, options);
+  }
+
   /**
    * 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)

package/src/layers/effect/TransparentPassEffectDesc.ts

@@ -22,7 +22,7 @@ export class TransparentPassEffectDesc extends EffectDesc<
   RenderPass
 > {
   static key = "transparent";
-  static insertAfter = ["ssao", "clouds", "atmosphere", "mrt"];
+  static insertBefore = ["final"];
 
   light = new Group();
   lightsSyncMap = new Map();

package/src/mesh/nvLineGeometry.test.ts

@@ -0,0 +1,88 @@
+import { InterleavedBufferAttribute } from "three";
+import { describe, expect, it } from "vitest";
+
+import { NvLineGeometry } from "./nvLineGeometry";
+
+// 4 vertices → 3 candidate segments (0-1, 1-2, 2-3)
+const HIGH = new Float32Array([0, 0, 0, 10, 0, 0, 20, 0, 0, 30, 0, 0]);
+const LOW = new Float32Array([0.1, 0, 0, 0.2, 0, 0, 0.3, 0, 0, 0.4, 0, 0]);
+
+describe("NvLineGeometry.setPositionsHighLow", () => {
+  it("builds interleaved start/end high/low attributes per segment", () => {
+    const geometry = new NvLineGeometry();
+    geometry.setPositionsHighLow(HIGH, LOW);
+
+    const startHigh = geometry.getAttribute(
+      "instanceStartHigh",
+    ) as InterleavedBufferAttribute;
+    const endHigh = geometry.getAttribute(
+      "instanceEndHigh",
+    ) as InterleavedBufferAttribute;
+    const startLow = geometry.getAttribute(
+      "instanceStartLow",
+    ) as InterleavedBufferAttribute;
+    const endLow = geometry.getAttribute(
+      "instanceEndLow",
+    ) as InterleavedBufferAttribute;
+
+    // Same layout as LineSegmentsGeometry.setPositions: one interleaved
+    // buffer of stride 6, start at offset 0, end at offset 3.
+    expect(startHigh.data).toBe(endHigh.data);
+    expect(startLow.data).toBe(endLow.data);
+    expect(startHigh.data.stride).toBe(6);
+    expect(startHigh.offset).toBe(0);
+    expect(endHigh.offset).toBe(3);
+
+    // 3 segments
+    expect(startHigh.count).toBe(3);
+    expect(startLow.count).toBe(3);
+
+    // segment 1 = vertices 1 → 2
+    expect(startHigh.getX(1)).toBe(10);
+    expect(endHigh.getX(1)).toBe(20);
+    expect(startLow.getX(1)).toBeCloseTo(0.2);
+    expect(endLow.getX(1)).toBeCloseTo(0.3);
+  });
+
+  it("computes bounds from reconstructed high+low positions", () => {
+    // setPositions is not called in RTE mode, so setPositionsHighLow must
+    // provide the bounding volumes itself (culling / depth sorting read them).
+    const geometry = new NvLineGeometry();
+    geometry.setPositionsHighLow(HIGH, LOW);
+
+    const box = geometry.boundingBox;
+    const sphere = geometry.boundingSphere;
+    expect(box).not.toBeNull();
+    expect(sphere).not.toBeNull();
+
+    // absolute x spans [0.1, 30.4], y = z = 0
+    expect(box?.min.x).toBeCloseTo(0.1, 5);
+    expect(box?.max.x).toBeCloseTo(30.4, 5);
+    expect(box?.min.y).toBe(0);
+    expect(box?.max.z).toBe(0);
+
+    expect(sphere?.center.x).toBeCloseTo(15.25, 5);
+    expect(sphere?.radius).toBeCloseTo(15.15, 5);
+  });
+
+  it("skips the same segments as setPositions", () => {
+    const geometry = new NvLineGeometry();
+    const skip = new Uint32Array([1]); // drop segment starting at vertex 1
+    geometry.setPositions(HIGH, skip);
+    geometry.setPositionsHighLow(HIGH, LOW, skip);
+
+    const start = geometry.getAttribute(
+      "instanceStart",
+    ) as InterleavedBufferAttribute;
+    const startHigh = geometry.getAttribute(
+      "instanceStartHigh",
+    ) as InterleavedBufferAttribute;
+
+    expect(startHigh.count).toBe(2);
+    expect(startHigh.count).toBe(start.count);
+
+    // remaining segments are 0→1 and 2→3
+    expect(startHigh.getX(0)).toBe(0);
+    expect(startHigh.getX(1)).toBe(20);
+  });
+});