@navaramap/three 0.0.0

package/src/material/enhancer/model/pntsEnhancer/index.ts

@@ -0,0 +1,82 @@
+import { defaults } from "lodash-es";
+import type { WebGLProgramParametersWithUniforms } from "three";
+import invariant from "tiny-invariant";
+
+import type { MaterialEnhancer } from "../../MaterialEnhancer";
+
+import { AVAILABLE_SHADERS, type SupportedMaterial } from "./material";
+import { updateMaterialProps } from "./material";
+import { createPntsMutates } from "./mutates";
+import { transformShader } from "./shader";
+import { DEFAULT_PNTS_PROPS, DEFAULT_PNTS_STATE, updateState } from "./state";
+import type { PntsMutates, PntsProps, PntsState } from "./types";
+
+/**
+ * Factory function to create a PNTS (point cloud) material enhancer.
+ *
+ * This enhancer handles:
+ * - Point size
+ * - Color
+ * - Height offset via geodetic normal
+ * - PNTS color range normalization (1/65535)
+ *
+ * @param material - The Three.js PointsMaterial to enhance
+ */
+export function createPntsEnhancer(
+  material: SupportedMaterial,
+): MaterialEnhancer<
+  SupportedMaterial,
+  PntsProps,
+  PntsState,
+  PntsMutates,
+  typeof AVAILABLE_SHADERS
+> {
+  let state: PntsState | null = null;
+  let mutates: PntsMutates | null = null;
+
+  return {
+    material,
+    availableShaders: AVAILABLE_SHADERS,
+
+    transformShader: (shader: WebGLProgramParametersWithUniforms): void => {
+      invariant(
+        state && mutates,
+        "mount() must be called before transformShader",
+      );
+      transformShader(shader, state, mutates);
+    },
+
+    mount: (props: PntsProps): void => {
+      const mergedProps = defaults({}, props, DEFAULT_PNTS_PROPS);
+      state = updateState(mergedProps, DEFAULT_PNTS_STATE);
+      mutates = createPntsMutates();
+      mutates.update(state);
+      updateMaterialProps(material, mergedProps);
+    },
+
+    update: (props: PntsProps): void => {
+      invariant(state && mutates, "mount() must be called before update");
+      state = updateState(props, state);
+      mutates.update(state);
+      updateMaterialProps(material, props);
+    },
+
+    states: (): PntsState => {
+      invariant(state, "mount() must be called before states");
+      return state;
+    },
+
+    mutates: (): PntsMutates => {
+      invariant(mutates, "mount() must be called before mutates");
+      return mutates;
+    },
+
+    programCacheKey: (): string => {
+      // PNTS has no state that affects shader defines
+      return "";
+    },
+  };
+}
+
+export type { PntsMutates, PntsProps, PntsState };
+export type { SupportedMaterial } from "./material";

package/src/material/enhancer/model/pntsEnhancer/markers.ts

@@ -0,0 +1,6 @@
+import type { ShaderMarkers } from "../../ShaderReplacer";
+
+export const PNTS_SHADER_MARKERS = {
+  vertex: {},
+  fragment: {},
+} as const satisfies ShaderMarkers;

package/src/material/enhancer/model/pntsEnhancer/material.test.ts

@@ -0,0 +1,37 @@
+import { PointsMaterial } from "three";
+import { describe, expect, it } from "vitest";
+
+import { updateMaterialProps } from "./material";
+
+describe("pntsEnhancer/material", () => {
+  describe("updateMaterialProps", () => {
+    it("should not update properties when props are undefined", () => {
+      const material = new PointsMaterial();
+      material.color.set(0xff0000);
+      material.size = 5;
+
+      updateMaterialProps(material, {});
+      expect(material.color.getHex()).toBe(0xff0000);
+      expect(material.size).toBe(5);
+    });
+
+    it("should update color when provided", () => {
+      const material = new PointsMaterial();
+      updateMaterialProps(material, { color: 0x00ff00 });
+      expect(material.color.getHex()).toBe(0x00ff00);
+    });
+
+    it("should update pointSize when provided", () => {
+      const material = new PointsMaterial();
+      updateMaterialProps(material, { pointSize: 3 });
+      expect(material.size).toBe(3);
+    });
+
+    it("should update both color and pointSize when provided", () => {
+      const material = new PointsMaterial();
+      updateMaterialProps(material, { color: 0x0000ff, pointSize: 7 });
+      expect(material.color.getHex()).toBe(0x0000ff);
+      expect(material.size).toBe(7);
+    });
+  });
+});

package/src/material/enhancer/model/pntsEnhancer/material.ts

@@ -0,0 +1,21 @@
+import type { MaterialsFromShaders, ShaderName } from "../../MaterialEnhancer";
+
+import type { PntsProps } from "./types";
+
+export const AVAILABLE_SHADERS = ["points"] satisfies ShaderName[];
+export type SupportedMaterial = MaterialsFromShaders<typeof AVAILABLE_SHADERS>;
+
+/**
+ * Update Three.js PointsMaterial properties from props.
+ */
+export const updateMaterialProps = (
+  material: SupportedMaterial,
+  props: PntsProps,
+): void => {
+  if (props.color !== undefined) {
+    material.color.set(props.color);
+  }
+  if (props.pointSize !== undefined) {
+    material.size = props.pointSize;
+  }
+};

package/src/material/enhancer/model/pntsEnhancer/mutates.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+
+import type { ShaderUniforms } from "../../MaterialEnhancer";
+
+import { createPntsMutates } from "./mutates";
+import { DEFAULT_PNTS_STATE } from "./state";
+import type { PntsState } from "./types";
+
+describe("pntsEnhancer/mutates", () => {
+  describe("update syncs refs from state", () => {
+    it("should sync uAddHeight from state.height", () => {
+      const state: PntsState = { ...DEFAULT_PNTS_STATE, height: 100 };
+      const mutates = createPntsMutates();
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uAddHeight?.value).toBe(100);
+    });
+
+    it("should sync uGeodeticNormal from state.geodeticNormal", () => {
+      const state: PntsState = {
+        ...DEFAULT_PNTS_STATE,
+        geodeticNormal: { x: 0.1, y: 0.2, z: 0.3 },
+      };
+      const mutates = createPntsMutates();
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uGeodeticNormal?.value).toEqual([0.1, 0.2, 0.3]);
+    });
+
+    it("should default to zero values", () => {
+      const mutates = createPntsMutates();
+      mutates.update(DEFAULT_PNTS_STATE);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, DEFAULT_PNTS_STATE);
+
+      expect(uniforms.uAddHeight?.value).toBe(0);
+      expect(uniforms.uGeodeticNormal?.value).toEqual([0, 0, 0]);
+    });
+
+    it("should update refs when state changes", () => {
+      const mutates = createPntsMutates();
+
+      const state1: PntsState = { ...DEFAULT_PNTS_STATE, height: 50 };
+      mutates.update(state1);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state1);
+      expect(uniforms.uAddHeight?.value).toBe(50);
+
+      const state2: PntsState = { ...DEFAULT_PNTS_STATE, height: 200 };
+      mutates.update(state2);
+      // Ref should be updated in place
+      expect(uniforms.uAddHeight?.value).toBe(200);
+    });
+  });
+
+  describe("updateUniforms assigns refs", () => {
+    it("should assign ref objects (not copies) to uniforms", () => {
+      const mutates = createPntsMutates();
+      mutates.update(DEFAULT_PNTS_STATE);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, DEFAULT_PNTS_STATE);
+
+      const heightRef = uniforms.uAddHeight;
+      expect(heightRef).toBeDefined();
+
+      // Update state and verify the same ref object is updated
+      mutates.update({ ...DEFAULT_PNTS_STATE, height: 999 });
+      expect(heightRef?.value).toBe(999);
+    });
+  });
+});

package/src/material/enhancer/model/pntsEnhancer/mutates.ts

@@ -0,0 +1,29 @@
+import type { PntsMutates, PntsRefs } from "./types";
+
+/**
+ * Default refs with initial values.
+ */
+const DEFAULT_PNTS_REFS: PntsRefs = {
+  uAddHeight: { value: 0 },
+  uGeodeticNormal: { value: [0, 0, 0] },
+};
+
+/**
+ * Create mutation functions for the PNTS enhancer.
+ * Refs are created internally and captured via closure.
+ */
+export const createPntsMutates = (): PntsMutates => {
+  const refs = structuredClone(DEFAULT_PNTS_REFS) as PntsRefs;
+
+  return {
+    update: (state) => {
+      refs.uAddHeight.value = state.height;
+      const n = state.geodeticNormal;
+      refs.uGeodeticNormal.value = [n.x, n.y, n.z];
+    },
+    updateUniforms: (uniforms) => {
+      uniforms.uAddHeight = refs.uAddHeight;
+      uniforms.uGeodeticNormal = refs.uGeodeticNormal;
+    },
+  };
+};

package/src/material/enhancer/model/pntsEnhancer/shader.test.ts

@@ -0,0 +1,32 @@
+import { testShaderCompatibility } from "../../test-utils/shaderCompatibility";
+
+import { PNTS_SHADER_MARKERS } from "./markers";
+
+import { createPntsEnhancer, type SupportedMaterial } from ".";
+
+testShaderCompatibility(
+  "pntsEnhancer",
+  (material) => createPntsEnhancer(material as SupportedMaterial),
+  [
+    {
+      name: "Default props",
+      props: {},
+    },
+    {
+      name: "With all props",
+      props: {
+        color: 0xff0000,
+        pointSize: 5,
+        height: 100,
+        geodeticNormal: { x: 0.1, y: 0.2, z: 0.97 },
+      },
+    },
+    {
+      name: "With divideColor",
+      props: {
+        divideColor: true,
+      },
+    },
+  ],
+  PNTS_SHADER_MARKERS,
+);

package/src/material/enhancer/model/pntsEnhancer/shader.ts

@@ -0,0 +1,56 @@
+import type { WebGLProgramParametersWithUniforms } from "three";
+import { ShaderChunk } from "three";
+
+import { createReplacer } from "../../../../utils";
+
+import type { PntsMutates, PntsState } from "./types";
+
+const COLOR_DIVISOR = 65535.0;
+
+/**
+ * Transform shader with PNTS-specific modifications.
+ *
+ * Vertex shader changes:
+ * - Adds uAddHeight and uGeodeticNormal uniforms
+ * - When `divideColor` is `true`, scales vertex colors by 1/65535 (PNTS color range normalization)
+ * - Offsets vertex position along geodetic normal by uAddHeight
+ */
+export const transformShader = (
+  shader: WebGLProgramParametersWithUniforms,
+  state: PntsState,
+  mutates: PntsMutates,
+): void => {
+  shader.defines ??= {};
+
+  mutates.updateUniforms(shader.uniforms, state);
+
+  shader.vertexShader = createReplacer(shader.vertexShader)
+    .replaceWithCondition(
+      "#include <color_vertex>",
+      createReplacer(ShaderChunk.color_vertex).replace(
+        "vColor = vec4( 1.0 );",
+        `vColor = vec4( 1.0 / ${COLOR_DIVISOR}.0 );`,
+      ).source,
+      state.divideColor,
+    )
+    .replace(
+      "#include <common>",
+      `#include <common>
+uniform float uAddHeight;
+uniform vec3 uGeodeticNormal;`,
+    )
+    .replace(
+      "#include <project_vertex>",
+      createReplacer(ShaderChunk.project_vertex)
+        .replace(
+          "vec4 mvPosition = vec4( transformed, 1.0 );",
+          `vec4 mvPosition = vec4( transformed, 1.0 );
+vec4 mvNormal = viewMatrix * vec4(uGeodeticNormal, 0.0);`,
+        )
+        .replace(
+          "gl_Position = projectionMatrix * mvPosition;",
+          `mvPosition += mvNormal * uAddHeight;
+gl_Position = projectionMatrix * mvPosition;`,
+        ).source,
+    ).source;
+};

package/src/material/enhancer/model/pntsEnhancer/state.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+
+import { DEFAULT_PNTS_STATE, updateState } from "./state";
+import type { PntsProps, PntsState } from "./types";
+
+/**
+ * Helper to create expected state by merging with defaults.
+ */
+const createExpectedState = (
+  overrides: Partial<PntsState> = {},
+): PntsState => ({
+  ...DEFAULT_PNTS_STATE,
+  ...overrides,
+});
+
+describe("pntsEnhancer/state", () => {
+  describe("updateState", () => {
+    type TestCase = {
+      name: string;
+      props: PntsProps;
+      currentState: PntsState;
+      expected: PntsState;
+    };
+
+    const testCases: TestCase[] = [
+      {
+        name: "returns default state when given empty props",
+        props: {},
+        currentState: DEFAULT_PNTS_STATE,
+        expected: createExpectedState(),
+      },
+      {
+        name: "applies height only",
+        props: { height: 100 },
+        currentState: DEFAULT_PNTS_STATE,
+        expected: createExpectedState({ height: 100 }),
+      },
+      {
+        name: "applies geodeticNormal only",
+        props: { geodeticNormal: { x: 0.5, y: 0.5, z: 0.707 } },
+        currentState: DEFAULT_PNTS_STATE,
+        expected: createExpectedState({
+          geodeticNormal: { x: 0.5, y: 0.5, z: 0.707 },
+        }),
+      },
+      {
+        name: "applies all state props",
+        props: {
+          height: 200,
+          geodeticNormal: { x: 1, y: 0, z: 0 },
+        },
+        currentState: DEFAULT_PNTS_STATE,
+        expected: createExpectedState({
+          height: 200,
+          geodeticNormal: { x: 1, y: 0, z: 0 },
+        }),
+      },
+    ];
+
+    it.each(testCases)("$name", ({ props, currentState, expected }) => {
+      const result = updateState(props, currentState);
+      expect(result).toEqual(expected);
+    });
+
+    it("falls back to currentState for missing props", () => {
+      const currentState: PntsState = {
+        height: 150,
+        geodeticNormal: { x: 0.1, y: 0.2, z: 0.3 },
+        divideColor: false,
+      };
+      const result = updateState({}, currentState);
+      expect(result.height).toBe(150);
+      expect(result.geodeticNormal).toEqual({ x: 0.1, y: 0.2, z: 0.3 });
+    });
+
+    it("overrides only specified props", () => {
+      const currentState: PntsState = {
+        height: 150,
+        geodeticNormal: { x: 0.1, y: 0.2, z: 0.3 },
+        divideColor: false,
+      };
+      const result = updateState({ height: 300 }, currentState);
+      expect(result.height).toBe(300);
+      expect(result.geodeticNormal).toEqual({ x: 0.1, y: 0.2, z: 0.3 });
+    });
+  });
+});

package/src/material/enhancer/model/pntsEnhancer/state.ts

@@ -0,0 +1,29 @@
+import type { PntsProps, PntsState } from "./types";
+
+export const DEFAULT_PNTS_PROPS: Required<PntsProps> = {
+  color: 0,
+  pointSize: 1,
+  height: 0,
+  geodeticNormal: { x: 0, y: 0, z: 0 },
+  divideColor: false,
+};
+
+/** Default state derived from DEFAULT_PNTS_PROPS. */
+export const DEFAULT_PNTS_STATE: PntsState = {
+  height: DEFAULT_PNTS_PROPS.height,
+  geodeticNormal: DEFAULT_PNTS_PROPS.geodeticNormal,
+  divideColor: false,
+};
+
+/**
+ * Update immutable state from props.
+ * Props override currentState values; missing props fall back to currentState.
+ */
+export const updateState = (
+  props: PntsProps,
+  currentState: PntsState,
+): PntsState => ({
+  height: props.height ?? currentState.height,
+  geodeticNormal: props.geodeticNormal ?? currentState.geodeticNormal,
+  divideColor: !!props.divideColor,
+});

package/src/material/enhancer/model/pntsEnhancer/types.ts

@@ -0,0 +1,38 @@
+import type { UniformValue } from "../../../types";
+import type { Mutates } from "../../MaterialEnhancer";
+
+/**
+ * Props for the PNTS (point cloud) enhancer.
+ */
+export type PntsProps = {
+  color?: number;
+  pointSize?: number;
+  height?: number;
+  divideColor?: boolean;
+  geodeticNormal?: { x: number; y: number; z: number };
+};
+
+/**
+ * Immutable state for the PNTS enhancer.
+ */
+export type PntsState = Readonly<{
+  height: number;
+  geodeticNormal: { x: number; y: number; z: number };
+  divideColor: boolean;
+}>;
+
+/**
+ * Mutable references (uniforms) for the PNTS enhancer.
+ * Internal type - not exposed externally.
+ */
+export type PntsRefs = {
+  uAddHeight: UniformValue<number>;
+  uGeodeticNormal: UniformValue<number[]>;
+};
+
+export type PntsUniforms = Partial<PntsRefs>;
+
+/**
+ * Mutation functions for the PNTS enhancer.
+ */
+export type PntsMutates = Mutates<PntsState, PntsUniforms>;

package/src/material/enhancer/polygon/index.ts

@@ -0,0 +1,22 @@
+export { createPolygonBaseEnhancer } from "./polygonBaseEnhancer";
+export {
+  POLYGON_BASE_SHADER_MARKERS,
+  createPolygonBaseShaderReplacer,
+} from "./polygonBaseEnhancer";
+export type {
+  PolygonBaseMutates,
+  PolygonBaseProps,
+  PolygonBaseState,
+} from "./polygonBaseEnhancer";
+
+export { createPolygonWaterEnhancer } from "./polygonWaterEnhancer";
+export type {
+  PolygonWaterCombinedMutates,
+  PolygonWaterCombinedStates,
+  PolygonWaterProps,
+  PolygonWaterState,
+  WaterOnlyProps,
+} from "./polygonWaterEnhancer";
+
+export { createPolygonMaterialEnhancer } from "./polygonMaterialEnhancer";
+export type { PolygonMaterialProps } from "./polygonMaterialEnhancer";

package/src/material/enhancer/polygon/polygonBaseEnhancer/index.test.ts

@@ -0,0 +1,101 @@
+import { MeshLambertMaterial } from "three";
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { createPolygonBaseEnhancer } from ".";
+
+describe("polygonBaseEnhancer", () => {
+  let enhancer: ReturnType<typeof createPolygonBaseEnhancer>;
+
+  beforeEach(() => {
+    enhancer = createPolygonBaseEnhancer(new MeshLambertMaterial());
+  });
+
+  describe("lifecycle", () => {
+    it("states() should throw if called before mount", () => {
+      const freshEnhancer = createPolygonBaseEnhancer(
+        new MeshLambertMaterial(),
+      );
+      expect(() => freshEnhancer.states()).toThrow(
+        "mount() must be called before states",
+      );
+    });
+
+    it("mutates() should throw if called before mount", () => {
+      const freshEnhancer = createPolygonBaseEnhancer(
+        new MeshLambertMaterial(),
+      );
+      expect(() => freshEnhancer.mutates()).toThrow(
+        "mount() must be called before mutates",
+      );
+    });
+
+    it("update() should throw if called before mount", () => {
+      const freshEnhancer = createPolygonBaseEnhancer(
+        new MeshLambertMaterial(),
+      );
+      expect(() => freshEnhancer.update({})).toThrow(
+        "mount() must be called before update",
+      );
+    });
+  });
+
+  describe("programCacheKey", () => {
+    it("should return cache key based on shader-affecting state", () => {
+      enhancer.mount({
+        useBatchTexture: true,
+        useBatchColorShow: false,
+        useBatchHeight: true,
+        useBatchExtrudedHeight: false,
+        isTexturized: true,
+        clampToGround: false,
+        useRTE: true,
+      });
+
+      const cacheKey = enhancer.programCacheKey();
+      const parsed = JSON.parse(cacheKey);
+
+      expect(parsed).toEqual({
+        useBatchTexture: true,
+        useBatchColorShow: false,
+        useBatchHeight: true,
+        useBatchExtrudedHeight: false,
+        isTexturized: true,
+        clampToGround: false,
+        useRTE: true,
+      });
+    });
+
+    it("should return different cache keys when useRTE differs", () => {
+      enhancer.mount({ useRTE: false });
+      const cacheKey1 = enhancer.programCacheKey();
+
+      const enhancer2 = createPolygonBaseEnhancer(new MeshLambertMaterial());
+      enhancer2.mount({ useRTE: true });
+      const cacheKey2 = enhancer2.programCacheKey();
+
+      expect(cacheKey1).not.toBe(cacheKey2);
+    });
+
+    it("should return different cache keys for different shader-affecting states", () => {
+      enhancer.mount({ useBatchTexture: false });
+      const cacheKey1 = enhancer.programCacheKey();
+
+      const enhancer2 = createPolygonBaseEnhancer(new MeshLambertMaterial());
+      enhancer2.mount({ useBatchTexture: true });
+      const cacheKey2 = enhancer2.programCacheKey();
+
+      expect(cacheKey1).not.toBe(cacheKey2);
+    });
+
+    it("should return same cache key for same shader-affecting states with different non-affecting states", () => {
+      enhancer.mount({ useBatchTexture: true, addHeight: 10, opacity: 0.5 });
+      const cacheKey1 = enhancer.programCacheKey();
+
+      const enhancer2 = createPolygonBaseEnhancer(new MeshLambertMaterial());
+      enhancer2.mount({ useBatchTexture: true, addHeight: 100, opacity: 1.0 });
+      const cacheKey2 = enhancer2.programCacheKey();
+
+      expect(cacheKey1).toBe(cacheKey2);
+    });
+  });
+});