s3m-three 0.2.0 → 0.3.1

package/src/render/S3MViewer.ts

@@ -21,7 +21,7 @@
  * MapLibre / Mapbox 的胶水层在 s3m-maplibre 包的 S3MLayer.ts。
  */
 import * as THREE from 'three';
-import { S3MTileset } from '../tileset/S3MTileset.js';
+import { S3MTileset, usableGeoBounds } from '../tileset/S3MTileset.js';
 import type { BuildTileFn, TileNode } from '../tileset/S3MTileset.js';
 import { setMaxAnisotropy } from './TextureFactory.js';
 import {
@@ -33,6 +33,7 @@ import {
   createOutlineMaterial,
 } from './StyleMaterial.js';
 import type { OutlineMaterial, StyledMaterial, StyleMode, SelectMode, S3MStyle } from './StyleMaterial.js';
+import { applyPointCloudStyle, isOwnedPointCloudMaterial } from './PointCloudMaterial.js';
 import { Picker } from './Picker.js';
 import {
   buildFeatureEdgeSegments,
@@ -191,6 +192,8 @@ interface MeshUserData {
   geoRef?: GeoPackageEntry;
   tileRef?: ParsedTile;
   primitiveType?: number;
+  /** 点云对象（THREE.Points）：不吃面着色，也没有棱可描 */
+  isPointCloud?: boolean;
   /** CPU 端现算的棱线对象（等宽线 Mesh） */
   edges?: THREE.Object3D | null;
   /** 数据自带棱线包（此时不再用 EdgesGeometry 现算） */
@@ -211,6 +214,11 @@ function styledMaterialOf(mesh: THREE.Mesh): StyledMaterial | null {
   return styled?.userData?.isStyled ? styled : null;
 }
 
+/** 点云是 THREE.Points 不是 Mesh，样式 / 拾取 / 卸载链路都靠这个判定放行 */
+function isPointCloudObject(o: THREE.Object3D): o is THREE.Points {
+  return (o as unknown as THREE.Points).isPoints === true;
+}
+
 /* ------------------------------------------------------------------ 图层 */
 
 export class S3MViewer {
@@ -272,7 +280,7 @@ export class S3MViewer {
   private _heightMax = -Infinity;
   private readonly _boxScratch = new THREE.Box3();
   private _selection: PickResult | null = null;
-  private _selectedMeshes: THREE.Mesh[] = [];
+  private _selectedMeshes: THREE.Object3D[] = [];
   private _outlineMesh: THREE.Mesh | null = null;
   private _outlineMeshes: THREE.Mesh[] = [];
   private _selectionEdges: THREE.Mesh | null = null;
@@ -540,8 +548,11 @@ export class S3MViewer {
   /**
    * 物理地表网格的高度跟随「主数据集的应用层抬升量」，
    * 保证贴地后地表覆盖 / 地下透视的物理关系与被抬升的模型一致。
+   * `ground.trackHeight = false` 时不跟随：地表钉在当前高度，
+   * 高程调整只动模型不动切割面。
    */
   private _syncGroundHeight(): void {
+    if (!this.groundManager.trackHeight) return;
     const primaryId = this.datasets.keys().next().value;
     if (!primaryId) return;
     const userOffset = this._datasetManager.getDatasetHeight(primaryId);
@@ -704,6 +715,15 @@ export class S3MViewer {
     this._requestRepaint();
   }
 
+  /**
+   * 开关「物理地表作为深度遮挡源」：开启后地表以下的几何被真正切掉。
+   * 不依赖宿主是否开启 MapLibre terrain——深度缓冲是共用的，谁更近谁遮挡。
+   */
+  setGroundOcclude(enabled: boolean): void {
+    this.groundManager.setOcclude(enabled);
+    this._requestRepaint();
+  }
+
   /* ---------------------------------------------------------------- 状态纹理同步 */
 
   private _isFeatureHidden(smid: number | null, _batchId: number): boolean {
@@ -773,6 +793,7 @@ export class S3MViewer {
         mesh.geometry?.dispose?.();
         const styled = styledMaterialOf(mesh);
         if (styled) styled.dispose();
+        if (isOwnedPointCloudMaterial(mesh.material)) (mesh.material as THREE.Material).dispose();
         this._featureStyleManager.disposeMesh(mesh);
       });
     });
@@ -808,8 +829,10 @@ export class S3MViewer {
         continue;
       }
 
+      // 点云是 THREE.Points 不是 Mesh，但同样要进拾取表、吃不透明度、跟着着色模式走
+      const isPoints = isPointCloudObject(child);
       const mesh = child as THREE.Mesh;
-      if (!mesh.isMesh) continue;
+      if (!mesh.isMesh && !isPoints) continue;
       const ud = mesh.userData as MeshUserData;
       ud.pickId = this._allocPickId();
       ud.datasetId = entry.id;
@@ -822,29 +845,88 @@ export class S3MViewer {
       });
       this._indexMeshSmids(mesh);
       this._addMeshHeight(mesh);
-      if (this._edgesEnabled && !hasNativeEdges) this._ensureEdges(mesh);
+      // 点云没有「棱」：给一堆孤立点建 EdgesGeometry 又慢又没意义
+      if (this._edgesEnabled && !hasNativeEdges && !isPoints) this._ensureEdges(mesh);
 
       // 新瓦片要继承当前的不透明度与着色方式
-      const mat = styledMaterialOf(mesh);
-      if (mat) {
-        const o = Math.min(1, Math.max(0.05, this.style.opacity ?? 1));
-        mat.opacity = o;
-        mat.transparent = o < 0.999;
-        mat.depthWrite = o >= 0.999;
-        mat.flatShading = this.style.shading !== 'smooth';
-        mat.needsUpdate = true;
-        this._featureStyleManager.applyOverridesToMesh(mesh);
+      if (isPoints) {
+        this._applyPointCloudStyle(child as THREE.Points);
+      } else {
+        const mat = styledMaterialOf(mesh);
+        if (mat) {
+          const o = Math.min(1, Math.max(0.05, this.style.opacity ?? 1));
+          mat.opacity = o;
+          mat.transparent = o < 0.999;
+          mat.depthWrite = o >= 0.999;
+          mat.flatShading = this.style.shading !== 'smooth';
+          mat.needsUpdate = true;
+          this._featureStyleManager.applyOverridesToMesh(mesh);
+        }
       }
+
+      // 选中状态也要跟着继承：LOD 细化 / 瓦片重载会换掉 mesh，
+      // 不重放就出现「点中的那栋楼一拉近就没高亮了」
+      this._replaySelectionOnto(mesh);
     }
   }
 
+  /**
+   * 把「当前选中」重放到一块新登记的 mesh 上。
+   *
+   * 为什么需要：选中高亮是直接写在各 mesh 材质的 uSelBatch / uSelWhole 上的，
+   * 而 LOD 细化、瓦片重载、淘汰回补都会换掉 mesh —— 不重放的话，用户点中的那栋楼
+   * 一细化就失去高亮（状态还在 _selection.smid 里，只是没人往新 mesh 上刷）。
+   */
+  private _replaySelectionOnto(mesh: THREE.Mesh): void {
+    const sel = this._selection;
+    if (!sel) return;
+    const mat = styledMaterialOf(mesh);
+    if (!mat) return;
+
+    const ud = mesh.userData as MeshUserData;
+    let batchId = -1;
+    if (sel.smid != null) {
+      const pickInfo = ud.geoRef?.pickInfo as Record<string | number, unknown> | undefined;
+      const entry = pickInfo?.[sel.smid] ?? pickInfo?.[String(sel.smid)];
+      batchId = entry ? pickEntryId(entry as any) : -1;
+    }
+    // 拾取命中的那块 mesh 用原始 batchId；同一 smid 散在别的几何里时按各自的区间算
+    if (mesh === sel.mesh) batchId = sel.batchId;
+    // 这块几何里根本没有这个单体 → 不动它（否则会把无关瓦片一起点亮）
+    if (batchId < 0 && mesh !== sel.mesh) return;
+
+    mat.userData.uSelBatch.value = batchId;
+    mat.userData.uSelWhole.value = batchId < 0 ? 1 : 0;
+    if (!this._selectedMeshes.includes(mesh)) this._selectedMeshes.push(mesh);
+    if (isPointCloudObject(mesh)) this._applyPointCloudStyle(mesh, true);
+    this.uniforms.uSelMix.value = 1;
+    this.uniforms.uDim.value = this.style.dimOthers ? 1 : 0;
+  }
+
   /** 瓦片被淘汰：从拾取表和场景里摘掉，并释放它自己的 GPU 资源 */
   private _unregisterTile(node: TileNode, entry: S3MDatasetEntry): void {
     for (const child of [...node.group.children]) {
       const mesh = child as THREE.Mesh;
       if (!mesh.isMesh) continue;
       const ud = mesh.userData as MeshUserData;
-      if (this._selection?.mesh === mesh || this._selectedMeshes.includes(mesh)) this.select(null);
+      // 「这块 mesh 没了」≠「用户不再选中」：LOD 细化 / 淘汰回补都会换掉 mesh。
+      // 以前这里一律 select(null)，于是点中的那栋楼一拉近，选中状态就整个被清掉。
+      const wasSelected = this._selectedMeshes.includes(mesh);
+      if (wasSelected) {
+        this._selectedMeshes = this._selectedMeshes.filter((m) => m !== mesh);
+      }
+      if (this._selection?.mesh === mesh) {
+        const smid = this._selection.smid;
+        const carrier =
+          smid != null ? [...(this._smidMeshes.get(smid) ?? [])].find((m) => m !== mesh && m.parent) : undefined;
+        if (carrier) {
+          // 选中身份交给承载同一 smid 的另一块 mesh（通常是接替显示的子瓦）
+          this._selection = { ...this._selection, mesh: carrier };
+          this._replaySelectionOnto(carrier);
+        } else {
+          this.select(null);
+        }
+      }
       if (ud.pickId != null) {
         this._pickables.delete(ud.pickId);
         this._releasePickId(ud.pickId);
@@ -855,6 +937,8 @@ export class S3MViewer {
       this._featureStyleManager.disposeMesh(mesh);
       const styled = styledMaterialOf(mesh);
       styled?.dispose?.();
+      // 点云材质是本模块按模式建的，不走 styled 那条链
+      if (isOwnedPointCloudMaterial(mesh.material)) (mesh.material as THREE.Material).dispose();
       mesh.geometry?.dispose?.();
     }
     entry.root.remove(node.group);
@@ -890,6 +974,8 @@ export class S3MViewer {
     this.style = { ...this.style, ...patch };
     this._applyStyleUniforms();
     if ('opacity' in patch || 'depthWrite' in patch) this._applyOpacity();
+    // 点云不走 StyleMaterial 的 uMode，模式切换要单独同步它的材质
+    if ('mode' in patch) this._applyPointCloudStyles();
     if ('shading' in patch) this._applyShading();
     if ('edges' in patch) this.setEdges(!!this.style.edges);
     else if ('edgeColor' in patch || 'edgeWidth' in patch || 'opacity' in patch || 'edgeOpacity' in patch) {
@@ -959,6 +1045,10 @@ export class S3MViewer {
     // 关键：若 depthWrite 开启（默认开启），即使半透明也保持深度写入，完美遮挡背面棱线，防止背面线条透出
     const keepDepth = this.style.depthWrite !== false;
     for (const p of this._pickables.values()) {
+      if (isPointCloudObject(p.mesh)) {
+        this._applyPointCloudStyle(p.mesh);
+        continue;
+      }
       const m = styledMaterialOf(p.mesh);
       if (!m) continue;
       m.opacity = o;
@@ -968,6 +1058,19 @@ export class S3MViewer {
     this._requestRepaint();
   }
 
+  /** 单个点云对象同步当前样式（着色模式 + 不透明度 + 选中高亮） */
+  private _applyPointCloudStyle(points: THREE.Points, selected = this._selectedMeshes.includes(points)): void {
+    applyPointCloudStyle(points, this.style, this.uniforms, selected);
+  }
+
+  /** 全部点云刷新：着色模式切换时用（uniform 是共享引用，改色不用走这里） */
+  private _applyPointCloudStyles(): void {
+    for (const p of this._pickables.values()) {
+      if (isPointCloudObject(p.mesh)) this._applyPointCloudStyle(p.mesh);
+    }
+    this._requestRepaint();
+  }
+
   /** 平面/平滑着色：FLAT_SHADED 是编译期宏，改它必须重编译 */
   private _applyShading(): void {
     const flat = this.style.shading !== 'smooth';
@@ -1104,7 +1207,8 @@ export class S3MViewer {
       .map((p) => p.mesh)
       .filter((m) => {
         const ud = m.userData as MeshUserData;
-        return !ud.edges && !ud.nativeEdges;
+        // 点云没有棱可描
+        return !ud.edges && !ud.nativeEdges && !isPointCloudObject(m);
       });
     let i = 0;
     const step = (): void => {
@@ -1614,8 +1718,13 @@ export class S3MViewer {
   select(result: PickResult | null, { silent = false }: { silent?: boolean } = {}): void {
     // 清掉上一次
     if (this._selection) {
-      for (const mesh of this._selectedMeshes) {
-        const mat = styledMaterialOf(mesh);
+      for (const obj of this._selectedMeshes) {
+        // 点云：恢复成当前着色模式（去掉选中混色）
+        if (isPointCloudObject(obj)) {
+          this._applyPointCloudStyle(obj, false);
+          continue;
+        }
+        const mat = styledMaterialOf(obj as THREE.Mesh);
         if (mat) {
           mat.userData.uSelBatch.value = -1;
           mat.userData.uSelWhole.value = 0;
@@ -1666,14 +1775,22 @@ export class S3MViewer {
       mat.userData.uSelWhole.value = batchId < 0 ? 1 : 0;
       this._selectedMeshes.push(mesh);
     }
+    // 点云没有单体粒度：整块混成 selectColor，让选中至少看得见
+    for (const mesh of this._selectedMeshes) {
+      if (isPointCloudObject(mesh)) this._applyPointCloudStyle(mesh, true);
+    }
     this.uniforms.uSelMix.value = 1;
     this.uniforms.uDim.value = this.style.dimOthers ? 1 : 0;
 
     if (this.style.outline) {
-      if ((this.style.outlineStyle ?? 'edges') === 'edges') {
-        this._addSelectionEdges(result, targetMeshes);
-      } else {
-        this._addSelectionHull(result, targetMeshes);
+      // 棱线 / 外扩轮廓都是按「面」设计的，点云画不出来也不该画
+      const decoMeshes = [...targetMeshes].filter((m) => !isPointCloudObject(m));
+      if (decoMeshes.length) {
+        if ((this.style.outlineStyle ?? 'edges') === 'edges') {
+          this._addSelectionEdges(result, decoMeshes);
+        } else {
+          this._addSelectionHull(result, decoMeshes);
+        }
       }
     }
     this._requestRepaint();
@@ -1973,9 +2090,8 @@ export class S3MViewer {
     let maxLon = -Infinity;
     let maxLat = -Infinity;
     for (const entry of this.datasets.values()) {
-      const b = entry.tileset?.config?.geoBounds as
-        | { left: number; bottom: number; right: number; top: number }
-        | undefined;
+      // 同 DatasetManager.getBounds：退化 / 越界的 geoBounds 不参与，避免视角甩到 (0,0)
+      const b = usableGeoBounds(entry.tileset?.config?.geoBounds);
       if (!b) continue;
       minLon = Math.min(minLon, b.left);
       maxLon = Math.max(maxLon, b.right);

package/src/render/StyleMaterial.ts

@@ -208,6 +208,16 @@ export function createSharedUniforms(): StyleUniforms {
 const VERT_PARS = /* glsl */ `
   attribute float aBatchId;
   attribute vec3 aColor;
+  #ifdef S3M_ATLAS
+    attribute vec4 aAtlasRect;
+    #ifdef S3M_ATLAS_SEC
+      attribute vec4 aAtlasRect1;
+      attribute vec2 aSecUv;
+      varying vec2 vSecUv;
+      varying vec4 vSecRect;
+    #endif
+    varying vec4 vAtlasRect;
+  #endif
   // 实例化几何没有逐顶点 batchId：顶点是 base mesh 的，单体粒度落在实例上
   #ifdef USE_INSTANCING
     attribute float aInstanceBatchId;
@@ -267,6 +277,14 @@ const VERT_WORLD = /* glsl */ `
   vBatchId = s3mBatchRaw();
   vVertColor = aColor;
 
+  #ifdef S3M_ATLAS
+    vAtlasRect = aAtlasRect;
+    #ifdef S3M_ATLAS_SEC
+      vSecUv = aSecUv;
+      vSecRect = aAtlasRect1;
+    #endif
+  #endif
+
   #ifdef USE_INSTANCING
     mat3 s3mNormMat = mat3( modelMatrix ) * mat3( instanceMatrix );
   #else
@@ -276,6 +294,75 @@ const VERT_WORLD = /* glsl */ `
 `;
 
 const FRAG_PARS = /* glsl */ `
+  #ifdef S3M_ATLAS
+    varying vec4 vAtlasRect;
+    uniform vec2 uAtlasDim;
+    #ifdef S3M_ATLAS_SEC
+      uniform sampler2D uSecMap;
+      uniform vec2 uAtlasDim1;
+      varying vec2 vSecUv;
+      varying vec4 vSecRect;
+    #endif
+    /**
+     * 官方 CalculateMipLevel（vec2 版），逐字照抄 iClient3D 12.1.1。
+     * 用**未 fract** 的 uv 求屏幕空间导数 —— 先 fract 再求导会在平铺接缝处炸出
+     * 一个巨大导数，GPU 直接把整块砖采成最糊的 mip，表现为每块砖边缘一条暗线。
+     */
+    void s3mMipLevel( vec2 uv, vec2 texSize, float maxMip, out float mip ) {
+      vec2 dx = dFdx( uv * texSize.x );
+      vec2 dy = dFdy( uv * texSize.y );
+      float dotX = dot( dx, dx );
+      float dotY = dot( dy, dy );
+      float dMax = max( dotX, dotY );
+      float dMin = min( dotX, dotY );
+      float off = clamp( ( dMax - dMin ) / max( dMax + dMin, 1e-8 ), 0.0, 1.0 );
+      float d = dMax * ( 1.0 - off ) + dMin * off;
+      mip = clamp( 0.5 * log2( max( d, 1e-8 ) ), 0.0, maxMip - 1.62 );
+    }
+
+    /**
+     * 按指定 mip 档采样子区域（官方 czm_getTexColorForS3M 的内层循环体）。
+     *
+     * ★ 子区域 rect 的**右 1/3 不是贴图内容，是内联 mip 金字塔**：
+     *   mip0 只占左 2/3，右 1/3 从上往下依次堆 1/2、1/4、1/8 缩略图，总高恰好 = rect 高。
+     *   官方那句 width *= 2.0/3.0 就是为这个，不是「经验收缩系数」。
+     *   数值实证：14 个块 691 条子纹理里 96.7% 满足「右侧 1/3 ≈ 左 2/3 的 1/2 下采样」
+     *   （平均误差 6.8 vs 27.3）。
+     *   所以 mip > 0 时采样点必须右移到 x + 2/3·w，并下移到 (2^(m-1)-1)/2^(m-1)。
+     */
+    vec4 s3mAtlasLod( vec2 uv, vec2 translate, vec2 scale, vec2 texSize, sampler2D tex, float mip ) {
+      vec2 t = translate;
+      if ( mip > 0.0 ) {
+        t.x = translate.x + scale.x;
+        float temp = pow( 2.0, mip - 1.0 );
+        t.y = translate.y + scale.y * ( temp - 1.0 ) / temp;
+      }
+      float inv = 1.0 / pow( 2.0, mip );
+      vec2 o = fract( uv );
+      // 半纹素内缩，避免双线性把邻格内容混进来
+      vec2 guard = vec2( pow( 2.0, mip ) / texSize.x, pow( 2.0, mip ) / texSize.y );
+      o = clamp( o, guard, vec2( 1.0 ) - guard );
+      return texture2D( tex, o * inv * scale + t );
+    }
+
+    /**
+     * 图集采样入口：层级由 ceil/floor 两档各采一次再平均（官方同样做法），
+     * 因为内联金字塔只有 2 的整数次幂，中间档必须靠混合。
+     */
+    vec4 s3mAtlasUnit( vec2 uv, vec4 rect, vec2 atlasDim, sampler2D tex ) {
+      // 退化矩形 = 官方 batchId < 0：该纹理单元不参与合成
+      if ( rect.z <= 0.0 || rect.w <= 0.0 ) return vec4( 1.0 );
+      vec2 dimPx = vec2( rect.z * atlasDim.x, rect.w * atlasDim.y );
+      vec2 texSize = vec2( dimPx.x * ( 2.0 / 3.0 ), dimPx.y );
+      float maxMip = log2( max( min( texSize.x, texSize.y ), 1.0 ) );
+      vec2 scale = texSize / atlasDim;
+      float mip = 0.0;
+      s3mMipLevel( uv, texSize, maxMip, mip );
+      vec4 hi = s3mAtlasLod( uv, rect.xy, scale, texSize, tex, ceil( mip ) );
+      vec4 lo = s3mAtlasLod( uv, rect.xy, scale, texSize, tex, floor( mip ) );
+      return hi * 0.5 + lo * 0.5;
+    }
+  #endif
   uniform int uMode;
   uniform vec3 uColorA;
   uniform vec3 uColorB;
@@ -445,6 +532,14 @@ const FRAG_EMISSIVE = /* glsl */ `
   }
 `;
 
+const FRAG_BAKE = /* glsl */ `
+  #ifdef S3M_ATLAS_SEC
+    // 官方 getTextureColorForS3M = firstColor(base) * secColor(bake)，
+    // 两套独立的 rect / 尺寸（实测 base 11 条、bake 1 条，条数并不相同）
+    diffuseColor *= s3mAtlasUnit( vSecUv, vSecRect, uAtlasDim1, uSecMap );
+  #endif
+`;
+
 export interface StyledMaterialOptions {
   uniforms: StyleUniforms;
   map?: THREE.Texture | null;
@@ -454,6 +549,12 @@ export interface StyledMaterialOptions {
   opacity?: number;
   roughness?: number;
   flatShading?: boolean;
+  /** >0 时开启 alphaTest：镂空贴图（S3MBLOCK 图集）的透明片元直接丢弃，避免渲染成黑面 */
+  alphaTest?: number;
+  /** 贴图为 S3MBLOCK 图集：几何需带 aAtlasRect，平铺改由片元按子区域做 */
+  atlas?: boolean;
+  /** 图集材质的第二套纹理（官方 BakeTex，光照烘焙），与 base 相乘 */
+  secMap?: THREE.Texture | null;
 }
 
 /**
@@ -476,6 +577,7 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
     flatShading: opts.flatShading !== false,
     // 顶点色、贴图全部在自定义 chunk 里处理，不让 three 插手
     vertexColors: false,
+    alphaTest: opts.alphaTest ?? 0,
   }) as StyledMaterial;
 
   // 选中单体编号：每个 Mesh 独立，默认 -1 表示无选中
@@ -486,6 +588,15 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
   const uBatchTexWidth = { value: 1.0 };
   const uBatchTexActive = { value: 0 };
 
+  // 图集材质：只有几何确实带了 aAtlasRect 才开这个宏，否则缺属性会采到 (0,0) 的默认值
+  const atlas = !!opts.atlas && !!opts.map;
+  const secMap = atlas ? (opts.secMap ?? null) : null;
+  if (atlas) mat.defines = { ...(mat.defines as Record<string, string>), S3M_ATLAS: '' };
+  if (secMap) mat.defines = { ...mat.defines, S3M_ATLAS_SEC: '' };
+  // 官方 uTextureDim = (base宽, base高, bake宽, bake高)，取实际绑定纹理的像素尺寸
+  const uAtlasDim = { value: new THREE.Vector2(opts.map?.image?.width || 1, opts.map?.image?.height || 1) };
+  const uAtlasDim1 = { value: new THREE.Vector2(secMap?.image?.width || 1, secMap?.image?.height || 1) };
+
   mat.onBeforeCompile = (shader) => {
     Object.assign(shader.uniforms, uniforms, {
       uSelBatch,
@@ -493,6 +604,9 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
       uBatchTex,
       uBatchTexWidth,
       uBatchTexActive,
+      uSecMap: { value: secMap },
+      uAtlasDim,
+      uAtlasDim1,
     });
 
     shader.vertexShader = shader.vertexShader
@@ -504,10 +618,29 @@ export function createStyledMaterial(opts: StyledMaterialOptions): StyledMateria
       .replace('#include <common>', `#include <common>\n${FRAG_PARS}`)
       .replace('#include <color_fragment>', `#include <color_fragment>\n${FRAG_COLOR}`)
       .replace('#include <emissivemap_fragment>', `#include <emissivemap_fragment>\n${FRAG_EMISSIVE}`);
+
+    if (atlas) {
+      // onBeforeCompile 收到的还是未展开的 `#include <map_fragment>`，不是 include 里的
+      // `texture2D( map, vMapUv )`。只替换后者会静默 no-op，最终仍按整张图集普通采样。
+      const atlasMapFragment = /* glsl */ `
+        #ifdef USE_MAP
+          vec4 sampledDiffuseColor = s3mAtlasUnit( vMapUv, vAtlasRect, uAtlasDim, map );
+          diffuseColor *= sampledDiffuseColor;
+        #endif
+      `;
+      shader.fragmentShader = shader.fragmentShader.replace(
+        '#include <map_fragment>',
+        `${atlasMapFragment}${secMap ? `\n${FRAG_BAKE}` : ''}`
+      );
+    } else if (secMap) {
+      shader.fragmentShader = shader.fragmentShader.replace('#include <map_fragment>', `#include <map_fragment>\n${FRAG_BAKE}`);
+    }
   };
 
-  // 不同材质共用同一段注入代码，必须让 three 认为它们的 program 可复用
-  mat.customProgramCacheKey = () => 's3m-styled';
+  // 不同材质共用同一段注入代码，必须让 three 认为它们的 program 可复用；
+  // 但图集 / 烘焙两套宏会改注入结果，必须进 cacheKey，否则会复用错 program。
+  mat.customProgramCacheKey = () =>
+    `s3m-styled${atlas ? '-atlas' : ''}${secMap ? '-bake' : ''}`;
 
   mat.userData.uSelBatch = uSelBatch;
   mat.userData.uSelWhole = uSelWhole;

package/src/render/TextureFactory.ts

@@ -47,7 +47,7 @@ function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
   tex.magFilter = THREE.LinearFilter;
   tex.minFilter = THREE.LinearMipmapLinearFilter;
   tex.generateMipmaps = true;
-  // 建筑立面大多是斜视角，各向异性过滤对清晰度的提升比提高分辨率更直接
+  // 各向异性过滤对斜视角立面清晰度的提升比提高分辨率更直接
   tex.anisotropy = maxAnisotropy;
   if (srgb) tex.colorSpace = THREE.SRGBColorSpace;
   tex.flipY = false;
@@ -55,13 +55,61 @@ function configure<T extends THREE.Texture>(tex: T, srgb = true): T {
   return tex;
 }
 
+/**
+ * S3MBLOCK 图集专用：关掉 GPU mip。
+ *
+ * 官方 `sampleLod` 是显式 `textureLod(tex, uv, 0.0)`，层级靠「把子区域 rect 平移 +
+ * 内缩」自己算（见 StyleMaterial 的 s3mAtlasUnit）。若让 GPU 对整张图集生成 mip，
+ * 自动选的层级会把相邻子区域混进来，远处就是一糊串色 —— 实测照抄公式但留着 GPU mip
+ * 时，画面反而比不改更糟，就是因为这两个变量叠在一起了。
+ */
+function configureAtlas<T extends THREE.Texture>(tex: T): T {
+  configure(tex);
+  tex.wrapS = THREE.ClampToEdgeWrapping;
+  tex.wrapT = THREE.ClampToEdgeWrapping;
+  tex.minFilter = THREE.LinearFilter;
+  tex.generateMipmaps = false;
+  tex.anisotropy = 1;
+  tex.needsUpdate = true;
+  return tex;
+}
+
+/** 行序翻转（原地）。S3MBLOCK 图集按 GL 方向存储（v=0 在最后一行），解码后要翻一次行 */
+function flipRows(rgba: Uint8Array, width: number, height: number): void {
+  const row = width * 4;
+  const tmp = new Uint8Array(row);
+  for (let y = 0; y < height >> 1; y++) {
+    const a = y * row;
+    const b = (height - 1 - y) * row;
+    tmp.set(rgba.subarray(a, a + row));
+    rgba.copyWithin(a, b, b + row);
+    rgba.set(tmp, b);
+  }
+}
+
+/** 该像素格式自带 alpha 通道（DXT1 的 1bit alpha 不算，历史上没开过 alphaTest） */
+function hasAlphaChannel(pixelFormat: number): boolean {
+  return (
+    pixelFormat === PixelFormat.DXT3 ||
+    pixelFormat === PixelFormat.DXT4 ||
+    pixelFormat === PixelFormat.DXT5 ||
+    pixelFormat === PixelFormat.ARGB ||
+    pixelFormat === PixelFormat.ABGR ||
+    pixelFormat === PixelFormat.BGRA ||
+    pixelFormat === PixelFormat.RGBA
+  );
+}
+
 /** 解 DXT 到 RGBA8。DXT5 是 1 字节/像素，DXT1 是 0.5 字节/像素。 */
 /** DXT 解码只需要尺寸 / 格式 / 字节，CRN 转码出来的结果也走这条路 */
-function decodeDXT(tex: Pick<S3MTexture, 'width' | 'height' | 'pixelFormat' | 'data'>): THREE.DataTexture {
+function decodeDXT(tex: Pick<S3MTexture, 'width' | 'height' | 'pixelFormat' | 'data' | 'flipY'>): THREE.DataTexture {
   const { width, height, pixelFormat, data } = tex;
   const out = new Uint8Array(width * height * 4);
   DXTTextureDecode.decode(out, width, height, data, pixelFormat);
-  return new THREE.DataTexture(out, width, height, THREE.RGBAFormat, THREE.UnsignedByteType);
+  if (tex.flipY) flipRows(out, width, height);
+  const dt = new THREE.DataTexture(out, width, height, THREE.RGBAFormat, THREE.UnsignedByteType);
+  if (hasAlphaChannel(pixelFormat)) dt.userData.s3mHasAlpha = true;
+  return dt;
 }
 
 function fromRawRGB(tex: S3MTexture): THREE.DataTexture {
@@ -83,12 +131,20 @@ function fromRawRGB(tex: S3MTexture): THREE.DataTexture {
     out[d + 2] = swapRB ? data[p] : data[p + 2];
     out[d + 3] = hasAlpha ? data[alphaFirst ? s : s + 3] : 255;
   }
-  return new THREE.DataTexture(out, width, height, THREE.RGBAFormat, THREE.UnsignedByteType);
+  if (tex.flipY) flipRows(out, width, height);
+  const dt = new THREE.DataTexture(out, width, height, THREE.RGBAFormat, THREE.UnsignedByteType);
+  if (hasAlphaChannel(pixelFormat)) dt.userData.s3mHasAlpha = true;
+  return dt;
 }
 
 export async function createTexture(tex: S3MTexture | null | undefined): Promise<DecodedTexture> {
   if (!tex || !tex.width || !tex.height) return { texture: null, decoded: 'empty' };
 
+  // 图集纹理（flipY 的原始 DXT 图集 / AtlasPack 拼出来的 RGBA 大图 / leaf 组合画布）都必须
+  // 关 GPU mip，层级由 StyleMaterial.s3mAtlasUnit 的内联金字塔自己算。
+  const isAtlas = tex.packed === true || tex.flipY === true || tex.composed === true;
+  const asAtlas = <T extends THREE.Texture>(t: T): T => (isAtlas ? configureAtlas(t) : configure(t));
+
   // 判定只能看 compressType：v3.00 的 CRN 纹理 pixelFormat 是 13（ABGR）、
   // 行标的 CRN 是 32856（GL_RGBA8），都不是 26 / 27（见 core/TextureFormat.ts）
   const kind = resolveTextureKind(tex.compressType ?? 0, tex.pixelFormat);
@@ -102,7 +158,7 @@ export async function createTexture(tex: S3MTexture | null | undefined): Promise
         pixelFormat: crn.dxtFormat === 1 ? 17 : 21,
         data: crn.data,
       });
-      return { texture: configure(decoded), decoded: `crn->dxt${crn.dxtFormat}` };
+      return { texture: asAtlas(decoded), decoded: `crn->dxt${crn.dxtFormat}` };
     } catch (e) {
       // 一张纹理坏了不该带崩整个瓦片，如实上报并降级成无贴图
       console.warn('[s3m] CRN 转码失败：', e);
@@ -111,10 +167,9 @@ export async function createTexture(tex: S3MTexture | null | undefined): Promise
   }
 
   if (kind === 'dxt1' || kind === 'dxt3' || kind === 'dxt4' || kind === 'dxt5') {
-    return {
-      texture: configure(decodeDXT({ ...tex, pixelFormat: dxtPixelFormatOf(kind) })),
-      decoded: kind,
-    };
+    const decoded = decodeDXT({ ...tex, pixelFormat: dxtPixelFormatOf(kind) });
+    // flipY 为真即 S3MBLOCK 图集（见 core/types.ts），必须无 mip
+    return { texture: asAtlas(decoded), decoded: kind };
   }
 
   if (kind === 'webp') {
@@ -122,11 +177,12 @@ export async function createTexture(tex: S3MTexture | null | undefined): Promise
     const bmp = await createImageBitmap(blob);
     const t = new THREE.Texture(bmp);
     t.needsUpdate = true;
-    return { texture: configure(t), decoded: 'webp' };
+    return { texture: asAtlas(t), decoded: 'webp' };
   }
 
   if (kind === 'raw') {
-    return { texture: configure(fromRawRGB(tex)), decoded: 'raw' };
+    const decoded = fromRawRGB(tex);
+    return { texture: asAtlas(decoded), decoded: 'raw' };
   }
 
   // KTX2 / ETC 需要额外解码器，先如实上报而不是静默出错