@navaramap/three 0.0.0

package/src/tileTexture/index.ts

@@ -0,0 +1,8 @@
+export * from "./types";
+export * from "./SlotPlanner";
+export * from "./TileTextureCache";
+export * from "./TileTextureCompositor";
+export {
+  generateCompositeFragmentShader,
+  COMPOSITE_VERTEX_SHADER,
+} from "./CompositeShader";

package/src/tileTexture/types.ts

@@ -0,0 +1,150 @@
+import type { TileHandle } from "@navaramap/core";
+import type {
+  Color,
+  Texture,
+  Vector2,
+  Vector3,
+  Vector4,
+  WebGLRenderTarget,
+} from "three";
+
+/**
+ * Why a tile's composite atlas needs to be re-rendered.
+ * Aggregated per-handle so a single composite pass services multiple updates.
+ */
+export type DirtyReason =
+  | "material"
+  | "texture-binding"
+  | "vector-revision"
+  | "hillshade";
+
+/**
+ * A composite atlas is a single MRT render target (count=3) with three named
+ * attachments:
+ * - color: composited diffuse (sRGB)
+ * - attr:  packed per-pixel material attributes (water flag/scale/speed, …)
+ * - normal: hillshade normal map in [0,1] (neutral 0.5,0.5,1 when no hillshade)
+ *
+ * One draw call writes all three; the main TileMesh shader samples them
+ * independently as Textures.
+ */
+export type CompositeAtlas = {
+  readonly target: WebGLRenderTarget;
+  readonly color: Texture;
+  readonly attr: Texture;
+  readonly normal: Texture;
+  dispose: () => void;
+};
+
+/** Creates the per-tile MRT trio. Injected so tests can supply fakes. */
+export type AtlasFactory = (size: number) => CompositeAtlas;
+
+/**
+ * View on the atlas suitable for binding as TileMesh uniforms.
+ * Same Textures live across the atlas's lifetime; only `needsUpdate` flips.
+ */
+export type CompositeOutputs = {
+  color: Texture;
+  attr: Texture;
+  normal: Texture;
+};
+
+/** Features detected from the Rust material — drives CPU shader branch elision. */
+export type CompositeFeatures = {
+  hasHillshade: boolean;
+  hasWater: boolean;
+  hasElevationHeatmap: boolean;
+  /**
+   * Quantized-mesh watermask is present. Sampled once after the slot loop
+   * and OR'd into `isWater` so it takes priority even when no per-slot
+   * `uWaters[k]` is set. Independent of `hasWater` (per-slot flag path).
+   */
+  hasWatermask: boolean;
+};
+
+/** A handle's cache entry. Public surface is via TileTextureCache methods. */
+export type CacheEntry = {
+  readonly handle: TileHandle;
+  readonly atlas: CompositeAtlas;
+  refCount: number;
+  dirty: Set<DirtyReason>;
+};
+
+// ---------------------------------------------------------------------------
+// Composite domain model
+//
+// Typed replacement for the parallel-array bridge (shows[]/colors[]/
+// isHillshades[]/… read out of material.userData). Each active layer is one
+// self-describing record; the SlotPlanner flattens them into compact slots and
+// the composite layer enhancers consume them. `region` keeps the existing
+// raster/vector split (the compact-slot space skips the gap between them) and
+// drives the compile-time `isTexturized` constant.
+// ---------------------------------------------------------------------------
+
+/** Which compact-slot region a layer lives in (raster low indices vs vector). */
+export type CompositeLayerRegion = "raster" | "vector";
+
+type CompositeLayerBase = {
+  /**
+   * Absolute slot index into the TileMesh main shader's per-slot uniform
+   * arrays. Baked into the atlas as the winning slot so the main shader can
+   * look the layer's precision-sensitive attrs back up.
+   */
+  absSlot: number;
+  region: CompositeLayerRegion;
+  texture: Texture | null;
+  uvOffset: Vector2;
+  uvScale: Vector2;
+};
+
+/** A sampled color layer — a raster tile or a texturized vector scene. */
+export type RasterCompositeLayer = CompositeLayerBase & {
+  kind: "raster";
+  color: Color;
+  opacity: number;
+  water: boolean;
+  /**
+   * `[south, north]` latitude (radians) of the terrain tile when this slot is a
+   * WebMercator raster draped on Geographic terrain — the composite shader uses
+   * it to reproject the latitude axis (Mercator). `undefined` for same-scheme
+   * drapes (no reprojection).
+   */
+  reproject?: [number, number];
+};
+
+/** A DEM-derived normal map; contributes no color, only a hillshade normal. */
+export type HillshadeCompositeLayer = CompositeLayerBase & {
+  kind: "hillshade";
+};
+
+/** A DEM elevation raster colorized through the shared colormap. */
+export type ElevationHeatmapCompositeLayer = CompositeLayerBase & {
+  kind: "elevationHeatmap";
+  opacity: number;
+};
+
+export type CompositeLayer =
+  | RasterCompositeLayer
+  | HillshadeCompositeLayer
+  | ElevationHeatmapCompositeLayer;
+
+/**
+ * Tile-wide inputs that are not per-slot. Kept separate from CompositeLayer so
+ * adding a new per-layer expression doesn't bloat a shared struct (and vice
+ * versa). Consumed by the layer enhancers that own slot-independent uniforms.
+ */
+export type CompositeGlobals = {
+  /** Hillshade normal exaggeration (shared across hillshade layers). */
+  hillshadeExaggeration: number;
+  /** Quantized-mesh watermask (1×1 uniform or 256×256), or null. */
+  watermask: Texture | null;
+  /** Elevation heatmap colormap ramp, or null. */
+  colorMapTexture: Texture | null;
+  /** Elevation heatmap shared decoder params. */
+  elevationRGBScaler: Vector3;
+  elevationMinMaxHeightAndBoundary: Vector3;
+  elevationMinMaxOffsetAndEpsilonAndOffset: Vector4;
+  logarithmic: boolean;
+  logBase: number;
+  logBoundary: number;
+};

package/src/type/index.ts

@@ -0,0 +1,261 @@
+import type { NormalizeWASMClass, TileHandle } from "@navaramap/core";
+import type {
+  B3dmLayerDescription,
+  PntsLayerDescription,
+  Cesium3dTilesLayerDescription,
+  GeoJsonLayerDescription,
+  TerrainLayerDescription,
+  TileLayerDescription,
+  MvtLayerDescription,
+  VectorLayerDescription,
+  RasterLayerDescription,
+  TerrainSourceLayerDescription,
+  Tiles3dLayerDescription,
+  GeoJsonSourceDescription,
+  VectorTileSourceDescription,
+  RasterTileSourceDescription,
+  RasterDemSourceDescription,
+  QuantizedMeshSourceDescription,
+  Tiles3dSourceDescription,
+  SourceDescription as SourceDescriptionImpl,
+} from "@navaramap/engine";
+import type { Promise as WorkerPoolPromise } from "@navaramap/worker";
+import type { Feature, FeatureCollection, Geometry } from "geojson";
+import type { Mesh, Sprite, Object3D } from "three";
+
+import type { Color } from "../Color";
+import type { FeatureInfo } from "../evaluations";
+import type {
+  FinalCopyPassConfig,
+  MRTPassConfig,
+  SkyEnvMapPassConfig,
+  TransparentPassConfig,
+} from "../layers/effect";
+import type { TileMesh } from "../mesh";
+import type { Source } from "../source";
+
+export type { Promise as WorkerPoolPromise } from "@navaramap/worker";
+
+export type Descriptions = {
+  mesh?: object;
+  light?: object;
+  effect?: object;
+};
+
+export type EmptyDescriptions = {
+  mesh: undefined;
+  light: undefined;
+  effect: undefined;
+};
+
+export type OmitType<T> = T extends unknown ? Omit<T, "type"> : never;
+
+export type BuiltInEffectDescription =
+  | FinalCopyPassConfig
+  | MRTPassConfig
+  | SkyEnvMapPassConfig
+  | TransparentPassConfig;
+
+// export type MVTLayer = {
+//   type: "mvt";
+//   zoom: number;
+//   layers?: string[];
+//   height?: number;
+//   extent?: Extent;
+//   url: string;
+//   color?: number;
+// };
+
+type Layer<LD> = NormalizeWASMClass<LD>;
+
+/**
+ * Helper type to add Navara Color object support to color-related number fields.
+ * This recursively transforms any field named 'color' or ending with 'Color'
+ * to accept both number and Navara Color objects.
+ */
+type ConvertColorFields<T> = {
+  [K in keyof T]: K extends `${string}Color` | "color"
+    ? T[K] extends number | undefined
+      ? Color | undefined
+      : T[K] extends number
+        ? Color
+        : T[K]
+    : T[K] extends object | undefined
+      ? ConvertColorFields<T[K]> | Extract<T[K], undefined>
+      : T[K];
+};
+
+/**
+ * Helper type to enable Navara Color objects in all color-related fields.
+ * This applies to model, point, billboard, text, polyline, polygon, rasterTile, etc.
+ * Both number and Navara Color objects are accepted for backward compatibility.
+ */
+type WithColorSupport<T> = ConvertColorFields<T>;
+
+export type TilesLayer = WithColorSupport<
+  Layer<TileLayerDescription & { type: "tiles" }>
+>;
+export type TerrainLayer = Layer<TerrainLayerDescription & { type: "terrain" }>;
+export type GeoJsonLayer = WithColorSupport<
+  Layer<GeoJsonLayerDescription & { type: "geojson" }>
+>;
+export type B3dmLayer = WithColorSupport<
+  Layer<B3dmLayerDescription & { type: "b3dm" }>
+>;
+export type PntsLayer = WithColorSupport<
+  Layer<PntsLayerDescription & { type: "pnts" }>
+>;
+export type Cesium3dTilesLayer = WithColorSupport<
+  Layer<Cesium3dTilesLayerDescription & { type: "cesium3dtiles" }>
+>;
+export type MvtLayer = WithColorSupport<
+  Layer<MvtLayerDescription & { type: "mvt" }>
+>;
+
+/**
+ * A reference to a {@link Source}: either the source handle returned by
+ * `addSource`, or its `id` string.
+ */
+export type SourceRef = string | Source;
+
+export type SourceLayerBase<Layer extends { source?: string | undefined }> =
+  Omit<Layer, "source"> & {
+    source?: SourceRef;
+  };
+
+type VectorLayerBase = WithColorSupport<
+  Layer<VectorLayerDescription & { type: "vector" }>
+>;
+
+/**
+ * A `vector` layer renders a `geojson` or `vector-tile` source as points,
+ * lines, polygons, text and billboards.
+ */
+export type VectorLayer = SourceLayerBase<VectorLayerBase>;
+
+type RasterLayerBase = WithColorSupport<
+  Layer<RasterLayerDescription & { type: "raster" }>
+>;
+
+/** A `raster` layer renders a `raster-tile` (imagery) or `raster-dem` source. */
+export type RasterLayer = SourceLayerBase<RasterLayerBase>;
+
+type TerrainSourceLayerBase = WithColorSupport<
+  Layer<TerrainSourceLayerDescription & { type: "terrain" }>
+>;
+
+/**
+ * A `terrain` layer renders a `raster-dem` or `quantized-mesh` source as the globe surface.
+ */
+export type TerrainSourceLayer = SourceLayerBase<TerrainSourceLayerBase>;
+
+type Tiles3dLayerBase = WithColorSupport<
+  Layer<Tiles3dLayerDescription & { type: "3d-tiles" }>
+>;
+
+/** A `3d-tiles` layer renders a `3d-tiles`, `b3dm`, or `pnts` source. */
+export type Tiles3dLayer = SourceLayerBase<Tiles3dLayerBase>;
+
+export type LayerDescription =
+  | TilesLayer
+  | TerrainLayer
+  | GeoJsonLayer
+  | B3dmLayer
+  | PntsLayer
+  | Cesium3dTilesLayer
+  | MvtLayer
+  | VectorLayer
+  | RasterLayer
+  | TerrainSourceLayer
+  | Tiles3dLayer;
+
+/**
+ * Fields common to every source, independent of its `type`.
+ *
+ * An optional `id` may be given; when omitted a random id is generated. Adding a
+ * source with an existing id overrides it (later definition wins). Combined with
+ * referencing a source by its id string from a layer, this enables defining the
+ * whole map declaratively (MapLibre-style) from JSON.
+ */
+export type SourceBase = Omit<
+  NormalizeWASMClass<SourceDescriptionImpl>,
+  "type"
+>;
+
+/** A `geojson` source: inline GeoJSON, or GeoJSON fetched from a `url`. */
+export type GeoJsonSource = SourceBase &
+  Omit<
+    WithColorSupport<Layer<GeoJsonSourceDescription & { type: "geojson" }>>,
+    "data"
+  > & {
+    /** Inline GeoJSON. Use `url` instead to fetch from a URL. */
+    data?: FeatureCollection | Feature | Geometry;
+  };
+
+/** A `vector-tile` source: Mapbox Vector Tiles fetched from a `url` template. */
+export type VectorTileSource = SourceBase &
+  WithColorSupport<
+    Layer<VectorTileSourceDescription & { type: "vector-tile" }>
+  >;
+
+/** A `raster-tile` source: raster imagery tiles fetched from a `url` template. */
+export type RasterTileSource = SourceBase &
+  WithColorSupport<
+    Layer<RasterTileSourceDescription & { type: "raster-tile" }>
+  >;
+
+/** A `raster-dem` source: RGB-encoded elevation tiles fetched from a `url` template. */
+export type RasterDemSource = SourceBase &
+  WithColorSupport<Layer<RasterDemSourceDescription & { type: "raster-dem" }>>;
+
+/** A `quantized-mesh` source: Cesium quantized-mesh terrain tiles. */
+export type QuantizedMeshSource = SourceBase &
+  WithColorSupport<
+    Layer<QuantizedMeshSourceDescription & { type: "quantized-mesh" }>
+  >;
+
+/** A `3d-tiles` source: a 3D Tiles tileset (`tileset.json`). */
+export type Tiles3dSource = SourceBase &
+  WithColorSupport<Layer<Tiles3dSourceDescription & { type: "3d-tiles" }>>;
+
+/** A `b3dm` source: a single Batched 3D Model tile. */
+export type B3dmSource = SourceBase &
+  WithColorSupport<Layer<Tiles3dSourceDescription & { type: "b3dm" }>>;
+
+/** A `pnts` source: a single Point Cloud tile. */
+export type PntsSource = SourceBase &
+  WithColorSupport<Layer<Tiles3dSourceDescription & { type: "pnts" }>>;
+
+/**
+ * A source describes where data comes from and how it is fetched/decoded.
+ * Register one with `addSource` and reference it from layers by handle or id.
+ *
+ * This is the discriminated union of every per-type source description
+ * ({@link GeoJsonSource}, {@link QuantizedMeshSource}, ...); use an individual
+ * member type when you only accept one source type.
+ */
+export type SourceDescription =
+  | GeoJsonSource
+  | VectorTileSource
+  | RasterTileSource
+  | RasterDemSource
+  | QuantizedMeshSource
+  | Tiles3dSource
+  | B3dmSource
+  | PntsSource;
+
+export type MeshCache = Map<string, Mesh | Sprite | Object3D>;
+
+// Make a reference of TileMesh by TileHandle.
+export type TileMapByHandle = Map<TileHandle, TileMesh>;
+
+export type AbortControllers = Map<string, AbortController>;
+
+export type WorkerPoolPromises = Map<string, WorkerPoolPromise<unknown>>;
+
+export type PickedFeature = FeatureInfo;
+
+export type RenderFlag = {
+  forceUpdate: boolean;
+  animation: boolean;
+};

package/src/uniforms.ts

@@ -0,0 +1,20 @@
+import type { Matrix4, Texture } from "three";
+
+type Ref<K extends string, T> = Record<K, T | undefined | null>;
+type RefThree<T> = Ref<"value", T>;
+
+// TODO: Separate as individual library
+export type CommonUniforms = {
+  viewportAndPixelRatio: RefThree<[x: number, y: number, z: number]>;
+  frustumRatio: RefThree<[x: number, y: number, z: number, w: number]>;
+  frustumNearFar: RefThree<[x: number, y: number]>;
+  tGlobeDepth: RefThree<Texture>;
+  tGlobeNormal: RefThree<Texture>;
+  tSkyEnvMap: RefThree<Texture>;
+  inverseProjectionMatrix: RefThree<Matrix4>;
+  fov: RefThree<number>;
+  screenHeightPx: RefThree<number>;
+  time: RefThree<number>;
+  colorMapTexture: RefThree<Texture>;
+  waterTexture: RefThree<Texture>;
+};

package/src/utils/arraysEqual.ts

@@ -0,0 +1,9 @@
+export function arraysEqual<T>(
+  a: T[] | undefined,
+  b: T[] | undefined,
+): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  if (a.length !== b.length) return false;
+  return a.every((v, i) => v === b[i]);
+}

package/src/utils/blendModes.ts

@@ -0,0 +1,80 @@
+import { BlendFunction } from "postprocessing";
+
+export type BlendMode =
+  | "skip"
+  | "set"
+  | "add"
+  | "alpha"
+  | "average"
+  | "color"
+  | "colorBurn"
+  | "colorDodge"
+  | "darken"
+  | "difference"
+  | "divide"
+  | "dst"
+  | "exclusion"
+  | "hardLight"
+  | "hardMix"
+  | "hue"
+  | "invert"
+  | "invertRgb"
+  | "lighten"
+  | "linearBurn"
+  | "linearDodge"
+  | "linearLight"
+  | "luminosity"
+  | "multiply"
+  | "negation"
+  | "normal"
+  | "overlay"
+  | "pinLight"
+  | "reflect"
+  | "saturation"
+  | "screen"
+  | "softLight"
+  | "src"
+  | "subtract"
+  | "vividLight";
+
+const BLEND_MAP: Record<BlendMode, BlendFunction> = {
+  skip: BlendFunction.SKIP,
+  set: BlendFunction.SET,
+  add: BlendFunction.ADD,
+  alpha: BlendFunction.ALPHA,
+  average: BlendFunction.AVERAGE,
+  color: BlendFunction.COLOR,
+  colorBurn: BlendFunction.COLOR_BURN,
+  colorDodge: BlendFunction.COLOR_DODGE,
+  darken: BlendFunction.DARKEN,
+  difference: BlendFunction.DIFFERENCE,
+  divide: BlendFunction.DIVIDE,
+  dst: BlendFunction.DST,
+  exclusion: BlendFunction.EXCLUSION,
+  hardLight: BlendFunction.HARD_LIGHT,
+  hardMix: BlendFunction.HARD_MIX,
+  hue: BlendFunction.HUE,
+  invert: BlendFunction.INVERT,
+  invertRgb: BlendFunction.INVERT_RGB,
+  lighten: BlendFunction.LIGHTEN,
+  linearBurn: BlendFunction.LINEAR_BURN,
+  linearDodge: BlendFunction.LINEAR_DODGE,
+  linearLight: BlendFunction.LINEAR_LIGHT,
+  luminosity: BlendFunction.LUMINOSITY,
+  multiply: BlendFunction.MULTIPLY,
+  negation: BlendFunction.NEGATION,
+  normal: BlendFunction.NORMAL,
+  overlay: BlendFunction.OVERLAY,
+  pinLight: BlendFunction.PIN_LIGHT,
+  reflect: BlendFunction.REFLECT,
+  saturation: BlendFunction.SATURATION,
+  screen: BlendFunction.SCREEN,
+  softLight: BlendFunction.SOFT_LIGHT,
+  src: BlendFunction.SRC,
+  subtract: BlendFunction.SUBTRACT,
+  vividLight: BlendFunction.VIVID_LIGHT,
+};
+
+export function blendFunction(mode: BlendMode): BlendFunction {
+  return BLEND_MAP[mode] ?? BlendFunction.SRC;
+}

package/src/utils/geometry.ts

@@ -0,0 +1,53 @@
+// Ref: https://github.com/takram-design-engineering/geovanni/blob/ee91f675ba2558ee3099f635dfa30bbe3adfe103/libs/core/src/utils.ts
+
+import { isNotNullish } from "@navaramap/core";
+import { pick } from "lodash-es";
+import { BufferAttribute, BufferGeometry } from "three";
+
+export type BufferGeometryLike = Pick<
+  BufferGeometry,
+  "attributes" | "index" | "boundingBox" | "boundingSphere"
+>;
+
+export function toBufferGeometryLike(
+  geometry: BufferGeometry,
+): [BufferGeometryLike, ArrayBuffer[]] {
+  return [
+    pick(geometry, ["attributes", "index", "boundingBox", "boundingSphere"]),
+    (
+      [
+        ...Object.values(geometry.attributes).map(
+          (attribute) => attribute.array.buffer,
+        ),
+        geometry.index?.array.buffer,
+      ] as ArrayBuffer[]
+    ).filter(isNotNullish),
+  ];
+}
+
+export function fromBufferGeometryLike(
+  input: BufferGeometryLike,
+  result = new BufferGeometry(),
+): BufferGeometry {
+  for (const [name, attribute] of Object.entries(input.attributes)) {
+    result.setAttribute(
+      name,
+      new BufferAttribute(
+        attribute.array,
+        attribute.itemSize,
+        attribute.normalized,
+      ),
+    );
+  }
+  result.index =
+    input.index != null
+      ? new BufferAttribute(
+          input.index.array,
+          input.index.itemSize,
+          input.index.normalized,
+        )
+      : null;
+  result.boundingBox = input.boundingBox;
+  result.boundingSphere = input.boundingSphere;
+  return result;
+}