s3m-three 0.4.22 → 0.4.24

package/src/render/S3MViewer.ts

@@ -25,8 +25,9 @@ import { S3MTileset, usableGeoBounds } from '../tileset/S3MTileset.js';
 import type { BuildTileFn, TileNode } from '../tileset/S3MTileset.js';
 import type { AuthenticateFn } from '../core/AuthFetch.js';
 import { setSplatViewport } from './GeometryBuilder.js';
-import { setMaxAnisotropy, setCompressedTexturesSupported, setTextureOffThreadDecode, setMaxTextureSize as setTextureSizeCap } from './TextureFactory.js';
-import { getMaterialQuality, normalizeMaterialQuality } from './StyleMaterial.js';
+import { setMaxAnisotropy, setCompressedTexturesSupported, setTextureOffThreadDecode, setMaxTextureSize as setTextureSizeCap, applyAnisotropyCap } from './TextureFactory.js';
+import type { TextureCreateOptions } from './TextureFactory.js';
+import { getMaterialQuality, normalizeMaterialQuality, getColorPipeline, normalizeColorPipeline } from './StyleMaterial.js';
 import type { LightingPreset } from './lightingPreset.js';
 import { LightRig } from './viewer/LightRig.js';
 import { HeightIndex } from './viewer/HeightIndex.js';
@@ -62,13 +63,37 @@ import type {
   EdgeModes,
   EdgesOption,
   MaterialQuality,
+  ColorPipeline,
 } from './StyleMaterial.js';
 import { applyPointCloudStyle, isOwnedPointCloudMaterial } from './PointCloudMaterial.js';
 import type { DegradationKind, UnsupportedPolicy } from '../core/degradations.js';
 import { Picker } from './Picker.js';
 import { GpuEdgePass } from './GpuEdgePass.js';
 import { Animator } from '../anim/Animator.js';
-import type { Channel, TransitionOptions } from '../anim/Animator.js';
+import {
+  buildClipPlanes,
+  lineOfSight as computeLineOfSight,
+  measureSegment,
+  polygonArea,
+  polygonAreaHorizontal,
+  polygonPerimeter,
+  polylineLength,
+  polylineLengthHorizontal,
+} from '../analysis/index.js';
+import type {
+  ClipOptions,
+  LineOfSightOptions,
+  LineOfSightResult,
+  LngLatAlt,
+  MeasureResult,
+  SkylineResult,
+  Vec3,
+  ViewshedResult,
+} from '../analysis/index.js';
+import { skylineFromDepth } from '../analysis/skyline.js';
+import { computeViewshed, makeCubeDistanceSampler } from '../analysis/viewshed.js';
+import { captureRadialCube, captureSkylineDepth } from './analysis/DepthPass.js';
+import type { DepthCaptureContext } from './analysis/DepthPass.js';import type { Channel, TransitionOptions } from '../anim/Animator.js';
 import { Path } from '../anim/Path.js';
 import type { EasingFn, EasingName } from '../anim/easing.js';
 import type { LineSharedUniforms, ThickLineMaterial } from './EdgeLines.js';
@@ -86,7 +111,7 @@ import type {
   StyleUniforms,
 } from '../core/types.js';
 
-import { lngLatFromWorld, type GeoAdapter } from './GeoAdapter.js';
+import { lngLatFromWorld, worldFromLngLat, type GeoAdapter } from './GeoAdapter.js';
 
 import {
   DatasetManager,
@@ -204,6 +229,18 @@ const STYLE_SCALAR_KEYS = [
   'outlineWidth',
 ] as const;
 
+/**
+ * 标量样式键在「用户还没设过」时的动画起点。
+ *
+ * 只对 `metalness` / `roughness` 有意义：它们的 uniform 默认是 -1（不覆盖，保持数据
+ * 自身的值），从 -1 插值没意义 —— 取数据侧常见值当起点，过渡才不会先跳到 0。
+ * 其余键缺省仍是 0（与旧行为一致）。
+ */
+const SCALAR_ANIM_START: Partial<Record<(typeof STYLE_SCALAR_KEYS)[number], number>> = {
+  metalness: 0, // S3M 数据的 metalness 恒为 0
+  roughness: 0.95, // shininess 映射后的常见值，见 GeometryBuilder 的 roughness
+};
+
 /** 能逐帧插值的颜色键（在线性空间插值，与 shader 消费端一致） */
 const STYLE_COLOR_KEYS = ['colorA', 'colorB', 'colorC', 'selectColor', 'edgeColor'] as const;
 
@@ -257,6 +294,19 @@ export class S3MViewer {
    * 传了值就只认自己，多图层同页各用各的，互不覆盖。
    */
   private _materialQuality: MaterialQuality | undefined;
+  /**
+   * 本图层的颜色管线。
+   *
+   * `undefined` = 没指定，跟随模块级默认（`getColorPipeline()`）。
+   * 与 materialQuality 同理：传了值就只认自己，同页多图层互不污染 —— 这条尤其重要，
+   * 因为 `lightingPreset: 'supermap'` 会同时改管线、纹理解码方式与各向异性，
+   * 以前是三个模块级全局一起被改写。
+   */
+  private _colorPipeline: ColorPipeline | undefined;
+  /** fade-through 编排的代次：中途再切一次，旧编排作废（与 setMode 同一套） */
+  private _pipelineGen = 0;
+  /** 当前裁剪配置；renderer 就绪前后都要能设，所以单独存一份（见 `_applyClipping`） */
+  private _clip: ClipOptions | null = null;
   /** 单体样式、专题着色与状态纹理管理器 */
   private readonly _featureStyleManager: FeatureStyleManager;
   /** GPU 路径动画管理器 */
@@ -395,7 +445,12 @@ export class S3MViewer {
     );
 
     this.uniforms = createSharedUniforms();
-    // 光源状态在这里就位：LightRig 构造时会按 lightingPreset 切模块级颜色管线，
+    // 图层 profile 先落位（显式传了就只认自己），再把 LightRig 挂上来 ——
+    // 它构造时会按 lightingPreset 覆盖一次管线，这一步走的是图层级通道，
+    // 不再去改模块级全局（以前三个全局一起被改写，同页多图层互相污染）。
+    this._colorPipeline = normalizeColorPipeline(options.colorPipeline);
+    this._applyRenderProfile({}, true);
+    // 光源状态在这里就位：LightRig 构造时会按 lightingPreset 切图层颜色管线，
     // 挂进场景要等 scene 建好（构造函数上面已经建了）。
     this._lights = new LightRig({
       scene: () => this.scene,
@@ -406,6 +461,8 @@ export class S3MViewer {
       // 走公共 triggerRepaint 而不是 _requestRepaint：宿主 / 单测会覆盖前者来观察重绘，
       // 绕过它会让「有没有触发重绘」这件事失去观测点
       repaint: () => this.triggerRepaint(),
+      // 构造期（initial）只记状态：那时还没有材质可重建、没有数据集可同步
+      applyRenderProfile: (p, initial) => this._applyRenderProfile(p, initial),
     });
     this._lights.addToScene();
     this._heights = new HeightIndex(this.uniforms);
@@ -534,6 +591,8 @@ export class S3MViewer {
     this.renderer = this._createRenderer(canvas, gl);
     setMaxAnisotropy(this.renderer.capabilities.getMaxAnisotropy(), this.options.anisotropyCap ?? Infinity);
     this._syncTextureCapabilities(gl);
+    // 裁剪是构造期就能设的（还没 mount 时 `_applyClipping` 会先跳过），这里补挂一次
+    this._applyClipping();
 
     this.scene = new THREE.Scene();
     this.scene.add(this.groundManager.group);
@@ -576,6 +635,8 @@ export class S3MViewer {
     this.renderer = this._createRenderer(this.canvas, gl);
     setMaxAnisotropy(this.renderer.capabilities.getMaxAnisotropy(), this.options.anisotropyCap ?? Infinity);
     this._syncTextureCapabilities(gl);
+    // 新 renderer 的 clippingPlanes 是空的，裁剪状态要重新挂上去
+    this._applyClipping();
     this.picker?.dispose();
     this.picker = new Picker(this.renderer);
     // GPU 描边的 RT / 材质绑定在旧上下文上，整体丢弃，下一帧按需重建
@@ -1855,7 +1916,13 @@ export class S3MViewer {
       this.animator.register(`style.${key}`, {
         dim: 1,
         read: (out) => {
-          out[0] = Number((this.style as unknown as Record<string, number>)[key] ?? 0);
+          // 金属度 / 粗糙度没设过时 uniform 是 -1（= 不覆盖，保持数据自身的值），
+          // 动画起点不能取 0：那会让 roughness 从 0.95 先跳到 0 再爬回去。
+          // 这里给的是数据侧的常见值（S3M 的 shininess 映射后 ≈0.95、metalness 恒 0），
+          // 过渡起点因此是连续的。
+          out[0] = Number(
+            (this.style as unknown as Record<string, number>)[key] ?? SCALAR_ANIM_START[key] ?? 0
+          );
         },
         write: (v) => {
           (this.style as unknown as Record<string, number>)[key] = v[0];
@@ -2115,6 +2182,112 @@ export class S3MViewer {
     return this._materialQuality ?? getMaterialQuality();
   }
 
+  /**
+   * 运行时切换**本图层**的颜色管线（`'linear'` | `'direct'`）。
+   *
+   * `'direct'` = 官方 iClient3D 的 sRGB 直乘管线（配合纹理解码关 sRGB），
+   * 见 `lightingPreset: 'supermap'`。切换牵扯三样东西：材质宏（换 program）、
+   * 纹理 colorSpace（重传，**不重新下载瓦片**）、以及各向异性档位。
+   *
+   * 给 `duration > 0` 时走 fade-through：压暗 → 在同一帧回调里换管线 → 亮回来。
+   * 逐像素混合做不到干净 —— 两条管线的差异有一部分在采样端（硬件 sRGB 解码 vs
+   * 原始字节），要混合就得让贴图恒为原始字节并在片元里手动解码，那会改掉默认路径。
+   */
+  setColorPipeline(q: ColorPipeline, opts: { duration?: number; dim?: number } = {}): Promise<void> {
+    const next = normalizeColorPipeline(q) ?? 'linear';
+    if (next === this.colorPipeline) return Promise.resolve();
+
+    const d = Math.max(0, opts.duration ?? 0);
+    if (d <= 0) {
+      this._applyRenderProfile({ colorPipeline: next });
+      return Promise.resolve();
+    }
+
+    const dim = Math.min(1, Math.max(0.05, opts.dim ?? 0.35));
+    const gen = ++this._pipelineGen;
+    return new Promise<void>((resolve) => {
+      this.animator.to('style.fade', dim, {
+        duration: d,
+        easing: 'easeInOutQuad',
+        onComplete: () => {
+          // 中途又切了一次：这次编排作废，收尾交给新的那次
+          if (gen !== this._pipelineGen) {
+            resolve();
+            return;
+          }
+          this._applyRenderProfile({ colorPipeline: next });
+          this.animator.to('style.fade', 1, {
+            duration: d,
+            easing: 'easeInOutQuad',
+            onComplete: resolve,
+          });
+        },
+      });
+    });
+  }
+
+  /** 当前颜色管线（本图层指定了就用本图层的，否则是模块级默认） */
+  get colorPipeline(): ColorPipeline {
+    return this._colorPipeline ?? getColorPipeline();
+  }
+
+  /** 本图层此刻该用的纹理创建参数（图层的渲染 profile 就落在这里） */
+  private _textureOptions(): TextureCreateOptions {
+    return {
+      // direct 管线的前提是贴图字节值不解码，两者必须一起切
+      srgbDecode: this.colorPipeline !== 'direct',
+      maxSize: this.options.maxTextureSize ?? Infinity,
+      anisotropyCap: this.options.anisotropyCap ?? Infinity,
+    };
+  }
+
+  /**
+   * 应用图层渲染 profile（颜色管线 / 各向异性上限）。
+   *
+   * `initial` = 构造期：只记状态并推给数据集管理器，不重建材质、不重传纹理
+   * （那时还没有瓦片）。
+   */
+  private _applyRenderProfile(
+    patch: { colorPipeline?: ColorPipeline; anisotropyCap?: number },
+    initial = false
+  ): void {
+    const prev = this.colorPipeline;
+    if (patch.colorPipeline !== undefined) {
+      this._colorPipeline = normalizeColorPipeline(patch.colorPipeline) ?? 'linear';
+    }
+    if (patch.anisotropyCap !== undefined) this.options.anisotropyCap = patch.anisotropyCap;
+
+    const textureOptions = this._textureOptions();
+    // 之后加载的瓦片按新参数走（已建好的数据集也要跟着换）
+    this._datasetManager.setRenderProfile({ colorPipeline: this.colorPipeline, textureOptions });
+    if (initial) return;
+
+    // 管线变了才需要换 program；只改各向异性时重建纯属浪费
+    if (this.colorPipeline !== prev) this._rebuildStyledMaterials();
+    this._syncCachedTextures(textureOptions);
+    this._requestRepaint();
+  }
+
+  /**
+   * 把纹理解码方式 / 各向异性同步到**已上传**的纹理上。
+   *
+   * 两者都不需要重新解码：`colorSpace` 改了 + `needsUpdate` 让 three 重传一次像素，
+   * `anisotropy` 同理。所以切管线不用重拉瓦片，代价只有一次纹理上传。
+   */
+  private _syncCachedTextures(opts: TextureCreateOptions): void {
+    const want = opts.srgbDecode ? THREE.SRGBColorSpace : THREE.NoColorSpace;
+    for (const entry of this.datasets.values()) {
+      const cache = entry.tileset?.textureCache;
+      if (!cache) continue;
+      for (const tex of cache.values()) {
+        if (tex.colorSpace === want) continue;
+        tex.colorSpace = want;
+        tex.needsUpdate = true;
+      }
+      applyAnisotropyCap(cache.values(), opts.anisotropyCap ?? Infinity);
+    }
+  }
+
   /** 按创建参数原位重建所有 styled 材质（materialQuality 切换用） */
   private _rebuildStyledMaterials(): void {
     // 逐材质 own uniform 的状态要在重建时搬过去，否则选中高亮 / 瓦片淡入会闪没
@@ -2134,9 +2307,14 @@ export class S3MViewer {
       const old = raw as StyledMaterial | undefined;
       if (!old?.userData?.isStyled || !old.userData?.s3mOpts) continue;
       const opts = old.userData.s3mOpts as StyledMaterialOptions;
-      // 显式传本层档位：s3mOpts 里记的是创建时的参数，可能是 undefined（跟随全局），
-      // 重建时必须钉成本层当前档位，否则「别处改了全局」会把这一层带跑。
-      const fresh = createStyledMaterial({ ...opts, uniforms: this.uniforms, materialQuality: this.materialQuality });
+      // 显式传本层档位与管线：s3mOpts 里记的是创建时的参数，可能是 undefined（跟随全局），
+      // 重建时必须钉成本层当前值，否则「别处改了全局」会把这一层带跑。
+      const fresh = createStyledMaterial({
+        ...opts,
+        uniforms: this.uniforms,
+        materialQuality: this.materialQuality,
+        colorPipeline: this.colorPipeline,
+      });
       for (const key of PRESERVED) {
         const src = old.userData[key] as { value: unknown } | undefined;
         const dst = fresh.userData[key] as { value: unknown } | undefined;
@@ -2297,6 +2475,208 @@ export class S3MViewer {
     return this._picks.getFeatureBounds(smid);
   }
 
+  /* -------------------------------------------------------------- 三维空间分析 */
+
+  /**
+   * 经纬度 + 高程 → 场景 ENU 米制坐标。
+   *
+   * 场景锚点可能还没就绪（没加数据集），此时按世界原点处理 —— 量算 API 会因此
+   * 给出「以原点为基准」的结果，但不会抛错。真实使用里锚点在 addDataset 之后必然存在。
+   */
+  private _sceneFromLngLat(p: LngLatAlt): Vec3 {
+    const anchor = this.sceneAnchor;
+    if (!anchor) return [0, 0, 0];
+    const s = anchor.meterInMercator;
+    const w = worldFromLngLat(this.geo, p.lng, p.lat, p.altitude);
+    // 注意 y 取反：three 的 y 向上，墨卡托 y 向下（与 PickService.pickPosition 互逆）
+    return [(w.x - anchor.x) / s, -(w.y - anchor.y) / s, p.altitude - (anchor.altitude ?? 0)];
+  }
+
+  /**
+   * 经纬度 + 绝对高程 → 场景 ENU 米制坐标。
+   *
+   * 外围要做「分析代理几何」（底图建筑挤出）、或者在 three 里画自定义标注时，
+   * 都得先把经纬度落到这个坐标系里 —— 场景的 ENU 原点在 `sceneAnchor`，
+   * 不是经纬度，所以必须走这个换算。
+   */
+  lngLatToPoint(p: LngLatAlt): Vec3 {
+    return this._sceneFromLngLat(p);
+  }
+
+  /** 场景 ENU 米制坐标 → 经纬度 + 绝对高程（`pointToLngLat` 的逆） */
+  pointToLngLat(v: Vec3): LngLatAlt {
+    return this._lngLatFromScene(v);
+  }
+
+  /** 场景 ENU 米制坐标 → 经纬度 + 绝对高程 */
+  private _lngLatFromScene(v: Vec3): LngLatAlt {
+    const anchor = this.sceneAnchor;
+    if (!anchor) return { lng: 0, lat: 0, altitude: v[2] };
+    const s = anchor.meterInMercator;
+    const [lng, lat] = lngLatFromWorld(this.geo, v[0] * s + anchor.x, -v[1] * s + anchor.y);
+    return { lng, lat, altitude: v[2] + (anchor.altitude ?? 0) };
+  }
+
+  /**
+   * 两点量算：三维距离 / 水平距离 / 高差。
+   *
+   * 输入是经纬度 + 绝对高程（`pickPosition` 的返回值直接能用），
+   * 内部换算到 ENU 米再算，所以不会受投影单位影响。
+   */
+  measureDistance(a: LngLatAlt, b: LngLatAlt): MeasureResult {
+    return measureSegment(this._sceneFromLngLat(a), this._sceneFromLngLat(b));
+  }
+
+  /** 折线长度（三维 + 水平投影两套口径） */
+  measurePolyline(points: readonly LngLatAlt[]): { length3D: number; lengthHorizontal: number } {
+    const scene = points.map((p) => this._sceneFromLngLat(p));
+    return { length3D: polylineLength(scene), lengthHorizontal: polylineLengthHorizontal(scene) };
+  }
+
+  /**
+   * 多边形量算：坡面真实面积 / 水平投影面积 / 周长。
+   *
+   * 建筑面积、用地面积按 `areaHorizontal` 算；坡面覆盖面积按 `area3D`。
+   */
+  measurePolygon(points: readonly LngLatAlt[]): {
+    area3D: number;
+    areaHorizontal: number;
+    perimeter: number;
+  } {
+    const scene = points.map((p) => this._sceneFromLngLat(p));
+    return {
+      area3D: polygonArea(scene),
+      areaHorizontal: polygonAreaHorizontal(scene),
+      perimeter: polygonPerimeter(scene),
+    };
+  }
+
+  /**
+   * 通视分析：两点之间是否被已加载的 S3M 几何挡住。
+   *
+   * 走 CPU 射线求交（`Raycaster` 打全部 pickable mesh），几十万面量级是几十毫秒，
+   * 适合点击式查询；要拖拽时逐帧刷新，得等深度图版本的批量采样。
+   *
+   * 注意范围：**只认 S3M 场景里的几何**。MapLibre 底图地形与 MVT 建筑不在这个场景里，
+   * 它们不参与遮挡（见 `docs/API.md` 的「分析范围」）。
+   */
+  lineOfSight(a: LngLatAlt, b: LngLatAlt, opts: LineOfSightOptions = {}): LineOfSightResult {
+    const from = this._sceneFromLngLat(a);
+    const to = this._sceneFromLngLat(b);
+    return computeLineOfSight(from, to, (origin, dir, maxDistance) => {
+      const hit = this._picks.raycastDistance(origin, dir, maxDistance);
+      if (!hit) return null;
+      return { distance: hit.distance, point: hit.point };
+    }, opts);
+  }
+
+  /**
+   * 裁剪 / 剖切（平面、Box、十字）。
+   *
+   * 平面列表挂在**本图层的 renderer** 上（每个 `S3MLayer` 一个 `WebGLRenderer`），
+   * 所以天然是图层级：同页别的图层不受影响。传 `null` 取消裁剪。
+   *
+   * 已知边界：只做「切掉」，不做**封口**——剖开后看到的是空壳/背面；
+   * 凹多边形裁剪需要多组半空间并集，three 的 `clippingPlanes` 表达不了（只能凸）。
+   */
+  setClipping(opt: ClipOptions | null): void {
+    this._clip = opt;
+    this._applyClipping();
+    this._requestRepaint();
+  }
+
+  /** 当前裁剪配置（`null` = 未裁剪） */
+  get clipping(): ClipOptions | null {
+    return this._clip;
+  }
+
+  private _applyClipping(): void {
+    const r = this.renderer;
+    if (!r) return; // mount 前先记着，`_createRenderer` 之后会补一次
+    if (!this._clip) {
+      r.clippingPlanes = [];
+      return;
+    }
+    r.clippingPlanes = buildClipPlanes(this._clip).map(
+      (p) => new THREE.Plane(new THREE.Vector3(p.normal[0], p.normal[1], p.normal[2]), p.constant)
+    );
+  }
+
+  /** 分析用的离屏采集上下文（renderer / scene / camera 都可能在 mount 前为空） */
+  private _depthCtx(): DepthCaptureContext {
+    return {
+      renderer: () => this.renderer,
+      scene: () => this.scene,
+      camera: () => this.camera,
+    };
+  }
+
+  /**
+   * 天际线分析：用当前视角渲染一张深度图，按列抽出「方位角 → 仰角」曲线。
+   *
+   * 一次调用 = 一趟额外渲染 + 一次全图回读，**不要每帧调**。
+   * 典型用法是相机停下来（`moveend`）后算一次。
+   *
+   * @param opts.width 采集分辨率（默认 640）。精度由它决定：
+   *   640 宽 ≈ 0.56°/列，1280 宽 ≈ 0.28°/列。
+   */
+  skyline(opts: {
+    width?: number;
+    height?: number;
+    step?: number;
+    /** 额外参与遮挡的代理几何（底图建筑 / 地形网格），只在这一趟深度渲染里存在 */
+    include?: readonly THREE.Object3D[];
+  } = {}): SkylineResult | null {
+    const cap = captureSkylineDepth(
+      this._depthCtx(),
+      opts.width ?? 640,
+      opts.height ?? 360,
+      opts.include
+    );
+    if (!cap) return null;
+    return skylineFromDepth({
+      rgba: cap.rgba,
+      width: cap.width,
+      height: cap.height,
+      inverseViewProj: cap.inverseViewProj,
+      cameraPos: cap.cameraPos,
+      step: opts.step,
+    });
+  }
+
+  /**
+   * 360° 可视域（地面栅格版）：从观察点朝 6 个方向各渲染一次深度，
+   * 再在 CPU 上对地面网格逐格判定可见性。
+   *
+   * 一次调用 = 6 趟额外渲染 + 6 次回读，成本明显高于天际线，
+   * 只在点击/松手时算。返回的 `raster` 可以直接当贴图画在地面上。
+   */
+  viewshed(opts: {
+    /** 观察点（经纬度 + 地面高程；眼高由 `eyeHeight` 另加） */
+    origin: LngLatAlt;
+    /** 分析半径（米） */
+    radius: number;
+    /** 栅格边长（默认 96） */
+    grid?: number;
+    /** 眼高（米，默认 1.7） */
+    eyeHeight?: number;
+    /** 立方体深度图分辨率（默认 128；越大边缘越准，回读越慢） */
+    size?: number;
+    /** 额外参与遮挡的代理几何（底图建筑 / 地形网格），只在这一趟深度渲染里存在 */
+    include?: readonly THREE.Object3D[];
+  }): ViewshedResult | null {
+    const eye = opts.eyeHeight ?? 1.7;
+    const origin = this._sceneFromLngLat({ ...opts.origin, altitude: opts.origin.altitude + eye });
+    const size = opts.size ?? 128;
+    const faces = captureRadialCube(this._depthCtx(), origin, size, opts.radius, opts.include);
+    if (!faces) return null;
+    return computeViewshed(origin, makeCubeDistanceSampler(faces, size, opts.radius), {
+      radius: opts.radius,
+      grid: opts.grid,
+      groundZ: 0,
+    });
+  }
+
   /** @internal 见 viewer/PickService.ts */
   _intersectMeshAtRay(mesh: THREE.Mesh, ray: THREE.Ray, instanceIndex?: number): THREE.Vector3 | null {
     return this._picks.intersectMeshAtRay(mesh, ray, instanceIndex);
@@ -2508,16 +2888,19 @@ export class S3MViewer {
   }
 
   /**
-   * 调整各向异性过滤上限（默认 Infinity = 取 GPU 最大值）。
-   * 只影响**之后创建**的纹理——已上传的纹理需要重新上传才会变，代价远大于收益，
-   * 所以切换档位请在建图层前决定，或接受「新瓦片按新档位、旧瓦片保持原样」。
+   * 调整本图层的各向异性过滤上限（默认 Infinity = 取 GPU 最大值）。
+   *
+   * 与 0.4.22 之前不同：已上传的纹理**会立刻跟着变**（改 sampling 参数 + 重传，
+   * 不需要重新解码，也不需要重载瓦片），所以切 `lightingPreset: 'supermap'` 时
+   * 立面清晰度是当场变的，不再等新瓦片。
    */
   setAnisotropyCap(cap: number): void {
     const next = Number.isFinite(cap) && cap > 0 ? Math.max(1, cap) : Infinity;
     this.options.anisotropyCap = next;
+    // 同步模块级默认：直接调 createTexture / buildTileObjects 的老用法仍读它
     const gpuMax = this.renderer?.capabilities.getMaxAnisotropy?.() ?? 1;
     setMaxAnisotropy(gpuMax, next);
-    this._requestRepaint();
+    this._applyRenderProfile({ anisotropyCap: next });
   }
 
   /** 当前纹理长边像素上限。Infinity = 不限制 */
@@ -2528,12 +2911,16 @@ export class S3MViewer {
   /**
    * 调整纹理长边像素上限（默认 Infinity = 不限制）。
    * 只影响之后解码的纹理；非图集的 RGBA / WebP 产物按 2× 减半逼近上限。
-   * 注意这是**模块级**设置（图集 / 解码 Worker 共享），多 viewer 实例会互相覆盖。
+   *
+   * 图层级：只改本层，同页其它图层不受影响（同时同步模块级默认，照顾直接调
+   * `createTexture` 的老用法）。已解码的纹理不会重解 —— 那是另一件事。
    */
   setMaxTextureSize(n: number): void {
     const next = Number.isFinite(n) && n >= 1 ? n : Infinity;
     this.options.maxTextureSize = next;
     setTextureSizeCap(next);
+    // 只推给数据集，不动材质也不重传纹理（尺寸上限只影响「之后解码」的纹理）
+    this._datasetManager.setRenderProfile({ textureOptions: this._textureOptions() });
     this._requestRepaint();
   }
 

package/src/render/StyleMaterial.ts

@@ -317,7 +317,9 @@ export function getMaterialQuality(): MaterialQuality {
  *   （0.8·NdotL + 0.7）、输出前抵消 renderer 的 OETF。与 `setSrgbTextureDecode(false)`
  *   配套使用，`lightingPreset: 'supermap'` 会同时打开两者。
  *
- * 与 materialQuality 同一套全局约定：只影响之后创建的材质，已加载瓦片要重载才换。
+ * 与 materialQuality 同一套约定：这里只是**模块级默认值**，不是全局开关 ——
+ * 图层显式传了 `colorPipeline` 就只认自己，没传才读这里。只影响之后创建的材质，
+ * 已加载瓦片要重载或在图层上调 `setColorPipeline` 才会换。
  */
 export type ColorPipeline = 'linear' | 'direct';
 let colorPipeline: ColorPipeline = 'linear';
@@ -330,6 +332,13 @@ export function getColorPipeline(): ColorPipeline {
   return colorPipeline;
 }
 
+/** 归一颜色管线：只认 'linear' / 'direct'，其余返回 undefined（= 去读模块级默认） */
+export function normalizeColorPipeline(p: unknown): ColorPipeline | undefined {
+  if (p === 'direct') return 'direct';
+  if (p === 'linear') return 'linear';
+  return undefined;
+}
+
 export type StyledMaterial = (THREE.MeshStandardMaterial | THREE.MeshLambertMaterial) & {
   userData: {
     uSelBatch: { value: number };
@@ -1128,6 +1137,11 @@ export interface StyledMaterialOptions {
    * 一路透传到这里，不再让所有图层共享同一份模块级状态。
    */
   materialQuality?: MaterialQuality;
+  /**
+   * 颜色管线。不传 = 读模块级默认（`getColorPipeline()`），行为与旧版一致。
+   * 与 `materialQuality` 同一套：图层把自己的 profile 透传进来，同页互不污染。
+   */
+  colorPipeline?: ColorPipeline;
 }
 
 /**
@@ -1230,7 +1244,7 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
   if (texCoordZ) mat.defines = { ...(mat.defines as Record<string, string>), S3M_TEXCOORD_Z: '' };
   if (secMap) mat.defines = { ...mat.defines, S3M_ATLAS_SEC: '' };
   // supermap 完整版：官方 sRGB 直乘管线（配合 setSrgbTextureDecode(false)）
-  const direct = colorPipeline === 'direct';
+  const direct = (opts.colorPipeline ?? colorPipeline) === 'direct';
   if (direct) mat.defines = { ...mat.defines, S3M_DIRECT_COLOR: '' };
   // 官方 uTextureDim = (base宽, base高, bake宽, bake高)，取实际绑定纹理的像素尺寸
   const uAtlasDim = { value: new THREE.Vector2(opts.map?.image?.width || 1, opts.map?.image?.height || 1) };