s3m-three 0.4.22 → 0.4.24

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/analysis/DepthPass.ts

@@ -0,0 +1,278 @@
+/**
+ * 分析用的离屏深度采集（P1 的 GPU 部分）。
+ *
+ * 这里只干一件事：把场景渲染成「一张能回读的深度图」，判断逻辑全在
+ * `analysis/skyline.ts` 与 `analysis/viewshed.ts` 里（纯数学、有单测）。
+ * 这样 GPU 侧出错只可能是「图不对」（demo 里一眼看得出），
+ * 而不会把归约逻辑一起搅进去。
+ *
+ * 两个采集器：
+ * - `captureSkylineDepth`：用当前相机视角渲染一次，给天际线用（three 的 RGBADepthPacking）；
+ * - `captureRadialCube`：从观察点朝 6 个方向各渲染一次，存「到观察点的距离」，
+ *   给 360° 可视域用。
+ *
+ * 三条硬约束（都是踩过的坑）：
+ * 1. **必须 `resetState()`**：MapLibre 在上一次 draw 之后改过 GL 状态，
+ *    three 的缓存还停在上一次自己的 render 上，不重置会出现深度测试失效。
+ * 2. **清屏成白色**：`packDepthToRGBA(1)` 返回全白，清屏也用白，
+ *    于是「背景」和「远平面」解包后都是 1.0，背景判定只需一个阈值。
+ * 3. **回读是行倒序的**：WebGL 的 `readPixels` 原点在左下，这里翻成正序再交出去。
+ */
+import * as THREE from 'three';
+import type { Vec3 } from '../../analysis/measure.js';
+
+export interface DepthCaptureContext {
+  renderer: () => THREE.WebGLRenderer | null;
+  scene: () => THREE.Scene | null;
+  camera: () => THREE.Camera | null;
+}
+
+/**
+ * 参与深度采集的**额外几何**（分析代理）。
+ *
+ * 用途：分析只看得见 S3M 场景里的东西。要让 MapLibre 的 MVT 建筑 / 地形也参与
+ * 遮挡，外围得自己把它们挤出成几何，通过这个参数临时挂进场景 —— 只在这一趟
+ * 深度渲染里存在，**不进主渲染、不影响画面**，渲染完立刻摘掉。
+ *
+ * 注意：
+ * - 传进来的对象不要已经有 parent（会被临时 add 到 viewer 的场景上再移除）；
+ * - 代理几何的材质会被 `overrideMaterial` 覆盖，所以给什么材质都行；
+ * - 代理和 MapLibre 实际画出来的可能有细微偏差（表达式插值、terrain 抬升等），
+ *   这是「复制一份几何」这条路固有的代价。
+ */
+export interface DepthCaptureInclude {
+  include?: readonly THREE.Object3D[];
+}
+
+/** 临时把代理几何挂进场景，返回「摘掉」的函数 */
+function attachProxy(scene: THREE.Scene, include?: readonly THREE.Object3D[]): () => void {
+  if (!include?.length) return () => {};
+  const added = include.filter((o) => o && !o.parent);
+  for (const o of added) scene.add(o);
+  return () => {
+    for (const o of added) scene.remove(o);
+  };
+}
+
+/* ------------------------------------------------------------------ 渲染器状态 */
+
+interface RendererState {
+  target: THREE.WebGLRenderTarget | null;
+  toneMapping: THREE.ToneMapping;
+  colorSpace: THREE.ColorSpace;
+  autoClear: boolean;
+  clearColor: THREE.Color;
+  clearAlpha: number;
+}
+
+function saveState(r: THREE.WebGLRenderer): RendererState {
+  return {
+    target: r.getRenderTarget(),
+    toneMapping: r.toneMapping,
+    colorSpace: r.outputColorSpace,
+    autoClear: r.autoClear,
+    clearColor: r.getClearColor(new THREE.Color()),
+    clearAlpha: r.getClearAlpha(),
+  };
+}
+
+function restoreState(r: THREE.WebGLRenderer, s: RendererState): void {
+  r.setRenderTarget(s.target);
+  r.toneMapping = s.toneMapping;
+  r.outputColorSpace = s.colorSpace;
+  r.autoClear = s.autoClear;
+  r.setClearColor(s.clearColor, s.clearAlpha);
+}
+
+/** 回读并把像素翻成正序（行 0 = 画面顶部） */
+function readFlipped(r: THREE.WebGLRenderer, rt: THREE.WebGLRenderTarget, width: number, height: number): Uint8Array {
+  const raw = new Uint8Array(width * height * 4);
+  r.readRenderTargetPixels(rt, 0, 0, width, height, raw);
+  const out = new Uint8Array(raw.length);
+  const rowBytes = width * 4;
+  for (let y = 0; y < height; y++) {
+    out.set(raw.subarray((height - 1 - y) * rowBytes, (height - y) * rowBytes), y * rowBytes);
+  }
+  return out;
+}
+
+function makeTarget(w: number, h: number): THREE.WebGLRenderTarget {
+  return new THREE.WebGLRenderTarget(w, h, {
+    format: THREE.RGBAFormat,
+    type: THREE.UnsignedByteType,
+    minFilter: THREE.NearestFilter,
+    magFilter: THREE.NearestFilter,
+    depthBuffer: true,
+  });
+}
+
+/* ------------------------------------------------------------------ 天际线 */
+
+export interface SkylineCapture {
+  rgba: Uint8Array;
+  width: number;
+  height: number;
+  inverseViewProj: Float32Array;
+  cameraPos: Vec3;
+}
+
+/**
+ * 用当前相机渲染一张深度图（RGBADepthPacking）。
+ *
+ * @param width 采集分辨率。精度由它决定：1280 宽 ≈ 0.28°/列；320 宽 ≈ 1.1°/列。
+ */
+export function captureSkylineDepth(
+  ctx: DepthCaptureContext,
+  width: number,
+  height: number,
+  include?: readonly THREE.Object3D[]
+): SkylineCapture | null {
+  const r = ctx.renderer();
+  const scene = ctx.scene();
+  const camera = ctx.camera();
+  if (!r || !scene || !camera) return null;
+
+  const w = Math.max(1, Math.floor(width));
+  const h = Math.max(1, Math.floor(height));
+  const rt = makeTarget(w, h);
+  const depthMat = new THREE.MeshDepthMaterial({ depthPacking: THREE.RGBADepthPacking });
+
+  const prevOverride = scene.overrideMaterial;
+  const state = saveState(r);
+  const detach = attachProxy(scene, include);
+  let rgba: Uint8Array | null = null;
+
+  try {
+    r.resetState();
+    r.setRenderTarget(rt);
+    r.toneMapping = THREE.NoToneMapping;
+    r.outputColorSpace = THREE.LinearSRGBColorSpace;
+    r.autoClear = true;
+    r.setClearColor(0xffffff, 1);
+    r.clear();
+
+    scene.overrideMaterial = depthMat;
+    camera.updateMatrixWorld();
+    r.render(scene, camera);
+    rgba = readFlipped(r, rt, w, h);
+  } finally {
+    detach();
+    scene.overrideMaterial = prevOverride;
+    restoreState(r, state);
+    depthMat.dispose();
+    rt.dispose();
+  }
+
+  const vp = new THREE.Matrix4().multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
+  const inv = new Float32Array(vp.clone().invert().elements);
+  const pos = new THREE.Vector3().setFromMatrixPosition(camera.matrixWorld);
+
+  return { rgba, width: w, height: h, inverseViewProj: inv, cameraPos: [pos.x, pos.y, pos.z] };
+}
+
+/* ------------------------------------------------------------------ 360° 可视域 */
+
+/**
+ * 6 个面的朝向。**与 `analysis/viewshed.ts` 的采样器约定必须逐字一致**，
+ * 否则可视域会镜像到错误的一侧（而且看起来还挺像真的）。
+ *
+ * 约定：`right = forward × up`；采样器里 `u = dot(dir, right) / dot(dir, forward)`，
+ * `v = dot(dir, up) / dot(dir, forward)`，像素 = `((u + 1) / 2 * size, (v + 1) / 2 * size)`。
+ */
+export const CUBE_FACES: readonly { forward: Vec3; up: Vec3 }[] = [
+  { forward: [1, 0, 0], up: [0, -1, 0] },
+  { forward: [-1, 0, 0], up: [0, -1, 0] },
+  { forward: [0, 1, 0], up: [0, 0, 1] },
+  { forward: [0, -1, 0], up: [0, 0, -1] },
+  { forward: [0, 0, 1], up: [0, -1, 0] },
+  { forward: [0, 0, -1], up: [0, -1, 0] },
+];
+
+/** 按上面的约定造 6 台 90° 相机；抽出来是为了能脱离 WebGL 单测朝向 */
+export function buildCubeCameras(origin: Vec3, near: number, far: number): THREE.PerspectiveCamera[] {
+  return CUBE_FACES.map(({ forward, up }) => {
+    const cam = new THREE.PerspectiveCamera(90, 1, near, far);
+    cam.up.set(up[0], up[1], up[2]);
+    cam.position.set(origin[0], origin[1], origin[2]);
+    cam.lookAt(origin[0] + forward[0], origin[1] + forward[1], origin[2] + forward[2]);
+    cam.updateMatrixWorld(true);
+    return cam;
+  });
+}
+
+/**
+ * 从观察点朝 6 个方向渲染「到观察点的距离」，归一化到 [0,1] 后按
+ * three 的 `packDepthToRGBA` 打包。
+ *
+ * ⚠️ 用 `overrideMaterial` 换材质，**实例化网格（InstancedMesh）不会被正确变换** ——
+ * 简化着色器不处理 `instanceMatrix`。点云 / 树木这类实例化内容不参与遮挡。
+ */
+export function captureRadialCube(
+  ctx: DepthCaptureContext,
+  origin: Vec3,
+  size: number,
+  maxDist: number,
+  include?: readonly THREE.Object3D[]
+): Uint8Array[] | null {
+  const r = ctx.renderer();
+  const scene = ctx.scene();
+  if (!r || !scene) return null;
+
+  const s = Math.max(8, Math.floor(size));
+  const rt = makeTarget(s, s);
+  const mat = new THREE.ShaderMaterial({
+    uniforms: {
+      uOrigin: { value: new THREE.Vector3(origin[0], origin[1], origin[2]) },
+      uMaxDist: { value: maxDist },
+    },
+    vertexShader: /* glsl */ `
+      varying vec3 vWorld;
+      void main() {
+        vec4 world = modelMatrix * vec4( position, 1.0 );
+        vWorld = world.xyz;
+        gl_Position = projectionMatrix * viewMatrix * world;
+      }
+    `,
+    fragmentShader: /* glsl */ `
+      #include <common>
+      #include <packing>
+      uniform vec3 uOrigin;
+      uniform float uMaxDist;
+      varying vec3 vWorld;
+      void main() {
+        float d = clamp( length( vWorld - uOrigin ) / uMaxDist, 0.0, 1.0 );
+        gl_FragColor = packDepthToRGBA( d );
+      }
+    `,
+  });
+
+  const prevOverride = scene.overrideMaterial;
+  const state = saveState(r);
+  const detach = attachProxy(scene, include);
+  const cameras = buildCubeCameras(origin, 0.1, maxDist);
+  const faces: Uint8Array[] = [];
+
+  try {
+    r.resetState();
+    r.setRenderTarget(rt);
+    r.toneMapping = THREE.NoToneMapping;
+    r.outputColorSpace = THREE.LinearSRGBColorSpace;
+    r.autoClear = true;
+    r.setClearColor(0xffffff, 1); // 白 = 该方向没有几何（与 pack(1) 一致）
+    scene.overrideMaterial = mat;
+
+    for (const cam of cameras) {
+      r.clear();
+      r.render(scene, cam);
+      faces.push(readFlipped(r, rt, s, s));
+    }
+  } finally {
+    detach();
+    scene.overrideMaterial = prevOverride;
+    restoreState(r, state);
+    mat.dispose();
+    rt.dispose();
+  }
+
+  return faces;
+}

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/PickService.ts

@@ -407,6 +407,53 @@ export class PickService {
     return null;
   }
 
+  /**
+   * 沿给定射线求**最近**交点距离（通视分析用）。
+   *
+   * 与 `pick` 不同：不走 GPU、不认批次，只回答「这条线上最先撞到什么」，
+   * 所以一次查询的代价是 O(已加载三角面)，几十万面的场景在几十毫秒量级，
+   * 适合点击式查询；要逐帧连续更新得换深度图方案（见 `docs/API.md`）。
+   *
+   * @param origin 起点（场景 ENU 米）
+   * @param dir 单位方向
+   * @param maxDistance 只关心这个距离内的交点
+   */
+  raycastDistance(
+    origin: readonly [number, number, number],
+    dir: readonly [number, number, number],
+    maxDistance: number
+  ): { distance: number; point: [number, number, number] } | null {
+    if (!this.host.scene) return null;
+    const meshes = [...this.pickables.values()]
+      .map((p) => p.mesh)
+      .filter((m) => {
+        // 被隐藏的单体所在网格、以及整层隐藏的都要排除，否则会「撞到看不见的墙」
+        let curr: THREE.Object3D | null = m;
+        while (curr) {
+          if (!curr.visible) return false;
+          curr = curr.parent;
+        }
+        return true;
+      });
+    if (!meshes.length) return null;
+
+    const raycaster = new THREE.Raycaster();
+    raycaster.set(
+      new THREE.Vector3(origin[0], origin[1], origin[2]),
+      new THREE.Vector3(dir[0], dir[1], dir[2]).normalize()
+    );
+    raycaster.near = 0;
+    raycaster.far = maxDistance;
+
+    const hits = raycaster.intersectObjects(meshes, false);
+    if (!hits.length) return null;
+    const h = hits[0];
+    return {
+      distance: h.distance,
+      point: [h.point.x, h.point.y, h.point.z],
+    };
+  }
+
   /**
    * 沿视线方向穿透拾取多个单体，按由近至远排序返回。
    */

package/src/render/viewer/types.ts

@@ -174,6 +174,18 @@ export interface S3MViewerOptions {
    * `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;
   /**

package/src/tileset/S3MTileset.ts

@@ -32,6 +32,7 @@ import type {
 } from '../core/S3MBlockParser.js';
 import type { Anchor, ParsedTile, Stats, StyleUniforms } from '../core/types.js';
 import type { TileGeometryData } from '../core/TileGeometry.js';
+import type { TextureCreateOptions } from '../render/TextureFactory.js';
 import type { Group, Texture } from 'three';
 
 function dirOf(url: string): string {
@@ -248,6 +249,10 @@ export type BuildTileFn = (
     polygonOffset?: { factor: number; units: number };
     /** 光照模型档位（透传给 buildTileObjects），见 BuildTileOptions.materialQuality */
     materialQuality?: 'pbr' | 'lambert';
+    /** 颜色管线（透传给 buildTileObjects），见 BuildTileOptions.colorPipeline */
+    colorPipeline?: 'linear' | 'direct';
+    /** 纹理创建参数（透传给 buildTileObjects → createTexture） */
+    textureOptions?: TextureCreateOptions;
   }
 ) => Promise<{ group: Group; stats: Partial<Stats> }>;
 
@@ -265,6 +270,10 @@ export interface S3MTilesetOptions {
    * 由 DatasetManager 从图层 / 数据集设置带下来。
    */
   materialQuality?: 'pbr' | 'lambert';
+  /** 颜色管线，透传给 buildTileObjects。不传 = 读模块级默认。由图层的渲染 profile 带下来 */
+  colorPipeline?: 'linear' | 'direct';
+  /** 纹理创建参数（sRGB 解码 / 尺寸上限 / 各向异性上限），透传给 createTexture */
+  textureOptions?: TextureCreateOptions;
   /**
    * 是否用 Web Worker 解析经典 `.s3mb` 瓦片（默认开）。
    *
@@ -479,6 +488,8 @@ export class S3MTileset {
   private _buildTile: BuildTileFn | null;
   private readonly _polygonOffset: { factor: number; units: number } | undefined;
   private _materialQuality: 'pbr' | 'lambert' | undefined;
+  private _colorPipeline: 'linear' | 'direct' | undefined;
+  private _textureOptions: TextureCreateOptions | undefined;
   private readonly _uniforms: StyleUniforms | null;
   /** 经典 .s3mb 的 Worker 解析客户端；undefined = 尚未尝试创建，null = 不可用/已降级 */
   private _workerClient: S3MWorkerClient | null | undefined;  private readonly _useWorker: boolean;
@@ -500,6 +511,8 @@ export class S3MTileset {
     this._buildTile = options.buildTile ?? null;
     this._polygonOffset = options.polygonOffset;
     this._materialQuality = options.materialQuality;
+    this._colorPipeline = options.colorPipeline;
+    this._textureOptions = options.textureOptions;
     // 着色器共享 uniform，由 S3MLayer 持有并传进来
     this._uniforms = options.uniforms ?? null;
     this._useWorker = options.useWorker !== false;
@@ -740,6 +753,15 @@ export class S3MTileset {
     this._materialQuality = q;
   }
 
+  /**
+   * 运行时改本数据集的渲染 profile（颜色管线 / 纹理参数）。
+   * 只影响**之后**构建的瓦片材质与纹理；场上已有的由 `S3MViewer` 统一重建 / 重传。
+   */
+  setRenderProfile(p: { colorPipeline?: 'linear' | 'direct'; textureOptions?: TextureCreateOptions }): void {
+    if (p.colorPipeline !== undefined) this._colorPipeline = p.colorPipeline;
+    if (p.textureOptions !== undefined) this._textureOptions = p.textureOptions;
+  }
+
   /**
    * 当前数据集驻留的显存与内存总字节数（几何缓冲精确大小 + 纹理显存估计）
    */
@@ -1264,6 +1286,8 @@ export class S3MTileset {
         assembled,
         polygonOffset: this._polygonOffset,
         materialQuality: this._materialQuality,
+        colorPipeline: this._colorPipeline,
+        textureOptions: this._textureOptions,
       });
       const { group, stats } = buildRes;
       const texKeys = (buildRes as any).textureKeys ?? (group.userData?.textureKeys as string[] | undefined) ?? Object.keys(tile.textures ?? {});