s3m-three 0.4.27 → 0.4.29

package/docs/API.md

@@ -175,6 +175,7 @@ new S3MViewer(options?: S3MViewerOptions)
 | `lodRangeScale` | `number` | `1.0` | LOD 切换距离缩放系数，> 1 更倾向保留粗模，< 1 提前细化 |
 | `lodTransition` | `'binary' \| 'incremental'` | `'binary'` | LOD 细化过渡策略。`'binary'`（默认）：整节点二值切换，所有子瓦片全部就绪或失败后整块替换；`'incremental'`：增量细化（primary / fallback 双列表 + LEQUAL 深度推移），子瓦片就绪一个显示一个，未就绪区域由最近父瓦片（fallback）垫底填充，消除整块跳变与慢 child 阻塞，极端角度接缝无缝衔接且不出洞 |
 | `fallbackOffset` | `{ factor?: number; units?: number }` | `{ factor: 1, units: 2 }` | 增量细化模式下 fallback 兜底瓦片的材质深度偏移系数，向远处推移深度配合 gl.LEQUAL 消除共面 z-fighting |
+| `cullRefine` | `boolean` | `false` | 细化视锥剔除（第一期，Issue #25）。开启后视野外的瓦片不再请求与细化子瓦片，大幅减少转头与大范围场景下的无效下载、Worker 解码与显存上传。默认 `false`（不变式 ①，保持全向加载） |
 | `lodPixelRatioCap` | `number` | `Infinity` | LOD 判定屏幕高度的 **DPR 上限**（不截断）。默认按 `canvasHeight` 物理像素算，与官方 `calcPixFromCam` 同口径；3x DPR 手机上由此会多细化、多拉瓦片，传 `2` 即按「CSS 高度 × 2」截断 |
 | `anisotropyCap` | `number` | `Infinity` | 各向异性过滤上限（不封顶 = 取 GPU 最大值，通常 16）。移动端封到 4 / 8 肉眼通常无差，采样成本明显下降。**图层级**：运行时 `setAnisotropyCap()` 会立刻应用到已上传纹理（改采样参数 + 重传，不重解码、不重载瓦片），图集纹理恒为 1 |
 | `maxTextureSize` | `number` | `Infinity` | 纹理长边像素上限（不限制）。非图集的 RGBA / WebP 产物按 2× 盒式滤波减半到上限内；DXT 压缩直传与图集不受影响。**图层级**，但只影响之后解码的纹理（已解码的不重解） |
@@ -532,6 +533,8 @@ setLodRangeScale(scale: number, datasetId?: string): void
 readonly lodRangeScale: number
 readonly lodTransition: 'binary' | 'incremental'
 setLodTransition(mode: 'binary' | 'incremental'): void
+setCullRefine(enabled: boolean): void             // 细化视锥剔除开关，默认 false
+readonly cullRefine: boolean
 setLodPixelRatioCap(cap: number): void        // Infinity = 不截断（默认）
 readonly lodPixelRatioCap: number
 setMaxTriangles(n: number, datasetId?: string): void   // Infinity = 不限制（默认）

package/package.json

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

package/src/core/S3M1Parser.ts

@@ -62,6 +62,7 @@
  */
 import { BinaryReader } from './BinaryReader.js';
 import type {
+  Geode,
   GeoPackageEntry,
   GroupNode,
   IndexPackage,
@@ -124,7 +125,13 @@ interface XmlMaterial {
   addressMode?: { u: number; v: number };
 }
 
-interface XmlLod {
+export interface XmlGeode {
+  geoName: string;
+  matrix: number[];
+}
+
+export interface XmlLod {
+  geodes?: XmlGeode[];
   geoNames: string[];
   matrix: number[];
   childTile: string;
@@ -158,7 +165,7 @@ function rangeModeOf(text: string | null): number {
   return 1;
 }
 
-function parseXmlLods(xml: string): XmlLod[] {
+export function parseXmlLods(xml: string): XmlLod[] {
   const blocks = [...xml.matchAll(/<(?:[A-Za-z0-9_-]+:)?PagedLOD[^>]*>([\s\S]*?)<\/(?:[A-Za-z0-9_-]+:)?PagedLOD>/gi)];
   const out: XmlLod[] = [];
   for (const b of blocks) {
@@ -180,6 +187,39 @@ function parseXmlLods(xml: string): XmlLod[] {
       radius: num(tag(sphere, 'radius')),
     });
   }
+  // 兜底：S3M 1.x 叶子瓦片没有 <PagedLOD>，<PageLods> 内部直接是 <Geode>
+  if (out.length === 0) {
+    const pageLodsBlock = /<(?:[A-Za-z0-9_-]+:)?PageLods[^>]*>([\s\S]*?)<\/(?:[A-Za-z0-9_-]+:)?PageLods>/i.exec(xml);
+    const scope = pageLodsBlock ? pageLodsBlock[1] : xml;
+    const geodeBlocks = [...scope.matchAll(/<(?:[A-Za-z0-9_-]+:)?Geode[^>]*>([\s\S]*?)<\/(?:[A-Za-z0-9_-]+:)?Geode>/gi)];
+    if (geodeBlocks.length > 0) {
+      const geodes: XmlGeode[] = [];
+      for (const gb of geodeBlocks) {
+        const gs = gb[1];
+        const gName = tag(gs, "GeoName") ?? "";
+        const matStr = tag(gs, "GeoDeModMatrix");
+        const mat = (matStr ?? "1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1")
+          .split(",")
+          .map((x) => parseFloat(x.trim()))
+          .filter((x) => Number.isFinite(x));
+        geodes.push({
+          geoName: gName,
+          matrix: mat.length === 16 ? mat : [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
+        });
+      }
+      out.push({
+        geoNames: geodes.map((g) => g.geoName).filter(Boolean),
+        matrix: geodes[0]?.matrix ?? [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
+        geodes,
+        childTile: "",
+        rangeMode: rangeModeOf(null), // 1 = 屏幕像素
+        rangeValue: 0,
+        center: { x: 0, y: 0, z: 0 },
+        radius: 0,
+      });
+    }
+  }
+
   return out;
 }
 
@@ -645,6 +685,108 @@ function readTextures(br: BinaryReader, texSize: number): Record<string, S3MText
 let warnedV1Attrs = false;
 let warnedQuantBox = false;
 
+function computeLodBoundingSphere(
+  geodes: { matrix: number[]; skeletonNames: string[] }[],
+  meshes: MeshRecord[]
+): { center: { x: number; y: number; z: number }; radius: number } | null {
+  const meshMap = new Map(meshes.map((m) => [`SuperMapCache#${m.geoName}`, m]));
+  let minX = Infinity, maxX = -Infinity;
+  let minY = Infinity, maxY = -Infinity;
+  let minZ = Infinity, maxZ = -Infinity;
+  let totalPoints = 0;
+
+  for (const geode of geodes) {
+    const mat = geode.matrix;
+    const isIdentity =
+      !mat ||
+      (mat[0] === 1 && mat[1] === 0 && mat[2] === 0 && mat[3] === 0 &&
+       mat[4] === 0 && mat[5] === 1 && mat[6] === 0 && mat[7] === 0 &&
+       mat[8] === 0 && mat[9] === 0 && mat[10] === 1 && mat[11] === 0 &&
+       mat[12] === 0 && mat[13] === 0 && mat[14] === 0 && mat[15] === 1);
+
+    for (const name of geode.skeletonNames) {
+      const mesh = meshMap.get(name);
+      if (!mesh || !mesh.position) continue;
+      const pos = mesh.position;
+      totalPoints += pos.length / 3;
+
+      if (isIdentity) {
+        for (let i = 0; i < pos.length; i += 3) {
+          const x = pos[i]!, y = pos[i + 1]!, z = pos[i + 2]!;
+          if (x < minX) minX = x; if (x > maxX) maxX = x;
+          if (y < minY) minY = y; if (y > maxY) maxY = y;
+          if (z < minZ) minZ = z; if (z > maxZ) maxZ = z;
+        }
+      } else {
+        const m0 = mat[0]!, m1 = mat[1]!, m2 = mat[2]!;
+        const m4 = mat[4]!, m5 = mat[5]!, m6 = mat[6]!;
+        const m8 = mat[8]!, m9 = mat[9]!, m10 = mat[10]!;
+        const m12 = mat[12]!, m13 = mat[13]!, m14 = mat[14]!;
+        for (let i = 0; i < pos.length; i += 3) {
+          const x = pos[i]!, y = pos[i + 1]!, z = pos[i + 2]!;
+          const tx = m0 * x + m4 * y + m8 * z + m12;
+          const ty = m1 * x + m5 * y + m9 * z + m13;
+          const tz = m2 * x + m6 * y + m10 * z + m14;
+          if (tx < minX) minX = tx; if (tx > maxX) maxX = tx;
+          if (ty < minY) minY = ty; if (ty > maxY) maxY = ty;
+          if (tz < minZ) minZ = tz; if (tz > maxZ) maxZ = tz;
+        }
+      }
+    }
+  }
+
+  if (totalPoints === 0 || !Number.isFinite(minX)) return null;
+
+  const cx = (minX + maxX) * 0.5;
+  const cy = (minY + maxY) * 0.5;
+  const cz = (minZ + maxZ) * 0.5;
+
+  let maxR2 = 0;
+  for (const geode of geodes) {
+    const mat = geode.matrix;
+    const isIdentity =
+      !mat ||
+      (mat[0] === 1 && mat[1] === 0 && mat[2] === 0 && mat[3] === 0 &&
+       mat[4] === 0 && mat[5] === 1 && mat[6] === 0 && mat[7] === 0 &&
+       mat[8] === 0 && mat[9] === 0 && mat[10] === 1 && mat[11] === 0 &&
+       mat[12] === 0 && mat[13] === 0 && mat[14] === 0 && mat[15] === 1);
+
+    for (const name of geode.skeletonNames) {
+      const mesh = meshMap.get(name);
+      if (!mesh || !mesh.position) continue;
+      const pos = mesh.position;
+
+      if (isIdentity) {
+        for (let i = 0; i < pos.length; i += 3) {
+          const dx = pos[i]! - cx, dy = pos[i + 1]! - cy, dz = pos[i + 2]! - cz;
+          const r2 = dx * dx + dy * dy + dz * dz;
+          if (r2 > maxR2) maxR2 = r2;
+        }
+      } else {
+        const m0 = mat[0]!, m1 = mat[1]!, m2 = mat[2]!;
+        const m4 = mat[4]!, m5 = mat[5]!, m6 = mat[6]!;
+        const m8 = mat[8]!, m9 = mat[9]!, m10 = mat[10]!;
+        const m12 = mat[12]!, m13 = mat[13]!, m14 = mat[14]!;
+        for (let i = 0; i < pos.length; i += 3) {
+          const x = pos[i]!, y = pos[i + 1]!, z = pos[i + 2]!;
+          const tx = m0 * x + m4 * y + m8 * z + m12;
+          const ty = m1 * x + m5 * y + m9 * z + m13;
+          const tz = m2 * x + m6 * y + m10 * z + m14;
+          const dx = tx - cx, dy = ty - cy, dz = tz - cz;
+          const r2 = dx * dx + dy * dy + dz * dz;
+          if (r2 > maxR2) maxR2 = r2;
+        }
+      }
+    }
+  }
+
+  const radius = Math.sqrt(maxR2);
+  return {
+    center: { x: cx, y: cy, z: cz },
+    radius: radius > 0 ? radius : 0.001,
+  };
+}
+
 export async function parseS3M1(arrayBuffer: ArrayBuffer, options: ParseS3M1Options = {}): Promise<ParsedTile> {
   const inflate = options.inflate ?? defaultInflate;
   const r = new BinaryReader(arrayBuffer);
@@ -770,17 +912,45 @@ export async function parseS3M1(arrayBuffer: ArrayBuffer, options: ParseS3M1Opti
   const xmlLods = parseXmlLods(xml);
   const pageLods: PageLOD[] = [];
   xmlLods.forEach((lod, i) => {
-    const named = lod.geoNames.map((n) => keyOf.get(n)).filter((k): k is string => !!k);
-    // 名字对不上时退回位置匹配，并让上层有机会发现（宁可少一个 LOD 也不要挂错球）
-    const fallback = meshes[i] ? [`SuperMapCache#${meshes[i].geoName}`] : [];
-    const skeletonNames = named.length ? [...new Set(named)] : fallback;
-    if (!skeletonNames.length) return;
+    let geodes: Geode[];
+    if (lod.geodes && lod.geodes.length > 0) {
+      geodes = lod.geodes
+        .map((g, gi) => {
+          const key = keyOf.get(g.geoName);
+          const fallback = meshes[gi] ? [`SuperMapCache#${meshes[gi].geoName}`] : [];
+          const skeletonNames = key ? [key] : fallback;
+          return {
+            matrix: g.matrix,
+            skeletonNames,
+          };
+        })
+        .filter((g) => g.skeletonNames.length > 0);
+    } else {
+      const named = lod.geoNames.map((n) => keyOf.get(n)).filter((k): k is string => !!k);
+      // 名字对不上时退回位置匹配，并让上层有机会发现（宁可少一个 LOD 也不要挂错球）
+      const fallback = meshes[i] ? [`SuperMapCache#${meshes[i].geoName}`] : [];
+      const skeletonNames = named.length ? [...new Set(named)] : fallback;
+      geodes = skeletonNames.length ? [{ matrix: lod.matrix, skeletonNames }] : [];
+    }
+    if (!geodes.length) return;
+
+    let center = { ...lod.center };
+    let radius = lod.radius;
+    // 缺包围球（如叶子瓦片）时，从网格顶点实时计算真实几何包围球
+    if (radius <= 0) {
+      const computed = computeLodBoundingSphere(geodes, meshes);
+      if (computed) {
+        center = computed.center;
+        radius = computed.radius;
+      }
+    }
+
     pageLods.push({
       rangeValue: lod.rangeValue,
       rangeMode: lod.rangeMode,
-      boundingSphere: { center: { ...lod.center }, radius: lod.radius },
+      boundingSphere: { center, radius },
       childTile: lod.childTile,
-      geodes: [{ matrix: lod.matrix, skeletonNames }],
+      geodes,
     });
   });
   const groupNode: GroupNode = { pageLods };

package/src/index.ts

@@ -69,7 +69,7 @@ export type { GeoAdapter, WorldCoordinateResult } from './render/GeoAdapter.js';
 
 // —— 瓦片层
 export { S3MTileset, parseConfigText, classifyDatasetKind } from './tileset/S3MTileset.js';
-export type { TileNode, BuildTileFn, S3MTilesetOptions, DatasetKind } from './tileset/S3MTileset.js';
+export type { TileNode, BuildTileFn, S3MTilesetOptions, DatasetKind, TileVisibilityTest } from './tileset/S3MTileset.js';
 
 // —— 渲染层
 export { S3MViewer } from './render/S3MViewer.js';

package/src/render/S3MViewer.ts

@@ -22,7 +22,7 @@
  */
 import * as THREE from 'three';
 import { S3MTileset, usableGeoBounds } from '../tileset/S3MTileset.js';
-import type { BuildTileFn, TileNode } from '../tileset/S3MTileset.js';
+import type { BuildTileFn, TileNode, TileVisibilityTest } from '../tileset/S3MTileset.js';
 import type { AuthenticateFn } from '../core/AuthFetch.js';
 import { setSplatViewport } from './GeometryBuilder.js';
 import { setMaxAnisotropy, setCompressedTexturesSupported, setTextureOffThreadDecode, setMaxTextureSize as setTextureSizeCap, applyAnisotropyCap } from './TextureFactory.js';
@@ -430,6 +430,11 @@ export class S3MViewer {
   private _getBearing: (() => number) | undefined;
   /** 鉴权适配（全局默认），构造时注入 */
   private readonly _authenticate: AuthenticateFn | undefined;
+  /** 视锥细化剔除开关，默认 false（issue #25 第一期） */
+  private _cullRefine = false;
+  /** 逐帧复用：视锥与球心测试用的临时向量，避免每帧 new */
+  private _frustum?: THREE.Frustum;
+  private _cullTestVec?: THREE.Vector3;
   private _lodRangeScale = 1.0;
   /** 图层级降级策略，数据集可覆盖，见 `S3MViewerOptions.unsupported` */
   private readonly _unsupported: UnsupportedPolicy;
@@ -464,6 +469,8 @@ export class S3MViewer {
     this._lodRangeScale = options.lodRangeScale ?? 1.0;
     this._unsupported = options.unsupported ?? 'warn';
     this._lodPixelRatioCap = options.lodPixelRatioCap ?? Infinity;
+    // 视锥剔除细化默认关闭：这是可选策略不是 bug 修复，不传就走全向加载的老路径
+    this._cullRefine = options.cullRefine === true || options.frustumCullRefine === true;
     // 瓦片级放置默认开启：旧行为是拿单一常量切平面拟合随纬度变化的墨卡托比例，属于 bug 修复，
     // 所以默认值跟着改（见 AGENTS.md 不变式 ①）。显式传 false 仍可回退。
     this._perTilePlacement = options.perTilePlacement !== false;
@@ -1737,16 +1744,29 @@ export class S3MViewer {
 
   private _registerTile(node: TileNode, entry: S3MDatasetEntry): void {
     // 必须在 add / updateMatrixWorld 之前设置：后者会拿当前 matrix 算 matrixWorld 并缓存
-    if (this._perTilePlacement && node.sphere) {
-      this._applyTilePlacement(node.group, node.sphere.center, entry);
-    } else {
+    //
+    // ★ 触发条件**不能**是「有没有包围球」。S3M 1.x 的叶子瓦片 XML 是
+    //   `<PageLods><Geode>`（外面没有 `<PagedLOD>` 包装），`parseXmlLods` 解析出来
+    //   pageLods 为空 → sphere 为 null。而 `entry.root` 上挂着 align 算出来的整体偏移
+    //   （索菲亚教堂是 heightRange.min = 119.84），那个偏移是靠 placement 里的
+    //   `- datasetOffset` 抵消的。少摆一块，这块就带着偏移显示 —— 实测 L23 整层
+    //   因此沉到地下 120 m，且 `localZ - worldZ` 恒等于偏移量。
+    //   缺球时用几何包围盒中心兜底；连几何都没有就退回旧口径。
+    const center = node.sphere?.center ?? this._localCenterOf(node.group);
+    if (this._perTilePlacement && center) {
+      this._applyTilePlacement(node.group, center, entry);
+    }
+    // 上面没摆成（关掉本功能 / 缺锚点 / 几何为空）时 matrixAutoUpdate 仍是 true，走旧口径
+    if (node.group.matrixAutoUpdate) {
       const sceneAnchor = this.sceneAnchor;
       if (sceneAnchor) {
         const sEast = sceneAnchor.meterInMercatorEast ?? sceneAnchor.meterInMercator;
         const sNorth = sceneAnchor.meterInMercatorNorth ?? sceneAnchor.meterInMercator;
         const sUp = sceneAnchor.meterInMercatorUp ?? sEast;
-        const center = node.sphere ? ([node.sphere.center.x, node.sphere.center.y, node.sphere.center.z] as const) : ([0, 0, 0] as const);
-        this._updateTileUniforms(node.group, center, [1.0 / sEast, 1.0 / sNorth, 1.0 / sUp]);
+        const c = node.sphere
+          ? ([node.sphere.center.x, node.sphere.center.y, node.sphere.center.z] as const)
+          : ([0, 0, 0] as const);
+        this._updateTileUniforms(node.group, c, [1.0 / sEast, 1.0 / sNorth, 1.0 / sUp]);
       }
     }
     entry.root.add(node.group);
@@ -1820,6 +1840,22 @@ export class S3MViewer {
     }
   }
 
+  /**
+   * 瓦片几何在**数据集局部 ENU** 里的包围盒中心，给没有包围球的瓦片兜底。
+   *
+   * 调用时机固定在 `entry.root.add()` 之前：此时 group 还没挂到 root 上、matrix 还是
+   * 单位阵，`setFromObject` 得到的就是顶点自己的坐标系，正好是摆放要的枢轴。
+   * 挂上 root 之后再算会带上 root 的 offset，枢轴就偏了。
+   */
+  private _localCenterOf(group: THREE.Object3D): { x: number; y: number; z: number } | null {
+    if (!group.children.length) return null;
+    const box = new THREE.Box3().setFromObject(group);
+    if (box.isEmpty()) return null;
+    const c = box.getCenter(new THREE.Vector3());
+    if (!Number.isFinite(c.x) || !Number.isFinite(c.y) || !Number.isFinite(c.z)) return null;
+    return { x: c.x, y: c.y, z: c.z };
+  }
+
   /**
    * 把一块瓦片摆到「用它自己中心纬度算出的尺度」上（`perTilePlacement` 开启时才走）。
    *
@@ -3243,6 +3279,28 @@ export class S3MViewer {
     this._requestRepaint();
   }
 
+  /** 当前是否开启细化视锥剔除（第一期，issue #25） */
+  get cullRefine(): boolean {
+    return this._cullRefine;
+  }
+
+  set cullRefine(enabled: boolean) {
+    this.setCullRefine(enabled);
+  }
+
+  /**
+   * 开关细化视锥剔除（第一期，issue #25）。
+   *
+   * 只影响「要不要继续细化」：视野外的瓦片不再 `_enqueue` 子瓦片，
+   * 已加载的瓦片、`lastSeen` 刷新、淘汰与显存预算都不动。
+   */
+  setCullRefine(enabled: boolean): void {
+    const val = !!enabled;
+    if (this._cullRefine === val) return;
+    this._cullRefine = val;
+    this._requestRepaint();
+  }
+
   /**
    * 动态调整 LOD 切换范围缩放系数。
    * scale > 1 时倾向保留粗模（降低瓦片请求与面数）；scale < 1 时提前细化加载高精瓦片。
@@ -3364,6 +3422,15 @@ export class S3MViewer {
     // LOD 判定高度：默认就是绘图缓冲高度（物理像素，与官方口径一致）；
     // 配了 lodPixelRatioCap 才按 CSS 高度截断，默认状态下这两行不产生任何开销。
     const lodScreenHeight = this._lodScreenHeight(opts.canvasHeight);
+
+    let frustum: THREE.Frustum | null = null;
+    let cullTestVec: THREE.Vector3 | null = null;
+    if (this._cullRefine) {
+      frustum = this._frustum ??= new THREE.Frustum();
+      frustum.setFromProjectionMatrix(mvp);
+      cullTestVec = this._cullTestVec ??= new THREE.Vector3();
+    }
+
     for (const entry of this.datasets.values()) {
       if (!entry.visible || !entry.tileset) continue;
       const local: [number, number, number] = [
@@ -3371,7 +3438,45 @@ export class S3MViewer {
         camEnu[1] - entry.offset[1],
         camEnu[2] - entry.offset[2],
       ];
-      if (entry.tileset.update(local, opts.fovRad, lodScreenHeight)) {
+
+      let isVisible: TileVisibilityTest | undefined;
+      if (frustum && cullTestVec) {
+        const f = frustum;
+        const v = cullTestVec;
+        const entryOffset = entry.offset;
+        isVisible = (center, radius, node) => {
+          let worldX: number;
+          let worldY: number;
+          let worldZ: number;
+          let worldRadius = radius;
+
+          if (node?.group && node.group.parent) {
+            v.set(center.x, center.y, center.z).applyMatrix4(node.group.matrixWorld);
+            worldX = v.x;
+            worldY = v.y;
+            worldZ = v.z;
+            worldRadius *= node.group.matrixWorld.getMaxScaleOnAxis();
+          } else {
+            worldX = center.x + entryOffset[0];
+            worldY = center.y + entryOffset[1];
+            worldZ = center.z + entryOffset[2];
+          }
+
+          // 边界余量：按球半径的 15% 且至少保留 10 米余量，避免视野边缘临界抖动与转头瞬间缺块
+          const margin = Math.max(worldRadius * 0.15, 10);
+          const limit = -(worldRadius + margin);
+
+          const planes = f.planes;
+          for (let i = 0; i < 6; i++) {
+            const p = planes[i];
+            const dist = p.normal.x * worldX + p.normal.y * worldY + p.normal.z * worldZ + p.constant;
+            if (dist < limit) return false;
+          }
+          return true;
+        };
+      }
+
+      if (entry.tileset.update(local, opts.fovRad, lodScreenHeight, isVisible)) {
         tilesetChanged = true;
       }
     }

package/src/render/viewer/types.ts

@@ -171,6 +171,16 @@ export interface S3MViewerOptions {
    * 见 `render/tilePlacement.ts` 的文件头。
    */
   perTilePlacement?: boolean;
+  /**
+   * 视锥剔除细化（第一期，默认 false，见 issue #25）。
+   * 开启后视野外的瓦片不再继续请求/细化子瓦片，大幅减少转头时的无效下载、解析与上传。
+   *
+   * 这不是 bug 修复，属于「另一种可选策略」，所以默认关闭（AGENTS.md 不变式 ①）：
+   * 不传时全向加载的老路径逐字不变。
+   */
+  cullRefine?: boolean;
+  /** `cullRefine` 的别名，两者取或 */
+  frustumCullRefine?: boolean;
   /**
    * 是否对瓦片逐顶点烘焙精确 Web 墨卡托偏移（消除全球大尺度下的视差游动/呼吸效应）。
    * - undefined（默认）：自动判定。当瓦片集根节点包围球半径 > 25 km 时自动启用，<= 25 km 时保持关闭（逐字节保持原有 ENU 顶点缓冲不变）。

package/src/tileset/S3MTileset.ts

@@ -289,6 +289,13 @@ export interface TileNode {
   stats?: { meshes: number; vertices: number; triangles: number; memory?: number };
 }
 
+/** 视锥可见性判定回调（返回 false 表示瓦片完全在视锥外，应跳过进一步细化） */
+export type TileVisibilityTest = (
+  center: { x: number; y: number; z: number },
+  radius: number,
+  node?: TileNode
+) => boolean;
+
 /** 瓦片构建器可注入，用于测试 / 服务端渲染（此时不需要 three） */
 export type BuildTileFn = (
   tile: ParsedTile,
@@ -951,6 +958,15 @@ export class S3MTileset {
         victim = node;
         continue;
       }
+      // 可见性优先于时间戳：没有包围球的瓦片算不出距离，`lastSeen` 天然比别的瓦片旧，
+      // 只看时间戳会把「正在显示」的那块先踢掉（开洞 → 回补 → 再踢 = 闪）。
+      // 只有不可见的候选分不出来时，才轮到 lastSeen / distance 决定。
+      const nodeVisible = node.group.visible ? 1 : 0;
+      const victimVisible = victim.group.visible ? 1 : 0;
+      if (nodeVisible !== victimVisible) {
+        if (nodeVisible < victimVisible) victim = node;
+        continue;
+      }
       const a = node.lastSeen ?? -1;
       const b = victim.lastSeen ?? -1;
       if (a < b || (a === b && (node.distance ?? 0) > (victim.distance ?? 0))) victim = node;
@@ -1507,12 +1523,22 @@ export class S3MTileset {
    * @param screenHeight 视口像素高度
    * @returns 瓦片加载队列或可见性是否发生变化
    */
-  update(camEnu: [number, number, number], fovRad: number, screenHeight: number): boolean {
+  update(
+    camEnu: [number, number, number],
+    fovRad: number,
+    screenHeight: number,
+    isVisible?: TileVisibilityTest
+  ): boolean {
     this._frame++;
     let hasChanges = false;
 
     for (const node of this.nodes.values()) {
       if (!node.sphere) {
+        // 没有包围球（S3M 1.x 叶子瓦片：XML 是 `<PageLods><Geode>`，没有 PagedLOD）时
+        // 算不出距离，但**仍要记「最近用过」**：`lastSeen` 恒为 undefined 会让它在
+        // `_pickVictim` 里永远排最前（`?? -1`），硬上限一触发 `allowUncovered`，
+        // 第一块被踢掉的就是正在显示的那块 —— 画面立刻一个洞，下一帧又加载回来。
+        node.lastSeen = this._frame;
         node.needRefine = false;
         continue;
       }
@@ -1576,10 +1602,13 @@ export class S3MTileset {
             })
           : null;
 
-      const needRefine = splat
+      let needRefine = splat
         ? splat.needRefine
         : childUrls.length > 0 &&
           (byDistance ? metric < threshold * hFactor : metric > threshold * hFactor);
+      if (needRefine && isVisible && !isVisible(c, node.sphere.radius, node)) {
+        needRefine = false;
+      }
       node.needRefine = needRefine;
 
       const dbgSeen = ((globalThis as { __S3M_LOD_SEEN?: Set<string> }).__S3M_LOD_SEEN ??= new Set<string>());