s3m-three 0.4.19 → 0.4.21

package/src/render/viewer/HeightIndex.ts

@@ -0,0 +1,94 @@
+/**
+ * 世界高度范围的增量维护。
+ *
+ * 原来每注册一块瓦片都要把所有网格重新遍历一遍、每个都 clone 一个 Box3 再乘矩阵，
+ * 加载 n 块瓦片就是 O(n²) 次矩阵乘 + n² 个垃圾对象。现在只在网格进出的记一次，
+ * 全局值从缓存里滚：只有被移除的那块正好卡在边界上时，才回退到一次 O(n) 重算。
+ *
+ * 结果写进共享 uniform `uHeightMin` / `uHeightMax`，供着色器做高度渐变 / 拔高。
+ */
+import * as THREE from 'three';
+import type { StyleUniforms } from '../../core/types.js';
+
+export class HeightIndex {
+  /** 每块网格的世界高度范围 */
+  private readonly _meshHeight = new Map<THREE.Mesh, { min: number; max: number }>();
+  private _min = Infinity;
+  private _max = -Infinity;
+  /** 换算世界包围盒用的临时对象，避免每次 new */
+  private readonly _box = new THREE.Box3();
+
+  constructor(private readonly uniforms: StyleUniforms) {}
+
+  get size(): number {
+    return this._meshHeight.size;
+  }
+
+  add(mesh: THREE.Mesh): void {
+    const bb = mesh.geometry?.boundingBox;
+    if (!bb) return;
+    this._box.copy(bb).applyMatrix4(mesh.matrixWorld);
+    const min = this._box.min.z;
+    const max = this._box.max.z;
+    if (!Number.isFinite(min) || !Number.isFinite(max)) return;
+    this._meshHeight.set(mesh, { min, max });
+    if (min < this._min) this._min = min;
+    if (max > this._max) this._max = max;
+    this._push();
+  }
+
+  remove(mesh: THREE.Mesh): void {
+    const rec = this._meshHeight.get(mesh);
+    if (!rec) return;
+    this._meshHeight.delete(mesh);
+    // 只有正好卡在边界上才需要重算，否则滚动的 min/max 依然成立
+    if (rec.min === this._min || rec.max === this._max) this._recompute();
+    else this._push();
+  }
+
+  /** 数据集整体位移（换高程偏移 / 重新布局）后，缓存的世界高度全部失效 */
+  refreshAll(): void {
+    if (this._meshHeight.size === 0) return;
+    const meshes = [...this._meshHeight.keys()];
+    this._meshHeight.clear();
+    this._min = Infinity;
+    this._max = -Infinity;
+    for (const mesh of meshes) this.add(mesh);
+    this._push();
+  }
+
+  /** 场景清空时重置 */
+  clear(): void {
+    this._meshHeight.clear();
+    this._min = Infinity;
+    this._max = -Infinity;
+  }
+
+  /** 当前高度范围（未初始化时是 Infinity / -Infinity，调用方自己兜底） */
+  get range(): { min: number; max: number } {
+    return { min: this._min, max: this._max };
+  }
+
+  private _recompute(): void {
+    let min = Infinity;
+    let max = -Infinity;
+    for (const h of this._meshHeight.values()) {
+      if (h.min < min) min = h.min;
+      if (h.max > max) max = h.max;
+    }
+    this._min = min;
+    this._max = max;
+    this._push();
+  }
+
+  private _push(): void {
+    let min = this._min;
+    let max = this._max;
+    if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min) {
+      min = 0;
+      max = 100;
+    }
+    this.uniforms.uHeightMin.value = min;
+    this.uniforms.uHeightMax.value = max;
+  }
+}

package/src/render/viewer/LightRig.ts

@@ -0,0 +1,267 @@
+/**
+ * 光照与色调映射：四个光源 + 光照预设 + 环境贴图。
+ *
+ * 从 `S3MViewer` 里整体搬出来的第一块 —— 它只依赖 `scene` / `renderer` / 共享
+ * uniform / 宿主方位角，不碰几何、瓦片、拾取，是耦合最低的一块。
+ *
+ * ## 两个模块级全局态
+ *
+ * `setColorPipeline` / `setSrgbTextureDecode` / `setAnisotropyCap` 都是模块级设置，
+ * 影响**之后创建**的材质与纹理。所以切预设时已加载的瓦片要重载才换观感，
+ * 这是已知的架构债（一个页面两个 viewer 用不同预设会互相污染），
+ * 拆分没有改变这一点。
+ */
+import * as THREE from 'three';
+import { resolveLightingPreset, type LightingPreset } from '../lightingPreset.js';
+import { setColorPipeline } from '../StyleMaterial.js';
+import { setAnisotropyCap, setSrgbTextureDecode } from '../TextureFactory.js';
+import type { LightOptions, S3MViewerOptions } from '../S3MViewer.js';
+import type { StyleUniforms } from '../../core/types.js';
+
+/** 四个光源的强度 / 颜色 / 朝向。`mainIntensity` / `mainColor` 是 keyLight 的别名 */
+type LightState = Required<Omit<LightOptions, 'mainIntensity' | 'mainColor'>>;
+
+const DEFAULT_LIGHT: LightState = {
+  ambientIntensity: 0.4,
+  ambientColor: 0xffffff,
+  hemisphereIntensity: 0.8,
+  hemisphereColor: 0xffffff,
+  hemisphereGroundColor: 0xb6c0cb,
+  keyLightIntensity: 1.0,
+  keyLightColor: 0xffffff,
+  fillLightIntensity: 0.35,
+  fillLightColor: 0xffffff,
+  mode: 'headlamp',
+  azimuth: 150,
+  altitude: 50,
+};
+
+/**
+ * 宿主侧依赖。全部用取值函数而不是对象引用 —— 宿主可能在 mount 之前构造 viewer，
+ * 而 `scene` / `renderer` 在 mount 时才存在，存快照会拿到 null。
+ */
+export interface LightRigContext {
+  scene: () => THREE.Scene | null;
+  renderer: () => THREE.WebGLRenderer | null;
+  uniforms: StyleUniforms;
+  options: S3MViewerOptions;
+  /** 地图方位角（度），让主光跟着视角走；纯 three 宿主可以不传 */
+  getBearing?: () => number | undefined;
+  /** 宿主需要重画的信号 */
+  repaint: () => void;
+}
+
+export class LightRig {
+  ambient: THREE.AmbientLight | null = null;
+  hemi: THREE.HemisphereLight | null = null;
+  key: THREE.DirectionalLight | null = null;
+  fill: THREE.DirectionalLight | null = null;
+
+  private readonly _state: LightState;
+  /** 环境贴图的 PMREM 渲染目标（setEnvironment 建的，dispose 时释放） */
+  private _envRT: THREE.WebGLRenderTarget | null = null;
+
+  /** @internal 环境贴图 RT，供单测观察「有没有释放旧的」 */
+  get envRT(): THREE.WebGLRenderTarget | null {
+    return this._envRT;
+  }
+  set envRT(v: THREE.WebGLRenderTarget | null) {
+    this._envRT = v;
+  }
+
+  constructor(private readonly ctx: LightRigContext) {
+    this._state = { ...DEFAULT_LIGHT };
+    const options = ctx.options;
+    if (options.lightingPreset && options.lightingPreset !== 'default') {
+      Object.assign(this._state, resolveLightingPreset(options.lightingPreset));
+      this.applyColorPipeline(options.lightingPreset);
+    }
+    if (options.light) Object.assign(this._state, options.light);
+  }
+
+  /* ---------------------------------------------------------------- 场景挂载 */
+
+  private _create(): void {
+    this.ambient = new THREE.AmbientLight(this._state.ambientColor as THREE.ColorRepresentation, this._state.ambientIntensity);
+    this.hemi = new THREE.HemisphereLight(
+      this._state.hemisphereColor as THREE.ColorRepresentation,
+      this._state.hemisphereGroundColor as THREE.ColorRepresentation,
+      this._state.hemisphereIntensity
+    );
+    this.key = new THREE.DirectionalLight(this._state.keyLightColor as THREE.ColorRepresentation, this._state.keyLightIntensity);
+    this.fill = new THREE.DirectionalLight(this._state.fillLightColor as THREE.ColorRepresentation, this._state.fillLightIntensity);
+    this.update();
+  }
+
+  /** 把四个光源挂进场景；重复调用是幂等的 */
+  addToScene(): void {
+    const scene = this.ctx.scene();
+    if (!scene) return;
+    if (!this.ambient) this._create();
+    scene.add(this.ambient!, this.hemi!, this.key!, this.fill!);
+  }
+
+  /** 光源实例是否已建（构造后、mount 前是 false） */
+  get created(): boolean {
+    return this.ambient !== null;
+  }
+
+  /* ---------------------------------------------------------------- 参数 */
+
+  private _applyOptions(): void {
+    const s = this._state;
+    if (this.ambient) {
+      this.ambient.intensity = s.ambientIntensity;
+      this.ambient.color.set(s.ambientColor as THREE.ColorRepresentation);
+    }
+    if (this.hemi) {
+      this.hemi.intensity = s.hemisphereIntensity;
+      this.hemi.color.set(s.hemisphereColor as THREE.ColorRepresentation);
+      this.hemi.groundColor.set(s.hemisphereGroundColor as THREE.ColorRepresentation);
+    }
+    if (this.key) {
+      this.key.intensity = s.keyLightIntensity;
+      this.key.color.set(s.keyLightColor as THREE.ColorRepresentation);
+    }
+    if (this.fill) {
+      this.fill.intensity = s.fillLightIntensity;
+      this.fill.color.set(s.fillLightColor as THREE.ColorRepresentation);
+    }
+  }
+
+  /**
+   * 更新光照位置与方向：
+   * - `'headlamp'`：随地图方位角 bearing 旋转，主光始终在镜头上方，受光面面向镜头；
+   * - `'fixed'`：固定世界方位角（如模拟恒定日光）。
+   */
+  update(): void {
+    if (!this.key || !this.fill) return;
+    const s = this._state;
+    const bearing = s.mode === 'fixed' ? 0 : ((this.ctx.getBearing?.() ?? 0) * Math.PI) / 180;
+    const place = (light: THREE.DirectionalLight | null, azOffsetDeg: number, elevDeg: number): void => {
+      if (!light) return;
+      const az = bearing + (azOffsetDeg * Math.PI) / 180;
+      const el = (elevDeg * Math.PI) / 180;
+      const c = Math.cos(el);
+      light.position.set(Math.sin(az) * c, Math.cos(az) * c, Math.sin(el)).multiplyScalar(1000);
+    };
+    place(this.key, s.azimuth, s.altitude);
+    place(this.fill, s.azimuth + 65, Math.max(10, s.altitude - 20));
+    // direct 管线的官方 Lambert 用主光方向（共享 uniform，所有材质同步生效）
+    const sun = this.ctx.uniforms?.uSunDirection;
+    if (sun) (sun.value as THREE.Vector3).copy(this.key.position).normalize();
+  }
+
+  /**
+   * supermap 完整版 = 光照强度 + 颜色管线一起切：
+   * direct 管线下纹理不做 sRGB 解码、片元按官方常数 Lambert 直乘（见 lightingPreset.ts）。
+   * 两个都是模块级全局态，只影响之后创建的材质 / 纹理 —— 已加载瓦片要重载才换。
+   */
+  applyColorPipeline(preset: LightingPreset): void {
+    const direct = preset === 'supermap';
+    setColorPipeline(direct ? 'direct' : 'linear');
+    setSrgbTextureDecode(!direct);
+    // 官方不开各向异性：远处直接采高 mip 平均成纯色（"灰色滤镜"的一部分）。
+    // 我们默认 Infinity（倾斜摄影立面清晰度优先），supermap 模式必须收回。
+    setAnisotropyCap(direct ? 1 : Infinity);
+  }
+
+  setLightingPreset(preset: LightingPreset): void {
+    Object.assign(this._state, resolveLightingPreset(preset));
+    this.applyColorPipeline(preset);
+    this.ctx.options.lightingPreset = preset;
+    this._applyOptions();
+    this.update();
+    this.ctx.repaint();
+  }
+
+  setLight(options: Partial<LightOptions>): void {
+    const normalized: Partial<LightOptions> = { ...options };
+    if (normalized.mainColor !== undefined && normalized.keyLightColor === undefined) {
+      normalized.keyLightColor = normalized.mainColor;
+    }
+    if (normalized.mainIntensity !== undefined && normalized.keyLightIntensity === undefined) {
+      normalized.keyLightIntensity = normalized.mainIntensity;
+    }
+    Object.assign(this._state, normalized);
+    this._applyOptions();
+    this.update();
+    this.ctx.repaint();
+  }
+
+  getLight(): LightOptions {
+    return { ...this._state };
+  }
+
+  setToneMapping(toneMapping: THREE.ToneMapping, exposure = 1.0): void {
+    this.ctx.options.toneMapping = toneMapping;
+    this.ctx.options.toneMappingExposure = exposure;
+    const r = this.ctx.renderer();
+    if (r) {
+      r.toneMapping = toneMapping;
+      r.toneMappingExposure = exposure;
+        this.ctx.repaint();
+    }
+  }
+
+  getToneMapping(): { toneMapping: THREE.ToneMapping; toneMappingExposure: number } {
+    const r = this.ctx.renderer();
+    return {
+      toneMapping: r ? r.toneMapping : (this.ctx.options.toneMapping ?? THREE.NoToneMapping),
+      toneMappingExposure: r ? r.toneMappingExposure : (this.ctx.options.toneMappingExposure ?? 1.0),
+    };
+  }
+
+  /* ---------------------------------------------------------------- 环境贴图 */
+
+  /**
+   * 挂 / 摘环境贴图。
+   *
+   * 金属度（`setStyle({ metalness })`）**必须**有环境图才看得出质感：
+   * PBR 的金属几乎没有漫反射，画面全靠 `scene.environment` 里的环境反射，
+   * 没有它时 metalness 一高就整片发黑，只剩两盏平行灯打成的小高光点。
+   *
+   * @param source 等距柱状图（.hdr / .jpg / .png，2:1）地址，或已加载的 `THREE.Texture`；
+   *               `null` = 关掉环境图
+   * @param intensity 环境光强度（`scene.environmentIntensity`，默认 1）
+   *
+   * 传入 URL 时纹理由内部加载并转成 PMREM（预滤波 mipmap）；传 Texture 时不会接管它的生命周期。
+   */
+  async setEnvironment(source: string | THREE.Texture | null, intensity = 1): Promise<void> {
+    const renderer = this.ctx.renderer();
+    const scene = this.ctx.scene();
+    if (!renderer || !scene) return;
+    scene.environmentIntensity = Math.max(0, intensity);
+
+    if (source == null) {
+      scene.environment = null;
+      this._envRT?.dispose();
+      this._envRT = null;
+      this.ctx.repaint();
+      return;
+    }
+
+    const fromUrl = typeof source === 'string';
+    const tex = fromUrl ? await new THREE.TextureLoader().loadAsync(source) : source;
+    // PMREM 只认等距柱状图；普通贴图也按 2:1 全景处理
+    tex.mapping = THREE.EquirectangularReflectionMapping;
+
+    const pmrem = new THREE.PMREMGenerator(renderer);
+    pmrem.compileEquirectangularShader();
+    const rt = pmrem.fromEquirectangular(tex);
+    pmrem.dispose();
+    if (fromUrl) tex.dispose();
+
+    scene.environment = rt.texture;
+    // 上一张（同一个 viewer 反复换）要释放，否则显存里会一直堆
+    this._envRT?.dispose();
+    this._envRT = rt;
+    this.ctx.repaint();
+  }
+
+  /** 释放环境贴图与光源（unmount 时调） */
+  dispose(): void {
+    this._envRT?.dispose();
+    this._envRT = null;
+  }
+}