@deck.gl-community/three 9.2.5

package/src/tree-layer/tree-geometry.ts

@@ -0,0 +1,204 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {
+  BufferGeometry,
+  BufferAttribute,
+  CylinderGeometry,
+  ConeGeometry,
+  SphereGeometry,
+  Matrix4
+} from 'three';
+
+/**
+ * Mesh format compatible with deck.gl SimpleMeshLayer.
+ * All geometries are Z-up (deck.gl convention), unit scale (0..1 in Z = bottom to top).
+ */
+export type TreeMesh = {
+  attributes: {
+    POSITION: {value: Float32Array; size: 3};
+    NORMAL: {value: Float32Array; size: 3};
+  };
+  indices: {value: Uint32Array; size: 1};
+  topology: 'triangle-list';
+  mode: 4;
+};
+
+/**
+ * Rotation matrix that converts from Three.js Y-up to deck.gl Z-up.
+ * Rotates -90 degrees around the X axis: Y -> Z, Z -> -Y.
+ */
+const Y_TO_Z_UP = new Matrix4().makeRotationX(-Math.PI / 2);
+
+/**
+ * Extract a TreeMesh from a Three.js BufferGeometry.
+ * Assumes the geometry has already been rotated to Z-up.
+ */
+function extractMesh(geo: BufferGeometry): TreeMesh {
+  geo.computeVertexNormals();
+  const posAttr = geo.attributes.position as BufferAttribute;
+  const norAttr = geo.attributes.normal as BufferAttribute;
+  const idx = geo.index;
+
+  return {
+    attributes: {
+      POSITION: {value: new Float32Array(posAttr.array), size: 3},
+      NORMAL: {value: new Float32Array(norAttr.array), size: 3}
+    },
+    indices: {value: new Uint32Array(idx ? idx.array : new Uint32Array(0)), size: 1},
+    topology: 'triangle-list',
+    mode: 4
+  };
+}
+
+/** Copy indices for one geometry slice, offsetting by the current vertex base. */
+function copyIndices(
+  out: Uint32Array,
+  outOffset: number,
+  geo: BufferGeometry,
+  vertexBase: number
+): number {
+  if (geo.index) {
+    const src = geo.index.array;
+    for (let i = 0; i < src.length; i++) out[outOffset + i] = src[i] + vertexBase;
+    return src.length;
+  }
+  const count = geo.attributes.position.count;
+  for (let i = 0; i < count; i++) out[outOffset + i] = vertexBase + i;
+  return count;
+}
+
+/**
+ * Merge multiple Three.js BufferGeometries into a single geometry.
+ * All input geometries must be indexed.
+ */
+function mergeGeometries(geos: BufferGeometry[]): BufferGeometry {
+  let totalVertices = 0;
+  let totalIndices = 0;
+  for (const geo of geos) {
+    totalVertices += geo.attributes.position.count;
+    totalIndices += geo.index ? geo.index.count : geo.attributes.position.count;
+  }
+
+  const positions = new Float32Array(totalVertices * 3);
+  const normals = new Float32Array(totalVertices * 3);
+  const indices = new Uint32Array(totalIndices);
+  let vOffset = 0;
+  let iOffset = 0;
+
+  for (const geo of geos) {
+    const count = geo.attributes.position.count;
+    const srcNor = geo.attributes.normal ? (geo.attributes.normal.array as Float32Array) : null;
+    positions.set(geo.attributes.position.array as Float32Array, vOffset * 3);
+    if (srcNor) normals.set(srcNor, vOffset * 3);
+    iOffset += copyIndices(indices, iOffset, geo, vOffset);
+    vOffset += count;
+  }
+
+  const merged = new BufferGeometry();
+  merged.setAttribute('position', new BufferAttribute(positions, 3));
+  merged.setAttribute('normal', new BufferAttribute(normals, 3));
+  merged.setIndex(new BufferAttribute(indices, 1));
+  return merged;
+}
+
+/**
+ * Unit trunk cylinder mesh: from z=0 (base) to z=1 (top), radius tapers from 1 to 0.7.
+ * Scale via `getScale = [trunkRadius, trunkRadius, trunkHeight]`.
+ */
+export function createTrunkMesh(segments = 8): TreeMesh {
+  const geo = new CylinderGeometry(0.7, 1.0, 1.0, segments);
+  // Three.js CylinderGeometry is centered at origin, extends from y=-0.5 to y=0.5
+  geo.applyMatrix4(Y_TO_Z_UP); // Rotate to Z-up: now z=-0.5 to z=0.5
+  geo.translate(0, 0, 0.5); // Shift so base is at z=0, top at z=1
+  return extractMesh(geo);
+}
+
+/**
+ * Unit pine canopy mesh: multiple tiered cones creating a Christmas tree silhouette.
+ * Extends from z=0 (base of canopy) to z=1 (tip).
+ *
+ * @param levels - number of cone tiers (1-5)
+ * @param segments - polygon segments per cone
+ */
+export function createPineCanopyMesh(levels = 3, segments = 8): TreeMesh {
+  const geos: BufferGeometry[] = [];
+  const tierHeight = 0.55 / levels;
+
+  for (let i = 0; i < levels; i++) {
+    const t = i / (levels - 1 || 1);
+    // Bottom tiers are wider, top tiers are narrower
+    const radius = (1 - t * 0.5) * 0.85;
+    // Tiers are staggered: each one starts 60% up the previous tier
+    const zBase = t * (1 - tierHeight * 1.2);
+
+    const cone = new ConeGeometry(radius, tierHeight, segments);
+    cone.applyMatrix4(Y_TO_Z_UP);
+    // ConeGeometry apex is at y=+height/2 -> z=+height/2 after rotation
+    // Translate so apex points upward and base is at zBase
+    cone.translate(0, 0, zBase + tierHeight);
+    geos.push(cone);
+  }
+
+  // Sharp tip at top
+  const tip = new ConeGeometry(0.12, 0.18, 6);
+  tip.applyMatrix4(Y_TO_Z_UP);
+  tip.translate(0, 0, 1.0);
+  geos.push(tip);
+
+  const merged = mergeGeometries(geos);
+  merged.computeVertexNormals();
+  return extractMesh(merged);
+}
+
+/**
+ * Unit oak canopy mesh: a large sphere.
+ * Extends from z=0 to z=1, center at z=0.5.
+ */
+export function createOakCanopyMesh(): TreeMesh {
+  const geo = new SphereGeometry(0.5, 12, 8);
+  // SphereGeometry is centered at origin, radius=0.5
+  geo.applyMatrix4(Y_TO_Z_UP);
+  geo.translate(0, 0, 0.5); // center at z=0.5, extends z=0 to z=1
+  return extractMesh(geo);
+}
+
+/**
+ * Unit palm canopy mesh: a flat, wide disk crown typical of palm trees.
+ * Extends from z=0 to z=0.35, radius=1.
+ */
+export function createPalmCanopyMesh(): TreeMesh {
+  // Flattened sphere acting as a spread crown
+  const geo = new SphereGeometry(0.7, 12, 5);
+  const flatten = new Matrix4().makeScale(1.4, 0.35, 1.4);
+  geo.applyMatrix4(flatten);
+  geo.applyMatrix4(Y_TO_Z_UP);
+  geo.translate(0, 0, 0.18);
+  return extractMesh(geo);
+}
+
+/**
+ * Unit birch canopy mesh: a narrow oval / diamond shape.
+ * Extends from z=0 to z=1, narrower than an oak.
+ */
+export function createBirchCanopyMesh(): TreeMesh {
+  const geo = new SphereGeometry(0.42, 10, 8);
+  // Elongate vertically (Z after rotation)
+  const elongate = new Matrix4().makeScale(1, 1.45, 1);
+  geo.applyMatrix4(elongate);
+  geo.applyMatrix4(Y_TO_Z_UP);
+  geo.translate(0, 0, 0.5);
+  return extractMesh(geo);
+}
+
+/**
+ * Unit cherry canopy mesh: a full, round sphere slightly larger than oak.
+ * Extends from z=0 to z=1.1 (slightly wider than tall for a lush look).
+ */
+export function createCherryCanopyMesh(): TreeMesh {
+  const geo = new SphereGeometry(0.52, 12, 8);
+  geo.applyMatrix4(Y_TO_Z_UP);
+  geo.translate(0, 0, 0.5);
+  return extractMesh(geo);
+}

package/src/tree-layer/tree-layer.ts

@@ -0,0 +1,365 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {CompositeLayer} from '@deck.gl/core';
+import type {Color, DefaultProps, LayerProps, Position} from '@deck.gl/core';
+import {SimpleMeshLayer} from '@deck.gl/mesh-layers';
+import {
+  createTrunkMesh,
+  createPineCanopyMesh,
+  createOakCanopyMesh,
+  createPalmCanopyMesh,
+  createBirchCanopyMesh,
+  createCherryCanopyMesh
+} from './tree-geometry';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** Tree species / silhouette variant. */
+export type TreeType = 'pine' | 'oak' | 'palm' | 'birch' | 'cherry';
+
+/** Season that drives default canopy colour when no explicit colour is supplied. */
+export type Season = 'spring' | 'summer' | 'autumn' | 'winter';
+
+// ---------------------------------------------------------------------------
+// Default colours
+// ---------------------------------------------------------------------------
+
+/** Default trunk colours per tree type [r, g, b, a]. */
+const DEFAULT_TRUNK_COLORS: Record<TreeType, Color> = {
+  pine: [80, 50, 20, 255],
+  oak: [91, 57, 23, 255],
+  palm: [140, 100, 55, 255],
+  birch: [220, 215, 205, 255], // white-grey birch bark
+  cherry: [100, 60, 40, 255]
+};
+
+/** Default canopy colours per (tree type, season) [r, g, b, a]. */
+const DEFAULT_CANOPY_COLORS: Record<TreeType, Record<Season, Color>> = {
+  pine: {
+    spring: [34, 100, 34, 255],
+    summer: [0, 64, 0, 255],
+    autumn: [0, 64, 0, 255], // evergreen — no colour change
+    winter: [0, 55, 0, 255]
+  },
+  oak: {
+    spring: [100, 180, 80, 255],
+    summer: [34, 120, 15, 255],
+    autumn: [180, 85, 20, 255],
+    winter: [100, 80, 60, 160] // sparse, semi-transparent
+  },
+  palm: {
+    spring: [50, 160, 50, 255],
+    summer: [20, 145, 20, 255],
+    autumn: [55, 150, 30, 255],
+    winter: [40, 130, 30, 255]
+  },
+  birch: {
+    spring: [150, 210, 110, 255],
+    summer: [80, 160, 60, 255],
+    autumn: [230, 185, 40, 255],
+    winter: [180, 180, 170, 90] // near-bare
+  },
+  cherry: {
+    spring: [255, 180, 205, 255], // pink blossom
+    summer: [50, 140, 50, 255],
+    autumn: [200, 60, 40, 255],
+    winter: [120, 90, 80, 110] // bare
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Pre-built unit-scale meshes (shared across all layer instances)
+// ---------------------------------------------------------------------------
+
+const TRUNK_MESH = createTrunkMesh();
+
+const CANOPY_MESHES: Record<TreeType, ReturnType<typeof createTrunkMesh>> = {
+  pine: createPineCanopyMesh(3),
+  oak: createOakCanopyMesh(),
+  palm: createPalmCanopyMesh(),
+  birch: createBirchCanopyMesh(),
+  cherry: createCherryCanopyMesh()
+};
+
+const ALL_TREE_TYPES: TreeType[] = ['pine', 'oak', 'palm', 'birch', 'cherry'];
+
+// ---------------------------------------------------------------------------
+// Props
+// ---------------------------------------------------------------------------
+
+type _TreeLayerProps<DataT> = {
+  /** Source data. */
+  data: DataT[];
+
+  /** Longitude/latitude position of the tree base. */
+  getPosition?: (d: DataT) => Position;
+
+  /** Base elevation (metres above sea level). @default 0 */
+  getElevation?: (d: DataT) => number;
+
+  /**
+   * Silhouette / species variant.
+   * 'pine'   – layered conical tiers (evergreen)
+   * 'oak'    – wide spherical canopy
+   * 'palm'   – tall thin trunk with flat crown
+   * 'birch'  – narrow oval canopy, pale bark
+   * 'cherry' – round lush canopy, seasonal blossom
+   * @default 'pine'
+   */
+  getTreeType?: (d: DataT) => TreeType;
+
+  /**
+   * Total tree height in metres.
+   * @default 10
+   */
+  getHeight?: (d: DataT) => number;
+
+  /**
+   * Fraction of total height occupied by the trunk (0–1).
+   * @default 0.35
+   */
+  getTrunkHeightFraction?: (d: DataT) => number;
+
+  /**
+   * Trunk base radius in metres.
+   * @default 0.5
+   */
+  getTrunkRadius?: (d: DataT) => number;
+
+  /**
+   * Horizontal radius of the canopy in metres.
+   * @default 3
+   */
+  getCanopyRadius?: (d: DataT) => number;
+
+  /**
+   * Explicit trunk colour [r, g, b, a].
+   * When null the species default is used.
+   * @default null
+   */
+  getTrunkColor?: (d: DataT) => Color | null;
+
+  /**
+   * Explicit canopy colour [r, g, b, a].
+   * When null the species × season default is used.
+   * @default null
+   */
+  getCanopyColor?: (d: DataT) => Color | null;
+
+  /**
+   * Season used to pick the default canopy colour when no explicit colour is provided.
+   * @default 'summer'
+   */
+  getSeason?: (d: DataT) => Season;
+
+  /**
+   * Number of cone tiers for pine trees (1–5).
+   * Higher values produce a denser layered silhouette.
+   * @default 3
+   */
+  getBranchLevels?: (d: DataT) => number;
+
+  /**
+   * Global size multiplier applied to all dimensions.
+   * @default 1
+   */
+  sizeScale?: number;
+};
+
+export type TreeLayerProps<DataT = unknown> = _TreeLayerProps<DataT> & LayerProps;
+
+const defaultProps: DefaultProps<TreeLayerProps<unknown>> = {
+  getPosition: {type: 'accessor', value: (d: any) => d.position},
+  getElevation: {type: 'accessor', value: (_d: any) => 0},
+  getTreeType: {type: 'accessor', value: (_d: any) => 'pine' as TreeType},
+  getHeight: {type: 'accessor', value: (_d: any) => 10},
+  getTrunkHeightFraction: {type: 'accessor', value: (_d: any) => 0.35},
+  getTrunkRadius: {type: 'accessor', value: (_d: any) => 0.5},
+  getCanopyRadius: {type: 'accessor', value: (_d: any) => 3},
+  getTrunkColor: {type: 'accessor', value: (_d: any) => null},
+  getCanopyColor: {type: 'accessor', value: (_d: any) => null},
+  getSeason: {type: 'accessor', value: (_d: any) => 'summer' as Season},
+  getBranchLevels: {type: 'accessor', value: (_d: any) => 3},
+  sizeScale: {type: 'number', value: 1, min: 0}
+};
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+
+type TreeLayerState = {
+  grouped: Record<TreeType, unknown[]>;
+  pineMeshes: Record<number, ReturnType<typeof createPineCanopyMesh>>;
+};
+
+// ---------------------------------------------------------------------------
+// Layer
+// ---------------------------------------------------------------------------
+
+/**
+ * **TreeLayer** — A parametric, Three.js-powered deck.gl layer that renders
+ * richly configurable 3D trees at geographic positions.
+ *
+ * Each tree is composed of two `SimpleMeshLayer` instances: one for the trunk
+ * (a tapered cylinder) and one for the canopy (silhouette depends on `getTreeType`).
+ * All geometry is generated procedurally using Three.js `BufferGeometry` primitives
+ * and converted to the `@loaders.gl/schema` `MeshGeometry` format accepted by
+ * `SimpleMeshLayer`.
+ *
+ * Parametric controls include:
+ * - Species / silhouette (`getTreeType`)
+ * - Total height (`getHeight`) and trunk-to-canopy proportion (`getTrunkHeightFraction`)
+ * - Trunk and canopy radii (`getTrunkRadius`, `getCanopyRadius`)
+ * - Explicit or season-driven colours (`getTrunkColor`, `getCanopyColor`, `getSeason`)
+ * - Pine tier density (`getBranchLevels`)
+ * - Global scale factor (`sizeScale`)
+ */
+export class TreeLayer<DataT = unknown, ExtraPropsT extends {} = {}> extends CompositeLayer<
+  ExtraPropsT & Required<_TreeLayerProps<DataT>>
+> {
+  static layerName = 'TreeLayer';
+  static defaultProps = defaultProps;
+
+  declare state: TreeLayerState;
+
+  initializeState() {
+    this.state = {
+      grouped: {pine: [], oak: [], palm: [], birch: [], cherry: []},
+      pineMeshes: {}
+    };
+  }
+
+  updateState({props, changeFlags}) {
+    if (changeFlags.dataChanged || changeFlags.updateTriggersChanged) {
+      const {data, getTreeType, getBranchLevels} = props;
+      const grouped: Record<TreeType, DataT[]> = {
+        pine: [],
+        oak: [],
+        palm: [],
+        birch: [],
+        cherry: []
+      };
+
+      // Build per-level pine mesh cache
+      const pineMeshes: Record<number, ReturnType<typeof createPineCanopyMesh>> = {};
+
+      for (const d of data as DataT[]) {
+        const type = getTreeType(d) as TreeType;
+        if (grouped[type]) grouped[type].push(d);
+        if (type === 'pine') {
+          const levels = Math.max(1, Math.min(5, Math.round(getBranchLevels(d) as number)));
+          pineMeshes[levels] ??= createPineCanopyMesh(levels);
+        }
+      }
+
+      this.setState({grouped, pineMeshes});
+    }
+  }
+
+  /** Build a single canopy sub-layer for one tree type. */
+  private _buildCanopyLayer(type: TreeType) {
+    const {
+      getPosition,
+      getElevation,
+      getHeight,
+      getTrunkHeightFraction,
+      getCanopyRadius,
+      getCanopyColor,
+      getSeason,
+      sizeScale
+    } = this.props; // eslint-disable-line max-len
+    const {grouped, pineMeshes} = this.state;
+
+    let mesh = CANOPY_MESHES[type];
+    if (type === 'pine') {
+      const firstLevel = Object.keys(pineMeshes)[0];
+      if (firstLevel) mesh = pineMeshes[Number(firstLevel)];
+    }
+
+    return new SimpleMeshLayer(
+      this.getSubLayerProps({
+        id: `canopy-${type}`,
+        data: grouped[type],
+        mesh,
+        getPosition: (d) => {
+          const pos = getPosition(d);
+          const elevation = getElevation(d) || 0;
+          const h = getHeight(d) * sizeScale;
+          const f = getTrunkHeightFraction(d);
+          return [pos[0], pos[1], elevation + h * f];
+        },
+        getScale: (d) => {
+          const h = getHeight(d) * sizeScale;
+          const f = getTrunkHeightFraction(d);
+          const r = getCanopyRadius(d) * sizeScale;
+          return [r, r, h * (1 - f)];
+        },
+        getColor: (d) => {
+          const explicit = getCanopyColor(d);
+          if (explicit) return explicit;
+          const season = getSeason(d) || 'summer';
+          return DEFAULT_CANOPY_COLORS[type][season];
+        },
+        pickable: this.props.pickable,
+        material: {ambient: 0.4, diffuse: 0.7, shininess: 12}
+      })
+    );
+  }
+
+  renderLayers() {
+    const {
+      getPosition,
+      getElevation,
+      getTreeType,
+      getHeight,
+      getTrunkHeightFraction,
+      getTrunkRadius,
+      getTrunkColor,
+      sizeScale
+    } = this.props;
+
+    const {grouped} = this.state;
+
+    // -----------------------------------------------------------------------
+    // 1. Trunk layer — one layer for ALL tree types, shared cylinder geometry
+    // -----------------------------------------------------------------------
+    const trunkLayer = new SimpleMeshLayer(
+      this.getSubLayerProps({
+        id: 'trunks',
+        data: this.props.data,
+        mesh: TRUNK_MESH,
+        getPosition: (d) => {
+          const pos = getPosition(d);
+          return [pos[0], pos[1], getElevation(d) || 0];
+        },
+        getScale: (d) => {
+          const h = getHeight(d) * sizeScale;
+          const f = getTrunkHeightFraction(d);
+          const r = getTrunkRadius(d) * sizeScale;
+          return [r, r, h * f];
+        },
+        getColor: (d) => {
+          const explicit = getTrunkColor(d);
+          if (explicit) return explicit;
+          const type = getTreeType(d) || 'pine';
+          return DEFAULT_TRUNK_COLORS[type] ?? DEFAULT_TRUNK_COLORS.pine;
+        },
+        pickable: this.props.pickable,
+        material: {ambient: 0.35, diffuse: 0.6, shininess: 8}
+      })
+    );
+
+    // -----------------------------------------------------------------------
+    // 2. Canopy layers — one per tree type, only for trees of that type
+    // -----------------------------------------------------------------------
+    const canopyLayers = ALL_TREE_TYPES.filter((type) => grouped[type].length > 0).map((type) =>
+      this._buildCanopyLayer(type)
+    );
+
+    return [trunkLayer, ...canopyLayers];
+  }
+}