@navaramap/three 0.0.3 → 0.0.5

package/src/atmosphere.ts

@@ -3,17 +3,38 @@ import {
   getECIToECEFRotationMatrix,
   getMoonDirectionECEF,
   getSunDirectionECEF,
-  PrecomputedTexturesLoader,
+  IRRADIANCE_TEXTURE_HEIGHT,
+  IRRADIANCE_TEXTURE_WIDTH,
+  SCATTERING_TEXTURE_DEPTH,
+  SCATTERING_TEXTURE_HEIGHT,
+  SCATTERING_TEXTURE_WIDTH,
+  TRANSMITTANCE_TEXTURE_HEIGHT,
+  TRANSMITTANCE_TEXTURE_WIDTH,
   type AtmosphereOverlay,
   type AtmosphereShadow,
   type AtmosphereShadowLength,
   type PrecomputedTextures,
 } from "@takram/three-atmosphere";
-import { Vector3, Matrix4, type WebGLRenderer } from "three";
-import invariant from "tiny-invariant";
+import {
+  EXR3DTextureLoader,
+  EXRTextureLoader,
+  Float16Array,
+  isFloatLinearSupported,
+  reinterpretType,
+} from "@takram/three-geospatial";
+import {
+  FloatType,
+  HalfFloatType,
+  LinearFilter,
+  Matrix4,
+  Vector3,
+  type DataTextureImageData,
+  type Texture,
+  type WebGLRenderer,
+} from "three";
 
 import { type ThreeViewCamera } from "./camera";
-import { ATMOSPHERE_ASSETS_URL, STBN_URL } from "./constants";
+import { ATMOSPHERE_TEXTURE_URLS, STBN_URL } from "./constants";
 import {
   dateForSolarTime,
   getSolarTime as solarTimeAt,
@@ -28,7 +49,7 @@ import {
 export type AtmosphereEvents = {
   /** Emitted when the atmosphere needs to trigger a re-render. */
   needsUpdate: () => void;
-  /** Emitted when precomputed atmosphere textures have been loaded. */
+  /** Emitted each time a precomputed atmosphere texture finishes loading. */
   textureLoaded: () => void;
   /** Emitted when the atmosphere is disposed. */
   disposed: () => void;
@@ -36,12 +57,62 @@ export type AtmosphereEvents = {
   sunChanged: (sunDirection: Vector3) => void;
 };
 
+/**
+ * Names of the precomputed atmosphere textures that can be loaded
+ * individually.
+ */
+export type AtmosphereTextureName =
+  "transmittance" | "scattering" | "irradiance" | "higherOrderScattering";
+
+/**
+ * Which precomputed textures a consumer needs, e.g.
+ * `{ transmittance: true }`. Only `true` is allowed as a value so that every
+ * listed texture is guaranteed to be loaded.
+ */
+export type AtmosphereTextureNeeds = Partial<
+  Record<AtmosphereTextureName, true>
+>;
+
+const ATMOSPHERE_TEXTURE_KEYS = {
+  transmittance: "transmittanceTexture",
+  scattering: "scatteringTexture",
+  irradiance: "irradianceTexture",
+  higherOrderScattering: "higherOrderScatteringTexture",
+} as const satisfies Record<AtmosphereTextureName, keyof PrecomputedTextures>;
+
+const ATMOSPHERE_TEXTURE_FILES: Record<AtmosphereTextureName, string> = {
+  transmittance: "transmittance.exr",
+  scattering: "scattering.exr",
+  irradiance: "irradiance.exr",
+  higherOrderScattering: "higher_order_scattering.exr",
+};
+
+const ALL_ATMOSPHERE_TEXTURE_NAMES = Object.keys(
+  ATMOSPHERE_TEXTURE_KEYS,
+) as AtmosphereTextureName[];
+
+/**
+ * The textures guaranteed to be present in an {@link Atmosphere.onTexturesReady}
+ * callback for a given needs declaration.
+ */
+export type LoadedAtmosphereTextures<N extends AtmosphereTextureNeeds> =
+  Required<
+    Pick<
+      PrecomputedTextures,
+      `${Extract<keyof N, AtmosphereTextureName>}Texture`
+    >
+  >;
+
 /**
  * Configuration options for the {@link Atmosphere} class.
  */
 export type AtmosphereOptions = {
-  /** URL to load precomputed atmosphere textures from. */
-  atmosphereAssetsUrl?: string;
+  /**
+   * URL of a directory to load precomputed atmosphere textures from. The
+   * directory must keep the original filenames (`transmittance.exr` etc.).
+   * When omitted, the assets bundled with the package are used.
+   */
+  atmosphereAssetsUrl?: string | undefined;
   /** URL to load STBN (Spatio-Temporal Blue Noise) textures from. */
   stbnUrl?: string;
   /** Date used for calculating sun/moon positions. Defaults to current date. */
@@ -51,8 +122,11 @@ export type AtmosphereOptions = {
 /**
  * Default values for {@link AtmosphereOptions}.
  */
-export const DEFAULT_ATMOSPHERE_OPTIONS: Required<AtmosphereOptions> = {
-  atmosphereAssetsUrl: ATMOSPHERE_ASSETS_URL,
+export const DEFAULT_ATMOSPHERE_OPTIONS: Required<
+  Omit<AtmosphereOptions, "atmosphereAssetsUrl">
+> &
+  Pick<AtmosphereOptions, "atmosphereAssetsUrl"> = {
+  atmosphereAssetsUrl: undefined,
   stbnUrl: STBN_URL,
   date: new Date(),
 };
@@ -85,10 +159,11 @@ export class Atmosphere extends EventHandler<AtmosphereEvents> {
   private rotationMatrix = new Matrix4();
 
   /**
-   * Precomputed atmosphere textures used for rendering.
-   * Loaded asynchronously via {@link initTextures}.
+   * Precomputed atmosphere textures used for rendering. Each texture is
+   * loaded lazily when a consumer declares a need for it via
+   * {@link onTexturesReady}, so the object may hold any subset at a time.
    */
-  textures?: PrecomputedTextures;
+  textures: Partial<PrecomputedTextures> = {};
 
   // Variables that come from Clouds.
   overlay = new Observed<AtmosphereOverlay | null>(null);
@@ -112,11 +187,11 @@ export class Atmosphere extends EventHandler<AtmosphereEvents> {
   private _camera: ThreeViewCamera | undefined;
 
   /**
-   * In-flight texture loading promise, shared across concurrent
-   * {@link initTextures} calls so the assets are fetched only once.
+   * In-flight per-texture loading promises, shared across consumers so each
+   * asset is fetched only once.
    * @private
    */
-  private texturesPromise: Promise<void> | undefined;
+  private texturePromises = new Map<AtmosphereTextureName, Promise<void>>();
 
   /**
    * Creates a new Atmosphere instance.
@@ -148,67 +223,156 @@ export class Atmosphere extends EventHandler<AtmosphereEvents> {
   };
 
   /**
-   * Loads precomputed atmosphere textures asynchronously.
-   * If textures are already loaded, this method returns immediately.
-   * @returns A promise that resolves when textures are loaded.
+   * Loads all precomputed atmosphere textures asynchronously.
+   *
+   * Each texture loads automatically once a consumer declares a need for it
+   * via {@link onTexturesReady}; call this manually only to prefetch every
+   * texture ahead of time.
+   *
+   * @returns A promise that resolves when all textures are loaded.
    */
-  // TODO: Add an option to disable loading textures.
   async initTextures() {
-    if (this.textures) return;
-
-    this.texturesPromise ??= new PrecomputedTexturesLoader()
-      .setType(this.renderer)
-      .loadAsync(
-        this.options.atmosphereAssetsUrl ??
-          DEFAULT_ATMOSPHERE_OPTIONS.atmosphereAssetsUrl,
-      )
-      .then((textures) => {
-        this.textures = textures;
-        this.emit("textureLoaded");
-      })
-      .finally(() => {
-        // Allow retrying after a failed load instead of caching the rejection.
-        this.texturesPromise = undefined;
-      });
-
-    await this.texturesPromise;
+    await Promise.all(
+      ALL_ATMOSPHERE_TEXTURE_NAMES.map((name) => this.loadTexture(name)),
+    );
   }
 
   /**
+   * Loads a single precomputed texture, sharing in-flight loads and caching
+   * the result. A failed load is forgotten so the next request retries it.
    * @private
    */
-  async _init() {
-    await this.initTextures();
+  private loadTexture(name: AtmosphereTextureName): Promise<void> {
+    let promise = this.texturePromises.get(name);
+    if (promise == null) {
+      const assetsUrl = this.options.atmosphereAssetsUrl;
+      const file = ATMOSPHERE_TEXTURE_FILES[name];
+      const url =
+        assetsUrl == null
+          ? ATMOSPHERE_TEXTURE_URLS[file]
+          : `${assetsUrl.replace(/\/+$/, "")}/${file}`;
+      promise = this.fetchTexture(name, url)
+        .then((texture) => {
+          const type = isFloatLinearSupported(this.renderer)
+            ? FloatType
+            : HalfFloatType;
+          texture.type = type;
+          // EXR data is parsed to Uint16Array, which must be converted to
+          // Float32Array when FloatType is used.
+          if (type === FloatType) {
+            reinterpretType<DataTextureImageData>(texture.image);
+            if (texture.image.data != null) {
+              texture.image.data = new Float32Array(
+                new Float16Array(texture.image.data.buffer),
+              );
+            }
+          }
+          texture.minFilter = LinearFilter;
+          texture.magFilter = LinearFilter;
+          Object.assign(this.textures, {
+            [ATMOSPHERE_TEXTURE_KEYS[name]]: texture,
+          });
+          this.emit("textureLoaded");
+        })
+        .catch((e: unknown) => {
+          // Allow retrying after a failed load instead of caching the
+          // rejection.
+          this.texturePromises.delete(name);
+          throw e;
+        });
+      this.texturePromises.set(name, promise);
+    }
+    return promise;
+  }
+
+  private fetchTexture(
+    name: AtmosphereTextureName,
+    url: string,
+  ): Promise<Texture> {
+    switch (name) {
+      case "transmittance":
+        return new EXRTextureLoader({
+          width: TRANSMITTANCE_TEXTURE_WIDTH,
+          height: TRANSMITTANCE_TEXTURE_HEIGHT,
+        }).loadAsync(url);
+      case "irradiance":
+        return new EXRTextureLoader({
+          width: IRRADIANCE_TEXTURE_WIDTH,
+          height: IRRADIANCE_TEXTURE_HEIGHT,
+        }).loadAsync(url);
+      case "scattering":
+      case "higherOrderScattering":
+        return new EXR3DTextureLoader({
+          width: SCATTERING_TEXTURE_WIDTH,
+          height: SCATTERING_TEXTURE_HEIGHT,
+          depth: SCATTERING_TEXTURE_DEPTH,
+        }).loadAsync(url);
+    }
   }
 
   /**
    * @private
    */
   _dispose() {
-    if (this.textures) {
-      this.textures.irradianceTexture.dispose();
-      this.textures.scatteringTexture.dispose();
-      this.textures.transmittanceTexture.dispose();
-      this.textures.singleMieScatteringTexture?.dispose();
-      this.textures.higherOrderScatteringTexture?.dispose();
-      this.textures = undefined;
+    for (const texture of Object.values(this.textures)) {
+      texture?.dispose();
     }
+    this.textures = {};
+    this.texturePromises.clear();
     this.emit("disposed");
   }
 
   /**
-   * Invokes the callback with precomputed textures immediately if already loaded,
-   * or registers a one-time listener to invoke it once textures are ready.
+   * Invokes the callback once every needed precomputed texture is loaded —
+   * immediately if they already are.
+   *
+   * Registering also starts loading the needed textures if they aren't loaded
+   * yet, so a texture is only fetched once something that needs it exists.
+   *
+   * @param callback - Receives the textures; the ones listed in `needs` are
+   * guaranteed to be present.
+   * @param needs - The textures the caller needs, e.g.
+   * `{ transmittance: true }`. Omit to load all of them.
+   *
+   * @example
+   * atmosphere.onTexturesReady(
+   *   (t) => light.setTransmittanceTexture(t.transmittanceTexture),
+   *   { transmittance: true },
+   * );
    */
-  onTexturesReady(callback: (textures: PrecomputedTextures) => void): void {
-    if (this.textures) {
-      callback(this.textures);
-    } else {
-      this.once("textureLoaded", () => {
-        invariant(this.textures);
-        callback(this.textures);
+  onTexturesReady<
+    N extends AtmosphereTextureNeeds = Record<AtmosphereTextureName, true>,
+  >(
+    callback: (textures: LoadedAtmosphereTextures<N>) => void,
+    needs?: N,
+  ): void {
+    const names =
+      needs == null
+        ? ALL_ATMOSPHERE_TEXTURE_NAMES
+        : ALL_ATMOSPHERE_TEXTURE_NAMES.filter((name) => needs[name]);
+    for (const name of names) {
+      this.loadTexture(name).catch((e: unknown) => {
+        console.error("Failed to load atmosphere textures:", e);
       });
     }
+
+    const isReady = () =>
+      names.every(
+        (name) => this.textures[ATMOSPHERE_TEXTURE_KEYS[name]] != null,
+      );
+    const invoke = () => {
+      callback(this.textures as LoadedAtmosphereTextures<N>);
+    };
+    if (isReady()) {
+      invoke();
+    } else {
+      const listener = () => {
+        if (!isReady()) return;
+        this.off("textureLoaded", listener);
+        invoke();
+      };
+      this.on("textureLoaded", listener);
+    }
   }
 
   /**

package/src/constants/assets.ts

@@ -1,30 +1,80 @@
-export const ATMOSPHERE_ASSETS_URL = new URL(
-  `${import.meta.env.BASE_URL}assets/atmosphere`,
+// Every bundled asset must be referenced through its own static
+// `new URL("<literal>", import.meta.url)` call so that consumers' bundlers
+// (Vite/Rollup/webpack) can detect the file and emit it into their build
+// output. Runtime-concatenated paths are invisible to bundlers and 404 in
+// production builds (#746). The `?no-inline` query opts each file out of
+// Vite's lib-mode base64 inlining so our own dist emits it as a fetchable
+// asset instead.
+
+export const ATMOSPHERE_TRANSMITTANCE_URL = new URL(
+  "../../assets/atmosphere/transmittance.exr?no-inline",
+  import.meta.url,
+).toString();
+
+export const ATMOSPHERE_SCATTERING_URL = new URL(
+  "../../assets/atmosphere/scattering.exr?no-inline",
+  import.meta.url,
+).toString();
+
+export const ATMOSPHERE_IRRADIANCE_URL = new URL(
+  "../../assets/atmosphere/irradiance.exr?no-inline",
+  import.meta.url,
+).toString();
+
+export const ATMOSPHERE_HIGHER_ORDER_SCATTERING_URL = new URL(
+  "../../assets/atmosphere/higher_order_scattering.exr?no-inline",
   import.meta.url,
 ).toString();
 
-export const CLOUD_ASSETS_URL = new URL(
-  `${import.meta.env.BASE_URL}assets/cloud`,
+export const ATMOSPHERE_SINGLE_MIE_SCATTERING_URL = new URL(
+  "../../assets/atmosphere/single_mie_scattering.exr?no-inline",
   import.meta.url,
 ).toString();
 
-export const NOISE_ASSETS_URL = new URL(
-  `${import.meta.env.BASE_URL}assets/noise`,
+export const STARS_ASSETS_URL = new URL(
+  "../../assets/atmosphere/stars.bin?no-inline",
   import.meta.url,
 ).toString();
 
-export const RAIN_ASSETS_URL = new URL(
-  `${import.meta.env.BASE_URL}assets/rain`,
+export const CLOUD_LOCAL_WEATHER_URL = new URL(
+  "../../assets/cloud/local_weather.png?no-inline",
   import.meta.url,
 ).toString();
 
-export const WATER_ASSETS_URL = new URL(
-  `${import.meta.env.BASE_URL}assets/water`,
+export const CLOUD_SHAPE_URL = new URL(
+  "../../assets/cloud/shape.bin?no-inline",
   import.meta.url,
 ).toString();
 
-export const STARS_ASSETS_URL = `${ATMOSPHERE_ASSETS_URL}/stars.bin`;
+export const CLOUD_SHAPE_DETAIL_URL = new URL(
+  "../../assets/cloud/shape_detail.bin?no-inline",
+  import.meta.url,
+).toString();
+
+export const CLOUD_TURBULENCE_URL = new URL(
+  "../../assets/cloud/turbulence.png?no-inline",
+  import.meta.url,
+).toString();
 
-export const STBN_URL = `${NOISE_ASSETS_URL}/stbn.bin`;
+export const STBN_URL = new URL(
+  "../../assets/noise/stbn.bin?no-inline",
+  import.meta.url,
+).toString();
+
+export const WATER_NORMAL_URL = new URL(
+  "../../assets/water/waternormals.jpg?no-inline",
+  import.meta.url,
+).toString();
 
-export const WATER_NORMAL_URL = `${WATER_ASSETS_URL}/waternormals.jpg`;
+/**
+ * Filenames requested by `PrecomputedTexturesLoader` mapped to their
+ * statically-resolved URLs. Used to remap directory-relative requests when
+ * loading the bundled default atmosphere assets.
+ */
+export const ATMOSPHERE_TEXTURE_URLS: Record<string, string> = {
+  "transmittance.exr": ATMOSPHERE_TRANSMITTANCE_URL,
+  "scattering.exr": ATMOSPHERE_SCATTERING_URL,
+  "irradiance.exr": ATMOSPHERE_IRRADIANCE_URL,
+  "higher_order_scattering.exr": ATMOSPHERE_HIGHER_ORDER_SCATTERING_URL,
+  "single_mie_scattering.exr": ATMOSPHERE_SINGLE_MIE_SCATTERING_URL,
+};

package/src/declutter/DeclutterManager.ts

@@ -203,7 +203,7 @@ export class DeclutterManager {
       camera.near,
       widthPx,
       heightPx,
-      // Plain math instead of @navara/three_api's degreeToRadian — that one
+      // Plain math instead of @navaramap/three-api's degreeToRadian — that one
       // is a WASM call whose result we'd only marshal straight back in.
       (camera.fov * Math.PI) / 180.0,
       DeclutterManager.PADDING_PX,

package/src/declutter/types.ts

@@ -31,7 +31,7 @@ export type DeclutterCandidate = {
   isShown: boolean;
   /** Participant that owns this candidate; receives the placement result. */
   owner: DeclutterParticipant;
-  /** Participant-defined id (mesh index for text batches, instance index for
+  /** Participant-defined id (label slot for text batches, instance index for
    *  sprites) passed back to `applyDeclutter`. */
   handle: number;
 };

package/src/evaluations/FeatureEvaluator.test.ts

@@ -0,0 +1,152 @@
+import { Object3D } from "three";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+import type { FeatureHandler } from "../event/context";
+
+import { FeatureEvaluator, type GeometryType } from "./FeatureEvaluator";
+
+// Mock worker module to avoid os.cpus() error in test environment
+vi.mock("@navaramap/worker", () => ({}));
+
+describe("FeatureEvaluator", () => {
+  let mockHandler: FeatureHandler;
+  let consoleWarnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    // Create mock FeatureHandler with minimal implementation
+    mockHandler = {
+      readAllBatchedProperties: vi.fn((_, callback) => {
+        // Simulate a single batch with empty properties object
+        callback(0, 0, {});
+      }),
+      readFilteredBatchedProperties: vi.fn((_, __, callback) => {
+        // Simulate a single batch with empty properties object (not array)
+        // Production code expects Record<string, unknown>, not an array
+        callback(0, 0, {});
+      }),
+    } as unknown as FeatureHandler;
+
+    // Spy on console.warn to check for warnings
+    consoleWarnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleWarnSpy.mockRestore();
+  });
+
+  describe("determineGeometryType", () => {
+    it("should pass through valid geometry type literals", () => {
+      // Test representative types: billboard and text (critical for symbol layers)
+      const mockMesh = new Object3D();
+      Object.defineProperty(mockMesh, "geometryType", {
+        get: () => "billboard",
+        configurable: true,
+      });
+
+      const evaluator = new FeatureEvaluator(
+        mockHandler,
+        "test-layer",
+        0n,
+        mockMesh,
+      );
+
+      let capturedGeometryType: GeometryType | undefined;
+      evaluator.readFeatureProperties(({ meshGeomType: gt }) => {
+        capturedGeometryType = gt;
+      });
+
+      expect(capturedGeometryType).toBe("billboard");
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+    });
+
+    it("should return undefined and warn once for invalid values", () => {
+      const mockMesh = new Object3D();
+      Object.defineProperty(mockMesh, "geometryType", {
+        get: () => "invalid-type",
+        configurable: true,
+      });
+
+      const evaluator = new FeatureEvaluator(
+        mockHandler,
+        "test-layer",
+        0n,
+        mockMesh,
+      );
+
+      // First evaluation - should warn
+      let capturedGeometryType: GeometryType | undefined;
+      evaluator.readFeatureProperties(({ meshGeomType: gt }) => {
+        capturedGeometryType = gt;
+      });
+
+      expect(capturedGeometryType).toBeUndefined();
+      expect(consoleWarnSpy).toHaveBeenCalledTimes(1);
+      expect(consoleWarnSpy).toHaveBeenCalledWith(
+        expect.stringContaining(
+          'Invalid geometry type returned from geometryType getter: "invalid-type"',
+        ),
+      );
+
+      // Second evaluation - should NOT warn again (same object)
+      consoleWarnSpy.mockClear();
+      evaluator.readFeatureProperties(({ meshGeomType: gt }) => {
+        capturedGeometryType = gt;
+      });
+
+      expect(capturedGeometryType).toBeUndefined();
+      expect(consoleWarnSpy).not.toHaveBeenCalled(); // No additional warnings
+    });
+
+    it("should return undefined without warning when geometryType is not present", () => {
+      const mockMesh = new Object3D();
+      // No geometryType getter
+
+      const evaluator = new FeatureEvaluator(
+        mockHandler,
+        "test-layer",
+        0n,
+        mockMesh,
+      );
+
+      let capturedGeometryType: GeometryType | undefined;
+      evaluator.readFeatureProperties(({ meshGeomType: gt }) => {
+        capturedGeometryType = gt;
+      });
+
+      expect(capturedGeometryType).toBeUndefined();
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+    });
+
+    it("should read geometryType dynamically on each evaluation (critical for symbol layers)", () => {
+      const mockMesh = new Object3D();
+      let currentType: GeometryType = "billboard";
+      Object.defineProperty(mockMesh, "geometryType", {
+        get: () => currentType,
+        configurable: true,
+      });
+
+      const evaluator = new FeatureEvaluator(
+        mockHandler,
+        "test-layer",
+        0n,
+        mockMesh,
+      );
+
+      // First read - should be "billboard"
+      let capturedGeometryType: GeometryType | undefined;
+      evaluator.readFeatureProperties(({ meshGeomType: gt }) => {
+        capturedGeometryType = gt;
+      });
+      expect(capturedGeometryType).toBe("billboard");
+
+      // Change the geometry type (simulates symbol layer switching from billboard to text)
+      currentType = "text";
+
+      // Second read - should be "text" (not cached)
+      evaluator.readFeatureProperties(({ meshGeomType: gt }) => {
+        capturedGeometryType = gt;
+      });
+      expect(capturedGeometryType).toBe("text");
+    });
+  });
+});