@navaramap/three 0.0.0

package/src/event/featureEvent.ts

@@ -0,0 +1,81 @@
+import type { EventHandler, FeatureSetId } from "@navaramap/core";
+import type { Object3D } from "three";
+
+import { ModelMesh, type ViewEvents } from "..";
+import { FeatureEvaluator } from "../evaluations";
+import { Layer } from "../layer";
+import { LayersManager } from "../layersManager";
+
+import type { FeatureHandler } from ".";
+
+export const handleFeatureCreatedEventByLayerId = (
+  handler: FeatureHandler,
+  obj: Object3D,
+  viewEvents: EventHandler<ViewEvents>,
+  layersManager: LayersManager,
+  layerId: string,
+  featureSetId: FeatureSetId,
+) => {
+  const layer = layersManager.get(layerId);
+
+  // Create the evaluator
+  const evaluator = new FeatureEvaluator(handler, layerId, featureSetId, obj);
+
+  // Register the feature evaluator with the layer if it exists
+  if (layer && layer instanceof Layer) {
+    layer._registerFeatureEvaluator(featureSetId, evaluator);
+  }
+
+  let credit = undefined;
+  if (obj instanceof ModelMesh && obj.credit) {
+    credit = obj.credit;
+  }
+
+  // Emit the evaluator
+  viewEvents.emit("layer", "featureCreated", layerId, {
+    featureSetId,
+    evaluator,
+    credit,
+  });
+
+  return layer;
+};
+
+export const handleFeatureUpdatedEventByLayerId = (
+  viewEvents: EventHandler<ViewEvents>,
+  layersManager: LayersManager,
+  layerId: string,
+  featureSetId: FeatureSetId,
+  updatedAt: number,
+) => {
+  const layer = layersManager.get(layerId);
+
+  if (!layer) return;
+
+  // Get the existing evaluator or create a new one
+  if (!(layer instanceof Layer)) return;
+  const evaluator = layer._getFeatureEvaluator(featureSetId);
+  if (!evaluator) return;
+
+  // Emit the event with the evaluator
+  viewEvents.emit("layer", "featureUpdated", layerId, {
+    featureSetId,
+    evaluator,
+    updatedAt,
+  });
+};
+
+export const handleFeatureVisibilityChangedEventByLayerId = (
+  layersManager: LayersManager,
+  layerId: string,
+  featureSetId: FeatureSetId,
+  visible: boolean,
+) => {
+  const layer = layersManager.get(layerId);
+
+  if (!layer) return;
+  if (!(layer instanceof Layer)) return;
+
+  // Emit the visibility changed event
+  layer.emit("featureVisibilityChanged", { featureSetId, visible });
+};

package/src/event/features/billboard.ts

@@ -0,0 +1,30 @@
+import type { BillboardMesh as NavaraBillboardMesh } from "@navaramap/engine";
+
+import { InstancedSpriteMesh } from "../../mesh";
+import { FEATURE_RENDER_ORDER } from "../../renderOrder";
+import type { EventContext } from "../context";
+
+export async function renderBillboard(
+  ctx: EventContext,
+  m: NavaraBillboardMesh,
+) {
+  if (!m.material.url) return;
+
+  const mesh = new InstancedSpriteMesh({
+    renderOrder: FEATURE_RENDER_ORDER,
+    ctx,
+  });
+  await mesh._init(m);
+  mesh.setActive(m.active);
+
+  return mesh;
+}
+
+export async function processBillboardChanged(
+  obj: InstancedSpriteMesh,
+  m: NavaraBillboardMesh,
+  active: boolean,
+) {
+  await obj._update(m);
+  obj.setActive(active);
+}

package/src/event/features/model.ts

@@ -0,0 +1,192 @@
+import { ModelMesh as NavaraModelMesh } from "@navaramap/engine";
+import { degreeToRadian } from "@navaramap/three_api";
+import {
+  BufferGeometry,
+  Points,
+  Group,
+  Float32BufferAttribute,
+  PointsMaterial,
+  Box3,
+  Vector3,
+  Box3Helper,
+  Mesh,
+  Sphere,
+} from "three";
+
+import { ModelMesh } from "../../mesh/model";
+import { toCreasedNormalsAsync } from "../../tasks/toCreasedNormalsAsync";
+import type { EventContext } from "../context";
+import {
+  initializeGltfLoader,
+  initializeDracoLoader,
+  decompressDraco,
+} from "../loaders";
+
+/**
+ * Recompute vertex normals via `toCreasedNormalsAsync` for every Mesh in the
+ * loaded scene. Awaited before the `ModelMesh` is constructed so downstream
+ * material/shadow setup observes the final geometry.
+ */
+async function applyCreasedNormals(
+  scene: Group,
+  creaseAngle: number,
+): Promise<void> {
+  const geometries = new Set<BufferGeometry>();
+  scene.traverse((object) => {
+    if (object instanceof Mesh && object.geometry instanceof BufferGeometry) {
+      geometries.add(object.geometry);
+    }
+  });
+
+  await Promise.all(
+    [...geometries].map((geometry) =>
+      toCreasedNormalsAsync(geometry, creaseAngle),
+    ),
+  );
+}
+
+export async function renderModel(ctx: EventContext, m: NavaraModelMesh) {
+  const { rawScene, credit } = await (async () => {
+    if (m.bin) {
+      // buf.u8 returns a short-lived view into WASM memory; copy it since the
+      // bin is consumed asynchronously (Draco / GLTFLoader) via its `.buffer`.
+      const bin = ctx.buf.u8(m.bin)?.slice();
+      if (!bin) {
+        return {};
+      }
+
+      const internal = m.material.__internal__;
+      // PNTS legacy bin path: only the PNTS parser sets `pointCloud=true`, and the
+      // bin here is the extracted position buffer (Draco blob or raw f32), not glTF.
+      // 3D Tiles 1.1 glTF tiles (point cloud or not) take the GLTFLoader path below.
+      if (internal?.pointCloud) {
+        let geometry: BufferGeometry | undefined;
+        const material = new PointsMaterial({
+          size: m.material.pointSize,
+          vertexColors: true,
+          sizeAttenuation: false,
+        });
+
+        if (internal.dracoCompressed) {
+          const { decoder, dispose } = initializeDracoLoader();
+          geometry = await (async () => {
+            try {
+              return await decompressDraco(bin.buffer as ArrayBuffer, decoder);
+            } finally {
+              dispose();
+            }
+          })();
+        } else {
+          geometry = new BufferGeometry();
+          geometry.setAttribute(
+            "position",
+            new Float32BufferAttribute(new Float32Array(bin.buffer), 3),
+          );
+        }
+
+        const group = new Group();
+        if (geometry) {
+          const points: Points = new Points(geometry, material);
+          group.add(points);
+
+          // Add bounding box helper using the precomputed AABB
+          const aabb_center = new Vector3(
+            m.aabb.center.x,
+            m.aabb.center.y,
+            m.aabb.center.z,
+          );
+          const aabb_extent = new Vector3(
+            m.aabb.extent.x,
+            m.aabb.extent.y,
+            m.aabb.extent.z,
+          );
+
+          geometry.boundingBox = new Box3(
+            aabb_center.clone().sub(aabb_extent),
+            aabb_center.clone().add(aabb_extent),
+          );
+
+          geometry.boundingSphere = new Sphere(
+            aabb_center,
+            aabb_extent.length(),
+          );
+
+          if (m.material.showBoundingBox) {
+            const boxHelper = new Box3Helper(geometry.boundingBox, 0xff0000);
+            group.add(boxHelper);
+          }
+        }
+        return { rawScene: group };
+      }
+
+      const { loader, dispose } = initializeGltfLoader();
+      const model = await loader.parseAsync(bin.buffer as ArrayBuffer, "");
+      dispose();
+      if (m.material.showBoundingBox) {
+        model.scene.traverse((child) => {
+          if (child instanceof Mesh) {
+            const boxHelper = new Box3Helper(
+              child.geometry.boundingBox,
+              0x0000ff,
+            );
+            child.add(boxHelper);
+          }
+        });
+      }
+
+      return {
+        rawScene: model.scene,
+        credit: model.asset.copyright,
+      };
+    } else {
+      if (!m.material.url) {
+        return {};
+      }
+      const { loader, dispose } = initializeGltfLoader();
+      let model;
+      try {
+        model = await loader.loadAsync(m.material.url);
+      } catch (e) {
+        console.warn(`Failed to load model: ${m.material.url}`, e);
+        return {};
+      } finally {
+        dispose();
+      }
+      if (m.material.showBoundingBox) {
+        model.scene.traverse((child) => {
+          if (child instanceof Mesh) {
+            const boxHelper = new Box3Helper(
+              child.geometry.boundingBox,
+              0x0000ff,
+            );
+            child.add(boxHelper);
+          }
+        });
+      }
+      return { rawScene: model.scene };
+    }
+  })();
+
+  if (!rawScene) {
+    return;
+  }
+
+  if (m.material.normals) {
+    await applyCreasedNormals(
+      rawScene,
+      m.material.creaseNormalAngle ?? degreeToRadian(30),
+    );
+  }
+
+  const scene = new ModelMesh(ctx, { scene: rawScene, credit }, m);
+
+  return scene;
+}
+
+export function processModelChanged(
+  obj: ModelMesh,
+  m: NavaraModelMesh,
+  active: boolean,
+) {
+  obj._update(m.material, active);
+}

package/src/event/features/modelGpuBytes.test.ts

@@ -0,0 +1,69 @@
+import {
+  BufferGeometry,
+  Float32BufferAttribute,
+  Group,
+  Mesh,
+  MeshBasicMaterial,
+  Uint16BufferAttribute,
+  DataTexture,
+} from "three";
+import { describe, expect, it } from "vitest";
+
+import { sumModelGpuBytes } from "./modelGpuBytes";
+
+describe("sumModelGpuBytes", () => {
+  it("sums geometry attribute + index bytes across the object tree", () => {
+    const geometry = new BufferGeometry();
+    // 3 vertices × 3 floats × 4 bytes = 36 bytes.
+    geometry.setAttribute(
+      "position",
+      new Float32BufferAttribute([0, 0, 0, 1, 0, 0, 0, 1, 0], 3),
+    );
+    // 3 indices × 2 bytes = 6 bytes.
+    geometry.setIndex(new Uint16BufferAttribute([0, 1, 2], 1));
+
+    const group = new Group();
+    group.add(new Mesh(geometry, new MeshBasicMaterial()));
+
+    // Geometry is counted once (GPU_GEOMETRY_RESIDENCY_FACTOR = 1): the CPU
+    // typed arrays are released via onUpload after the first GPU upload, so
+    // only the GPU copy stays resident.
+    expect(sumModelGpuBytes(group)).toBe(36 + 6);
+  });
+
+  it("counts a shared texture only once, without the residency factor", () => {
+    // 2×2 RGBA DataTexture → image.data.byteLength = 16.
+    const tex = new DataTexture(new Uint8Array(16), 2, 2);
+    const matA = new MeshBasicMaterial({ map: tex });
+    const matB = new MeshBasicMaterial({ map: tex });
+
+    const group = new Group();
+    group.add(new Mesh(new BufferGeometry(), matA));
+    group.add(new Mesh(new BufferGeometry(), matB));
+
+    // The shared texture's 16 bytes are counted once, not twice, and textures
+    // are not scaled by the geometry residency factor.
+    expect(sumModelGpuBytes(group)).toBe(16);
+  });
+
+  it("counts geometry and textures once each when both are present", () => {
+    const geometry = new BufferGeometry();
+    // 3 vertices × 3 floats × 4 bytes = 36 bytes.
+    geometry.setAttribute(
+      "position",
+      new Float32BufferAttribute([0, 0, 0, 1, 0, 0, 0, 1, 0], 3),
+    );
+    // 2×2 RGBA DataTexture → 16 bytes.
+    const tex = new DataTexture(new Uint8Array(16), 2, 2);
+
+    const group = new Group();
+    group.add(new Mesh(geometry, new MeshBasicMaterial({ map: tex })));
+
+    // 36 geometry bytes × 1 + 16 texture bytes × 1 = 52.
+    expect(sumModelGpuBytes(group)).toBe(36 + 16);
+  });
+
+  it("returns 0 for an empty object", () => {
+    expect(sumModelGpuBytes(new Group())).toBe(0);
+  });
+});

package/src/event/features/modelGpuBytes.ts

@@ -0,0 +1,87 @@
+import {
+  BufferGeometry,
+  type Material,
+  type Mesh,
+  type Object3D,
+  type Points,
+  type Texture,
+} from "three";
+
+/** After the first GPU upload the model's geometry attributes drop their
+ * CPU-side typed arrays via `onUpload` (see mesh/model.ts →
+ * releaseGeometryArraysAfterUpload), so only the GPU copy stays resident and
+ * each geometry byte is counted once. Mirrors the Rust
+ * `GPU_GEOMETRY_RESIDENCY_FACTOR` used for terrain/vector geometry. */
+const GPU_GEOMETRY_RESIDENCY_FACTOR = 1;
+
+/** Approximate GPU bytes of a texture: `image.data.byteLength` when present
+ * (raw DataTexture), else `width*height*4` (RGBA). Ignores mipmaps.
+ *
+ * Not scaled by the residency factor: `ImageBitmap`-backed textures (the glTF
+ * loader default) hand their pixels to the GPU and keep no CPU copy, so unlike
+ * geometry they are resident only once. `DataTexture`s do keep a CPU copy, but
+ * models rarely use them, so we accept the small undercount for simplicity. */
+function textureGpuBytes(tex: Texture): number {
+  const img = tex.image as
+    | { data?: { byteLength?: number }; width?: number; height?: number }
+    | undefined;
+  if (img?.data?.byteLength) return img.data.byteLength;
+  if (img?.width && img?.height) return img.width * img.height * 4;
+  return 0;
+}
+
+/**
+ * Sum the decoded GPU bytes of a rendered model: every geometry's vertex
+ * attributes + index, plus each unique material texture. This is measured
+ * AFTER glTF/Draco decode (which inflates geometry well beyond the compressed
+ * payload), so it is the accurate figure to report to the memory ledger.
+ *
+ * Kept dependency-free (only `three`) so it can be unit-tested without pulling
+ * in the GLTF/Draco loader module chain.
+ */
+export function sumModelGpuBytes(obj: Object3D): number {
+  let geometryBytes = 0;
+  let textureBytes = 0;
+  const seenGeometries = new Set<BufferGeometry>();
+  const seenTextures = new Set<Texture>();
+  obj.traverse((node) => {
+    const geometry = (node as Mesh | Points).geometry;
+    // Dedupe geometries too, not just textures: glTF instancing reuses one
+    // BufferGeometry across many nodes, and its GPU buffers are uploaded once,
+    // so counting it per-node would over-report and trip eviction early.
+    if (geometry instanceof BufferGeometry && !seenGeometries.has(geometry)) {
+      seenGeometries.add(geometry);
+      for (const attr of Object.values(geometry.attributes)) {
+        const array = (attr as { array?: { byteLength?: number } }).array;
+        if (array?.byteLength) geometryBytes += array.byteLength;
+      }
+      if (geometry.index?.array?.byteLength) {
+        geometryBytes += geometry.index.array.byteLength;
+      }
+    }
+    const material = (node as Mesh | Points).material as
+      | Material
+      | Material[]
+      | undefined;
+    const materials = Array.isArray(material)
+      ? material
+      : material
+        ? [material]
+        : [];
+    for (const mat of materials) {
+      for (const value of Object.values(mat)) {
+        if (
+          value &&
+          typeof value === "object" &&
+          "isTexture" in value &&
+          (value as Texture).isTexture &&
+          !seenTextures.has(value as Texture)
+        ) {
+          seenTextures.add(value as Texture);
+          textureBytes += textureGpuBytes(value as Texture);
+        }
+      }
+    }
+  });
+  return geometryBytes * GPU_GEOMETRY_RESIDENCY_FACTOR + textureBytes;
+}

package/src/event/features/point.ts

@@ -0,0 +1,25 @@
+import { PointMesh as NavaraPointMesh } from "@navaramap/engine";
+
+import { InstancedSpriteMesh } from "../../mesh";
+import { FEATURE_RENDER_ORDER } from "../../renderOrder";
+import type { EventContext } from "../context";
+
+export async function renderPoint(ctx: EventContext, m: NavaraPointMesh) {
+  const mesh = new InstancedSpriteMesh({
+    renderOrder: FEATURE_RENDER_ORDER,
+    ctx,
+  });
+  await mesh._init(m);
+  mesh.setActive(m.active);
+
+  return mesh;
+}
+
+export function processPointChanged(
+  obj: InstancedSpriteMesh,
+  m: NavaraPointMesh,
+  active: boolean,
+) {
+  obj._update(m);
+  obj.setActive(active);
+}

package/src/event/features/polygon.ts

@@ -0,0 +1,23 @@
+import type { TileHandle } from "@navaramap/core";
+import type { PolygonMesh as NavaraPolygonMesh } from "@navaramap/engine";
+
+import { PolygonMesh } from "../../mesh";
+import type { EventContext } from "../context";
+
+export async function renderPolygon(
+  ctx: EventContext,
+  mesh: NavaraPolygonMesh,
+  tileHandle: TileHandle | undefined,
+  layerId: string,
+) {
+  return new PolygonMesh(ctx, layerId).init(mesh, tileHandle);
+}
+
+export function processPolygonChanged(
+  obj: PolygonMesh,
+  m: NavaraPolygonMesh,
+  active: boolean,
+  tileHandle: TileHandle | undefined,
+) {
+  obj._update(m.material, active, !!tileHandle);
+}

package/src/event/features/polygonOutline.ts

@@ -0,0 +1,19 @@
+import type { PolygonMesh as NavaraPolygonMesh } from "@navaramap/engine";
+
+import { PolygonOutlineMesh } from "../../mesh";
+import type { EventContext } from "../context";
+
+export async function renderPolygonOutline(
+  ctx: EventContext,
+  mesh: NavaraPolygonMesh,
+) {
+  return new PolygonOutlineMesh(ctx, mesh);
+}
+
+export function processPolygonOutlineChanged(
+  obj: PolygonOutlineMesh,
+  m: NavaraPolygonMesh,
+  active: boolean,
+) {
+  obj._update(m.material, active);
+}

package/src/event/features/polyline.ts

@@ -0,0 +1,19 @@
+import { PolylineMesh as NavaraPolylineMesh } from "@navaramap/engine";
+
+import { PolylineMesh } from "../../mesh";
+import type { EventContext } from "../context";
+
+export async function renderPolyline(
+  ctx: EventContext,
+  mesh: NavaraPolylineMesh,
+) {
+  return new PolylineMesh(ctx).init(mesh);
+}
+
+export function processPolylineChanged(
+  obj: PolylineMesh,
+  m: NavaraPolylineMesh,
+  active: boolean,
+) {
+  obj._update(m.material, active);
+}

package/src/event/features/text.ts

@@ -0,0 +1,71 @@
+import { type TextMesh as NavaraTextMesh } from "@navaramap/engine";
+
+import { BatchedSdfTextMesh } from "../../mesh";
+import { FEATURE_RENDER_ORDER } from "../../renderOrder";
+import type { EventContext } from "../context";
+
+export async function renderText(
+  ctx: EventContext,
+  m: NavaraTextMesh,
+  layerId: string,
+) {
+  const { fontManager } = ctx;
+  const fontUrl = m.material.font;
+  if (!fontUrl || fontUrl === "") {
+    console.warn(
+      "material.font is required for text rendering but was not set.",
+    );
+    return;
+  }
+
+  // Use SDF pipeline when a font URL is specified and FontManager is available
+  if (fontManager) {
+    try {
+      // Load font(s) then shape the text so the cache is populated before mesh construction.
+      // For font families, only the face URLs needed for `text` are loaded (lazy).
+      // For raw URLs, the single font file is loaded directly.
+      const text = m.material.text ?? "";
+      const highQuality = m.material.highQuality ?? false;
+      const loadedFaceUrls = new Set<string>();
+      if (fontManager.isFamily(fontUrl)) {
+        if (text)
+          await fontManager.prepareText(
+            fontUrl,
+            text,
+            highQuality,
+            loadedFaceUrls,
+          );
+      } else {
+        await fontManager.loadFont(fontUrl, highQuality);
+        if (text) await fontManager.prepareText(fontUrl, text, highQuality);
+      }
+
+      const textGroup = new BatchedSdfTextMesh(
+        ctx,
+        m,
+        fontUrl,
+        {
+          renderOrder: FEATURE_RENDER_ORDER,
+          layerId,
+        },
+        loadedFaceUrls,
+      );
+      textGroup.setActive(m.active);
+
+      return textGroup;
+    } catch (e) {
+      console.warn(`Failed to load or prepare font "${fontUrl}". Error:`, e);
+    }
+  }
+}
+
+export async function processTextChanged(
+  obj: BatchedSdfTextMesh,
+  m: NavaraTextMesh,
+  active: boolean,
+) {
+  await obj._update(m, () => {
+    obj.ctx.renderFlag.forceUpdate = true;
+  });
+  obj.setActive(active);
+}