@navaramap/three 0.0.1 → 0.0.2

package/src/material/enhancer/sdfText/sdfTextBaseEnhancer/mutates.ts

@@ -44,6 +44,7 @@ export const createBaseMutates = (
     uTextWidth: { value: 0.0 },
     uTextHeight: { value: 0.0 },
     uBgYBounds: { value: new Vector2(0.0, 1.0) },
+    uDeclutterHide: { value: 0.0 },
     uRTCCenter: {
       value: new Vector3(
         rtcCenter?.[0] ?? 0,
@@ -113,6 +114,7 @@ export const createBaseMutates = (
       uniforms.uTextWidth = refs.uTextWidth;
       uniforms.uTextHeight = refs.uTextHeight;
       uniforms.uBgYBounds = refs.uBgYBounds;
+      uniforms.uDeclutterHide = refs.uDeclutterHide;
       uniforms.uRTCCenter = refs.uRTCCenter;
       uniforms.uRTCCenterView = refs.uRTCCenterView;
       uniforms.uEyeRTELow = refs.uEyeRTELow;
@@ -228,5 +230,9 @@ export const createBaseMutates = (
     setBatchId: (id: number) => {
       refs.nvr_uBatchId.value = id;
     },
+
+    setDeclutterHide: (value: number) => {
+      refs.uDeclutterHide.value = value;
+    },
   };
 };

package/src/material/enhancer/sdfText/sdfTextBaseEnhancer/types.ts

@@ -103,6 +103,10 @@ export type SdfTextBaseRefs = {
   uTextWidth: UniformValue<number>;
   uTextHeight: UniformValue<number>;
   uBgYBounds: UniformValue<Vector2>;
+  /** Screen-space declutter hide factor (0 = shown … 1 = hidden), animated
+   *  by the declutter fade. Driven by the declutter pass, not by material
+   *  style updates. */
+  uDeclutterHide: UniformValue<number>;
   uRTCCenter: UniformValue<Vector3>;
   uRTCCenterView: UniformValue<Vector3>;
   uEyeRTELow: UniformValue<Vector3>;
@@ -180,5 +184,12 @@ export type SdfTextBaseMutates = Mutates<
      * Set the batch ID uniform (immutable after mount, but needed for batch creation).
      */
     setBatchId: (batchId: number) => void;
+    /**
+     * Set the declutter hide factor (0 = shown … 1 = hidden); the fragment
+     * shader scales opacity by `1 - value` and the vertex shader hard-culls
+     * at 1. Kept separate from `show`/`opacity` so user-driven visibility and
+     * declutter results compose instead of clobbering each other.
+     */
+    setDeclutterHide: (value: number) => void;
   }
 >;

package/src/material/enhancer/tileComposite/tileCompositeBaseEnhancer/mutates.test.ts

@@ -0,0 +1,83 @@
+import { Color, Texture, Vector2 } from "three";
+import { describe, expect, it } from "vitest";
+
+import { createTestTileHandler } from "../../../../test-utils/engine";
+import type { RasterCompositeLayer } from "../../../../tileTexture/types";
+
+import {
+  createCoreUniformMutates,
+  type CompositeUniformTarget,
+} from "./mutates";
+
+// The real Rust `mercator_y` (clamped to the WM band), reached through the
+// same context handler the app injects — the clamp regression below exercises
+// the production implementation, not a reimplementation.
+const { mercatorY } = createTestTileHandler();
+
+const rasterLayer = (
+  reproject: [number, number] | undefined,
+): RasterCompositeLayer => ({
+  absSlot: 0,
+  region: "raster",
+  texture: null,
+  uvOffset: new Vector2(0, 0),
+  uvScale: new Vector2(1, 1),
+  kind: "raster",
+  color: new Color(1, 1, 1),
+  opacity: 1,
+  water: false,
+  reproject,
+});
+
+const bind = (reproject: [number, number] | undefined) => {
+  const mutates = createCoreUniformMutates(mercatorY);
+  const target: CompositeUniformTarget = {};
+  mutates.attachUniforms(target, 1, new Texture());
+  mutates.bindSlot(0, rasterLayer(reproject));
+  return target;
+};
+
+describe("bindSlot Mercator reprojection constants", () => {
+  it("clamps a polar latitude band to the WebMercator limit instead of NaN", () => {
+    // A z0 Geographic terrain tile's band is ±90°, and Rust hands it over as
+    // f32 — slightly PAST ±π/2, where an unclamped log(tan(...)) is NaN. A
+    // NaN span fails the shader's `abs(mDen) > 1e-3` guard, silently skipping
+    // reprojection for the whole tile (imagery squashes toward the equator).
+    const f32HalfPi = Math.fround(Math.PI / 2);
+    const target = bind([-f32HalfPi, f32HalfPi]);
+
+    const merc = target.uReprojectMerc.value[0];
+    // Band start/span from the clamped WM limit: mRs = -π, mDen = 2π.
+    expect(merc.x).toBeCloseTo(-Math.PI, 5);
+    expect(merc.y).toBeCloseTo(2 * Math.PI, 5);
+    // Both edges sit on the WM limit → both polar-cap clamp flags set.
+    expect(merc.z).toBe(1);
+    expect(merc.w).toBe(1);
+    expect(target.uReproject.value[0]).toBe(1);
+  });
+
+  it("keeps an interior band un-clamped and un-flagged", () => {
+    const south = 0.2;
+    const north = 0.7;
+    const target = bind([south, north]);
+
+    const merc = target.uReprojectMerc.value[0];
+    expect(merc.x).toBeCloseTo(mercatorY(south), 9);
+    expect(merc.y).toBeCloseTo(mercatorY(north) - mercatorY(south), 9);
+    expect(merc.z).toBe(0);
+    expect(merc.w).toBe(0);
+  });
+
+  it("flags but does not NaN a band touching one WM edge", () => {
+    // z1 north Geographic tile: [0, 90°]. South edge is fine; the north edge
+    // must clamp to the WM limit and set only the top polar-cap flag.
+    const target = bind([0, Math.fround(Math.PI / 2)]);
+
+    const merc = target.uReprojectMerc.value[0];
+    expect(merc.x).toBeCloseTo(0, 9);
+    expect(merc.y).toBeCloseTo(Math.PI, 5);
+    expect(merc.z).toBe(1);
+    expect(merc.w).toBe(0);
+    expect(Number.isFinite(merc.y)).toBe(true);
+  });
+});

package/src/material/enhancer/tileComposite/tileCompositeBaseEnhancer/mutates.ts

@@ -26,7 +26,11 @@ export type CoreUniformMutates = {
   bindSlot: (compactSlot: number, layer: CompositeLayer | undefined) => void;
 };
 
-export function createCoreUniformMutates(): CoreUniformMutates {
+/** `mercatorY` is Rust's clamped WebMercator northing, injected through the
+ * event context (`TileHandler.mercatorY`) like every other engine call. */
+export function createCoreUniformMutates(
+  mercatorY: (lat: number) => number,
+): CoreUniformMutates {
   const refs = {
     uShows: new Uniform<number[]>([]),
     uOpacities: new Uniform<number[]>([]),
@@ -120,8 +124,14 @@ export function createCoreUniformMutates(): CoreUniformMutates {
         const span = (Tn - Ts) / layer.uvScale.y;
         const Rs = Ts - layer.uvOffset.y * span;
         const Rn = Rs + span;
-        const mRs = Math.log(Math.tan(Math.PI * 0.25 + Rs * 0.5));
-        const mRn = Math.log(Math.tan(Math.PI * 0.25 + Rn * 0.5));
+        // Rust's clamped Mercator northing — the same function the bake affine
+        // uses (`uv_rect_from_extents_mercator`), so the pasted band stays
+        // aligned with the baked render target. The clamp matters: a polar
+        // tile's band reaches ±90° (as f32, slightly past it), where unclamped
+        // log(tan(...)) returns NaN — and a NaN span fails the shader's
+        // `abs(mDen)` guard, silently disabling reprojection for the tile.
+        const mRs = mercatorY(Rs);
+        const mRn = mercatorY(Rn);
         // Polar cap: clamp the overshoot onto the band-edge texel when this tile's
         // north/south edge sits on the WebMercator latitude limit.
         const clampTop = Rn >= WM_MAX_LAT - 1e-4 ? 1 : 0;

package/src/mesh/batchTexture.ts

@@ -183,8 +183,7 @@ export function getRowIndex(
   row: BatchTextureRowKey,
 ): number {
   const config = material.userData.batchTextureConfig as
-    | BatchTextureConfig
-    | undefined;
+    BatchTextureConfig | undefined;
   invariant(config);
 
   const rowIndex = config.rows.indexOf(row);
@@ -238,8 +237,7 @@ export function updateBatchAttribute(
   const data = texture.image.data as Float32Array;
   const texWidth = texture.image.width;
   const config = material.userData.batchTextureConfig as
-    | BatchTextureConfig
-    | undefined;
+    BatchTextureConfig | undefined;
   const rowCount = config?.rows.length ?? BATCH_TEXTURE_ROW.length;
 
   switch (attribute) {

package/src/mesh/batchedSdfText.ts

@@ -6,6 +6,10 @@ import type { FontManager } from "@navaramap/font";
 import { type Color } from "three";
 import invariant from "tiny-invariant";
 
+import type {
+  DeclutterCandidate,
+  DeclutterParticipant,
+} from "../declutter/types";
 import type { EventContext } from "../event/context";
 
 import { InstancedMesh, type InstancedMeshOptions } from "./instanced";
@@ -36,7 +40,7 @@ type PositionsInfo = PositionsInfoBase &
 
 export class BatchedSdfTextMesh
   extends InstancedMesh<SDFTextMesh>
-  implements PickableMesh
+  implements PickableMesh, DeclutterParticipant
 {
   readonly ctx: EventContext;
   /** The font identifier from material — may be a family name or a URL. */
@@ -79,6 +83,41 @@ export class BatchedSdfTextMesh
       this._highQuality,
       () => this._revalidateStaleMeshes(),
     );
+    ctx.declutter?.register(this);
+  }
+
+  // --- DeclutterParticipant ---
+
+  collectDeclutterCandidates(out: DeclutterCandidate[]): void {
+    if (!this.visible) return;
+    const meshes = this.meshes();
+    for (let i = 0; i < meshes.length; i++) {
+      const candidate = meshes[i].getDeclutterCandidate(this, i);
+      if (candidate) out.push(candidate);
+    }
+  }
+
+  applyDeclutter(handle: number, hidden: boolean): void {
+    this.meshes()[handle]?.setDeclutterHidden(hidden);
+  }
+
+  stepDeclutterFade(deltaMs: number): boolean {
+    let animating = false;
+    for (const mesh of this.meshes()) {
+      animating = mesh.stepDeclutterFade(deltaMs) || animating;
+    }
+    return animating;
+  }
+
+  /** Candidates changed (text, style, position, visibility): ask the shared
+   *  declutter pass to re-place on its next update. */
+  private _markDeclutterDirty(): void {
+    this.ctx.declutter?.markDirty();
+  }
+
+  override setActive(active: boolean) {
+    super.setActive(active);
+    this._markDeclutterDirty();
   }
 
   /**
@@ -111,6 +150,7 @@ export class BatchedSdfTextMesh
           // Force a rebuild even though the text string is unchanged: the baked
           // atlas rects and glyph retains must refresh against the new metrics.
           mesh.setText(text, true);
+          this._markDeclutterDirty();
           this._needRender?.();
         })
         .catch((err: unknown) => {
@@ -222,6 +262,8 @@ export class BatchedSdfTextMesh
           : position.subarray(posIdx, posIdx + positionSize);
         this.meshes()[i].setPosition(pos, RTE, transform);
       }
+      // Anchors moved (e.g. terrain height resolution) — re-place labels.
+      this._markDeclutterDirty();
     }
 
     const fontIdentifier = m.material.font ?? this._fontIdentifier;
@@ -292,6 +334,7 @@ export class BatchedSdfTextMesh
       mesh.update(material, forceUpdate);
       this.markVisibility(mesh);
     }
+    this._markDeclutterDirty();
 
     if (needRender) needRender();
   }
@@ -412,6 +455,7 @@ export class BatchedSdfTextMesh
             // Restore intended visibility now that text content is available
             mesh.visible = intendedVisible;
             this.markVisibility(mesh);
+            this._markDeclutterDirty();
             this._needRender?.();
           })
           .catch((err: unknown) => {
@@ -422,6 +466,7 @@ export class BatchedSdfTextMesh
       }
       mesh.setText(text);
       this.markVisibility(mesh);
+      this._markDeclutterDirty();
       this._needRender?.();
     }
   }
@@ -438,6 +483,7 @@ export class BatchedSdfTextMesh
     if (mesh) {
       mesh._setFeatureShow(rawVisible);
       this.markVisibility(mesh);
+      this._markDeclutterDirty();
     }
   }
 
@@ -445,6 +491,7 @@ export class BatchedSdfTextMesh
     const mesh = this.meshes()[batchIndex];
     if (mesh) {
       mesh.setHeight(height);
+      this._markDeclutterDirty();
     }
   }
 
@@ -452,6 +499,18 @@ export class BatchedSdfTextMesh
     const mesh = this.meshes()[batchIndex];
     if (mesh) {
       mesh.setSize(size);
+      this._markDeclutterDirty();
+    }
+  }
+
+  setFeatureDeclutterPriorityByBatchIndex(
+    batchIndex: number,
+    priority: number,
+  ) {
+    const mesh = this.meshes()[batchIndex];
+    if (mesh) {
+      mesh.setDeclutterPriority(priority);
+      this._markDeclutterDirty();
     }
   }
 
@@ -466,6 +525,7 @@ export class BatchedSdfTextMesh
   }
 
   dispose() {
+    this.ctx.declutter?.unregister(this);
     this._unsubscribeEvict?.();
     this._unsubscribeEvict = undefined;
     const q = this._highQuality;

package/src/mesh/sdfText.ts

@@ -26,6 +26,11 @@ import {
   Vector2,
 } from "three";
 
+import {
+  DECLUTTER_FADE_MS,
+  type DeclutterCandidate,
+  type DeclutterParticipant,
+} from "../declutter/types";
 import type { MaterialEnhancer } from "../material/enhancer/MaterialEnhancer";
 import {
   createSdfTextMaterialEnhancer,
@@ -219,6 +224,27 @@ export class SDFTextMesh
   private _requestRender?: () => void;
   // The COLRv1 color atlas is always FontManager-owned; no local field needed.
 
+  /** World-space anchor in ECEF meters (f64), kept in sync with the position
+   *  uniforms so the declutter pass can project it without touching WASM. */
+  private _worldAnchor = new Float64Array(3);
+  /** Whether this label participates in screen-space decluttering. */
+  private _declutter = false;
+  /** Layer-level placement priority from the material. */
+  private _declutterPriority = 0;
+  /** Per-feature priority set through the evaluator; overrides the layer
+   *  value when defined. */
+  private _declutterPriorityOverride: number | undefined;
+  /** Current animated hide factor (mirrors the uDeclutterHide uniform) and
+   *  the placement target it is fading toward. */
+  private _declutterHide = 0;
+  private _declutterTarget = 0;
+  /** Text block dimensions in em units, mirroring the uTextWidth/uTextHeight/
+   *  uBgYBounds uniforms; 0 width means "no collision box" (empty text). */
+  private _labelWidthEm = 0;
+  private _labelHeightEm = 0;
+  private _labelMinYEm = 0;
+  private _labelMaxYEm = 0;
+
   private _enhancer: MaterialEnhancer<
     ShaderMaterial,
     { base?: SdfTextBaseProps },
@@ -311,6 +337,22 @@ export class SDFTextMesh
       transform.ty,
       transform.tz,
     ]);
+    this._cacheWorldAnchor(position, RTE, [
+      transform.tx,
+      transform.ty,
+      transform.tz,
+    ]);
+
+    // Decluttered labels start hidden and fade in once the placement pass
+    // grants them space — otherwise dense tiles flash their full clutter for
+    // a frame before the first pass runs.
+    this._declutter = material.declutter ?? true;
+    this._declutterPriority = material.declutterPriority ?? 0;
+    if (this._declutter) {
+      this._declutterHide = 1;
+      this._declutterTarget = 1;
+      mutates.setDeclutterHide(1);
+    }
 
     // Register shader hook
     mat.onBeforeCompile = this._enhancer.transformShader;
@@ -446,6 +488,7 @@ export class SDFTextMesh
 
     if (!text) {
       this.geometry.instanceCount = 0;
+      this._labelWidthEm = 0;
       this._setGlyphKeys([]);
       return;
     }
@@ -457,6 +500,7 @@ export class SDFTextMesh
     );
     if (!shapeResult) {
       this.geometry.instanceCount = 0;
+      this._labelWidthEm = 0;
       this._setGlyphKeys([]);
       return;
     }
@@ -546,6 +590,36 @@ export class SDFTextMesh
     this._enhancer.update({ base: { opacity: clampedOpacity } });
   }
 
+  /**
+   * Set this label's declutter fade target; the actual hide factor animates
+   * toward it in {@link stepDeclutterFade}. Deliberately separate from
+   * `visible`/`show`: it neither churns scene-graph membership nor releases
+   * glyph atlas retains, so the declutter pass can retarget it every
+   * placement run at no cost.
+   */
+  setDeclutterHidden(hidden: boolean): void {
+    this._declutterTarget = hidden ? 1 : 0;
+  }
+
+  /**
+   * Advance the hide factor toward its target by `deltaMs / DECLUTTER_FADE_MS`
+   * and push it to the uniform. Returns true while still mid-fade.
+   */
+  stepDeclutterFade(deltaMs: number): boolean {
+    const target = this._declutterTarget;
+    let value = this._declutterHide;
+    if (value === target) return false;
+
+    const step = deltaMs / DECLUTTER_FADE_MS;
+    value =
+      value < target
+        ? Math.min(value + step, target)
+        : Math.max(value - step, target);
+    this._declutterHide = value;
+    this._enhancer.mutates().setDeclutterHide(value);
+    return value !== target;
+  }
+
   _setFeatureWidth(_width: number): void {
     // Width is not applicable to text meshes.
     // This method is intentionally a no-op to satisfy the FeatureMesh guard.
@@ -565,6 +639,80 @@ export class SDFTextMesh
     this._enhancer
       .mutates()
       .setPosition(position, RTE, [transform.tx, transform.ty, transform.tz]);
+    this._cacheWorldAnchor(position, RTE, [
+      transform.tx,
+      transform.ty,
+      transform.tz,
+    ]);
+  }
+
+  /** Reconstruct the absolute ECEF anchor from the same inputs the position
+   *  uniforms receive (RTE high+low split, or RTC-relative + center). */
+  private _cacheWorldAnchor(
+    position: Float32Array | { high: Float32Array; low: Float32Array },
+    RTE: boolean,
+    rtcCenter: [number, number, number],
+  ): void {
+    const anchor = this._worldAnchor;
+    if (RTE) {
+      const p = position as { high: Float32Array; low: Float32Array };
+      anchor[0] = p.high[0] + p.low[0];
+      anchor[1] = p.high[1] + p.low[1];
+      anchor[2] = (p.high[2] ?? 0.0) + (p.low[2] ?? 0.0);
+    } else {
+      const p = position as Float32Array;
+      anchor[0] = p[0] + rtcCenter[0];
+      anchor[1] = p[1] + rtcCenter[1];
+      anchor[2] = (p[2] ?? 0.0) + rtcCenter[2];
+    }
+  }
+
+  /**
+   * Build this label's collision candidate for the shared declutter pass, or
+   * null when it doesn't participate (declutter disabled, hidden, or empty).
+   * The local box mirrors the vertex shader's layout: glyphs span
+   * [0, textWidth] × [bgMinY, bgMaxY] in em units, shifted by the `center`
+   * anchor and scaled by the font size (sdfText.vert.glsl:111-115).
+   */
+  getDeclutterCandidate(
+    owner: DeclutterParticipant,
+    handle: number,
+  ): DeclutterCandidate | null {
+    if (!this._declutter || !this.visible || this._labelWidthEm <= 0) {
+      return null;
+    }
+    const state = this._enhancer.states();
+    const size = state.fontSize;
+    if (size <= 0) return null;
+
+    const cx = Math.min(Math.max(state.center[0], -0.5), 0.5);
+    const cy = Math.min(Math.max(state.center[1], -0.5), 0.5);
+    const w = this._labelWidthEm;
+    const h = this._labelHeightEm;
+    return {
+      anchorX: this._worldAnchor[0],
+      anchorY: this._worldAnchor[1],
+      anchorZ: this._worldAnchor[2],
+      addHeight: state.addHeight,
+      minX: (0 - cx * w) * size,
+      maxX: (w - cx * w) * size,
+      minY: (this._labelMinYEm - cy * h) * size,
+      maxY: (this._labelMaxYEm - cy * h) * size,
+      sizeInMeters: state.sizeInMeters,
+      priority: this._declutterPriorityOverride ?? this._declutterPriority,
+      isShown: this._declutterTarget === 0,
+      owner,
+      handle,
+    };
+  }
+
+  /**
+   * Set a per-feature placement priority (higher wins), overriding the
+   * layer-level `declutterPriority` for this label. Pass `undefined` to fall
+   * back to the layer value. Driven by the feature evaluator.
+   */
+  setDeclutterPriority(priority: number | undefined): void {
+    this._declutterPriorityOverride = priority;
   }
 
   /**
@@ -596,6 +744,17 @@ export class SDFTextMesh
       this.setText(this._text, true);
     }
 
+    // Read before the visibility early-return: the declutter pass consults
+    // these even while other style state is skipped for hidden labels.
+    const nextDeclutter = material.declutter ?? true;
+    if (this._declutter && !nextDeclutter) {
+      // Leaving declutter mode: clear any hide the pass applied — the mesh
+      // stops producing candidates, so nothing else would ever re-show it.
+      this.setDeclutterHidden(false);
+    }
+    this._declutter = nextDeclutter;
+    this._declutterPriority = material.declutterPriority ?? 0;
+
     this.visible = (material.show ?? true) && !!this._text;
     this._syncGlyphRefs();
     if (!this.visible) return;
@@ -921,6 +1080,7 @@ export class SDFTextMesh
     const count = renderable.length;
     if (count === 0) {
       this.geometry.instanceCount = 0;
+      this._labelWidthEm = 0;
       return;
     }
 
@@ -976,14 +1136,19 @@ export class SDFTextMesh
 
     this.geometry.instanceCount = count + 1;
 
-    // Update text dimension uniforms via mutates
+    // Update text dimension uniforms via mutates, mirroring them CPU-side for
+    // the declutter pass's collision box.
+    this._labelWidthEm = textWidth / SDF_PX_SIZE;
+    this._labelHeightEm = textHeight / SDF_PX_SIZE;
+    this._labelMinYEm = bgMinY === Infinity ? 0.0 : bgMinY;
+    this._labelMaxYEm = bgMaxY === -Infinity ? 1.0 : bgMaxY;
     this._enhancer
       .mutates()
       .updateTextDimensions(
-        textWidth / SDF_PX_SIZE,
-        textHeight / SDF_PX_SIZE,
-        bgMinY === Infinity ? 0.0 : bgMinY,
-        bgMaxY === -Infinity ? 1.0 : bgMaxY,
+        this._labelWidthEm,
+        this._labelHeightEm,
+        this._labelMinYEm,
+        this._labelMaxYEm,
       );
   }