@navaramap/three 0.0.0

package/src/tasks/constructPolygonBatchedFeature.ts

@@ -0,0 +1,34 @@
+import {
+  ConstructedPolygonGeometryLike,
+  ExtentRadianF32Like,
+  PolygonMaterialLike,
+  TransferablePolygonBatchedFeatureLike,
+} from "@navaramap/core";
+import type { Promise } from "@navaramap/worker";
+
+import { queueTask } from "./queueTask";
+
+export function constructPolygonBatchedFeature(
+  transferableBatchedFeatureLike: TransferablePolygonBatchedFeatureLike,
+  materialLike: PolygonMaterialLike,
+  flat: boolean,
+  tileExtent: ExtentRadianF32Like | undefined,
+): Promise<ConstructedPolygonGeometryLike | undefined> {
+  return queueTask(
+    "constructPolygonBatchedFeature",
+    [transferableBatchedFeatureLike, materialLike, flat, tileExtent],
+    {
+      transfer: [
+        transferableBatchedFeatureLike.batch_ids.buffer,
+        transferableBatchedFeatureLike.batch_indices.buffer,
+        transferableBatchedFeatureLike.expected_winding_orders.buffer,
+        transferableBatchedFeatureLike.holes.buffer,
+        transferableBatchedFeatureLike.holes_boundaries.buffer,
+        transferableBatchedFeatureLike.holes_sizes.buffer,
+        transferableBatchedFeatureLike.holes_total_sizes.buffer,
+        transferableBatchedFeatureLike.outer_ring.buffer,
+        transferableBatchedFeatureLike.outer_ring_sizes.buffer,
+      ],
+    },
+  );
+}

package/src/tasks/constructPolylineBatchedFeature.ts

@@ -0,0 +1,27 @@
+import {
+  ConstructedPolylineGeometryLike,
+  PolylineMaterialLike,
+  TransferablePolylineBatchedFeatureLike,
+} from "@navaramap/core";
+import type { Promise } from "@navaramap/worker";
+
+import { queueTask } from "./queueTask";
+
+export function constructPolylineBatchedFeature(
+  transferableBatchedFeatureLike: TransferablePolylineBatchedFeatureLike,
+  materialLike: PolylineMaterialLike,
+  flat: boolean,
+): Promise<ConstructedPolylineGeometryLike | undefined> {
+  return queueTask(
+    "constructPolylineBatchedFeature",
+    [transferableBatchedFeatureLike, materialLike, flat],
+    {
+      transfer: [
+        transferableBatchedFeatureLike.points.buffer,
+        transferableBatchedFeatureLike.points_sizes.buffer,
+        transferableBatchedFeatureLike.batch_ids.buffer,
+        transferableBatchedFeatureLike.batch_indices.buffer,
+      ],
+    },
+  );
+}

package/src/tasks/constructQuantizedMeshTerrainMesh.ts

@@ -0,0 +1,24 @@
+import {
+  ReturnedConstructedTerrainMeshLike,
+  TransferableTileLike,
+} from "@navaramap/core";
+import type { Promise } from "@navaramap/worker";
+
+import { queueTask } from "./queueTask";
+
+export function constructQuantizedMeshTerrainMesh(
+  bytes: Uint8Array,
+  tileLike: TransferableTileLike,
+  skirt: boolean,
+  skirtExaggeration: number,
+  geographic: boolean,
+  tms: boolean,
+): Promise<{
+  result: ReturnedConstructedTerrainMeshLike;
+}> {
+  return queueTask(
+    "constructQuantizedMeshTerrainMesh",
+    [bytes, tileLike, skirt, skirtExaggeration, geographic, tms],
+    { transfer: [bytes.buffer] },
+  );
+}

package/src/tasks/constructTerrainMesh.ts

@@ -0,0 +1,25 @@
+import {
+  ReturnedConstructedTerrainMeshLike,
+  TransferableRasterDEMDataLike,
+  TransferableTileLike,
+} from "@navaramap/core";
+import type { Promise } from "@navaramap/worker";
+
+import { queueTask } from "./queueTask";
+
+export function constructTerrainMesh(
+  bytes: Uint8Array,
+  tileLike: TransferableTileLike,
+  rasterDEMDataLike: TransferableRasterDEMDataLike,
+  size: number,
+  skirt: boolean,
+  skirtExaggeration: number,
+): Promise<{
+  result: ReturnedConstructedTerrainMeshLike;
+}> {
+  return queueTask(
+    "constructTerrainMesh",
+    [bytes, tileLike, rasterDEMDataLike, size, skirt, skirtExaggeration],
+    { transfer: [bytes.buffer] },
+  );
+}

package/src/tasks/getImageDataFromBlob.ts

@@ -0,0 +1,13 @@
+import type { Promise } from "@navaramap/worker";
+
+import { queueTask } from "./queueTask";
+
+/**
+ * Decode a compressed image Blob into raw RGBA pixels on a worker thread.
+ * The Blob is cheap to clone across the worker boundary (it references
+ * immutable backing storage), so the whole decode — including
+ * `createImageBitmap` — stays off the main thread.
+ */
+export function getImageDataFromBlob(blob: Blob): Promise<Uint8ClampedArray> {
+  return queueTask("getImageDataFromBlob", [blob]);
+}

package/src/tasks/getImageDataFromImageBitmap.ts

@@ -0,0 +1,12 @@
+import type { Promise } from "@navaramap/worker";
+
+import { queueTask } from "./queueTask";
+
+export function getImageDataFromImageBitmap(
+  img: ImageBitmap,
+  canvas: OffscreenCanvas,
+): Promise<Uint8ClampedArray> {
+  return queueTask("getImageDataFromImageBitmap", [img, canvas], {
+    transfer: [img, canvas],
+  });
+}

package/src/tasks/parseMvtTile.ts

@@ -0,0 +1,22 @@
+import { ExtentRadianF32Like } from "@navaramap/core";
+import type { ParsedMvtTileResultLike, Promise } from "@navaramap/worker";
+
+import { queueTask } from "./queueTask";
+
+export function parseMvtTile(
+  bytes: Uint8Array,
+  x: number,
+  y: number,
+  z: number,
+  tileExtent: ExtentRadianF32Like | undefined,
+  compression: number,
+  configsJson: string,
+): Promise<ParsedMvtTileResultLike> {
+  return queueTask(
+    "parseMvtTile",
+    [bytes, x, y, z, tileExtent, compression, configsJson],
+    {
+      transfer: [bytes.buffer],
+    },
+  );
+}

package/src/tasks/queueTask.ts

@@ -0,0 +1,19 @@
+import {
+  queueTask as queueTaskImpl,
+  type ExecOptions,
+  type TaskParams,
+  type WorkerTask,
+} from "@navaramap/worker";
+
+import type { Tasks } from "../worker";
+
+type AllTasks = WorkerTask<Tasks>;
+type TaskNames = keyof AllTasks;
+
+export function queueTask<T extends TaskNames>(
+  method: T,
+  params?: TaskParams<AllTasks, T>,
+  options?: ExecOptions,
+) {
+  return queueTaskImpl(method, params, options);
+}

package/src/tasks/toCreasedNormalsAsync.ts

@@ -0,0 +1,18 @@
+import { type BufferGeometry } from "three";
+
+import { fromBufferGeometryLike, toBufferGeometryLike } from "../utils";
+
+import { queueTask } from "./queueTask";
+
+export async function toCreasedNormalsAsync(
+  geometry: BufferGeometry,
+  creaseAngle?: number,
+): Promise<BufferGeometry> {
+  const [geometryLike, transfer] = toBufferGeometryLike(geometry);
+  const result = await queueTask(
+    "toCreasedNormals",
+    [geometryLike, creaseAngle],
+    { transfer },
+  );
+  return fromBufferGeometryLike(result, geometry);
+}

package/src/tasks/upsampleQuantizedMeshTerrainMesh.ts

@@ -0,0 +1,44 @@
+import {
+  ReturnedConstructedTerrainMeshLike,
+  TransferableTileLike,
+  UpsamplableTerrainGeometryLike,
+} from "@navaramap/core";
+import type { Promise } from "@navaramap/worker";
+
+import { queueTask } from "./queueTask";
+
+export function upsampleQuantizedMeshTerrainMesh(
+  tileLike: TransferableTileLike,
+  parentTileLike: TransferableTileLike,
+  upsamplableGeometryLike: UpsamplableTerrainGeometryLike,
+  skirt: boolean,
+  skirtExaggeration: number,
+  geographic: boolean,
+  tms: boolean,
+): Promise<ReturnedConstructedTerrainMeshLike> {
+  return queueTask(
+    "upsampleQuantizedMeshTerrainMesh",
+    [
+      tileLike,
+      parentTileLike,
+      upsamplableGeometryLike,
+      skirt,
+      skirtExaggeration,
+      geographic,
+      tms,
+    ],
+    {
+      transfer: [
+        upsamplableGeometryLike.uvs.buffer,
+        upsamplableGeometryLike.heights.buffer,
+        upsamplableGeometryLike.indices.buffer,
+        ...(upsamplableGeometryLike.normals
+          ? [upsamplableGeometryLike.normals.buffer]
+          : []),
+        ...(upsamplableGeometryLike.watermask
+          ? [upsamplableGeometryLike.watermask.buffer]
+          : []),
+      ],
+    },
+  );
+}

package/src/tasks/upsampleTerrainMesh.ts

@@ -0,0 +1,39 @@
+import {
+  ReturnedConstructedTerrainMeshLike,
+  TransferableRasterDEMDataLike,
+  TransferableTileLike,
+  UpsamplableTerrainGeometryLike,
+} from "@navaramap/core";
+import type { Promise } from "@navaramap/worker";
+
+import { queueTask } from "./queueTask";
+
+export function upsampleTerrainMesh(
+  tileLike: TransferableTileLike,
+  parentTileLike: TransferableTileLike,
+  rasterDEMDataLike: TransferableRasterDEMDataLike,
+  upsamplableGeometryLike: UpsamplableTerrainGeometryLike,
+  skirt: boolean,
+  skirtExaggeration: number,
+  tms: boolean,
+): Promise<ReturnedConstructedTerrainMeshLike> {
+  return queueTask(
+    "upsampleTerrainMesh",
+    [
+      tileLike,
+      parentTileLike,
+      rasterDEMDataLike,
+      upsamplableGeometryLike,
+      skirt,
+      skirtExaggeration,
+      tms,
+    ],
+    {
+      transfer: [
+        upsamplableGeometryLike.uvs.buffer,
+        upsamplableGeometryLike.heights.buffer,
+        upsamplableGeometryLike.indices.buffer,
+      ],
+    },
+  );
+}

package/src/texture.ts

@@ -0,0 +1,19 @@
+import type { Material, Object3D, Texture } from "three";
+
+// Adjust the texture's aspect ratio automatically.
+export function applyTextureAspect(obj: Object3D) {
+  const material = "material" in obj ? (obj.material as Material) : undefined;
+  if (
+    material &&
+    !Array.isArray(material) &&
+    "map" in material &&
+    material.map
+  ) {
+    const map = material.map as Texture<ImageData>;
+    if (map) {
+      const image = map.image;
+      const aspectRatio = image.height / image.width;
+      obj.scale.y *= aspectRatio;
+    }
+  }
+}

package/src/textures.ts

@@ -0,0 +1,13 @@
+// TODO: Provide an API to specify these settings for each material.
+export type TextureOptions = {
+  maxAnisotropy: number;
+  minFilter: number;
+  magFilter: number;
+  useMipmaps: boolean;
+  maxTextures: number;
+  // Automatically tracked - which additional textures are in use
+  additionalTexturesInUse?: {
+    waterTexture?: boolean;
+    colorMapTexture?: boolean;
+  };
+};

package/src/tileTexture/CompositeShader.snapshot.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+
+import { generateCompositeFragmentShader } from "./CompositeShader";
+import type { CompositeFeatures } from "./types";
+
+const OFF: CompositeFeatures = {
+  hasHillshade: false,
+  hasWater: false,
+  hasElevationHeatmap: false,
+  hasWatermask: false,
+};
+const ALL: CompositeFeatures = {
+  hasHillshade: true,
+  hasWater: true,
+  hasElevationHeatmap: true,
+  hasWatermask: true,
+};
+
+/**
+ * Characterization snapshots: pin the exact generated GLSL across a matrix of
+ * slot counts and feature combinations. The composite-pass refactor (extracting
+ * the base skeleton + per-layer enhancers) must keep output byte-identical —
+ * these snapshots fail loudly if any character drifts.
+ */
+const CASES: {
+  name: string;
+  args: [number, number, number, CompositeFeatures];
+}[] = [
+  { name: "raster+vector, all features off", args: [2, 2, 2, OFF] },
+  { name: "raster+single vector, boundary 24", args: [2, 1, 24, OFF] },
+  { name: "single raster+2 vector, boundary 24", args: [1, 2, 24, OFF] },
+  {
+    name: "hillshade only",
+    args: [2, 0, 24, { ...OFF, hasHillshade: true }],
+  },
+  { name: "water only", args: [2, 0, 24, { ...OFF, hasWater: true }] },
+  {
+    name: "elevation heatmap only",
+    args: [2, 0, 24, { ...OFF, hasElevationHeatmap: true }],
+  },
+  {
+    name: "watermask only feature, with slots",
+    args: [2, 0, 24, { ...OFF, hasWatermask: true }],
+  },
+  { name: "all features on, mixed raster+vector", args: [2, 2, 2, ALL] },
+  { name: "vector-only (rasterCount 0)", args: [0, 2, 24, OFF] },
+  {
+    name: "watermask-only shader (no slots)",
+    args: [0, 0, 24, { ...OFF, hasWatermask: true }],
+  },
+];
+
+describe("generateCompositeFragmentShader snapshots", () => {
+  for (const { name, args } of CASES) {
+    it(name, () => {
+      expect(generateCompositeFragmentShader(...args)).toMatchSnapshot();
+    });
+  }
+});

package/src/tileTexture/CompositeShader.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  compositeSlotMarker,
+  generateCompositeFragmentShader,
+} from "./CompositeShader";
+
+const ALL_OFF = {
+  hasHillshade: false,
+  hasWater: false,
+  hasElevationHeatmap: false,
+  hasWatermask: false,
+};
+
+describe("generateCompositeFragmentShader", () => {
+  it("emits MRT layout declarations for all three attachments", () => {
+    const src = generateCompositeFragmentShader(2, 2, 2, ALL_OFF);
+    expect(src).toContain("layout(location = 0) out vec4 colorBuffer;");
+    expect(src).toContain("layout(location = 1) out vec4 attrBuffer;");
+    expect(src).toContain("layout(location = 2) out vec4 normalBuffer;");
+  });
+
+  it("emits rasterCount + vectorCount compact slot blocks", () => {
+    const src = generateCompositeFragmentShader(2, 1, 24, ALL_OFF);
+    // Compact slot 0,1 are raster (absSlot 0,1); slot 2 is vector (absSlot 24).
+    expect(src).toContain(compositeSlotMarker(0, 0, false));
+    expect(src).toContain(compositeSlotMarker(1, 1, false));
+    expect(src).toContain(compositeSlotMarker(2, 24, true));
+    expect(src).not.toContain("compact slot 3");
+  });
+
+  it("bakes the absolute slot index into winningSlot so winIdx stays correct in the main shader", () => {
+    // raster=1, vector=2, boundary=24 → compact 0=abs0, compact 1=abs24, compact 2=abs25.
+    const src = generateCompositeFragmentShader(1, 2, 24, ALL_OFF);
+    expect(src).toContain(compositeSlotMarker(0, 0, false));
+    expect(src).toContain(compositeSlotMarker(1, 24, true));
+    expect(src).toContain(compositeSlotMarker(2, 25, true));
+    expect(src).toMatch(/winningSlot = 0;[\s\S]*isTexturized = 0\.0;/);
+    expect(src).toMatch(/winningSlot = 24;[\s\S]*isTexturized = 1\.0;/);
+    expect(src).toMatch(/winningSlot = 25;[\s\S]*isTexturized = 1\.0;/);
+  });
+
+  it("sizes uniform arrays to (rasterCount + vectorCount)", () => {
+    const src = generateCompositeFragmentShader(2, 3, 24, ALL_OFF);
+    expect(src).toContain("uniform int uShows[5];");
+    expect(src).toContain("uniform sampler2D uTextures[5];");
+  });
+
+  it("elides hillshade uniforms and code when feature is off", () => {
+    const src = generateCompositeFragmentShader(2, 2, 2, ALL_OFF);
+    expect(src).not.toContain("uIsHillshades");
+    expect(src).not.toContain("uHillshadeExaggeration");
+    expect(src).not.toContain("hillshadeNormal = n0");
+  });
+
+  it("includes hillshade normal sampling per compact slot when feature is on", () => {
+    const src = generateCompositeFragmentShader(2, 0, 24, {
+      ...ALL_OFF,
+      hasHillshade: true,
+    });
+    expect(src).toContain("uniform bool uIsHillshades[2];");
+    expect(src).toContain("uniform float uHillshadeExaggeration;");
+    expect(src).toContain("hillshadeNormal = n0 * 0.5 + 0.5;");
+    expect(src).toContain("hillshadeNormal = n1 * 0.5 + 0.5;");
+    // Hillshade slots must contribute no color to the composite.
+    expect(src).toContain(
+      "if (uIsHillshades[0]) {\n      texColor0 = vec4(0.0)",
+    );
+  });
+
+  it("elides water uniforms and writes constant isWater when off", () => {
+    const src = generateCompositeFragmentShader(2, 0, 24, ALL_OFF);
+    expect(src).not.toContain("uWaters");
+    expect(src).toContain("float isWater = 0.0;");
+    expect(src).not.toContain("isWater = uWaters[0]");
+  });
+
+  it("writes per-slot water flag when water is on", () => {
+    const src = generateCompositeFragmentShader(2, 0, 24, {
+      ...ALL_OFF,
+      hasWater: true,
+    });
+    expect(src).toContain("uniform bool uWaters[2];");
+    expect(src).toContain("isWater = uWaters[0] ? 1.0 : 0.0;");
+    expect(src).toContain("isWater = uWaters[1] ? 1.0 : 0.0;");
+    // Precision-sensitive water params live in TileMesh's uniform arrays.
+    expect(src).not.toContain("uWaterScaleNormals");
+    expect(src).not.toContain("uWaterSpeeds");
+  });
+
+  it("elides elevation heatmap uniforms/sampling when off", () => {
+    const src = generateCompositeFragmentShader(2, 0, 24, ALL_OFF);
+    expect(src).not.toContain("uIsElevationHeatmaps");
+    expect(src).not.toContain("uColorMapTexture");
+    expect(src).not.toContain("sampleElevationBilinear");
+  });
+
+  it("emits elevation heatmap branch + colormap sample when on", () => {
+    const src = generateCompositeFragmentShader(2, 0, 24, {
+      ...ALL_OFF,
+      hasElevationHeatmap: true,
+    });
+    expect(src).toContain("uniform bool uIsElevationHeatmaps[2];");
+    expect(src).toContain("uniform sampler2D uColorMapTexture;");
+    expect(src).toContain("if (uIsElevationHeatmaps[0])");
+    expect(src).toContain("sampleElevationBilinear(uTextures[0]");
+  });
+
+  it("encodes (winningSlot + 1) / 255 in attr.a", () => {
+    const src = generateCompositeFragmentShader(1, 0, 24, ALL_OFF);
+    expect(src).toContain("float(winningSlot + 1) / 255.0");
+  });
+
+  it("elides watermask uniform and sampling when feature is off", () => {
+    const src = generateCompositeFragmentShader(2, 0, 24, ALL_OFF);
+    expect(src).not.toContain("uWatermask");
+    expect(src).not.toContain("step(0.5, texture");
+  });
+
+  it("samples watermask after slot loop and OR's into isWater when on", () => {
+    const src = generateCompositeFragmentShader(2, 0, 24, {
+      ...ALL_OFF,
+      hasWater: true,
+      hasWatermask: true,
+    });
+    expect(src).toContain("uniform sampler2D uWatermask;");
+    // Watermask priority: max() with step() over the slot-loop result so the
+    // watermask flips isWater on even when no slot's uWaters[k] was true.
+    expect(src).toMatch(
+      /isWater = max\(isWater, step\(0\.5, texture\(uWatermask, vUv\)\.r\)\);/,
+    );
+  });
+
+  it("emits watermask path even without hasWater (independent feature)", () => {
+    // hasWater off → per-slot water flag path is elided; watermask still works
+    // because it operates on the always-declared `isWater` variable.
+    const src = generateCompositeFragmentShader(1, 0, 24, {
+      ...ALL_OFF,
+      hasWatermask: true,
+    });
+    expect(src).not.toContain("uWaters[");
+    expect(src).toContain("uniform sampler2D uWatermask;");
+    expect(src).toContain("isWater = max(isWater, step(0.5,");
+  });
+
+  it("handles vector-only (rasterCount=0) without emitting raster blocks", () => {
+    const src = generateCompositeFragmentShader(0, 2, 24, ALL_OFF);
+    expect(src).toContain(compositeSlotMarker(0, 24, true));
+    expect(src).toContain(compositeSlotMarker(1, 25, true));
+    expect(src).not.toContain("raster");
+  });
+
+  it("emits watermask-only shader (no slot uniforms) when both counts are 0", () => {
+    // Open-ocean tile: no raster + no vector layers, but a quantized-mesh
+    // watermask is present. GLSL forbids zero-length arrays so the per-slot
+    // declarations must be elided, but uWatermask and the post-loop sample
+    // must still be emitted so attr.r ends up flagged as water.
+    const src = generateCompositeFragmentShader(0, 0, 24, {
+      ...ALL_OFF,
+      hasWatermask: true,
+    });
+    expect(src).not.toContain("uShows[");
+    expect(src).not.toContain("uTextures[");
+    expect(src).not.toContain("uColors[");
+    expect(src).toContain("uniform sampler2D uWatermask;");
+    expect(src).toContain("isWater = max(isWater, step(0.5,");
+  });
+});

package/src/tileTexture/CompositeShader.ts

@@ -0,0 +1,53 @@
+import {
+  buildCompositeFragmentShader,
+  composeCompositeContributions,
+  compositeSlotMarker,
+  COMPOSITE_VERTEX_SHADER,
+  createCompositeLayerEnhancers,
+} from "../material/enhancer/tileComposite";
+
+import type { CompositeFeatures } from "./types";
+
+// Re-exported from the composite enhancer modules so existing import sites
+// (tests, index) keep resolving them from here.
+export { compositeSlotMarker, COMPOSITE_VERTEX_SHADER };
+
+/**
+ * Produce the fragment shader for the offscreen composite pass.
+ *
+ * Slot layout — to avoid wasting blocks on the sparse gap between active raster
+ * slots (low indices) and active vector slots (starting at
+ * `texturizedSceneIndexFrom`), the shader emits a **compact** index space:
+ *
+ *   compact slot k ∈ [0, rasterCount)              → absSlot = k             (raster)
+ *   compact slot k ∈ [rasterCount, rasterCount+vectorCount)
+ *                                                  → absSlot = texturizedSceneIndexFrom + (k - rasterCount)
+ *
+ * The absolute index is baked into `winningSlot = <abs>` so the TileMesh main
+ * shader's per-slot uniform arrays (sized at the original maxTextures) still
+ * index correctly via `winIdx`.
+ *
+ * Each expression (hillshade, elevation heatmap, water, watermask) is owned by a
+ * composite layer enhancer; `createCompositeLayerEnhancers` builds the chain for
+ * this feature set and `composeCompositeContributions` folds it onto the base
+ * enhancer's skeleton. CPU branch elision falls out naturally: an inactive
+ * enhancer contributes empty GLSL, so absent features cost nothing.
+ */
+export function generateCompositeFragmentShader(
+  rasterCount: number,
+  vectorCount: number,
+  texturizedSceneIndexFrom: number,
+  features: CompositeFeatures,
+): string {
+  const enhancers = createCompositeLayerEnhancers(features);
+  const contributions = composeCompositeContributions(
+    enhancers,
+    rasterCount + vectorCount,
+  );
+  return buildCompositeFragmentShader(
+    rasterCount,
+    vectorCount,
+    texturizedSceneIndexFrom,
+    contributions,
+  );
+}