s3m-three 0.3.12 → 0.3.14

package/docs/API.md

@@ -161,6 +161,7 @@ new S3MViewer(options?: S3MViewerOptions)
 | `ground` | `GroundOptions` | — | 3D 物理地表面 / 基坑开挖配置 |
 | `pickable` | `boolean` | `true` | 是否响应拾取 |
 | `maxTiles` | `number` | `64` | 每个数据集驻留瓦片上限，超了淘汰最久没用的（不是停止加载） |
+| `maxTriangles` | `number` | `Infinity` | 每个数据集**驻留三角形总数**的软上限（不限制）。`maxTiles` 数不了「一块精模几十万面」，这条按实际面数做刹车，走同一套 make-before-break 淘汰，不开洞 |
 | `totalMaxTiles` | `number` | — | 多数据集全局驻留瓦片总预算；开启后在可见数据集间动态均衡分配，防止叠加爆显存 |
 | `light` | `LightOptions` | — | 场景光照配置，可配环境光与主平行光的颜色、强度、模式与方位角/高度角 |
 | `maxConcurrent` | `number` | `4` | 每个数据集并发请求数 |
@@ -169,6 +170,9 @@ new S3MViewer(options?: S3MViewerOptions)
 | （随 `useWorker`）几何组装 | `boolean` | `true` | 顶点解交错 / 法线计算 / 同材质合批合并（`core/TileGeometry.ts`）随解析在 Worker 完成，主线程只做 three 对象包装；Worker 不可用时主线程跑同一份实现，产物一致 |
 | （随 `useWorker`）DXT 压缩直传 | 自动 | 自动 | 宿主 GL 同时支持 `WEBGL_compressed_texture_s3tc`(+srgb) 时，dxt1/dxt5（含 CRN 转码产物）不解码直接 `CompressedTexture` 上传，显存与上传带宽降为 1/4~1/8；块长与 4×4 对齐公式不符、flipY 图集、移动端无扩展时自动回退 RGBA 解码 |
 | `lodRangeScale` | `number` | `1.0` | LOD 切换距离缩放系数，> 1 更倾向保留粗模，< 1 提前细化 |
+| `lodPixelRatioCap` | `number` | `Infinity` | LOD 判定屏幕高度的 **DPR 上限**（不截断）。默认按 `canvasHeight` 物理像素算，与官方 `calcPixFromCam` 同口径；3x DPR 手机上由此会多细化、多拉瓦片，传 `2` 即按「CSS 高度 × 2」截断 |
+| `anisotropyCap` | `number` | `Infinity` | 各向异性过滤上限（不封顶 = 取 GPU 最大值，通常 16）。移动端封到 4 / 8 肉眼通常无差，采样成本明显下降。只影响之后创建的纹理 |
+| `maxTextureSize` | `number` | `Infinity` | 纹理长边像素上限（不限制）。非图集的 RGBA / WebP 产物按 2× 盒式滤波减半到上限内；DXT 压缩直传与图集不受影响 |
 | `buildTile` | `BuildTileFn \| null` | — | 自定义瓦片构建器（测试 / 服务端渲染时注入） |
 | `attributes` | `AttributeQueryOptions` | — | 业务属性查询配置，配了才能 `colorByField()`，见[按业务字段着色](#按业务字段着色) |
 | `onRequestRepaint` | `() => void` | — | 宿主请求重画的信号：纯 three 宿主接自己的渲染循环 |
@@ -366,11 +370,21 @@ getFeatureBounds(smid: number): [[number, number], [number, number]] | null
 ```ts
 setLodRangeScale(scale: number, datasetId?: string): void
 readonly lodRangeScale: number
+setLodPixelRatioCap(cap: number): void        // Infinity = 不截断（默认）
+readonly lodPixelRatioCap: number
+setMaxTriangles(n: number, datasetId?: string): void   // Infinity = 不限制（默认）
+readonly maxTriangles: number
+setAnisotropyCap(cap: number): void           // Infinity = 取 GPU 最大值（默认）
+readonly anisotropyCap: number
+setMaxTextureSize(n: number): void            // Infinity = 不限制（默认）
+readonly maxTextureSize: number
 readonly stats: Stats
 readonly fps: number
 getBounds(): [[number, number], [number, number]] | null  // 合并经纬度范围
 ```
 
+`lodPixelRatioCap` 只在**有限值**时才去读 `canvas.clientHeight`，默认状态下不产生任何额外开销；离屏 canvas（`clientHeight` 为 0）自动退回物理像素口径。截断会把每块瓦片的屏幕投影放大同样倍数，几何误差与纹理密度同步变差，取舍见[性能调优](#性能调优与显存管理)。
+
 ```ts
 interface Stats {
   tiles: number; loading: number; failed: number;
@@ -1189,6 +1203,10 @@ buildAttributes({ smid, box, triangles, floorHeight })  // → S3MFeatureAttribu
 |---|---|
 | `totalMaxTiles` | 多数据集全局瓦片总预算（如 `96` 或 `128`），自动在可见数据集间均衡分配配额，隐藏数据集时自动回收预算，防止多图层叠加爆显存 |
 | `maxTiles` | 单数据集瓦片驻留上限，默认 64。叠加多个数据集时建议配合 `totalMaxTiles` 或下调至 32~48 |
+| `maxTriangles` | 单数据集驻留面数软上限，默认不限制。`maxTiles` 只数瓦片个数，精模场景（一块几十万面）建议配 60 万~120 万 |
+| `lodPixelRatioCap` | LOD 判定用屏幕高度的 DPR 上限，默认不截断。见下方「移动端 / 差设备」 |
+| `anisotropyCap` | 各向异性过滤上限，默认取 GPU 最大值。移动端 4 / 8 通常肉眼无差 |
+| `maxTextureSize` | 纹理长边像素上限，默认不限制。手机上 1024 即可，显存降到 1/4 |
 | `maxImageCache` | 原始图集与 leaf 段图像记录的 LRU 缓存容量上限（默认 128），超限自动淘汰旧缓存，防止漫游时内存不断累积 |
 | 纹理引用计数 | 瓦片淘汰时按引用计数释放未被其他瓦片复用的 `Texture` 并调用 `dispose()`，真正归还 GPU 显存 |
 | 几何/材质深度释放 | 瓦片注销时深度遍历对象树，彻底释放 `Mesh`、`Points`（点云/高斯泼溅）以及 `LineSegments`（棱线包）的 `BufferGeometry` 与材质 |
@@ -1201,6 +1219,49 @@ buildAttributes({ smid, box, triangles, floorHeight })  // → S3MFeatureAttribu
 
 实测（上海某区，5 数据集叠加，45 万三角面，1440×900）：**85~90 fps**。
 
+### 移动端 / 差设备
+
+库本身不检测设备，所有刹车都由接入方按档位决定，**默认全部不启用，行为与旧版一致**：
+
+```ts
+// 低端档
+new S3MLayer({
+  lodPixelRatioCap: 2,      // 3x 屏 → 判定高度 2556 压到 ~1704，少约半层细化
+  maxTriangles: 800_000,    // 驻留面数超了就淘汰最久没用的瓦片
+  maxTiles: 40,
+  maxConcurrent: 2,         // 并发 4 → 2：Worker 省了解析，但几何组装与纹理上传仍在主线程
+  anisotropyCap: 4,         // 各向异性 16 → 4
+  maxTextureSize: 1024,     // 纹理长边 2048 → 1024，显存降到 1/4
+});
+```
+
+五个开关性质不同，按「改不改画质」分两类：
+
+| 开关 | 性质 | 观感代价 |
+|---|---|---|
+| `lodPixelRatioCap` | 画质换性能 | 有，见下表 |
+| `maxTextureSize` | 画质换显存 | 贴图略软；1024 与 2048 在手机上肉眼几乎无差 |
+| `anisotropyCap` | 画质换采样成本 | 斜视角立面清晰度略降；4 / 8 通常看不出 |
+| `maxConcurrent` | 纯加载节奏 | 无（只是瓦片到达得慢一点，掉帧少） |
+| `maxTriangles` | 兜底刹车 | 正常无感，见下 |
+
+**为什么 `lodPixelRatioCap` 在手机上收益最大**：LOD 的屏幕空间误差按 `canvasHeight` 物理像素算（与官方 `calcPixFromCam` 同口径），而手机 DPR 3 的绘图缓冲高度比 1440×900 桌面还高——细化层数与瓦片请求会多出近 3 倍，同时片元填充量再乘 2 倍多。截断只吃掉超采样的那部分，代价是每块瓦片在屏幕上铺得更开，几何误差与纹理密度同步变差：
+
+| 力度 | 判定高度（iPhone 15） | 几何误差 / 纹理密度 | 体感 |
+|---|---|---|---|
+| 不截断（默认） | 2556 | 基准 | 最清晰，最费 |
+| `2` | 1704 | ×1.5 / ×1/1.5 | 近景细看略软，整体几乎无感 |
+| `1.5` | 1278 | ×2 / ×1/2 | 立面与地面贴图明显变软 |
+| `1`（等价于按 CSS 高度） | 852 | ×2.84 / ×1/2.84 | 糊，圆形构件出棱角，不建议 |
+
+**`maxTextureSize` 的三个边界**（都需要知道，否会踩意外的坑）：
+
+- **图集不缩放**：S3MBLOCK 的 `AtlasPack` 大图与 leaf 组合画布的 UV 已重映射到子区域，缩放会让整体错位，`createTexture` 里直接跳过。
+- **压缩直传不缩放**：走 `CompressedTexture`（DXT / CRN 转码）时纹理在 GPU 里就是块数据，重采样没意义；真要省显存就在调用侧关掉压缩直传，或接受它已经是 1/4~1/8 的体积。
+- **缩放发生在 Worker 里**：`maxSize` 随解码请求一起传给共享 Worker，主线程零成本；Worker 不可用时才回落到主线程（4096² 减半一次约 10~50ms，属于一次性成本）。
+
+**`maxTriangles` 是兜底刹车而不是画质档位**：没超预算时代码路径不触发，画质零损失；超了只在「不显示」或「位置已被可见子瓦接手」的瓦片里淘汰，所以不会开洞。
+
 ### 批量改单体样式
 
 单体状态（颜色 / 抬高 / 隐藏）写在**每个网格各自一张一维纹理**里，改一个单体就是重写这张纹理。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3m-three",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "description": "SuperMap S3M 三维模型格式的 three.js 渲染内核：浏览器内直接解析 .s3mb 瓦片，无需转 3D Tiles，支持 LOD 调度、白膜/按高度/按单体/动态扫描着色、单体级 GPU 拾取。宿主无关，可单独用于任意 three 场景。",
   "type": "module",
   "repository": {
@@ -41,7 +41,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && node ../../tools/copy-assets.mjs s3m-three && vite build --config vite.browser.config.ts && vite build --config vite.browser.config.ts --mode ext",
+    "build": "tsc -p tsconfig.build.json && node ../../tools/copy-assets.mjs s3m-three && vite build --config vite.worker.config.ts && vite build --config vite.browser.config.ts && vite build --config vite.browser.config.ts --mode ext",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
   },

package/src/core/TextureDecode.ts

@@ -43,6 +43,82 @@ export interface DecodeOptions {
    * flipY 纹理走不了压缩上传（WebGL 对压缩纹理忽略 UNPACK_FLIP_Y），自动回退解码。
    */
   compressed?: boolean;
+  /**
+   * 解码产物长边的像素上限（默认不限制）。
+   *
+   * 手机上 1024 与 2048 肉眼几乎无差，但显存与上传带宽差 4 倍，所以允许接入方封顶。
+   * 只处理 RGBA / WebP 位图产物；**压缩直传（blocks）不缩放**——DXT 块不能重采样，
+   * 而且要直传的场合本就是想省显存。图集（flipY / packed / composed）的 UV 已经
+   * 重映射到子区域，缩放会整体错位，必须由调用方排除，这里不做判断。
+   */
+  maxSize?: number;
+}
+
+/** 2×2 盒式滤波减半（RGBA8）。奇数边丢弃最后一行/列，保证输出尺寸为 ⌊w/2⌋ × ⌊h/2⌋ */
+function halveRgba(
+  src: Uint8Array,
+  w: number,
+  h: number
+): { rgba: Uint8Array; width: number; height: number } {
+  const nw = Math.max(1, w >> 1);
+  const nh = Math.max(1, h >> 1);
+  const out = new Uint8Array(nw * nh * 4);
+  const row = w * 4;
+  for (let y = 0; y < nh; y++) {
+    const r0 = y * 2 * row;
+    const r1 = r0 + row;
+    let o = y * nw * 4;
+    for (let x = 0; x < nw; x++) {
+      const i0 = r0 + x * 8;
+      const i1 = r1 + x * 8;
+      out[o++] = (src[i0] + src[i0 + 4] + src[i1] + src[i1 + 4]) >> 2;
+      out[o++] = (src[i0 + 1] + src[i0 + 5] + src[i1 + 1] + src[i1 + 5]) >> 2;
+      out[o++] = (src[i0 + 2] + src[i0 + 6] + src[i1 + 2] + src[i1 + 6]) >> 2;
+      out[o++] = (src[i0 + 3] + src[i0 + 7] + src[i1 + 3] + src[i1 + 7]) >> 2;
+    }
+  }
+  return { rgba: out, width: nw, height: nh };
+}
+
+/**
+ * 按 `maxSize` 把产物缩到长边不超过上限（逐次 2× 减半，不引入任意比例插值）。
+ * 未配置或没超限时原样返回**同一个对象**，调用方不会多一次拷贝。
+ */
+async function applyMaxSize(
+  data: DecodedTextureData,
+  maxSize: number | undefined
+): Promise<DecodedTextureData> {
+  if (!maxSize || !Number.isFinite(maxSize) || maxSize < 1) return data;
+  const longest = Math.max(data.width, data.height);
+  if (longest <= maxSize) return data;
+
+  // 压缩块不能重采样；真要省显存就在调用侧关掉压缩直传
+  if (data.blocks) return data;
+
+  if (data.bitmap) {
+    const scale = maxSize / longest;
+    const w = Math.max(1, Math.round(data.width * scale));
+    const h = Math.max(1, Math.round(data.height * scale));
+    const resized = await createImageBitmap(data.bitmap, {
+      resizeWidth: w,
+      resizeHeight: h,
+      resizeQuality: 'high',
+    });
+    (data.bitmap as ImageBitmap & { close?: () => void }).close?.();
+    return { ...data, width: w, height: h, bitmap: resized };
+  }
+
+  let rgba = data.rgba;
+  if (!rgba) return data;
+  let w = data.width;
+  let h = data.height;
+  while (Math.max(w, h) > maxSize && w >= 2 && h >= 2) {
+    const next = halveRgba(rgba, w, h);
+    rgba = next.rgba;
+    w = next.width;
+    h = next.height;
+  }
+  return { ...data, width: w, height: h, rgba };
 }
 
 /** 行序翻转（原地）。S3MBLOCK 图集按 GL 方向存储（v=0 在最后一行），解码后要翻一次行 */
@@ -123,6 +199,17 @@ export function expectedDxtByteLength(width: number, height: number, format: 'dx
 export async function decodeTextureData(
   tex: S3MTexture,
   options: DecodeOptions = {}
+): Promise<DecodedTextureData> {
+  // 尺寸收口放在这一层：raw 里各分支（DXT / CRN / raw / WebP）有多个 return，
+  // 统一在外层套一次就不会漏掉任何一条路径。
+  const data = await decodeTextureDataRaw(tex, options);
+  return applyMaxSize(data, options.maxSize);
+}
+
+/** 各解码分支的原样产物（尺寸未收口），由上面的导出函数包一层 */
+async function decodeTextureDataRaw(
+  tex: S3MTexture,
+  options: DecodeOptions = {}
 ): Promise<DecodedTextureData> {
   const empty: DecodedTextureData = {
     kind: 'unsupported(0/0)',

package/src/index.ts

@@ -109,7 +109,7 @@ export type {
 export { buildTileObjects } from './render/GeometryBuilder.js';
 export type { BuildTileOptions, BuildTileResult, TileBuildStats } from './render/GeometryBuilder.js';
 
-export { createTexture, PixelFormat, setMaxAnisotropy } from './render/TextureFactory.js';
+export { createTexture, PixelFormat, setMaxAnisotropy, setMaxTextureSize } from './render/TextureFactory.js';
 export type { DecodedTexture } from './render/TextureFactory.js';
 
 export { resolveTextureKind, dxtPixelFormatOf, TextureCompress } from './core/TextureFormat.js';
@@ -137,6 +137,7 @@ export type {
 export {
   buildOrthoMVP,
   buildBlendedMVP,
+  buildNearScaledMVP,
   extractProjectionMatrix,
   extractNearFar,
   extractFovRadians,

package/src/render/DatasetManager.ts

@@ -20,6 +20,8 @@ export interface S3MDatasetOptions {
   configUrl: string;
   visible?: boolean;
   maxTiles?: number;
+  /** 该数据集驻留三角形总数的软上限（默认跟随图层级设置；都不传则不限制） */
+  maxTriangles?: number;
   lodRangeScale?: number;
   /**
    * 垂直对齐基准（默认 'origin'）：
@@ -164,7 +166,8 @@ export class DatasetManager {
     buildTile: any,
     maxTiles: number,
     maxConcurrent: number,
-    callbacks: DatasetManagerCallbacks
+    callbacks: DatasetManagerCallbacks,
+    maxTriangles: number = Infinity
   ): Promise<S3MDatasetEntry> {
     const existing = this.datasets.get(ds.id);
     if (existing) return existing;
@@ -194,6 +197,7 @@ export class DatasetManager {
       configUrl: ds.configUrl,
       maxTiles: ds.maxTiles ?? maxTiles,
       maxConcurrent: maxConcurrent,
+      maxTriangles: ds.maxTriangles ?? maxTriangles,
       lodRangeScale: ds.lodRangeScale ?? defaultLodRangeScale,
       buildTile: buildTile ?? null,
       useWorker: ds.useWorker,

package/src/render/OrthoProjection.ts

@@ -188,6 +188,64 @@ export function buildOrthoMVP(input: OrthoInput, params: OrthoParams): OrthoMVP
   return { matrix: ortho.projectionMatrix.clone().multiply(view), view };
 }
 
+/**
+ * 只缩小近裁剪面的透视 MVP（视场角、远平面完全不变）。
+ *
+ * 为什么要它：MapLibre 的近裁剪面是**硬编码**的 `nearZ = canvasHeight / 50`（CSS 像素），
+ * 在 zoom 16.5 / 纬度 31° 时 1 px ≈ 0.72 m，也就是近平面离相机约 **13 米**——
+ * 相机推进到楼体 13 米以内，整个楼面就被裁掉，画面变成一片空白。
+ * MapLibre 没有公开 API 改它，所以只能在自定义图层里自己换一个投影矩阵。
+ *
+ * 数学上只动两个元素：标准透视矩阵里只有
+ *   e[10] = -(far + near) / (far - near)
+ *   e[14] = -2 · far · near / (far - near)
+ * 依赖 near/far，其余元素（含 e[0] = 2n/(r-l)、e[5]）都不动 —— 这等价于把
+ * left/right/top/bottom 按 near 的比例等比缩放，所以**视场角逐点重合**，
+ * 缩放后画面与原画面完全一致，只是近处的几何不再被裁。
+ *
+ * 代价是深度缓冲的非线性变陡：near/far 比值每缩小 10 倍，远处可用的深度精度
+ * 就少一截。所以默认不启用，由接入方按「要不要贴脸看」决定。
+ *
+ * @param scale (0, 1) 之间：near' = near × scale。传 1 或 <= 0 表示不处理（返回 null）
+ * @returns null = 输入不是标准透视矩阵 / 参数不可用，调用方应保持原 MVP
+ */
+export function buildNearScaledMVP(input: OrthoInput, scale: number): THREE.Matrix4 | null {
+  if (!(scale > 0) || scale >= 1) return null;
+  const p = input.projectionMatrix;
+  if (!p || p.length < 16) return null;
+
+  const P = new THREE.Matrix4().fromArray(Array.from(p));
+  if (!Number.isFinite(P.determinant()) || P.determinant() === 0) return null;
+  // 只对标准透视投影生效：makePerspective 的 e[11] 恒为 -1，正交矩阵不是
+  if (Math.abs((P.elements[11] as number) + 1) > 1e-6) return null;
+
+  // near/far 优先用宿主给的；缺失就从矩阵反解
+  //   A = -e[10] = (f+n)/(f-n)  →  n = -e[14]/(A+1),  f = n(A+1)/(A-1)
+  let near = input.nearZ != null && input.nearZ > 0 ? input.nearZ : NaN;
+  let far = input.farZ != null && input.farZ > near ? input.farZ : NaN;
+  if (!(near > 0) || !(far > near)) {
+    const A = -P.elements[10];
+    if (!(A > 1)) return null;
+    near = -P.elements[14] / (A + 1);
+    far = (near * (A + 1)) / (A - 1);
+    if (!(near > 0) || !(far > near)) return null;
+  }
+
+  const near2 = near * scale;
+  if (!(near2 > 0) || !(near2 < far)) return null;
+
+  const scaled = P.clone();
+  scaled.elements[10] = -(far + near2) / (far - near2);
+  scaled.elements[14] = (-2 * far * near2) / (far - near2);
+
+  // MVP' = P' × P⁻¹ × MVP：等价于「同一视图矩阵换个投影」，不需要显式解 V
+  const out = scaled.multiply(P.clone().invert()).multiply(new THREE.Matrix4().fromArray(Array.from(input.mvp)));
+  for (let i = 0; i < 16; i++) {
+    if (!Number.isFinite(out.elements[i] as number)) return null;
+  }
+  return out;
+}
+
 /**
  * 平滑过渡正交与透视 MVP：
  * t = 0 时纯透视，t = 1 时纯正交，0 < t < 1 时在投影矩阵元素级平滑线性插值。

package/src/render/S3MViewer.ts

@@ -23,7 +23,7 @@
 import * as THREE from 'three';
 import { S3MTileset, usableGeoBounds } from '../tileset/S3MTileset.js';
 import type { BuildTileFn, TileNode } from '../tileset/S3MTileset.js';
-import { setMaxAnisotropy, setCompressedTexturesSupported, setTextureOffThreadDecode } from './TextureFactory.js';
+import { setMaxAnisotropy, setCompressedTexturesSupported, setTextureOffThreadDecode, setMaxTextureSize as setTextureSizeCap } from './TextureFactory.js';
 import { decodeTextureWithWorker } from '../worker/S3MWorkerClient.js';
 import {
   STYLE,
@@ -219,6 +219,33 @@ export interface S3MViewerOptions {
   useWorker?: boolean;
   /** LOD 切换范围缩放系数（默认 1.0），> 1 更倾向保留粗模，< 1 提前换细模 */
   lodRangeScale?: number;
+  /**
+   * LOD 判定用屏幕高度时的「设备像素比上限」（默认不限制，行为与旧版一致）。
+   *
+   * LOD 的屏幕空间误差按 `canvasHeight` 物理像素算（与官方 `calcPixFromCam` 同口径），
+   * 于是 3x DPR 的手机上判定高度是 2556 而不是 852，细化层数与瓦片数都会远多于桌面。
+   * 传 2 表示「按 CSS 高度 × 2 截断」，砍掉 3x 屏的超采样余量；传 `Infinity` = 不截断。
+   *
+   * 代价：截断会把每块瓦片的屏幕投影放大同样倍数，几何误差与纹理密度同步变差，
+   * 所以默认不启用，由接入方按设备档位自行决定。运行时可用 `setLodPixelRatioCap()` 调整。
+   */
+  lodPixelRatioCap?: number;
+  /**
+   * 每个数据集驻留三角形总数的软上限（默认不限制）。
+   * 见 `S3MTilesetOptions.maxTriangles`：瓦片数管不住的场景（精模、大面片）用这条刹车。
+   */
+  maxTriangles?: number;
+  /**
+   * 各向异性过滤上限（默认不封顶，取 GPU 报的最大值，通常 16）。
+   * 移动端封到 4 或 8 肉眼通常无差，采样成本明显下降。只影响**之后创建**的纹理。
+   */
+  anisotropyCap?: number;
+  /**
+   * 纹理长边像素上限（默认不限制）。
+   * 非图集的 RGBA / WebP 纹理会按 2× 盒式滤波逐次减半到上限内；DXT 压缩直传与
+   * 图集（UV 已重映射）不受影响。手机上 1024 与 2048 肉眼几乎无差，显存差 4 倍。
+   */
+  maxTextureSize?: number;
   /** 自定义瓦片构建器（测试 / 服务端渲染时注入） */
   buildTile?: BuildTileFn | null;
   /**
@@ -495,6 +522,8 @@ export class S3MViewer {
   private _onRequestRepaint: () => void = () => {};
   private _getBearing: (() => number) | undefined;
   private _lodRangeScale = 1.0;
+  /** LOD 判定屏幕高度的 DPR 上限。Infinity = 不截断（默认，行为同旧版） */
+  private _lodPixelRatioCap = Infinity;
 
   /** 宿主请求重画（MapLibre 传 triggerRepaint，纯 three 宿主传自己的渲染循环） */
   private _requestRepaint(): void {
@@ -509,6 +538,8 @@ export class S3MViewer {
     this.options = options;
     this.pickable = options.pickable !== false;
     this._lodRangeScale = options.lodRangeScale ?? 1.0;
+    this._lodPixelRatioCap = options.lodPixelRatioCap ?? Infinity;
+    setTextureSizeCap(options.maxTextureSize ?? Infinity);
     if (options.light) {
       Object.assign(this._lightOptions, options.light);
     }
@@ -543,8 +574,7 @@ export class S3MViewer {
 
     this.uniforms = createSharedUniforms();
     // 纹理解码优先派给共享解析 Worker（崩溃自动回主线程，见 decodeTextureWithWorker）
-    setTextureOffThreadDecode(decodeTextureWithWorker);
-    this.style = { ...DEFAULT_STYLE, ...(options.style ?? {}) };
+    setTextureOffThreadDecode(decodeTextureWithWorker);    this.style = { ...DEFAULT_STYLE, ...(options.style ?? {}) };
     this._styleTarget = { ...this.style };
     this._opacityTransparent = (this.style.opacity ?? 1) < 0.999;
     this._applyStyleUniforms();
@@ -615,7 +645,7 @@ export class S3MViewer {
     this.canvas = canvas;
 
     this.renderer = this._createRenderer(canvas, gl);
-    setMaxAnisotropy(this.renderer.capabilities.getMaxAnisotropy());
+    setMaxAnisotropy(this.renderer.capabilities.getMaxAnisotropy(), this.options.anisotropyCap ?? Infinity);
     this._syncTextureCapabilities(gl);
 
     this.scene = new THREE.Scene();
@@ -657,7 +687,7 @@ export class S3MViewer {
       /* noop */
     }
     this.renderer = this._createRenderer(this.canvas, gl);
-    setMaxAnisotropy(this.renderer.capabilities.getMaxAnisotropy());
+    setMaxAnisotropy(this.renderer.capabilities.getMaxAnisotropy(), this.options.anisotropyCap ?? Infinity);
     this._syncTextureCapabilities(gl);
     this.picker?.dispose();
     this.picker = new Picker(this.renderer);
@@ -854,7 +884,8 @@ export class S3MViewer {
         triggerRepaint: () => {
           this._requestRepaint();
         },
-      }
+      },
+      this.options.maxTriangles ?? Infinity
     );
     return entry;
   }
@@ -3449,6 +3480,99 @@ export class S3MViewer {
     return this._lodRangeScale;
   }
 
+  /* ------------------------------------------------ LOD 屏幕高度 / 面数预算 */
+
+  /** 当前 LOD 判定用的 DPR 上限。Infinity = 不截断 */
+  get lodPixelRatioCap(): number {
+    return this._lodPixelRatioCap;
+  }
+
+  /**
+   * 调整 LOD 判定屏幕高度的 DPR 上限（默认 Infinity = 不截断，行为与旧版一致）。
+   *
+   * 传 2 = 「按 CSS 高度 × 2 截断」：3x DPR 手机上把 2556 的判定高度压到 ~1704，
+   * 少约半层 LOD 的细化，观感几乎无损。传 `Infinity` 恢复原口径。
+   */
+  setLodPixelRatioCap(cap: number): void {
+    const next = cap > 0 ? cap : Infinity;
+    this._lodPixelRatioCap = next;
+    this.options.lodPixelRatioCap = next;
+    this._requestRepaint();
+  }
+
+  /**
+   * 计算 LOD 判定用的屏幕高度（像素）。
+   *
+   * 默认原样返回 `canvasHeight`（绘图缓冲物理像素，官方 `calcPixFromCam` 的口径）。
+   * 只有在 `lodPixelRatioCap` 有限时才去读 `clientHeight` 并按 CSS 高度截断——
+   * 离屏 canvas 没有布局尺寸（clientHeight 为 0）时退回原口径。
+   */
+  private _lodScreenHeight(canvasHeight: number): number {
+    const cap = this._lodPixelRatioCap;
+    if (!Number.isFinite(cap)) return canvasHeight;
+    const cssHeight = this.canvas?.clientHeight ?? 0;
+    if (cssHeight <= 0) return canvasHeight;
+    return Math.min(canvasHeight, cssHeight * cap);
+  }
+
+  /** 当前每个数据集的驻留面数预算。Infinity = 不限制 */
+  get maxTriangles(): number {
+    return this.options.maxTriangles ?? Infinity;
+  }
+
+  /**
+   * 调整每个数据集驻留三角形总数的软上限（默认 Infinity = 不限制）。
+   * 不传 `datasetId` 时对所有已存在数据集立即生效，并作为之后新增数据集的默认值。
+   * 实际裁剪发生在下一次 `update()` 末尾，不会当场掉内容。
+   */
+  setMaxTriangles(n: number, datasetId?: string): void {
+    const next = n > 0 ? n : Infinity;
+    if (datasetId) {
+      const entry = this.datasets.get(datasetId);
+      if (entry?.tileset) entry.tileset.setMaxTriangles(next);
+    } else {
+      this.options.maxTriangles = next;
+      for (const entry of this.datasets.values()) {
+        if (entry.tileset) entry.tileset.setMaxTriangles(next);
+      }
+    }
+  }
+
+  /** 当前各向异性过滤上限。Infinity = 不封顶 */
+  get anisotropyCap(): number {
+    return this.options.anisotropyCap ?? Infinity;
+  }
+
+  /**
+   * 调整各向异性过滤上限（默认 Infinity = 取 GPU 最大值）。
+   * 只影响**之后创建**的纹理——已上传的纹理需要重新上传才会变，代价远大于收益，
+   * 所以切换档位请在建图层前决定，或接受「新瓦片按新档位、旧瓦片保持原样」。
+   */
+  setAnisotropyCap(cap: number): void {
+    const next = Number.isFinite(cap) && cap > 0 ? Math.max(1, cap) : Infinity;
+    this.options.anisotropyCap = next;
+    const gpuMax = this.renderer?.capabilities.getMaxAnisotropy?.() ?? 1;
+    setMaxAnisotropy(gpuMax, next);
+    this._requestRepaint();
+  }
+
+  /** 当前纹理长边像素上限。Infinity = 不限制 */
+  get maxTextureSize(): number {
+    return this.options.maxTextureSize ?? Infinity;
+  }
+
+  /**
+   * 调整纹理长边像素上限（默认 Infinity = 不限制）。
+   * 只影响之后解码的纹理；非图集的 RGBA / WebP 产物按 2× 减半逼近上限。
+   * 注意这是**模块级**设置（图集 / 解码 Worker 共享），多 viewer 实例会互相覆盖。
+   */
+  setMaxTextureSize(n: number): void {
+    const next = Number.isFinite(n) && n >= 1 ? n : Infinity;
+    this.options.maxTextureSize = next;
+    setTextureSizeCap(next);
+    this._requestRepaint();
+  }
+
   /**
    * 动态调整 LOD 切换范围缩放系数。
    * scale > 1 时倾向保留粗模（降低瓦片请求与面数）；scale < 1 时提前细化加载高精瓦片。
@@ -3529,6 +3653,9 @@ export class S3MViewer {
     // 弧度视场角。MapLibre v5 起 transform.fov 是「度」，当弧度用会让
     // LOD 屏幕误差算大 20% 以上（提前加载更细的瓦片）—— 换算由宿主负责。
     let tilesetChanged = false;
+    // LOD 判定高度：默认就是绘图缓冲高度（物理像素，与官方口径一致）；
+    // 配了 lodPixelRatioCap 才按 CSS 高度截断，默认状态下这两行不产生任何开销。
+    const lodScreenHeight = this._lodScreenHeight(opts.canvasHeight);
     for (const entry of this.datasets.values()) {
       if (!entry.visible || !entry.tileset) continue;
       const local: [number, number, number] = [
@@ -3536,7 +3663,7 @@ export class S3MViewer {
         camEnu[1] - entry.offset[1],
         camEnu[2] - entry.offset[2],
       ];
-      if (entry.tileset.update(local, opts.fovRad, opts.canvasHeight)) {
+      if (entry.tileset.update(local, opts.fovRad, lodScreenHeight)) {
         tilesetChanged = true;
       }
     }

package/src/render/TextureFactory.ts

@@ -17,8 +17,28 @@ export { PixelFormat } from '../core/TextureFormat.js';
 /** 由 S3MLayer 在拿到 GL 上下文后注入，用于斜视角下保持纹理清晰 */
 let maxAnisotropy = 1;
 
-export function setMaxAnisotropy(n: number): void {
+/**
+ * 各向异性过滤的**上限**（默认 Infinity = 不封顶，取 GPU 报的最大值）。
+ *
+ * 各向异性对斜视角立面清晰度的提升比提高分辨率更直接，所以默认全量启用；
+ * 但它每像素要多采样，移动端 GPU 上封到 4 或 8 通常肉眼无差、成本明显下降。
+ * 由 `setMaxAnisotropy(gpuMax, cap)` 一起注入，接入方通过 `anisotropyCap` 配置。
+ */
+let anisotropyCap = Infinity;
+
+export function setMaxAnisotropy(n: number, cap = Infinity): void {
   maxAnisotropy = Math.max(1, n | 0);
+  anisotropyCap = Number.isFinite(cap) && cap > 0 ? Math.max(1, cap) : Infinity;
+}
+
+/**
+ * 纹理长边像素上限（默认 Infinity = 不限制）。
+ * 只作用于非图集的 RGBA / WebP 产物，见 `core/TextureDecode.ts` 的 `maxSize`。
+ */
+let maxTextureSize = Infinity;
+
+export function setMaxTextureSize(n: number): void {
+  maxTextureSize = Number.isFinite(n) && n >= 1 ? n : Infinity;
 }
 
 /**
@@ -42,23 +62,28 @@ export interface DecodedTexture {
 /**
  * 注入「离线解码」实现（S3MViewer 装配：走共享解析 Worker）。
  * 返回 null = Worker 不可用 / 崩溃，createTexture 自动退回主线程 decodeTextureData。
+ * `maxSize` 一并带过去，缩放也在 Worker 里做（同样是 CPU 活）。
  */
 let offThreadDecode:
-  | ((tex: S3MTexture, compressed: boolean) => Promise<DecodedTextureData | null>)
+  | ((tex: S3MTexture, compressed: boolean, maxSize?: number) => Promise<DecodedTextureData | null>)
   | null = null;
 
 export function setTextureOffThreadDecode(
-  fn: ((tex: S3MTexture, compressed: boolean) => Promise<DecodedTextureData | null>) | null
+  fn: ((tex: S3MTexture, compressed: boolean, maxSize?: number) => Promise<DecodedTextureData | null>) | null
 ): void {
   offThreadDecode = fn;
 }
 
-async function decodeTexture(tex: S3MTexture, compressed: boolean): Promise<DecodedTextureData> {
+async function decodeTexture(
+  tex: S3MTexture,
+  compressed: boolean,
+  maxSize: number
+): Promise<DecodedTextureData> {
   if (offThreadDecode) {
-    const viaWorker = await offThreadDecode(tex, compressed);
+    const viaWorker = await offThreadDecode(tex, compressed, maxSize);
     if (viaWorker) return viaWorker;
   }
-  return decodeTextureData(tex, { compressed });
+  return decodeTextureData(tex, { compressed, maxSize });
 }
 
 function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
@@ -68,7 +93,7 @@ function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
   tex.minFilter = THREE.LinearMipmapLinearFilter;
   tex.generateMipmaps = true;
   // 各向异性过滤对斜视角立面清晰度的提升比提高分辨率更直接
-  tex.anisotropy = maxAnisotropy;
+  tex.anisotropy = anisotropyCap === Infinity ? maxAnisotropy : Math.min(maxAnisotropy, anisotropyCap);
   if (srgb) tex.colorSpace = THREE.SRGBColorSpace;
   tex.flipY = false;
   tex.needsUpdate = true;
@@ -103,7 +128,9 @@ export async function createTexture(tex: S3MTexture | null | undefined): Promise
 
   // 压缩直传只在「宿主 GL 支持 + 非图集」时开：图集要 flipY / 无 mip，压缩上传做不了翻行
   const wantCompressed = compressedTexturesSupported && !isAtlas;
-  const data = await decodeTexture(tex, wantCompressed);
+  // 尺寸上限同样跳过图集：UV 已重映射到子区域，缩放会让整体错位
+  const sizeCap = isAtlas ? Infinity : maxTextureSize;
+  const data = await decodeTexture(tex, wantCompressed, sizeCap);
 
   if (!data.rgba && !data.blocks && !data.bitmap) {
     if (data.error) {