@navaramap/three 0.0.0

package/src/utils/hillshadeNormalMapGenerator.ts

@@ -0,0 +1,193 @@
+import HillshadeParsFragment from "@shaders/glsl/chunks/hillshade_pars_fragment.glsl";
+import {
+  DataTexture,
+  Mesh,
+  OrthographicCamera,
+  PlaneGeometry,
+  Scene,
+  ShaderMaterial,
+  WebGLRenderer,
+  WebGLRenderTarget,
+} from "three";
+
+import type { HillshadeConfig } from "../event/HillshadeContext";
+
+/**
+ * Generator for hillshade normal maps using offscreen rendering.
+ * Converts DEM textures into pre-computed normal maps to improve runtime performance.
+ */
+export class HillshadeNormalMapGenerator {
+  private renderer: WebGLRenderer;
+  private scene: Scene;
+  private camera: OrthographicCamera;
+  private material: ShaderMaterial;
+  private quad: Mesh;
+
+  constructor(renderer: WebGLRenderer) {
+    this.renderer = renderer;
+
+    // Setup scene and camera for offscreen rendering
+    this.scene = new Scene();
+    this.camera = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
+
+    // Create shader material for normal computation
+    // Uses hillshade_pars_fragment.glsl for DEM decoding
+    this.material = new ShaderMaterial({
+      uniforms: {
+        uDemTexture: { value: null },
+        uTexelSize: { value: [0, 0] },
+        uMetersPerTexel: { value: 1.0 },
+        uOutputSize: { value: [0, 0] }, // Output render target size (content size without padding)
+        // Hillshade decoder uniforms (will be set per-generation)
+        uHillshadeRGBScaler: { value: [256, 1, 1 / 256] },
+        uHillshadeBoundary: { value: 0 },
+        uHillshadeMinOffset: { value: 0 },
+        uHillshadeMaxOffset: { value: 0 },
+        uHillshadeEpsilon: { value: 1.0 },
+        uHillshadeOffset: { value: -32768 },
+      },
+      vertexShader: `
+        void main() {
+          gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+        }
+      `,
+      fragmentShader: `
+        #define USE_HILLSHADE 1
+
+        uniform sampler2D uDemTexture;
+        uniform vec2 uTexelSize;
+        uniform float uMetersPerTexel;
+        uniform vec2 uOutputSize;
+
+        // Import DEM decoding and normal computation from hillshade shader
+        ${HillshadeParsFragment}
+
+        void main() {
+          ivec2 texSize = textureSize(uDemTexture, 0);
+
+          // Compute UV from gl_FragCoord using correct OUTPUT size (not DEM padded size)
+          // gl_FragCoord ranges from (0.5, 0.5) to (width-0.5, height-0.5)
+          // Map to UV [0,1] spanning pixel centers: (fragCoord - 0.5) / (size - 1)
+          vec2 pixelCoord = gl_FragCoord.xy - 0.5;
+          vec2 uv = pixelCoord / (uOutputSize - 1.0);
+
+          // Flip Y to match DEM texture coordinate system (top-down)
+          // gl_FragCoord is OpenGL coords (y=0 at bottom), but DEM texture is top-down (y=0 at top)
+          uv.y = 1.0 - uv.y;
+
+          // Check if this is valid terrain data
+          float testHeight = sampleHeightBilinear(uDemTexture, uv, texSize);
+
+          if (!isValidHeight(testHeight)) {
+            // Invalid data (ocean/no-data), output default upward normal (0, 0, 1)
+            // Store directly in RGB channels, mapped from [-1,1] to [0,1]
+            gl_FragColor = vec4(0.5, 0.5, 1.0, 1.0);
+            return;
+          }
+
+          // Compute normal from DEM
+          vec3 normal = computeNormalFromDEM(uDemTexture, uv, uTexelSize, uMetersPerTexel);
+
+          // Store normal directly in RGB channels (linear, can use hardware bilinear filtering)
+          // Map from [-1,1] to [0,1] for 8-bit storage
+          gl_FragColor = vec4(normal * 0.5 + 0.5, 1.0);
+        }
+      `,
+    });
+
+    // Create fullscreen quad
+    const geometry = new PlaneGeometry(2, 2);
+    this.quad = new Mesh(geometry, this.material);
+    this.scene.add(this.quad);
+  }
+
+  /**
+   * Render normal map to an existing RenderTarget (GPU-only, no readback)
+   * Used by HillshadeContext's RenderTarget pool to avoid GPU→CPU→GPU round-trip
+   * @param renderTarget - Target to render to (owned by HillshadeContext)
+   * @param demTexture - Source DEM texture (padded)
+   * @param metersPerTexel - Meters per texel for normal calculation
+   * @param hillshadeConfig - Hillshade decoder configuration
+   */
+  renderToTarget(
+    renderTarget: WebGLRenderTarget,
+    demTexture: DataTexture,
+    metersPerTexel: number,
+    hillshadeConfig: HillshadeConfig,
+  ): void {
+    const contentWidth = renderTarget.width;
+    const contentHeight = renderTarget.height;
+
+    // Calculate texel size for DEM sampling
+    const texelSize = 1.0 / (contentWidth - 1);
+
+    // Update shader uniforms
+    this.material.uniforms.uDemTexture.value = demTexture;
+    this.material.uniforms.uTexelSize.value = [texelSize, texelSize];
+    this.material.uniforms.uMetersPerTexel.value = metersPerTexel;
+    this.material.uniforms.uOutputSize.value = [contentWidth, contentHeight];
+
+    // Update hillshade decoder uniforms from Rust config
+    this.material.uniforms.uHillshadeRGBScaler.value =
+      hillshadeConfig.rgbScaler;
+    this.material.uniforms.uHillshadeBoundary.value = hillshadeConfig.boundary;
+    this.material.uniforms.uHillshadeMinOffset.value =
+      hillshadeConfig.minOffset;
+    this.material.uniforms.uHillshadeMaxOffset.value =
+      hillshadeConfig.maxOffset;
+    this.material.uniforms.uHillshadeEpsilon.value = hillshadeConfig.epsilon;
+    this.material.uniforms.uHillshadeOffset.value = hillshadeConfig.offset;
+
+    const currentRenderTarget = this.renderer.getRenderTarget();
+    this.renderer.setRenderTarget(renderTarget);
+    this.renderer.render(this.scene, this.camera);
+    this.renderer.setRenderTarget(currentRenderTarget);
+  }
+
+  /**
+   * Debug: Save normal map to file
+   * @param renderTarget - RenderTarget to read from
+   * @param filename - Output filename
+   */
+  dbgSaveNormalMap(renderTarget: WebGLRenderTarget, filename: string): void {
+    const width = renderTarget.width;
+    const height = renderTarget.height;
+    const pixels = new Uint8Array(width * height * 4);
+
+    this.renderer.readRenderTargetPixels(
+      renderTarget,
+      0,
+      0,
+      width,
+      height,
+      pixels,
+    );
+
+    // Create canvas and write pixels
+    const canvas = document.createElement("canvas");
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return;
+
+    const imageData = ctx.createImageData(width, height);
+    imageData.data.set(pixels);
+    ctx.putImageData(imageData, 0, 0);
+
+    // Download
+    canvas.toBlob((blob) => {
+      if (!blob) return;
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement("a");
+      a.href = url;
+      a.download = filename;
+      a.click();
+      URL.revokeObjectURL(url);
+    });
+  }
+
+  dispose(): void {
+    this.material.dispose();
+    this.quad.geometry.dispose();
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,8 @@
+export * from "./arraysEqual";
+export * from "./geometry";
+export * from "./worker";
+export * from "./replacer";
+export * from "./screen";
+export * from "./blendModes";
+export * from "./object";
+export * from "./textureFragmentIndex";

package/src/utils/object.test.ts

@@ -0,0 +1,14 @@
+import { expect, it } from "vitest";
+
+import { getExcludedKeys } from "./object";
+
+it("should get all excluded keys", () => {
+  const obj = { type: "layer", material1: {}, material2: {} };
+  expect(getExcludedKeys(obj, ["type"])).toEqual(["material1", "material2"]);
+
+  expect(getExcludedKeys(obj, ["type", "material1"])).toEqual(["material2"]);
+
+  expect(getExcludedKeys(obj, ["type", "material1", "material2"])).toEqual([]);
+
+  expect(getExcludedKeys(obj, [])).toEqual(["type", "material1", "material2"]);
+});

package/src/utils/object.ts

@@ -0,0 +1,7 @@
+export const getExcludedKeys = <O extends object, K extends keyof O>(
+  object: O,
+  filters: K[],
+) => {
+  const keys = Object.keys(object) as (keyof O)[];
+  return keys.filter((k) => !filters.includes(k as K));
+};

package/src/utils/replacer.test.ts

@@ -0,0 +1,42 @@
+import { expect, test } from "vitest";
+
+import { Replacer, createReplacer } from "./replacer";
+
+test("Replacer should allow method chaining with side-effect free implementation", () => {
+  const source = "Hello, world! Hello, universe!";
+
+  // String replacements
+  const result1 = createReplacer(source)
+    .replace("world", "earth")
+    .replace("universe", "galaxy").source;
+  expect(result1).toBe("Hello, earth! Hello, galaxy!");
+
+  // RegExp replacements
+  const result2 = createReplacer(source)
+    .replace(/world/, "earth")
+    .replace(/universe/, "galaxy").source;
+  expect(result2).toBe("Hello, earth! Hello, galaxy!");
+
+  // Error case
+  expect(() =>
+    createReplacer("Hello, world!").replace(
+      "universe",
+      "galaxy",
+      "Custom Error",
+    ),
+  ).toThrow("Custom Error");
+
+  // Multiple replacements
+  const result3 = createReplacer(source)
+    .replace("Hello", "Hi")
+    .replace("world", "earth")
+    .replace("Hello", "Hi")
+    .replace("universe", "galaxy").source;
+  expect(result3).toBe("Hi, earth! Hi, galaxy!");
+
+  // Verify source property
+  const replacer = createReplacer("Hello, world!");
+  expect(replacer).toBeInstanceOf(Replacer);
+  expect(replacer.source).toBe("Hello, world!");
+  expect(replacer.source).toBe("Hello, world!");
+});

package/src/utils/replacer.ts

@@ -0,0 +1,89 @@
+/**
+ * Replaces a substring in a string and throws an error if the replacement didn't occur.
+ * This is useful for shader code replacements where silent failures can be hard to debug.
+ *
+ * @param source - The source string to perform replacement on
+ * @param search - The substring or regex to search for
+ * @param replace - The string to replace the search substring with
+ * @param errorMessage - Optional custom error message
+ * @returns The string with replacements applied
+ * @throws Error if the search string/pattern was not found in the source
+ */
+export function replaceOrThrow(
+  source: string,
+  search: string | RegExp,
+  replace: string,
+  errorMessage?: string,
+): string {
+  // Check if the pattern exists in the source
+  if (source.split(search).length === 1) {
+    throw new Error(
+      errorMessage ||
+        `Failed to replace "${search}" in shader code. The pattern was not found.`,
+    );
+  }
+
+  // Perform the replacement
+  return source.replace(search, replace);
+}
+
+/**
+ * A class for chaining string replacements with error detection.
+ * This allows for a more functional programming style with method chaining.
+ * This implementation is free of side effects - each method returns a new instance.
+ */
+export class Replacer {
+  readonly source: string;
+
+  /**
+   * Creates a new Replacer instance
+   *
+   * @param source - The source string to perform replacements on
+   */
+  constructor(source: string) {
+    this.source = source;
+  }
+
+  /**
+   * Replaces a substring in the source string and throws an error if the replacement didn't occur.
+   * Returns a new Replacer instance with the updated string.
+   *
+   * @param search - The substring or regex to search for
+   * @param replace - The string to replace the search substring with
+   * @param errorMessage - Optional custom error message
+   * @returns A new Replacer instance with the updated string
+   * @throws Error if the search string/pattern was not found in the source
+   */
+  replace(
+    search: string | RegExp,
+    replace: string,
+    errorMessage?: string,
+  ): Replacer {
+    const newSource = replaceOrThrow(
+      this.source,
+      search,
+      replace,
+      errorMessage,
+    );
+    return new Replacer(newSource);
+  }
+
+  replaceWithCondition(
+    search: string | RegExp,
+    replace: string,
+    condition: boolean,
+    errorMessage?: string,
+  ) {
+    return condition ? this.replace(search, replace, errorMessage) : this;
+  }
+}
+
+/**
+ * Creates a new Replacer instance for chaining string replacements
+ *
+ * @param source - The source string to perform replacements on
+ * @returns A new Replacer instance
+ */
+export function createReplacer(source: string): Replacer {
+  return new Replacer(source);
+}

package/src/utils/screen.ts

@@ -0,0 +1,29 @@
+import type { Nullable, XYZ } from "@navaramap/core";
+import { convertScreenToWorld } from "@navaramap/three_api";
+import { Vector2 } from "three";
+
+import type ThreeView from "../index";
+
+export const convertScreenPos = (
+  view: ThreeView,
+  x: number,
+  y: number,
+): Nullable<XYZ> => {
+  if (!view.camera) {
+    console.error("View camera is not initialized.");
+    return;
+  }
+
+  const screenSize = view.screenSize;
+  const pixelRatio = view.pixelRatio;
+
+  const win = {
+    width: screenSize.x,
+    height: screenSize.y,
+    pixelRatio: pixelRatio,
+  };
+
+  const pos = convertScreenToWorld(win, view.camera.raw, new Vector2(x, y));
+
+  return pos;
+};

package/src/utils/textureFragmentIndex.test.ts

@@ -0,0 +1,224 @@
+import { describe, it, expect, beforeEach } from "vitest";
+
+import type { TileMesh } from "../mesh/tile";
+
+import {
+  updateTextureFragmentIndex,
+  removeTextureFragmentIndex,
+  getTextureFragmentSlots,
+  type TextureSlot,
+} from "./textureFragmentIndex";
+
+function createTileMesh(id: string): TileMesh {
+  return { id } as unknown as TileMesh;
+}
+
+describe("textureFragmentIndex", () => {
+  let textureFragmentIndex: Map<string, Set<TextureSlot>>;
+  let tileMeshToFragmentIds: Map<TileMesh, Set<string>>;
+
+  beforeEach(() => {
+    textureFragmentIndex = new Map<string, Set<TextureSlot>>();
+    tileMeshToFragmentIds = new Map<TileMesh, Set<string>>();
+  });
+
+  function getSlotIndexes(fragmentId: string, tileMesh: TileMesh): number[] {
+    const slots = getTextureFragmentSlots(textureFragmentIndex, fragmentId);
+    if (!slots) return [];
+
+    return [...slots]
+      .filter((slot) => slot.tileMesh === tileMesh)
+      .map((slot) => slot.slotIndex)
+      .sort((a, b) => a - b);
+  }
+
+  it("indexes texture fragments for a tile mesh", () => {
+    const tileMesh = createTileMesh("tile-1");
+
+    updateTextureFragmentIndex(
+      textureFragmentIndex,
+      tileMeshToFragmentIds,
+      tileMesh,
+      ["frag-a", null, "frag-b"],
+    );
+
+    const fragASlots = getTextureFragmentSlots(textureFragmentIndex, "frag-a");
+    const fragBSlots = getTextureFragmentSlots(textureFragmentIndex, "frag-b");
+    const fragCSlots = getTextureFragmentSlots(textureFragmentIndex, "frag-c");
+
+    expect(fragASlots).toBeDefined();
+    expect(fragBSlots).toBeDefined();
+    expect(fragCSlots).toBeUndefined();
+
+    expect(getSlotIndexes("frag-a", tileMesh)).toEqual([0]);
+    expect(getSlotIndexes("frag-b", tileMesh)).toEqual([2]);
+
+    removeTextureFragmentIndex(
+      textureFragmentIndex,
+      tileMeshToFragmentIds,
+      tileMesh,
+    );
+  });
+
+  it("supports multiple tile meshes using the same fragment", () => {
+    const tileMesh1 = createTileMesh("tile-1");
+    const tileMesh2 = createTileMesh("tile-2");
+
+    updateTextureFragmentIndex(
+      textureFragmentIndex,
+      tileMeshToFragmentIds,
+      tileMesh1,
+      ["frag-shared"],
+    );
+    updateTextureFragmentIndex(
+      textureFragmentIndex,
+      tileMeshToFragmentIds,
+      tileMesh2,
+      ["frag-shared", "frag-x"],
+    );
+
+    const sharedSlots = getTextureFragmentSlots(
+      textureFragmentIndex,
+      "frag-shared",
+    );
+    expect(sharedSlots).toBeDefined();
+    expect(sharedSlots && [...sharedSlots].length).toBe(2);
+
+    expect(getSlotIndexes("frag-shared", tileMesh1)).toEqual([0]);
+    expect(getSlotIndexes("frag-shared", tileMesh2)).toEqual([0]);
+    expect(getSlotIndexes("frag-x", tileMesh2)).toEqual([1]);
+
+    removeTextureFragmentIndex(
+      textureFragmentIndex,
+      tileMeshToFragmentIds,
+      tileMesh1,
+    );
+    removeTextureFragmentIndex(
+      textureFragmentIndex,
+      tileMeshToFragmentIds,
+      tileMesh2,
+    );
+  });
+
+  it("removes previous index entries when updating the same tile mesh", () => {
+    const tileMesh = createTileMesh("tile-1");
+
+    updateTextureFragmentIndex(
+      textureFragmentIndex,
+      tileMeshToFragmentIds,
+      tileMesh,
+      ["frag-a", "frag-b"],
+    );
+    updateTextureFragmentIndex(
+      textureFragmentIndex,
+      tileMeshToFragmentIds,
+      tileMesh,
+      ["frag-c", null, "frag-b"],
+    );
+
+    expect(
+      getTextureFragmentSlots(textureFragmentIndex, "frag-a"),
+    ).toBeUndefined();
+    expect(getSlotIndexes("frag-b", tileMesh)).toEqual([2]);
+    expect(getSlotIndexes("frag-c", tileMesh)).toEqual([0]);
+
+    removeTextureFragmentIndex(
+      textureFragmentIndex,
+      tileMeshToFragmentIds,
+      tileMesh,
+    );
+  });
+
+  it("removes all slots for a tile mesh", () => {
+    const tileMesh = createTileMesh("tile-1");
+
+    updateTextureFragmentIndex(
+      textureFragmentIndex,
+      tileMeshToFragmentIds,
+      tileMesh,
+      ["frag-a", "frag-b"],
+    );
+    removeTextureFragmentIndex(
+      textureFragmentIndex,
+      tileMeshToFragmentIds,
+      tileMesh,
+    );
+
+    expect(
+      getTextureFragmentSlots(textureFragmentIndex, "frag-a"),
+    ).toBeUndefined();
+    expect(
+      getTextureFragmentSlots(textureFragmentIndex, "frag-b"),
+    ).toBeUndefined();
+  });
+
+  it("does nothing when removing a tile mesh that is not indexed", () => {
+    const tileMesh = createTileMesh("tile-1");
+
+    expect(() =>
+      removeTextureFragmentIndex(
+        textureFragmentIndex,
+        tileMeshToFragmentIds,
+        tileMesh,
+      ),
+    ).not.toThrow();
+  });
+
+  it("ignores null fragment ids", () => {
+    const tileMesh = createTileMesh("tile-1");
+
+    updateTextureFragmentIndex(
+      textureFragmentIndex,
+      tileMeshToFragmentIds,
+      tileMesh,
+      [null, null, "frag-a", null],
+    );
+
+    expect(
+      getTextureFragmentSlots(textureFragmentIndex, "frag-a"),
+    ).toBeDefined();
+    expect(getSlotIndexes("frag-a", tileMesh)).toEqual([2]);
+    expect(
+      getTextureFragmentSlots(textureFragmentIndex, "null"),
+    ).toBeUndefined();
+
+    removeTextureFragmentIndex(
+      textureFragmentIndex,
+      tileMeshToFragmentIds,
+      tileMesh,
+    );
+  });
+
+  it("deduplicates fragment ids in the bidirectional index but preserves slot entries", () => {
+    const tileMesh = createTileMesh("tile-1");
+
+    updateTextureFragmentIndex(
+      textureFragmentIndex,
+      tileMeshToFragmentIds,
+      tileMesh,
+      ["frag-a", "frag-a", "frag-b"],
+    );
+
+    expect(getSlotIndexes("frag-a", tileMesh)).toEqual([0, 1]);
+    expect(getSlotIndexes("frag-b", tileMesh)).toEqual([2]);
+
+    removeTextureFragmentIndex(
+      textureFragmentIndex,
+      tileMeshToFragmentIds,
+      tileMesh,
+    );
+
+    expect(
+      getTextureFragmentSlots(textureFragmentIndex, "frag-a"),
+    ).toBeUndefined();
+    expect(
+      getTextureFragmentSlots(textureFragmentIndex, "frag-b"),
+    ).toBeUndefined();
+  });
+
+  it("returns undefined for unknown fragment ids", () => {
+    expect(
+      getTextureFragmentSlots(textureFragmentIndex, "not-exists"),
+    ).toBeUndefined();
+  });
+});