s3m-three 0.4.20 → 0.4.22

package/docs/API.md

@@ -162,6 +162,7 @@ new S3MViewer(options?: S3MViewerOptions)
 | `pickable` | `boolean` | `true` | 是否响应拾取 |
 | `maxTiles` | `number` | `64` | 每个数据集驻留瓦片上限，超了淘汰最久没用的（不是停止加载） |
 | `maxTriangles` | `number` | `Infinity` | 每个数据集**驻留三角形总数**的软上限（不限制）。`maxTiles` 数不了「一块精模几十万面」，这条按实际面数做刹车，走同一套 make-before-break 淘汰，不开洞 |
+| `maxMemory` | `number` | `Infinity` | 每个数据集**驻留显存/内存字节数**的软上限（不限制）。包含几何缓冲精确字节与纹理显存估计，超限走同一套 make-before-break 淘汰，不开洞 |
 | `totalMaxTiles` | `number` | — | 多数据集全局驻留瓦片总预算；开启后在可见数据集间动态均衡分配，防止叠加爆显存 |
 | `light` | `LightOptions` | — | 场景光照配置，可配环境光与主平行光的颜色、强度、模式与方位角/高度角 |
 | `maxConcurrent` | `number` | `4` | 每个数据集并发请求数 |
@@ -174,7 +175,7 @@ new S3MViewer(options?: S3MViewerOptions)
 | `anisotropyCap` | `number` | `Infinity` | 各向异性过滤上限（不封顶 = 取 GPU 最大值，通常 16）。移动端封到 4 / 8 肉眼通常无差，采样成本明显下降。只影响之后创建的纹理 |
 | `maxTextureSize` | `number` | `Infinity` | 纹理长边像素上限（不限制）。非图集的 RGBA / WebP 产物按 2× 盒式滤波减半到上限内；DXT 压缩直传与图集不受影响 |
 | `maxImageCache` | `number` | `128` | 纹理缓存条数上限。一条 = 一张已解码的瓦片纹理，1024² RGBA 约 4MB，128 条即约 512MB 显存；低端设备 32~48。LRU，降下来下次淘汰时释放 |
-| `materialQuality` | `'pbr' \| 'lambert'` | `'pbr'` | 光照模型。`lambert` 用 `MeshLambertMaterial` 替换 PBR，去掉 GGX 与环境球谐，片元约省一半；白模 / 纯色 / 按高度着色几乎无差。模块级全局，只影响之后创建的材质 |
+| `materialQuality` | `'pbr' \| 'lambert'` | `'pbr'` | 光照模型。`lambert` 用 `MeshLambertMaterial` 替换 PBR，去掉 GGX 与环境球谐，片元约省一半；白模 / 纯色 / 按高度着色几乎无差。**图层级**：同页多个图层各用各的，互不覆盖；不传则跟随模块级默认（`setMaterialQuality`）。只影响之后创建的材质 |
 | `buildTile` | `BuildTileFn \| null` | — | 自定义瓦片构建器（测试 / 服务端渲染时注入） |
 | `attributes` | `AttributeQueryOptions` | — | 可选的 iServer 数据服务配置，配了才能用 `colorByField()` 等便利方法；不配就自己取数 + `setFeaturesStyle()`，见[业务字段](#业务字段锚点在库内对应关系在外部) |
 | `onRequestRepaint` | `() => void` | — | 宿主请求重画的信号：纯 three 宿主接自己的渲染循环 |
@@ -397,6 +398,8 @@ setLodPixelRatioCap(cap: number): void        // Infinity = 不截断（默认
 readonly lodPixelRatioCap: number
 setMaxTriangles(n: number, datasetId?: string): void   // Infinity = 不限制（默认）
 readonly maxTriangles: number
+setMaxMemory(bytes: number, datasetId?: string): void  // 显存字节上限，Infinity = 不限制（默认）
+readonly maxMemory: number
 setAnisotropyCap(cap: number): void           // Infinity = 取 GPU 最大值（默认）
 readonly anisotropyCap: number
 setMaxTextureSize(n: number): void            // Infinity = 不限制（默认）
@@ -1311,11 +1314,12 @@ buildAttributes({ smid, box, triangles, floorHeight })  // → S3MFeatureAttribu
 | `totalMaxTiles` | 多数据集全局瓦片总预算（如 `96` 或 `128`），自动在可见数据集间均衡分配配额，隐藏数据集时自动回收预算，防止多图层叠加爆显存 |
 | `maxTiles` | 单数据集瓦片驻留上限，默认 64。叠加多个数据集时建议配合 `totalMaxTiles` 或下调至 32~48 |
 | `maxTriangles` | 单数据集驻留面数软上限，默认不限制。`maxTiles` 只数瓦片个数，精模场景（一块几十万面）建议配 60 万~120 万 |
+| `maxMemory` | 单数据集驻留显存/内存软上限（字节），默认不限制。精确统计几何缓冲与纹理显存，超限按 make-before-break 自动主动回收 |
 | `lodPixelRatioCap` | LOD 判定用屏幕高度的 DPR 上限，默认不截断。见下方「移动端 / 差设备」 |
 | `anisotropyCap` | 各向异性过滤上限，默认取 GPU 最大值。移动端 4 / 8 通常肉眼无差 |
 | `maxTextureSize` | 纹理长边像素上限，默认不限制。手机上 1024 即可，显存降到 1/4 |
 | `maxImageCache` | 纹理缓存条数，默认 128。低端机 32~48，和 `maxTextureSize` 一起管显存 |
-| `materialQuality: 'lambert'` | 换成 Lambert 光照，片元约省一半。白模 / 按高度配色看不出差别，贴图模式会略平 |
+| `materialQuality: 'lambert'` | 换成 Lambert 光照，片元约省一半。白模 / 按高度配色看不出差别，贴图模式会略平。图层级设置，同页其它图层不受影响 |
 | `maxImageCache` | 原始图集与 leaf 段图像记录的 LRU 缓存容量上限（默认 128），超限自动淘汰旧缓存，防止漫游时内存不断累积 |
 | 纹理引用计数 | 瓦片淘汰时按引用计数释放未被其他瓦片复用的 `Texture` 并调用 `dispose()`，真正归还 GPU 显存 |
 | 几何/材质深度释放 | 瓦片注销时深度遍历对象树，彻底释放 `Mesh`、`Points`（点云/高斯泼溅）以及 `LineSegments`（棱线包）的 `BufferGeometry` 与材质 |
@@ -1395,34 +1399,11 @@ viewer.flushOverrides();
 
 ## 已知限制
 
-- **Draco 压缩几何**已支持（v3.01 点云分支）：内联 wasm 按需 `import`，解码后与标准骨架同路输出 attribute，点云按 `primitiveType = 1` 走 `THREE.Points`，分类码 / 强度 / 权重三种自定义属性一并解出。两点要留意：一是**容器与规范描述对不上**，字段顺序是从真实瓦片逐字节标定的（`payloadSize` / `dracoSize` / `"DRACO"` 魔数 / `skeletonStreamSize` 四重自校验兜读偏，另有单骨架 64M 点数上限），官方 SDK 的 `parseDracoSkeleton` 字段顺序多一个 `materialCount` 且 `version === 3` 的判定对 v3.01 不成立，解析不了同一个服务，不能照抄；二是这条路径**还没有回归测试钉住**（目前只有排查探针脚本），改 `core/Draco.ts` 的字段顺序必须拿真实瓦片复验。
-- **实例化单体**（`pickInfo` 里给的是 `instanceIds` 而不是 `batchId`，白模常见）只做了渲染，没做按单体控制：`setFeatureStyle` / `filterByField` / `elevateByField` / GPU 拾取走的都是 `aBatchId`，这条路径对实例化几何不生效。要支持得把每个实例单独上色，得改 InstancedMesh 的 instanceColor + 拾取编码。
-- **CRN 纹理**已支持，且已在真实服务上验证：内联的 crunch wasm 转回 DXT 后走现成解码，DXT 具体格式看 CRN 头，wasm 约 76KB、只有真遇到 CRN 时才动态加载。**判定看 `compressType` 而不是 `pixelFormat`**——实测 v3.00 是 `ct=26 / pf=13`、行标是 `ct=50000 / pf=32856`，按 `pixelFormat` 26 / 27 判断会把真实 CRN 整包丢掉（模型变灰模）。判定收敛在 `packages/s3m-three/src/core/TextureFormat.ts`（`resolveTextureKind` / `TextureCompress` / `dxtPixelFormatOf`，已从包入口导出）。用 `bun run probe:crn -- --crn <数据集 config 地址>` 可以对任意服务跑「尺寸吻合 / 色数 / 粗糙度 / ASCII 预览」的实测。
-- **纹理分包（`s3m:TextureSharing` / S3MBLOCK）已完整支持**：
-  - **容器结构**：`.s3mblock` 单文件容器 = 若干 RO 组，每组包含一段 pageLOD 元信息 + zlib 压缩的 v2 瓦片体（段目录：groupNode / 骨架 / secondColor / 图集 / 材质 / 单体化）；纹理是图集（`isSaveData`），材质按图集 id（`-N.texblock`）引用，几何顶点区间绑定到图集子区域；
-  - **解析与 UV 重映射**：解析端把顶点 UV 用 `fract` 平铺语义重映射进图集空间，多图集自动走货架式装箱合并（`AtlasPack`），下游材质直接绑定整张图集；
-  - **细级 LOD（leaf）外部图集加载**：细级瓦片的图集未内嵌原始像素（`data = null`），由 `_fillExternalAtlases` 解析子请求名（`_subRequestNames`）：
-    - 支持展开 `Tex_x.texblock#<三位数字串>` 多精灵容器索引；
-    - 对齐官方 `Uci` 规范的 pack 请求：URL 拼装 `extratiles=<names>` 批量合并拉取，避免高并发零碎请求；
-    - 响应体通过 `parseTexblockSegments` 解码 `kMi` 分段记录，并通过 `leafRequestCache` 与 `_leafPending` 实现跨瓦片并发请求自动去重缓存；
-    - **组合画布与装配**：对 leaf 模式，解出子精灵 RGBA 缓冲，按 `subTexInfos[i]` 的偏移量（`offsetX`、`offsetY`）以标准自上而下行序拷贝进高分辨率组合画布；
-    - **安全判定与重拼**：外部图集接入前通过 `evaluateAtlasUpgrade` 进行长宽比与下采样色差校验，判定通过后由 `rebuildBlockTextureState` 重新生成拼图与重算归一化 `texRect`；
-  - 实现位于 `core/S3MBlockParser.ts`、`core/AtlasPack.ts` 与 `tileset/S3MTileset.ts`，并通过 `tests/unit/s3mblock.test.ts`、`tests/unit/leaf-atlas.test.ts` 和 `tests/unit/leaf-uv-render.test.ts` 交叉验证钉住。
-- **多块 MeshOpt 骨架**（`blockCount > 1`）已支持。这类骨架里**每块后面紧跟自己的索引包**（不是所有块之后再统一放一份），索引是块内局部编号；解析时按块顺序合并顶点流，再把每块索引加上顶点基数偏移，对外仍是一份顶点缓冲 + 多组索引包。实测 `3D-WorkSpace_pbr1/pbrmodel` 的 `blockCount=2` / `3` 瓦片可正常加载。
-- **切线顶点流**只跳过不解码（渲染没有法线贴图通道），带 TANGENT 的数据不会被判失败。
-- **S3M 1.x（`.s3m`，SuperMapCache）已支持**。这类服务的 `config` 返回 `SuperMapCache` XML（`sml:FileType = OSGBFile`），位置与范围按米制盒反算（见「锚点」）；瓦片是 `73 33 6D 00` 魔数 + zlib 的老容器，`parseS3MB` 认出魔数后交给 `core/S3M1Parser.ts`，输出同形状的 `ParsedTile`，下游渲染 / LOD / 拾取零改动。
-  **注意：它的下一级 LOD 并不是 `.osgb`** —— XML 里 `RangeDataList` 写的 `..._L16_0.osgb` 只是切片时的原始文件名，服务实际发布的是同名换 `.s3m` 后缀，走 `datas/<数据源>/data/path/<瓦片目录>/<名>.s3m`（实测 L16/L17/L18 全部 200，`?sceneName=` 不参与寻址）。所以整棵 LOD 树都是同一种容器，**不需要 OSG Binary 解码器**；早先「因为子瓦是 .osgb 所以做不了」的结论是没验证就下的，已作废。
-  已标定：`73 33 6D 00` 魔数 + zlib；解压后 `uint32 xmlSize + XML + 补齐 4 字节对齐（实测 2~3 个 0x30，不是固定标记）+ (uint32 size + data) × 3`，三段长度链在四块样本上全部精确闭合；几何流 = `uint32 meshCount` + 每块网格 `{ geoName, 7, 772, V, 0 }` + `V × 16B` 顶点 `(x, y, z, z)` + 数组区 + `uint32 1` + `uint32 materialId`（与 XML 材质号一致）；纹理流 = `uint32 count` + 每条 `{ id, width, height, format, size, flag }` + `size` 字节（实测 `format=14`、0.5 B/px = DXT1，`28 + size` 精确等于段长）；索引确认为 u16（值域最大恰为 `V-1`）；几何里**没有法线数组**，接解码时要 `computeVertexNormals()`。
-  接这种格式时有三个坑，都是实测出来的，别凭直觉：
-  1. **几何里没有法线数组**（全段扫 `|v|≈1` 的最长游程只有 4~10 个），建完要 `computeVertexNormals()`；
-  2. **头里的 `format` 不是 `S3MPixelFormat` 枚举** —— 实测四块瓦片都是 `14`，而这枚举里 14 = BGRA（4 B/px），照搬就会把 0.5 B/px 的 DXT1 当 4 字节读，满屏彩噪。必须按 `size / (width*height)` 反推（`pixelFormatOfBpp`）；
-  3. **UV 是「v = 0 对应文件首行」**，与 DXT 解码器内部那次 GL 方向的 Y 翻转相反。不抵消的话几何的 v（实测 0.483~0.983）会正好采到图集空的那半张 —— 区域均值亮度 5.6 对比 76.1，模型上就是一片黑块。所以 v1 纹理要置 `S3MTexture.flipY = true`。
-
-  子瓦地址规则见 `s3m1ChildUrl`：XML 的 `RangeDataList` 给的是切片时残留的 `.osgb` 名，实际发布是同名换 `.s3m` 并插在 `datas/<数据源>/data/path/<瓦片目录>/` 下；父瓦自己已经在 `data/path` 下时只能换文件名，再插一层就成了 `data/path/data/path/...` 全部 404（有回归测试钉住）。
-- **高斯泼溅（`3DGaussianSplatting`）只按点渲染**。加载、细化、出图整条链路是通的（这类瓦片没有索引包，顶点即点，`GeometryBuilder` 会补一个「顶点即点」的伪包走 `THREE.Points`；不补的话整块瓦片落到「无可用几何」被丢掉，这是之前"加载不出来"的第二个原因）。但画出来的是带顶色的点集，不是真正的泼溅：`gsScale` / `gsRotation` 两条自定义流的量化格式还没标定，而且颜色是 RGBA（A 通道是泼溅不透明度），现在的顶点色路径会丢掉 alpha。要上 EWA splatting 得先按深度层级取样把这两条流对准，再补协方差 + 深度排序的 alpha 混合。
-- **KTX2** 不在 S3M 的 `pixelFormat` 枚举里，iServer 也不会发；要支持需自行引入 `basis_transcoder.wasm` 并解析容器，属于「换数据源才需要考虑」的项。
-- **骨骼动画**解析了但未驱动。
-- 跨城市量级的数据集叠加会有 float32 精度问题。
+- **实例化单体（`instanceMode` 16 / 17）**：白模中较常见（`pickInfo` 里给的是 `instanceIds` 而不是 `batchId`）。目前支持正常网格渲染，单体级操作（`setFeatureStyle` / `filterByField` / `elevateByField`）与 GPU 单体拾取走的都是 `aBatchId`，对实例化几何暂不生效。
+- **切线（TANGENT）顶点流不参与法线贴图**：着色器目前未接入切线空间法线贴图通道，TANGENT 顶点流直接跳过不解码；带 TANGENT 的模型可正常着色渲染，不受影响。
+- **骨骼动画未挂接驱动**：S3M 数据中的骨骼动画元信息与 JSON 已解析，但目前未接入逐帧骨骼驱动。
+- **KTX2 纹理未内置**：S3M 官方 `pixelFormat` 枚举与主流 iServer 服务不包含 KTX2 / Basis 压缩纹理，当前未内置 `basis_transcoder.wasm` 转码。
+- **多数据集跨城市叠加精度**：跨城市广域（数十公里以上）多个不同中心的数据集叠加受 WebGL 单精度 float32 深度和位置精度限制，建议同场景数据集位于同一城市量级内（几公里内）。
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3m-three",
-  "version": "0.4.20",
+  "version": "0.4.22",
   "description": "SuperMap S3M 三维模型格式的 three.js 渲染内核：浏览器内直接解析 .s3mb 瓦片，无需转 3D Tiles，支持 LOD 调度、白膜/按高度/按单体/动态扫描着色、单体级 GPU 拾取。宿主无关，可单独用于任意 three 场景。",
   "type": "module",
   "repository": {

package/src/render/DatasetManager.ts

@@ -24,6 +24,8 @@ export interface S3MDatasetOptions {
   maxTiles?: number;
   /** 该数据集驻留三角形总数的软上限（默认跟随图层级设置；都不传则不限制） */
   maxTriangles?: number;
+  /** 该数据集驻留显存/内存字节数的软上限（默认跟随图层级设置；都不传则不限制） */
+  maxMemory?: number;
   /** 该数据集的纹理缓存条数上限（默认跟随图层级设置，图层不传则 128） */
   maxImageCache?: number;
   lodRangeScale?: number;
@@ -41,6 +43,11 @@ export interface S3MDatasetOptions {
   useWorker?: boolean;
   /** 三角面材质深度偏移（共面摩尔纹 / 重合面归属），见 BuildTileOptions.polygonOffset */
   polygonOffset?: { factor: number; units: number };
+  /**
+   * 本数据集的光照模型档位（不填则用图层级设置）。
+   * 只影响该数据集**之后创建**的材质。
+   */
+  materialQuality?: 'pbr' | 'lambert';
   /**
    * 是否对该数据集生成几何棱线（CPU 端 EdgesGeometry）。
    * - 不填：跟随全局 `style.edges`
@@ -91,6 +98,25 @@ export class DatasetManager {
   readonly datasets = new Map<string, S3MDatasetEntry>();
   sceneAnchor: { x: number; y: number; z: number; meterInMercator: number; altitude?: number } | null = null;
   totalMaxTiles: number = 0;
+  /**
+   * 图层级默认光照模型档位（`undefined` = 跟随模块级默认）。
+   * 数据集自己指定了 `materialQuality` 就用自己的。
+   */
+  defaultMaterialQuality: 'pbr' | 'lambert' | undefined = undefined;
+
+  /**
+   * 图层档位变更：同步给已存在的数据集（它们之后加载的瓦片才用新档位；
+   * 场上已有材质由 `S3MViewer._rebuildStyledMaterials` 原位重建）。
+   *
+   * 数据集自己指定过档位的不动 —— 那是它显式要的，不该被图层级设置覆盖。
+   */
+  setDefaultMaterialQuality(q: 'pbr' | 'lambert' | undefined): void {
+    this.defaultMaterialQuality = q;
+    for (const entry of this.datasets.values()) {
+      if (entry.options.materialQuality) continue;
+      entry.tileset?.setMaterialQuality(q);
+    }
+  }
 
   get(id: string): S3MDatasetEntry | undefined {
     return this.datasets.get(id);
@@ -185,7 +211,8 @@ export class DatasetManager {
     callbacks: DatasetManagerCallbacks,
     maxTriangles: number = Infinity,
     maxImageCache: number = 128,
-    authenticate?: AuthenticateFn
+    authenticate?: AuthenticateFn,
+    maxMemory: number = Infinity
   ): Promise<S3MDatasetEntry> {
     const existing = this.datasets.get(ds.id);
     if (existing) return existing;
@@ -216,10 +243,13 @@ export class DatasetManager {
       maxTiles: ds.maxTiles ?? maxTiles,
       maxConcurrent: maxConcurrent,
       maxTriangles: ds.maxTriangles ?? maxTriangles,
+      maxMemory: ds.maxMemory ?? maxMemory,
       maxImageCache: ds.maxImageCache ?? maxImageCache,
       lodRangeScale: ds.lodRangeScale ?? defaultLodRangeScale,
       buildTile: buildTile ?? null,
       polygonOffset: ds.polygonOffset,
+      // 数据集 > 图层 > 模块级默认（undefined 一路传下去，由 createStyledMaterial 回落）
+      materialQuality: ds.materialQuality ?? this.defaultMaterialQuality,
       useWorker: ds.useWorker,
       authenticate: ds.authenticate ?? authenticate,
       unsupported: ds.unsupported,

package/src/render/GeometryBuilder.ts

@@ -323,6 +323,7 @@ export interface TileBuildStats {
   /** 该瓦片的高斯实例数。泼溅瓦片才有值，LOD 判据用它算屏幕覆盖率 */
   splatCount?: number;
   /** 被跳过的东西，加载完可以直接在控制台看 */
+  memory?: number;
   skipped: string[];
 }
 
@@ -359,6 +360,13 @@ export interface BuildTileOptions {
    * 偏移量随斜率/距离缩放，量级在微米级，正常相邻面不受影响。
    */
   polygonOffset?: { factor: number; units: number };
+  /**
+   * 光照模型档位，透传给 `createStyledMaterial`。
+   *
+   * 不传 = 读模块级默认（`getMaterialQuality()`），与旧行为一致。
+   * 由 `S3MTileset` 从图层 / 数据集一路带下来，所以同页多个图层可以各用各的。
+   */
+  materialQuality?: 'pbr' | 'lambert';
 }
 
 export interface BuildTileResult {
@@ -540,6 +548,8 @@ export async function buildTileObjects(
       // uv 第三分量（custom0）：几何带了这条流，材质才走官方的「按 z 决定采样」分支
       texCoordZ: hasTexCoordZ && !!map,
       secMap,
+      // 图层 / 数据集的档位；undefined 时 createStyledMaterial 自己回落到模块级默认
+      materialQuality: options.materialQuality,
     });
     // 用户配置的深度偏移（共面摩尔纹 / 重合面归属的人工定序，见 BuildTileOptions 注释）
     if (options.polygonOffset) {
@@ -769,6 +779,26 @@ export async function buildTileObjects(
 
   if (!group.children.length) stats.skipped.push('tile 无可用几何');
 
+  let totalGeoBytes = 0;
+  for (const obj of objects) {
+    const mesh = obj as THREE.Mesh;
+    const geo = mesh.geometry;
+    if (geo) {
+      if (geo.attributes) {
+        for (const attr of Object.values(geo.attributes)) {
+          if (attr && attr.array) totalGeoBytes += attr.array.byteLength;
+        }
+      }
+      if (geo.index && geo.index.array) totalGeoBytes += geo.index.array.byteLength;
+    }
+    if ((mesh as THREE.InstancedMesh).isInstancedMesh) {
+      const inst = mesh as THREE.InstancedMesh;
+      if (inst.instanceMatrix && inst.instanceMatrix.array) totalGeoBytes += inst.instanceMatrix.array.byteLength;
+      if (inst.instanceColor && inst.instanceColor.array) totalGeoBytes += inst.instanceColor.array.byteLength;
+    }
+  }
+  stats.memory = totalGeoBytes;
+
   group.userData.textureKeys = usedTextureKeys;
   return { group, stats, objects, textureKeys: usedTextureKeys };
 }

package/src/render/S3MViewer.ts

@@ -26,7 +26,7 @@ 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 { getMaterialQuality, normalizeMaterialQuality } from './StyleMaterial.js';
 import type { LightingPreset } from './lightingPreset.js';
 import { LightRig } from './viewer/LightRig.js';
 import { HeightIndex } from './viewer/HeightIndex.js';
@@ -249,6 +249,14 @@ export class S3MViewer {
   readonly groundManager: GroundManager;
   /** 多数据集生命周期与锚点管理器 */
   private readonly _datasetManager = new DatasetManager();
+  /**
+   * 本图层的光照模型档位。
+   *
+   * `undefined` = 没指定，跟随模块级默认（`getMaterialQuality()`）—— 老代码
+   * `setMaterialQuality('lambert')` 一行改全场的用法靠这条继续有效。
+   * 传了值就只认自己，多图层同页各用各的，互不覆盖。
+   */
+  private _materialQuality: MaterialQuality | undefined;
   /** 单体样式、专题着色与状态纹理管理器 */
   private readonly _featureStyleManager: FeatureStyleManager;
   /** GPU 路径动画管理器 */
@@ -352,7 +360,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;
     }
@@ -717,7 +729,8 @@ export class S3MViewer {
       },
       this.options.maxTriangles ?? Infinity,
       this.options.maxImageCache ?? 128,
-      this._authenticate
+      this._authenticate,
+      this.options.maxMemory ?? Infinity
     );
     return entry;
   }
@@ -2081,22 +2094,25 @@ 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();
   }
 
   /** 按创建参数原位重建所有 styled 材质（materialQuality 切换用） */
@@ -2118,7 +2134,9 @@ 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 });
       for (const key of PRESERVED) {
         const src = old.userData[key] as { value: unknown } | undefined;
         const dst = fresh.userData[key] as { value: unknown } | undefined;
@@ -2461,6 +2479,29 @@ export class S3MViewer {
     }
   }
 
+  /** 当前每个数据集的驻留显存/内存字节预算。Infinity = 不限制 */
+  get maxMemory(): number {
+    return this.options.maxMemory ?? Infinity;
+  }
+
+  /**
+   * 调整每个数据集驻留显存字节数的软上限（默认 Infinity = 不限制）。
+   * 不传 `datasetId` 时对所有已存在数据集立即生效，并作为之后新增数据集的默认值。
+   * 实际裁剪发生在每帧调度末尾（make-before-break），不会当场开洞。
+   */
+  setMaxMemory(bytes: number, datasetId?: string): void {
+    const next = Number.isFinite(bytes) && bytes > 0 ? bytes : Infinity;
+    if (datasetId) {
+      const entry = this.datasets.get(datasetId);
+      if (entry?.tileset) (entry.tileset as any).setMaxMemory(next);
+    } else {
+      this.options.maxMemory = next;
+      for (const entry of this.datasets.values()) {
+        if (entry.tileset) (entry.tileset as any).setMaxMemory(next);
+      }
+    }
+  }
+
   /** 当前各向异性过滤上限。Infinity = 不封顶 */
   get anisotropyCap(): number {
     return this.options.anisotropyCap ?? Infinity;

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`，只保留漫反射 + 平行光，片元开销约省一半；
@@ -1105,6 +1121,13 @@ export interface StyledMaterialOptions {
   texCoordZ?: boolean;
   /** 图集材质的第二套纹理（官方 BakeTex，光照烘焙），与 base 相乘 */
   secMap?: THREE.Texture | null;
+  /**
+   * 光照模型档位。不传 = 读模块级默认（`getMaterialQuality()`），行为与旧版一致。
+   *
+   * 传了就按传的建 —— 图层级隔离靠这条：`S3MLayer` / `S3MViewer` 把自己的档位
+   * 一路透传到这里，不再让所有图层共享同一份模块级状态。
+   */
+  materialQuality?: MaterialQuality;
 }
 
 /**
@@ -1152,6 +1175,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 +1196,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,
@@ -1311,6 +1337,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/viewer/types.ts

@@ -138,6 +138,12 @@ export interface S3MViewerOptions {
    * 见 `S3MTilesetOptions.maxTriangles`：瓦片数管不住的场景（精模、大面片）用这条刹车。
    */
   maxTriangles?: number;
+  /**
+   * 每个数据集驻留显存/内存字节总数的软上限（默认 Infinity = 不限制）。
+   * 包含几何顶点缓冲（精确字节）与纹理显存估计。
+   * 超限时在每帧末尾（make-before-break）主动回收非显示的瓦片及其独占纹理。
+   */
+  maxMemory?: number;
   /**
    * 纹理缓存条数上限（默认 128）。一条对应一张已解码的瓦片纹理，
    * 1024² 的 RGBA 一张约 4MB，128 条就是 512MB 显存 —— 低端设备建议 32~48。
@@ -162,8 +168,10 @@ export interface S3MViewerOptions {
    * - `'lambert'`：`MeshLambertMaterial`，只保留漫反射 + 平行光，片元开销约省一半；
    *   白模 / 纯色 / 按高度着色这类不需要高光的模式肉眼差别很小
    *
-   * 模块级全局状态：同页多个图层会互相覆盖，后创建的那个决定全局。
-   * 只影响**之后创建**的材质 —— 已加载的瓦片要重新加载才会换。
+   * **图层级**：只定这一层，同页多个图层各用各的，互不覆盖；构造时不会写模块级
+   * 默认（`setMaterialQuality`）。不传 = 跟随模块级默认，老用法照旧有效。
+   * 只影响**之后创建**的材质 —— 已加载的瓦片要重载，或在图层上调
+   * `setMaterialQuality()` 原位重建。
    */
   materialQuality?: 'pbr' | 'lambert';
   /** 自定义瓦片构建器（测试 / 服务端渲染时注入） */