@navaramap/three 0.0.0

package/src/evaluations/FeatureEvaluator.ts

@@ -0,0 +1,529 @@
+import {
+  type ExtractProperties,
+  type FeatureSetId,
+  type LayerId,
+} from "@navaramap/core";
+import type {
+  ModelMaterial as NavaraModelMaterial,
+  PointMaterial,
+  PolygonMaterial,
+  PolylineMaterial,
+  TextMaterial,
+} from "@navaramap/engine";
+import { BufferGeometry, Mesh, Object3D } from "three";
+import type { NormalBufferAttributes } from "three";
+
+import { Color } from "../Color";
+import type { FeatureHandler } from "../event";
+import {
+  InstancedMesh,
+  isFeatureMesh,
+  ModelMesh,
+  type ModelMaterial,
+  BatchedFeatureMesh,
+  type ModelBatchedAttributeName,
+  type BatchedAttributeName,
+  InstancedSpriteMesh,
+  BatchedSdfTextMesh,
+} from "../mesh";
+
+type AvailableMaterialProperty = ExtractProperties<
+  PointMaterial &
+    PolylineMaterial &
+    PolygonMaterial &
+    NavaraModelMaterial &
+    TextMaterial
+>;
+
+/**
+ * Material properties that can be evaluated and modified per-feature.
+ */
+export type EvaluatableMaterialProperty = {
+  /** Feature color expression from layer configuration. */
+  color: AvailableMaterialProperty["color"];
+  /** Feature visibility expression from layer configuration. */
+  show: AvailableMaterialProperty["show"];
+  /** Extruded height expression from layer configuration (for polygons). */
+  extrudedHeight: AvailableMaterialProperty["extrudedHeight"];
+  /** Height expression from layer configuration. */
+  height: AvailableMaterialProperty["height"];
+  /** Text content expression from layer configuration (for text). */
+  text: AvailableMaterialProperty["text"];
+  /** Line width expression from layer configuration (for polylines). */
+  width: AvailableMaterialProperty["width"];
+  /** Point/text size expression from layer configuration (for points/text). */
+  size: AvailableMaterialProperty["size"];
+  /** Opacity expression from layer configuration (for polygons/points/text where supported). */
+  opacity: AvailableMaterialProperty["opacity"];
+  /** Image URL for billboards; packed into a shared per-mesh texture atlas. */
+  image: string;
+};
+
+type EvaluatableMaterialPropertyKey = keyof EvaluatableMaterialProperty;
+
+type EvaluatedMaterialProperty = {
+  color: Color;
+  show: boolean;
+  extrudedHeight: number;
+  height: number;
+  text: string;
+  width: number;
+  size: number;
+  opacity: number;
+  image: string | null;
+};
+
+/**
+ * The evaluated values that can be returned from the evaluate callback.
+ * All properties are optional - only return the ones you want to modify.
+ */
+export type EvaluatedValue = {
+  /** The evaluated color for this feature. */
+  [K in EvaluatableMaterialPropertyKey]: EvaluatedMaterialProperty[K];
+};
+
+/**
+ * Information about a feature batch, passed to evaluation callbacks.
+ */
+export type FeatureInfo = {
+  batchId: number;
+  properties: Record<string, unknown> | undefined;
+  layerId: LayerId | undefined;
+};
+
+/**
+ * Callback function type for feature evaluator operations.
+ */
+export type FeatureEvaluatorCallback = (
+  info: FeatureInfo,
+) => Partial<EvaluatedValue>;
+
+/**
+ * Provides access to feature data and allows dynamic styling of features based on their properties.
+ * Received through the `featureCreated` and `featureUpdated` events on a Layer.
+ *
+ * Use this class to:
+ * - Read feature properties from the data source
+ * - Dynamically style features based on their properties
+ *
+ * @example
+ * ```typescript
+ * // Style 3D Tiles buildings by height
+ * layer.on("featureUpdated", (evaluator) => {
+ *   evaluator.evaluate(({ properties }) => {
+ *     const measuredHeight = properties?.["height"] as number;
+ *
+ *     // Color and visibility based on building height
+ *     const color = (() => {
+ *       if (measuredHeight < 30) return new Color().setStyle("#00ff00");
+ *       if (measuredHeight < 60) return new Color().setStyle("#ffff00");
+ *       if (measuredHeight < 90) return new Color().setStyle("#ff00ff");
+ *       return new Color().setStyle("#ff0000");
+ *     })();
+ *
+ *     return {
+ *       color,
+ *       show: measuredHeight >= 30, // Hide small buildings
+ *     };
+ *   });
+ * });
+ *
+ * // Style GeoJSON polygons with extrusion based on properties
+ * layer.on("featureUpdated", (evaluator) => {
+ *   evaluator.evaluate(({ properties }) => {
+ *     const height = (properties?.["height"] as number) ?? 0;
+ *     const extrudedHeight = (properties?.["extrudedHeight"] as number) ?? 0;
+ *
+ *     return {
+ *       height,
+ *       extrudedHeight,
+ *     };
+ *   });
+ * });
+ *
+ * // Re-evaluate styles
+ * const onChange = () => {
+ *   layer.forceUpdate(); // Triggers featureUpdated events
+ * };
+ * ```
+ */
+export class FeatureEvaluator {
+  private handler: FeatureHandler;
+  private layerId: LayerId;
+  private featureSetId: FeatureSetId;
+  private cachedBatchedProperties?: Map<
+    number,
+    Record<string, unknown> | undefined
+  >;
+  private filterCacheKey?: string;
+  private cachedFilteredProperties?: Map<
+    number,
+    Record<string, unknown> | undefined
+  >;
+  private batchIds: number[] = [];
+
+  /**
+   * The underlying Three.js object representing this feature.
+   * Can be used for advanced manipulation, but prefer using `evaluate()` for styling.
+   */
+  // TODO: Need to support TSL if we export it.
+  private obj: Object3D;
+
+  constructor(
+    handler: FeatureHandler,
+    layerId: LayerId,
+    featureSetId: FeatureSetId,
+    obj: Object3D,
+  ) {
+    this.handler = handler;
+    this.layerId = layerId;
+    this.featureSetId = featureSetId;
+    this.obj = obj;
+  }
+
+  /**
+   * Gets the unique identifier of this feature set.
+   */
+  get id() {
+    return this.featureSetId;
+  }
+
+  /**
+   * Reads the properties of this feature from the data source.
+   * The callback is invoked for each batch within this feature.
+   *
+   * @param f - Callback function that receives feature info for each batch
+   *
+   * @example
+   * ```typescript
+   * // Log all properties
+   * evaluator.readFeatureProperties(({ batchId, properties }) => {
+   *   console.log(`Batch ${batchId}:`, properties);
+   * });
+   *
+   * // Access nested JSON attributes (common in MVT/PLATEAU data)
+   * evaluator.readFeatureProperties(({ properties }) => {
+   *   const attributes = JSON.parse((properties?.["attributes"] as string) ?? "{}");
+   *   const minHeight = attributes["minHeight"];
+   *   const maxHeight = attributes["maxHeight"];
+   * });
+   * ```
+   */
+  readFeatureProperties(f: (info: FeatureInfo, batchIndex: number) => void) {
+    if (this.cachedBatchedProperties) {
+      for (const [batchIdx, properties] of this.cachedBatchedProperties) {
+        f(
+          {
+            layerId: this.layerId,
+            batchId: this.batchIds[batchIdx],
+            properties,
+          },
+          batchIdx,
+        );
+      }
+    } else {
+      this.cachedBatchedProperties = new Map();
+      this.handler.readAllBatchedProperties(
+        this.featureSetId,
+        (
+          batchIdx: number,
+          batchId: number,
+          properties: Record<string, unknown> | undefined,
+        ) => {
+          this.cachedBatchedProperties?.set(batchIdx, properties);
+          this.batchIds[batchIdx] = batchId;
+          f(
+            {
+              layerId: this.layerId,
+              batchId,
+              properties,
+            },
+            batchIdx,
+          );
+        },
+      );
+    }
+  }
+
+  /**
+   * Reads only the specified root properties of this feature.
+   * This is more efficient than `readFeatureProperties` when only a few properties are needed.
+   *
+   * @param keys - Array of property key names to read
+   * @param f - Callback function that receives feature info for each batch
+   *
+   * @example
+   * ```typescript
+   * evaluator.readFilteredFeatureProperties(["height", "name"], ({ batchId, properties }) => {
+   *   const { height, name } = properties;
+   * });
+   * ```
+   */
+  readFilteredFeatureProperties(
+    keys: string[],
+    f: (info: FeatureInfo, batchIndex: number) => void,
+  ) {
+    const cacheKey = keys.join("|");
+    if (this.filterCacheKey === cacheKey && this.cachedFilteredProperties) {
+      for (const [batchIndex, filtered] of this.cachedFilteredProperties) {
+        f(
+          {
+            layerId: this.layerId,
+            batchId: this.batchIds[batchIndex],
+            properties: filtered,
+          },
+          batchIndex,
+        );
+      }
+    } else {
+      this.cachedFilteredProperties = new Map();
+      this.filterCacheKey = cacheKey;
+
+      this.handler.readFilteredBatchedProperties(
+        this.featureSetId,
+        keys,
+        (batchIndex: number, batchId: number, filtered?: unknown[]) => {
+          const properties: Record<string, unknown> = {};
+          for (let i = 0; i < keys.length; i++) {
+            properties[keys[i]] = filtered?.[i];
+          }
+          this.cachedFilteredProperties?.set(batchIndex, properties);
+          this.batchIds[batchIndex] = batchId;
+          f({ layerId: this.layerId, batchId, properties }, batchIndex);
+        },
+      );
+    }
+  }
+
+  /**
+   * Evaluates and applies dynamic styles to features based on their properties.
+   * The callback is invoked for each batch (sub-feature) within this feature.
+   *
+   * Supported style properties:
+   * - `color` - Feature color (use `new Color()`)
+   * - `show` - Feature visibility (boolean)
+   * - `height` - Feature height in meters
+   * - `extrudedHeight` - Extrusion height for polygons in meters
+   * - `text` - Label text content (for text/label features)
+   * - `width` - Line width in pixels (for polylines)
+   * - `size` - Feature size in pixels (for points/text)
+   * - `opacity` - Feature opacity 0-1
+   * - `image` - Image URL (for billboards); loaded once per distinct URL and
+   *   packed into the layer's texture atlas. Return `null` to clear a
+   *   previous per-feature image and revert to the material's default `url`;
+   *   omit the key to leave it unchanged.
+   *
+   * Note: Evaluated styles override the layer's default styles.
+   *
+   * @param f Callback function that receives feature info, returns style values
+   * @param options.filters - Root property's keys that get only the matched property values.
+   *
+   * @example
+   * ```typescript
+   * // Color MVT features based on a category property
+   * evaluator.evaluate(({ properties }) => {
+   *   const category = properties?.["category"] as string;
+   *
+   *   const color = (() => {
+   *     if (category === "A") return "#0000ff";
+   *     if (category === "B") return "#00ff00";
+   *     return "#ff0000";
+   *   })();
+   *
+   *   return {
+   *     color: new Color().setStyle(color),
+   *   };
+   * });
+   *
+   * // Filter and style text labels
+   * evaluator.evaluate(({ properties }) => {
+   *   const text = properties?.["name"] as string;
+   *
+   *   return {
+   *     text,
+   *     show: !!text,
+   *   };
+   * });
+   * ```
+   */
+  evaluate(
+    f: FeatureEvaluatorCallback,
+    options?: {
+      filters?: string[];
+    },
+  ) {
+    const evaluate = (info: FeatureInfo, batchIndex: number) => {
+      const evaluated = f(info);
+      this.applyEvaluatedValues(batchIndex, info.batchId, evaluated);
+    };
+
+    if (options?.filters) {
+      this.readFilteredFeatureProperties(options.filters, evaluate);
+    } else {
+      this.readFeatureProperties(evaluate);
+    }
+  }
+
+  private applyEvaluatedValues(
+    batchIndex: number,
+    batchId: number,
+    evaluated: Partial<EvaluatedValue>,
+  ) {
+    const obj = this.obj;
+
+    if (obj instanceof InstancedSpriteMesh) {
+      if (evaluated.color != null) {
+        obj.setFeatureColorByBatchId(batchId, evaluated.color.raw);
+      }
+      if (evaluated.show != null) {
+        obj.setFeatureShowByBatchId(batchId, evaluated.show);
+      }
+      if (evaluated.height != null) {
+        obj.setFeatureHeightByBatchId(batchId, evaluated.height);
+      }
+      if (evaluated.size != null) {
+        obj.setFeatureSizeByBatchId(batchId, evaluated.size);
+      }
+      if (evaluated.opacity != null) {
+        obj.setFeatureOpacityByBatchId(batchId, evaluated.opacity);
+      }
+      if ("image" in evaluated) {
+        // Async by nature (the image may need fetching); the atlas dedupes
+        // loads by URL so evaluating many features costs one fetch per image.
+        // A nullish url clears the override back to the material default.
+        void obj.setFeatureImageByBatchId(batchId, evaluated.image);
+      }
+      return;
+    }
+
+    if (obj instanceof InstancedMesh) {
+      if (evaluated.color != null) {
+        obj.setFeatureColorByBatchIndex(batchIndex, evaluated.color.raw);
+      }
+      if (evaluated.show != null) {
+        obj.setFeatureShowByBatchIndex(batchIndex, evaluated.show);
+      }
+      if (evaluated.height != null) {
+        obj.setFeatureHeightByBatchIndex(batchIndex, evaluated.height);
+      }
+      if (evaluated.text != null && obj instanceof BatchedSdfTextMesh) {
+        obj.setTextByBatchIndex(batchIndex, evaluated.text);
+      }
+      if (evaluated.size != null && obj instanceof BatchedSdfTextMesh) {
+        obj.setFeatureSizeByBatchIndex(batchIndex, evaluated.size);
+      }
+      if (evaluated.opacity != null && obj instanceof BatchedSdfTextMesh) {
+        obj.setFeatureOpacityByBatchIndex(batchIndex, evaluated.opacity);
+      }
+      return;
+    }
+
+    if (obj instanceof BatchedFeatureMesh) {
+      obj._initBatchDataTexture();
+      this.apply(obj, undefined, batchIndex, evaluated);
+      return;
+    }
+
+    if (obj instanceof ModelMesh) {
+      obj.traverse((m) => {
+        if (!(m instanceof Mesh)) return;
+        obj._initBatchDataTexture(m);
+        this.apply(m, obj, batchIndex, evaluated);
+      });
+    }
+  }
+
+  private apply(
+    m: Mesh | BatchedFeatureMesh,
+    parent: ModelMesh | undefined,
+    batchIndex: number,
+    evaluated: Partial<EvaluatedValue>,
+  ) {
+    const batchIdAttr =
+      "geometry" in m ? m.geometry.getAttribute("_batchid") : undefined;
+
+    // Non-batched feature mesh path (e.g. GeoJSON polyline/polygon)
+    const featureMesh = (() => {
+      if (batchIdAttr) return;
+      if (parent) return isFeatureMesh(parent) ? parent : undefined;
+      return isFeatureMesh(m) ? m : undefined;
+    })();
+
+    if (featureMesh) {
+      if (evaluated.color != null) {
+        featureMesh._setFeatureColor(
+          evaluated.color.raw,
+          m.material as ModelMaterial,
+        );
+      }
+      if (evaluated.show != null) {
+        featureMesh._setFeatureShow(evaluated.show);
+      }
+      if (evaluated.extrudedHeight != null) {
+        featureMesh._setFeatureExtrudedHeight(evaluated.extrudedHeight);
+      }
+      if (evaluated.height != null) {
+        featureMesh._setFeatureHeight(evaluated.height);
+      }
+      if (evaluated.width != null) {
+        featureMesh._setFeatureWidth(evaluated.width);
+      }
+      if (evaluated.opacity != null) {
+        featureMesh._setFeatureOpacity(evaluated.opacity);
+      }
+      return;
+    }
+
+    // Batched mesh path
+    if (!batchIdAttr) return;
+
+    const mesh =
+      parent instanceof ModelMesh
+        ? parent
+        : m instanceof BatchedFeatureMesh
+          ? m
+          : undefined;
+    if (!mesh) return;
+
+    const updateBatchAttribute = (
+      attribute: ModelBatchedAttributeName | BatchedAttributeName,
+      value: number | number[] | boolean,
+    ) => {
+      if (mesh instanceof ModelMesh) {
+        mesh._updateBatchAttribute(
+          m as Mesh<BufferGeometry<NormalBufferAttributes>, ModelMaterial>,
+          batchIndex,
+          attribute as ModelBatchedAttributeName,
+          value,
+        );
+      } else {
+        mesh._updateBatchAttribute(
+          batchIndex,
+          attribute as BatchedAttributeName,
+          value,
+        );
+      }
+    };
+
+    if (evaluated.color != null) {
+      updateBatchAttribute("color", evaluated.color.toArray());
+    }
+    if (evaluated.show != null) {
+      updateBatchAttribute("show", evaluated.show);
+    }
+    if (evaluated.height != null) {
+      updateBatchAttribute("height", evaluated.height);
+    }
+    if (evaluated.extrudedHeight != null) {
+      updateBatchAttribute("extrudedHeight", evaluated.extrudedHeight);
+    }
+    if (evaluated.width != null) {
+      updateBatchAttribute("lineWidth", evaluated.width);
+    }
+    if (evaluated.opacity != null) {
+      updateBatchAttribute("opacity", evaluated.opacity);
+    }
+
+    // size is handled by InstancedSpriteMesh / BatchedSdfTextMesh paths above
+  }
+}

package/src/evaluations/index.ts

@@ -0,0 +1 @@
+export * from "./FeatureEvaluator";