s3m-three 0.4.21 → 0.4.23

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, setMaterialQuality } 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,6 +63,7 @@ import type {
   EdgeModes,
   EdgesOption,
   MaterialQuality,
+  ColorPipeline,
 } from './StyleMaterial.js';
 import { applyPointCloudStyle, isOwnedPointCloudMaterial } from './PointCloudMaterial.js';
 import type { DegradationKind, UnsupportedPolicy } from '../core/degradations.js';
@@ -204,6 +206,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;
 
@@ -249,6 +263,25 @@ export class S3MViewer {
   readonly groundManager: GroundManager;
   /** 多数据集生命周期与锚点管理器 */
   private readonly _datasetManager = new DatasetManager();
+  /**
+   * 本图层的光照模型档位。
+   *
+   * `undefined` = 没指定，跟随模块级默认（`getMaterialQuality()`）—— 老代码
+   * `setMaterialQuality('lambert')` 一行改全场的用法靠这条继续有效。
+   * 传了值就只认自己，多图层同页各用各的，互不覆盖。
+   */
+  private _materialQuality: MaterialQuality | undefined;
+  /**
+   * 本图层的颜色管线。
+   *
+   * `undefined` = 没指定，跟随模块级默认（`getColorPipeline()`）。
+   * 与 materialQuality 同理：传了值就只认自己，同页多图层互不污染 —— 这条尤其重要，
+   * 因为 `lightingPreset: 'supermap'` 会同时改管线、纹理解码方式与各向异性，
+   * 以前是三个模块级全局一起被改写。
+   */
+  private _colorPipeline: ColorPipeline | undefined;
+  /** fade-through 编排的代次：中途再切一次，旧编排作废（与 setMode 同一套） */
+  private _pipelineGen = 0;
   /** 单体样式、专题着色与状态纹理管理器 */
   private readonly _featureStyleManager: FeatureStyleManager;
   /** GPU 路径动画管理器 */
@@ -352,7 +385,11 @@ export class S3MViewer {
     this._unsupported = options.unsupported ?? 'warn';
     this._lodPixelRatioCap = options.lodPixelRatioCap ?? Infinity;
     setTextureSizeCap(options.maxTextureSize ?? Infinity);
-    setMaterialQuality(options.materialQuality ?? 'pbr');
+    // 只记本层的档位，**不写模块级全局**：以前这里 setMaterialQuality(...) 会把全局
+    // 改掉，于是同页后创建的图层顺手把先创建的图层也打回去了（多层互相覆盖的根因）。
+    this._materialQuality = normalizeMaterialQuality(options.materialQuality);
+    // 之后 addDataset 的数据集按这个默认建材质（数据集自己指定则用自己的）
+    this._datasetManager.defaultMaterialQuality = this._materialQuality;
     if (options.totalMaxTiles) {
       this._datasetManager.totalMaxTiles = options.totalMaxTiles;
     }
@@ -383,7 +420,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,
@@ -394,6 +436,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);
@@ -1843,7 +1887,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];
@@ -2082,22 +2132,131 @@ export class S3MViewer {
   }
 
   /**
-   * 运行时切换材质质感（`'pbr'` | `'lambert'`）。
+   * 运行时切换**本图层**的材质质感（`'pbr'` | `'lambert'`）。
    *
-   * 档位是模块级设置（影响之后新建的材质）；已加载瓦片的材质在这里**原位重建**：
-   * 不重拉瓦片、不重建几何，按创建时记录的参数（`userData.s3mOpts`）换一个
-   * 新材质实例，并保留逐材质状态（选中编号、瓦片淡入、批量状态纹理）。
-   * 切换后 program 需要重新编译一次（lambert / pbr 是不同着色器），这是唯一开销。
+   * 档位是图层级的：只改这一层，同页其它图层不受影响（也不会去动模块级默认）。
+   * 已加载瓦片的材质在这里**原位重建**：不重拉瓦片、不重建几何，按创建时记录的
+   * 参数（`userData.s3mOpts`）换一个新材质实例，并保留逐材质状态（选中编号、
+   * 瓦片淡入、批量状态纹理）。切换后 program 需要重新编译一次（lambert / pbr 是
+   * 不同着色器），这是唯一开销。
    */
   setMaterialQuality(q: MaterialQuality): void {
-    setMaterialQuality(q);
+    this._materialQuality = normalizeMaterialQuality(q) ?? 'pbr';
+    // 已建好的数据集也要跟着换，否则之后新加载的瓦片还是旧档位（和重建结果打架）
+    this._datasetManager.setDefaultMaterialQuality(this._materialQuality);
     this._rebuildStyledMaterials();
     this._requestRepaint();
   }
 
-  /** 当前材质质感档位 */
+  /** 当前材质质感档位（本图层指定了就用本图层的，否则是模块级默认） */
   get materialQuality(): MaterialQuality {
-    return getMaterialQuality();
+    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 切换用） */
@@ -2119,7 +2278,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;
-      const fresh = createStyledMaterial({ ...opts, uniforms: this.uniforms });
+      // 显式传本层档位与管线：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;
@@ -2491,16 +2657,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 = 不限制 */
@@ -2511,12 +2680,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

@@ -272,13 +272,29 @@ export const DEFAULT_STYLE: S3MStyle = {
 export type MaterialQuality = 'pbr' | 'lambert';
 
 /**
- * 当前光照模型。模块级全局 —— 与 anisotropy / maxTextureSize 同一套设计，
- * 同页多个图层会互相覆盖，后创建的那个决定全局。只影响**之后创建**的材质。
+ * 模块级默认档位。**只是默认值**，不是全局开关：
+ * - `S3MViewer` / `S3MLayer` 构造时传了 `materialQuality` 的，只定自己那一层，
+ *   不读也不写这里（多图层同页互不干扰）；
+ * - 没传的图层、以及直接调 `createStyledMaterial` / `buildTileObjects` 的场景，
+ *   仍然读这里 —— 老代码 `setMaterialQuality('lambert')` 一行改全场的用法照旧有效。
+ *
+ * 只影响**之后创建**的材质；已加载的瓦片要重载或在 viewer 上调
+ * `setMaterialQuality` 才会换。
  */
 let materialQuality: MaterialQuality = 'pbr';
 
 /**
- * 切换光照模型。
+ * 归一档位：只认 'pbr' / 'lambert'，其余（含 undefined）返回 undefined，
+ * 表示「没指定，去读模块级默认」。
+ */
+export function normalizeMaterialQuality(q: unknown): MaterialQuality | undefined {
+  if (q === 'lambert') return 'lambert';
+  if (q === 'pbr') return 'pbr';
+  return undefined;
+}
+
+/**
+ * 设置模块级默认档位（不是全局开关，见上面的 `materialQuality` 注释）。
  *
  * 'pbr'（默认）= `MeshStandardMaterial`，GGX + 环境球谐，质感最好也最贵。
  * 'lambert' = `MeshLambertMaterial`，只保留漫反射 + 平行光，片元开销约省一半；
@@ -301,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';
@@ -314,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 };
@@ -1105,6 +1130,18 @@ export interface StyledMaterialOptions {
   texCoordZ?: boolean;
   /** 图集材质的第二套纹理（官方 BakeTex，光照烘焙），与 base 相乘 */
   secMap?: THREE.Texture | null;
+  /**
+   * 光照模型档位。不传 = 读模块级默认（`getMaterialQuality()`），行为与旧版一致。
+   *
+   * 传了就按传的建 —— 图层级隔离靠这条：`S3MLayer` / `S3MViewer` 把自己的档位
+   * 一路透传到这里，不再让所有图层共享同一份模块级状态。
+   */
+  materialQuality?: MaterialQuality;
+  /**
+   * 颜色管线。不传 = 读模块级默认（`getColorPipeline()`），行为与旧版一致。
+   * 与 `materialQuality` 同一套：图层把自己的 profile 透传进来，同页互不污染。
+   */
+  colorPipeline?: ColorPipeline;
 }
 
 /**
@@ -1152,6 +1189,9 @@ const FRAG_SURFACE = /* glsl */ `
 
 export function createStyledMaterial(opts: StyledMaterialOptions): StyledMaterial {
   const uniforms = opts.uniforms;
+  // 档位解析：显式传参 > 模块级默认。图层级隔离就靠这一行 —— 各图层把自己的
+  // 档位透传进来，不再共享同一份模块级状态。
+  const quality: MaterialQuality = normalizeMaterialQuality(opts.materialQuality) ?? getMaterialQuality();
   // 两种光照模型共用的参数。注入的 chunk 只动 diffuseColor / normal / transformed，
   // 在 Standard 与 Lambert 的 shader 里都存在同名 include，所以模板不用分支。
   const baseParams = {
@@ -1170,7 +1210,7 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
     alphaTest: opts.alphaTest ?? 0,
   };
   const mat = (
-    materialQuality === 'lambert'
+    quality === 'lambert'
       ? new THREE.MeshLambertMaterial(baseParams)
       : new THREE.MeshStandardMaterial({
           ...baseParams,
@@ -1204,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) };
@@ -1311,6 +1351,8 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
   mat.userData.uFlatShading = uFlatShading;
   // 记录创建参数：materialQuality 运行时切换时按原参数重建材质（换类不换外观）
   mat.userData.s3mOpts = opts;
+  // 记录实际生效的档位：重建 / 排查时不用再猜当时读的是哪一层设置
+  mat.userData.s3mQuality = quality;
   mat.userData.isStyled = true;
   return mat;
 }

package/src/render/TextureFactory.ts

@@ -31,6 +31,43 @@ export function setMaxAnisotropy(n: number, cap = Infinity): void {
   anisotropyCap = Number.isFinite(cap) && cap > 0 ? Math.max(1, cap) : Infinity;
 }
 
+/**
+ * 单次创建的纹理参数。三项都可缺省 —— 缺省时读模块级默认（`setSrgbTextureDecode`
+ * / `setMaxTextureSize` / `setAnisotropyCap`），所以老调用方行为逐字不变。
+ *
+ * 图层级隔离靠这条：`S3MLayer` 把自己的渲染 profile 透传进来，不再共享模块级状态。
+ */
+export interface TextureCreateOptions {
+  /** 是否做 sRGB 解码（默认读 `getSrgbTextureDecode()`）。`'direct'` 管线传 false */
+  srgbDecode?: boolean;
+  /** 长边像素上限（默认读 `setMaxTextureSize` 的值）。图集恒不缩放 */
+  maxSize?: number;
+  /** 各向异性上限（默认读 `setAnisotropyCap` 的值）。Infinity = 取 GPU 最大值 */
+  anisotropyCap?: number;
+}
+
+/** 把「上限」解析成实际的 anisotropy 值（GPU 最大值与 cap 取小） */
+function resolveAnisotropy(cap: number): number {
+  return Number.isFinite(cap) && cap > 0 ? Math.min(maxAnisotropy, Math.max(1, cap)) : maxAnisotropy;
+}
+
+/**
+ * 把各向异性上限**即时应用**到一批已上传的纹理。
+ *
+ * `anisotropy` 是采样参数，不需要重新解码 —— 改值 + `needsUpdate` 让 three 重传一次
+ * 即可，代价远小于重载瓦片。图集纹理（`configureAtlas` 打过 `s3mNoAniso` 标记）
+ * 保持 1：它关了 mip、靠子区域 rect 自己算层级，开各向异性会把相邻子区域混进来。
+ */
+export function applyAnisotropyCap(textures: Iterable<THREE.Texture>, cap: number): void {
+  const n = resolveAnisotropy(cap);
+  for (const tex of textures) {
+    if (!tex || (tex.userData as { s3mNoAniso?: boolean })?.s3mNoAniso) continue;
+    if (tex.anisotropy === n) continue;
+    tex.anisotropy = n;
+    tex.needsUpdate = true;
+  }
+}
+
 /**
  * 单独调各向异性上限（只影响之后创建的纹理）。
  * supermap 预设会设成 1 —— 官方 iClient3D 不开各向异性，斜视角直接采高 mip
@@ -114,15 +151,15 @@ export function getSrgbTextureDecode(): boolean {
   return srgbTextureDecode;
 }
 
-function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
+function configure<T extends THREE.Texture>(tex: T, srgb = true, opts: TextureCreateOptions = {}): T {
   tex.wrapS = THREE.RepeatWrapping;
   tex.wrapT = THREE.RepeatWrapping;
   tex.magFilter = THREE.LinearFilter;
   tex.minFilter = THREE.LinearMipmapLinearFilter;
   tex.generateMipmaps = true;
   // 各向异性过滤对斜视角立面清晰度的提升比提高分辨率更直接
-  tex.anisotropy = anisotropyCap === Infinity ? maxAnisotropy : Math.min(maxAnisotropy, anisotropyCap);
-  if (srgb && srgbTextureDecode) tex.colorSpace = THREE.SRGBColorSpace;
+  tex.anisotropy = resolveAnisotropy(opts.anisotropyCap ?? anisotropyCap);
+  if (srgb && (opts.srgbDecode ?? srgbTextureDecode)) tex.colorSpace = THREE.SRGBColorSpace;
   tex.flipY = false;
   tex.needsUpdate = true;
   return tex;
@@ -136,18 +173,23 @@ function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
  * 自动选的层级会把相邻子区域混进来，远处就是一糊串色 —— 实测照抄公式但留着 GPU mip
  * 时，画面反而比不改更糟，就是因为这两个变量叠在一起了。
  */
-function configureAtlas<T extends THREE.Texture>(tex: T): T {
-  configure(tex);
+function configureAtlas<T extends THREE.Texture>(tex: T, opts: TextureCreateOptions = {}): T {
+  configure(tex, true, opts);
   tex.wrapS = THREE.ClampToEdgeWrapping;
   tex.wrapT = THREE.ClampToEdgeWrapping;
   tex.minFilter = THREE.LinearFilter;
   tex.generateMipmaps = false;
   tex.anisotropy = 1;
+  // 标记给 applyAnisotropyCap：图集不吃各向异性上限（见该函数注释）
+  (tex.userData as { s3mNoAniso?: boolean }).s3mNoAniso = true;
   tex.needsUpdate = true;
   return tex;
 }
 
-export async function createTexture(tex: S3MTexture | null | undefined): Promise<DecodedTexture> {
+export async function createTexture(
+  tex: S3MTexture | null | undefined,
+  opts: TextureCreateOptions = {}
+): Promise<DecodedTexture> {
   if (!tex || !tex.width || !tex.height) return { texture: null, decoded: 'empty' };
 
   // 图集纹理（flipY 的原始 DXT 图集 / AtlasPack 拼出来的 RGBA 大图 / leaf 组合画布）都必须
@@ -157,7 +199,7 @@ export async function createTexture(tex: S3MTexture | null | undefined): Promise
   // 压缩直传只在「宿主 GL 支持 + 非图集」时开：图集要 flipY / 无 mip，压缩上传做不了翻行
   const wantCompressed = compressedTexturesSupported && !isAtlas;
   // 尺寸上限同样跳过图集：UV 已重映射到子区域，缩放会让整体错位
-  const sizeCap = isAtlas ? Infinity : maxTextureSize;
+  const sizeCap = isAtlas ? Infinity : (opts.maxSize ?? maxTextureSize);
   const data = await decodeTexture(tex, wantCompressed, sizeCap);
 
   if (!data.rgba && !data.blocks && !data.bitmap) {
@@ -194,7 +236,7 @@ export async function createTexture(tex: S3MTexture | null | undefined): Promise
     texture = dt;
   }
   texture.needsUpdate = true;
-  const configured = isAtlas ? configureAtlas(texture) : configure(texture);
+  const configured = isAtlas ? configureAtlas(texture, opts) : configure(texture, true, opts);
   if (data.blocks) {
     configured.generateMipmaps = false;
     // 带链 → 三线性取链上高层级（官方同款平均效果）；纯 level0 才退回 Linear 兜底

package/src/render/viewer/LightRig.ts

@@ -4,17 +4,16 @@
  * 从 `S3MViewer` 里整体搬出来的第一块 —— 它只依赖 `scene` / `renderer` / 共享
  * uniform / 宿主方位角，不碰几何、瓦片、拾取，是耦合最低的一块。
  *
- * ## 两个模块级全局态
+ * ## 颜色管线是图层级的
  *
- * `setColorPipeline` / `setSrgbTextureDecode` / `setAnisotropyCap` 都是模块级设置，
- * 影响**之后创建**的材质与纹理。所以切预设时已加载的瓦片要重载才换观感，
- * 这是已知的架构债（一个页面两个 viewer 用不同预设会互相污染），
- * 拆分没有改变这一点。
+ * 颜色管线 / 纹理解码 / 各向异性三者一起决定「官方 supermap 观感」，都由
+ * `ctx.applyRenderProfile` 落到本图层（见 `S3MViewer._applyRenderProfile`），
+ * 不再写模块级全局 —— 同页两个 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 { ColorPipeline } from '../StyleMaterial.js';
 import type { LightOptions, S3MViewerOptions } from '../S3MViewer.js';
 import type { StyleUniforms } from '../../core/types.js';
 
@@ -49,6 +48,14 @@ export interface LightRigContext {
   getBearing?: () => number | undefined;
   /** 宿主需要重画的信号 */
   repaint: () => void;
+  /**
+   * 应用图层级渲染 profile（颜色管线 + 各向异性）。
+   *
+   * `initial = true` 是构造期：那时还没有瓦片与材质，落地方只记状态即可。
+   * 换掉以前的 `setColorPipeline` / `setSrgbTextureDecode` / `setAnisotropyCap`
+   * 三个模块级全局调用 —— 它们会让同页多图层互相污染。
+   */
+  applyRenderProfile: (p: { colorPipeline: ColorPipeline; anisotropyCap: number }, initial?: boolean) => void;
 }
 
 export class LightRig {
@@ -74,7 +81,7 @@ export class LightRig {
     const options = ctx.options;
     if (options.lightingPreset && options.lightingPreset !== 'default') {
       Object.assign(this._state, resolveLightingPreset(options.lightingPreset));
-      this.applyColorPipeline(options.lightingPreset);
+      this.applyColorPipeline(options.lightingPreset, true);
     }
     if (options.light) Object.assign(this._state, options.light);
   }
@@ -155,15 +162,18 @@ export class LightRig {
   /**
    * supermap 完整版 = 光照强度 + 颜色管线一起切：
    * direct 管线下纹理不做 sRGB 解码、片元按官方常数 Lambert 直乘（见 lightingPreset.ts）。
-   * 两个都是模块级全局态，只影响之后创建的材质 / 纹理 —— 已加载瓦片要重载才换。
+   *
+   * 这三样（管线 / 解码 / 各向异性）以前都是模块级全局，同页两个图层用不同预设
+   * 会互相污染；现在交给 `ctx.applyRenderProfile`，由图层自己持有并透传给材质与纹理。
    */
-  applyColorPipeline(preset: LightingPreset): void {
+  applyColorPipeline(preset: LightingPreset, initial = false): void {
     const direct = preset === 'supermap';
-    setColorPipeline(direct ? 'direct' : 'linear');
-    setSrgbTextureDecode(!direct);
     // 官方不开各向异性：远处直接采高 mip 平均成纯色（"灰色滤镜"的一部分）。
     // 我们默认 Infinity（倾斜摄影立面清晰度优先），supermap 模式必须收回。
-    setAnisotropyCap(direct ? 1 : Infinity);
+    this.ctx.applyRenderProfile(
+      { colorPipeline: direct ? 'direct' : 'linear', anisotropyCap: direct ? 1 : Infinity },
+      initial
+    );
   }
 
   setLightingPreset(preset: LightingPreset): void {

package/src/render/viewer/types.ts

@@ -168,10 +168,24 @@ export interface S3MViewerOptions {
    * - `'lambert'`：`MeshLambertMaterial`，只保留漫反射 + 平行光，片元开销约省一半；
    *   白模 / 纯色 / 按高度着色这类不需要高光的模式肉眼差别很小
    *
-   * 模块级全局状态：同页多个图层会互相覆盖，后创建的那个决定全局。
-   * 只影响**之后创建**的材质 —— 已加载的瓦片要重新加载才会换。
+   * **图层级**：只定这一层，同页多个图层各用各的，互不覆盖；构造时不会写模块级
+   * 默认（`setMaterialQuality`）。不传 = 跟随模块级默认，老用法照旧有效。
+   * 只影响**之后创建**的材质 —— 已加载的瓦片要重载，或在图层上调
+   * `setMaterialQuality()` 原位重建。
    */
   materialQuality?: 'pbr' | 'lambert';
+  /**
+   * 颜色管线（默认 `'linear'`）。
+   *
+   * - `'linear'`：纹理 sRGB 解码 → 线性 PBR 光照 → linear→sRGB 输出（three 标准姿势）
+   * - `'direct'`：官方 iClient3D 的 sRGB 直乘管线，同时把纹理解码关掉（字节值原样进
+   *   shader）。`lightingPreset: 'supermap'` 会选它
+   *
+   * **图层级**：只定这一层，同页多图层各用各的；不传 = 跟随模块级默认。
+   * 已加载瓦片可以在运行时用 `setColorPipeline(q, { duration })` 平滑切过去
+   * （重建材质 + 重传纹理，不重新下载瓦片）。
+   */
+  colorPipeline?: 'linear' | 'direct';
   /** 自定义瓦片构建器（测试 / 服务端渲染时注入） */
   buildTile?: BuildTileFn | null;
   /**