s3m-three 0.3.0 → 0.3.2

package/src/core/TextureFormat.ts

@@ -65,6 +65,12 @@ function kindOfPixelFormat(pf: number): TextureKind | null {
 
 function kindOfCompress(ct: number): TextureKind | null {
   switch (ct) {
+    // 实测 iClient3D 数据里 compressType = 14 恒为 DXT5：
+    //   · 块内嵌图集   ct=14 pf=21（DXT5），512×512 恰好 0.5 B/px 对应 DXT1、1 B/px 对应 DXT5
+    //   · 独立 .texblock 里的图集 ct=14 pf=13，192×128 = 24576 B，正是 1 B/px 的 DXT5
+    // 后者 pf=13 会被 kindOfPixelFormat 判成 raw（ABGR 4 B/px）→ 按 1/4 长度读，整图碎掉。
+    case 14:
+      return 'dxt5';
     case TextureCompress.DXT1_RGB:
     case TextureCompress.DXT1_RGBA:
       return 'dxt1';
@@ -97,7 +103,19 @@ export function resolveTextureKind(compressType: number, pixelFormat: number): T
   return kindOfPixelFormat(pixelFormat) ?? 'unknown';
 }
 
-/** DXT 族对应的 pixelFormat（喂给 DXTTextureDecode，>11 即按 16 字节块解） */
+/**
+ * DXT 族对应的 pixelFormat，喂给 DXTTextureDecode 选块大小 / alpha 编码。
+ *
+ * 必须逐格式给回真实值：以前除 dxt1 之外一律给 21，DXT3 就被按 DXT5 的插值 alpha 解了
+ * （块大小同为 16 B，所以不会越界，但 alpha 是错的）。
+ */
+const DXT_PIXEL_FORMAT: Partial<Record<TextureKind, number>> = {
+  dxt1: 17,
+  dxt3: 19,
+  dxt4: 20,
+  dxt5: 21,
+};
+
 export function dxtPixelFormatOf(kind: TextureKind): number {
-  return kind === 'dxt1' ? 17 : 21;
+  return DXT_PIXEL_FORMAT[kind] ?? 21;
 }

package/src/core/types.ts

@@ -47,11 +47,27 @@ export interface IndexPackage {
   passNames: string[];
 }
 
+/** MeshOpt 块解码后的原始流清单（语义名 + 每顶点字节数），来自 parseMeshOptGeometry */
+export interface MeshOptInfo {
+  vertexCount: number;
+  compressOptions: number;
+  minVertices: [number, number, number];
+  vertScale: number;
+  texCoordScale: number[][];
+  texCoordOffset: number[][];
+  streams: Array<{ semantic: string; bytes: number; stride: number }>;
+}
+
 export interface VertexPackage {
   verticesCount: number;
   vertexAttributes: VertexAttribute[];
   /** semantic → 在 vertexAttributes 中的下标 */
   attrLocation: Record<string, number>;
+  /**
+   * MeshOpt 骨架的原始流清单（诊断用，也是接自定义属性 / 高斯泼溅属性的入口）：
+   * 每条流解码后每个顶点占 stride 字节，压缩前的字节数在 bytes 里。
+   */
+  meshOptInfo?: MeshOptInfo;
   instanceCount: number;
   /** 16 = 只有矩阵，17/29 = 矩阵 + 颜色 */
   instanceMode: number;
@@ -89,6 +105,12 @@ export interface GeoPackageEntry {
   indexPackages: IndexPackage[];
   /** SMID → batchId + 顶点区间（单体化信息） */
   pickInfo?: Record<number, PickEntry>;
+  /**
+   * v3 骨架条目末尾自带的 OBB（局部 ENU 系，中心/三个半轴都是 float64）。
+   * 多骨架瓦片里每块 geode 的范围各不相同，pageLOD 的包围球只取自其中一块，
+   * 要做按块的剔除/贴地就得用它。v2 没有这个字段。
+   */
+  obb?: BoundingBox;
 }
 
 /* ------------------------------------------------------------------ LOD 树 */
@@ -123,10 +145,49 @@ export interface S3MTexture {
   compressType: number;
   pixelFormat: number;
   data: Uint8Array;
+  /**
+   * S3MBLOCK 图集为真：数据按 GL 纹理方向（v=0 在最后一行）存储，
+   * 解码成 RGBA 后要翻一次行再上传，rect 坐标（offsetY 从 v=0 起）才对得上。
+   */
+  flipY?: boolean;
+  /**
+   * 由 AtlasPack 拼合出来的 RGBA 大图（不是文件里的原始 DXT 块）。
+   * 这类纹理：① 已是自上而下，flipY 必须为 false；② 不能开 GPU mipmap，
+   * 层级由 StyleMaterial 的内联金字塔自己算；③ rect 是拼图坐标系。
+   */
+  packed?: boolean;
+  /**
+   * leaf 模式按 `subTexInfos` 把多张精灵贴出来的自上而下 RGBA 画布（可能没进拼图，
+   * 只有一张图集时 packAtlases 返回 null）。与 packed 同等对待：flipY=false、
+   * 不开 GPU mipmap，层级由 StyleMaterial 的内联金字塔自己算。
+   */
+  composed?: boolean;
+  /**
+   * 拼图集合签名（`408x192#id1,id2,...`）。拼图是逐块做的，同一个 atlas id 在不同块里
+   * 可能落在不同位置，所以跨瓦片共享纹理时 key 必须带上它，否则会复用别的块的排布。
+   */
+  packKey?: string;
 }
 
 /* ------------------------------------------------------------------ 瓦片 */
 
+/**
+ * S3MBLOCK 图集：每个顶点所属子区域的归一化矩形 (x, y, w, h)。
+ * 未被绑定覆盖的顶点是 (0, 0, 1, 1)，即整张图集。
+ * uv 对应材质 textureunit 0，uv2 对应 unit 1（官方叫 BaseTex / BakeTex）。
+ */
+export interface S3MAtlasRects {
+  uv?: Float32Array;
+  uv2?: Float32Array;
+  /**
+   * 每个顶点所属的绑定组 id（= 块文件里「哪段顶点用哪张子纹理」）。
+   * 生成 UV 时按它分组，一组一面墙 → 一张精灵，跟官方 batch 表的语义一致。
+   */
+  group?: Float32Array;
+  /** 每个顶点所属子区域的像素尺寸 (w, h)：决定这段 uv 该怎么平铺 */
+  groupDim?: Float32Array;
+}
+
 export interface ParsedTile {
   version: number;
   compressedType: number;
@@ -134,6 +195,8 @@ export interface ParsedTile {
   groupNode: GroupNode;
   geoPackage: Record<string, GeoPackageEntry>;
   textures: Record<string, S3MTexture>;
+  /** 仅 S3MBLOCK：图集子区域矩形（按骨架名） */
+  atlasRects?: Record<string, S3MAtlasRects>;
   materials: unknown;
   pickInfo: unknown;
   extensions?: unknown;

package/src/index.ts

@@ -10,7 +10,8 @@
  */
 
 // —— 解析层（Node 可用，不依赖 three / WebGL）
-export { parseS3MB, S3M_VERSION, VertexTag, VertexTagV3 } from './core/S3MBParser.js';
+export { parseS3MB, S3MFormatError, S3M_VERSION, VertexTag, VertexTagV3 } from './core/S3MBParser.js';
+export { parseS3M1, isS3M1Buffer } from './core/S3M1Parser.js';
 export type { ParseOptions, InflateFn } from './core/S3MBParser.js';
 export { BinaryReader } from './core/BinaryReader.js';
 export { resolveFeature, measureSegments, buildAttributes, DEFAULT_FLOOR_HEIGHT } from './core/FeatureInfo.js';
@@ -94,6 +95,7 @@ export type {
   S3MFilter,
   GroundMode,
   GroundOptions,
+  LightOptions,
 } from './render/S3MViewer.js';
 
 export { buildTileObjects } from './render/GeometryBuilder.js';

package/src/render/DatasetManager.ts

@@ -8,7 +8,7 @@
  * 4. 多数据集全局经纬度包围盒计算（getBounds）
  */
 import * as THREE from 'three';
-import { S3MTileset } from '../tileset/S3MTileset.js';
+import { S3MTileset, usableGeoBounds } from '../tileset/S3MTileset.js';
 import type { Anchor } from '../core/types.js';
 import { worldFromLngLat, type GeoAdapter } from './GeoAdapter.js';
 
@@ -64,6 +64,68 @@ export interface DatasetManagerCallbacks {
 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;
+
+  get(id: string): S3MDatasetEntry | undefined {
+    return this.datasets.get(id);
+  }
+
+  values(): IterableIterator<S3MDatasetEntry> {
+    return this.datasets.values();
+  }
+
+  /**
+   * 同步预注册数据集（用于提前建立条目与预算平衡）
+   */
+  registerDataset(options: S3MDatasetOptions): S3MDatasetEntry {
+    const existing = this.datasets.get(options.id);
+    if (existing) return existing;
+    const root = new THREE.Group();
+    root.name = `s3m-dataset:${options.id}`;
+    root.visible = options.visible !== false;
+    const entry: S3MDatasetEntry = {
+      id: options.id,
+      name: options.name ?? options.id,
+      options,
+      root,
+      tileset: null,
+      anchor: null,
+      baseAlignOffset: 0,
+      userOffset: options.heightOffset ?? 0,
+      heightOffset: options.heightOffset ?? 0,
+      offset: [0, 0, 0],
+      visible: options.visible !== false,
+      error: null,
+    };
+    this.datasets.set(options.id, entry);
+    this.rebalanceBudgets();
+    return entry;
+  }
+
+  /**
+   * 全局多数据集预算再平衡：在所有可见数据集之间均衡分配 maxTiles
+   */
+  rebalanceBudgets(totalMaxTiles?: number): void {
+    const budget = totalMaxTiles ?? this.totalMaxTiles;
+    if (!budget || budget <= 0) return;
+    this.totalMaxTiles = budget;
+
+    const visibleEntries = Array.from(this.datasets.values()).filter((d) => d.visible && d.tileset);
+    const count = Math.max(1, visibleEntries.length);
+    const perDataset = Math.max(8, Math.floor(budget / count));
+
+    for (const entry of this.datasets.values()) {
+      if (!entry.tileset) continue;
+      if (entry.visible) {
+        entry.tileset.maxTiles = perDataset;
+        entry.tileset.hardCap = perDataset + Math.max(4, Math.ceil(perDataset * 0.5));
+      } else {
+        // 隐藏数据集仅保留极低配额（防止占着显存）
+        entry.tileset.maxTiles = Math.min(4, entry.tileset.maxTiles);
+        entry.tileset.hardCap = Math.min(6, entry.tileset.hardCap);
+      }
+    }
+  }
 
   /** 根据语义对齐方式（'top' | 'bottom' | 'center'）和数据源高度范围计算基准高度偏移 */
   computeAlignOffset(tileset: S3MTileset | null, align?: DatasetAlignment): number {
@@ -144,6 +206,7 @@ export class DatasetManager {
       },
     });
     entry.tileset = tileset;
+    this.rebalanceBudgets();
 
     try {
       await tileset.init();
@@ -179,6 +242,7 @@ export class DatasetManager {
     entry.tileset?.dispose();
     scene.remove(entry.root);
     this.datasets.delete(id);
+    this.rebalanceBudgets();
 
     if (this.datasets.size > 0) {
       this.recomputeAnchors(geo);
@@ -277,6 +341,7 @@ export class DatasetManager {
     if (!entry) return;
     entry.visible = visible;
     entry.root.visible = visible;
+    this.rebalanceBudgets();
   }
 
   /**
@@ -291,10 +356,10 @@ export class DatasetManager {
 
     for (const entry of this.datasets.values()) {
       if (!entry.visible || !entry.tileset?.config) continue;
-      const b = entry.tileset.config.geoBounds as
-        | { left: number; bottom: number; right: number; top: number }
-        | undefined;
-      if (b && Number.isFinite(b.left)) {
+      // 只认「确实是一张经纬度范围」的 geoBounds：OSGB/SuperMapCache 那类配置只给米制
+      // 局部包围盒，全 0 的退化框拿去 fitBounds 会把视角甩到几内亚湾
+      const b = usableGeoBounds(entry.tileset.config.geoBounds);
+      if (b) {
         minLon = Math.min(minLon, b.left);
         minLat = Math.min(minLat, b.bottom);
         maxLon = Math.max(maxLon, b.right);

package/src/render/GeometryBuilder.ts

@@ -35,11 +35,55 @@ import type {
  */
 export const LINE_PRIMITIVE = 13;
 
+/** primitiveType = 1：点云包。索引是点序号，画成三角面就是满屏彩色尖刺。 */
+export const POINT_PRIMITIVE = 1;
+
 function isLinePrimitive(primitiveType: number): boolean {
   // 1 = 点，2 = 线段，3 = 折线，13 = 棱线包
   return primitiveType === LINE_PRIMITIVE || primitiveType === 2 || primitiveType === 3;
 }
 
+function isPointPrimitive(primitiveType: number): boolean {
+  return primitiveType === POINT_PRIMITIVE;
+}
+
+/* ------------------------------------------------------------------ 图集 UV */
+
+/**
+ * S3MBLOCK 图集的 UV 一律用几何自带的 uv0 原值，这里不再做任何重算。
+ *
+ * 走过三轮弯路才定下来（每一条都不要再试）：
+ *   1. 「按世界尺度 fract」—— uv0 是建模工具留下的逐岛坐标，不是世界投影，
+ *      全局跨度 279 只是所有岛拼起来的包围盒，拿它除以瓦片尺寸算出的
+ *      「1 个 uv 周期 = 1.65 m」是错的；
+ *   2. 「按 binding 分组、逐面 0..1」—— 等于把作者排好的映射丢掉，
+ *      一面墙强行铺一整张精灵，长墙被横向拉糊；
+ *   3. 「按 uv 跨度 ÷ 精灵像素取整重复」—— 同上，而且依赖精灵像素尺寸这个
+ *      与几何无关的量。
+ *
+ * 官方引擎的做法（iClient3D 12.1.1，VS 里 getUVMatrixForBatch / FS 里
+ * czm_getTexColorForS3M）就是：fract(uv0) 直接乘子区域尺寸再平移到子区域，
+ * 一个 uv 周期 = 一张精灵，作者在 uv0 里已经把重复次数写死了。
+ * 唯一需要额外处理的是子区域右 1/3 那条内联 mip 链，见 StyleMaterial.s3mAtlasSample。
+ */
+
+
+/**
+ * 点云共享材质：顶点色直接上屏，不受光照影响。
+ * 固定像素尺寸（sizeAttenuation: false），远近点大小一致，高空浏览时不会缩成一团。
+ */
+let pointCloudMaterial: THREE.PointsMaterial | null = null;
+function getPointCloudMaterial(): THREE.PointsMaterial {
+  if (!pointCloudMaterial) {
+    pointCloudMaterial = new THREE.PointsMaterial({
+      size: 2,
+      sizeAttenuation: false,
+      vertexColors: true,
+    });
+  }
+  return pointCloudMaterial;
+}
+
 /* ------------------------------------------------------------------ 顶点流 */
 
 function bytesPerElement(dtype: AttrDType): number {
@@ -140,6 +184,9 @@ function toColorAttribute(attr: VertexAttribute | null, vertexCount: number): TH
   return new THREE.BufferAttribute(out, 3);
 }
 
+/** SuperMap 内置水面（`103.water`）的基色：偏深的青蓝，配合低粗糙度出一点天光反射 */
+const WATER_COLOR = new THREE.Color(0x1d4e63);
+
 /* ------------------------------------------------------------------ 材质描述 */
 
 interface RawMaterialUnit {
@@ -157,6 +204,7 @@ interface RawMaterialDef {
   diffuse?: { r?: number; g?: number; b?: number; a?: number };
   shininess?: number;
   alphaMode?: string;
+  alphaCutoff?: number;
   cullMode?: string;
   transparentsorting?: boolean;
   textureStates?: RawMaterialUnit[];
@@ -240,6 +288,7 @@ export interface BuildTileResult {
   group: THREE.Group;
   stats: TileBuildStats;
   objects: THREE.Object3D[];
+  textureKeys?: string[];
 }
 
 interface CachedGeometry {
@@ -260,6 +309,7 @@ export async function buildTileObjects(
   const textureByCode = options.textureCache ?? new Map<string, THREE.Texture>();
   const group = new THREE.Group();
   const objects: THREE.Object3D[] = [];
+  const usedTextureKeys: string[] = [];
   const stats: TileBuildStats = {
     meshes: 0,
     vertices: 0,
@@ -280,11 +330,31 @@ export async function buildTileObjects(
   group.userData.hasNativeEdges = false;
 
   // 1) 纹理
+  //
+  // 缓存 key 不能只用 atlas id：拼图（AtlasPack）是**逐块**做的，同一个 id 在 LOD 兄弟块里
+  // 参与的拼图集合可能不同、落位也不同。只按 id 复用会把别块的排布拿过来，
+  // 而 aAtlasRect 是本块的 —— 整块贴错图。带 packKey 的按「id#集合签名」隔离。
+  const texKeyOf = (code: string): string => {
+    const t = (tile.textures as Record<string, { packKey?: string }> | undefined)?.[code];
+    return t?.packKey ? `${code}#${t.packKey}` : code;
+  };
+
   for (const [code, tex] of Object.entries(tile.textures ?? {})) {
-    if (textureByCode.has(code)) continue;
+    // 同一个图集 id 会被很多瓦片共用：先到的那块可能只拿到内嵌缩略图（120x184），
+    // 后面的块换成了高清版（240x304）。只按 id 判「缓存已有」会让高清永远进不来，
+    // 满屏都是马赛克。所以尺寸变大时必须重解码并覆盖。
+    const key = texKeyOf(code);
+    const prev = textureByCode.get(key);
+    if (prev) {
+      const img = prev.image as { width?: number; height?: number } | undefined;
+      const prevPixels = (img?.width ?? 0) * (img?.height ?? 0);
+      if (prevPixels >= (tex.width ?? 0) * (tex.height ?? 0)) continue;
+      textureByCode.delete(key);
+    }
     const { texture, decoded } = await createTexture(tex);
     if (texture) {
-      textureByCode.set(code, texture);
+      textureByCode.set(key, texture);
+      usedTextureKeys.push(key);
       stats.textures++;
     } else {
       stats.skipped.push(`texture ${code} → ${decoded}`);
@@ -299,12 +369,19 @@ export async function buildTileObjects(
   // 材质对象本身很轻（program 由 customProgramCacheKey 复用），一栋一个不心疼。
   const materialList = resolveMaterialList(tile.materials);
 
-  const makeMaterial = (code?: string): StyledMaterial => {
+  const makeMaterial = (code?: string, hasAtlasRect = false): StyledMaterial => {
     const entry = materialList.find((e) => materialName(unwrapMaterial(e)) === code);
     const m = unwrapMaterial(entry);
     const units = materialUnits(m);
     const unit0 = units[0];
-    let map = unit0 ? (textureByCode.get(materialName(unit0) ?? unit0.id ?? '') ?? null) : null;
+    let map = unit0 ? (textureByCode.get(texKeyOf(materialName(unit0) ?? unit0.id ?? '')) ?? null) : null;
+    // S3MBLOCK 的烘焙图（unit1 / BakeTex）是光照烘焙，官方与 base 相乘；缺它建筑就是一片平白
+    const unit1 = units[1];
+    const noBake = (globalThis as { __S3M_NO_BAKE?: boolean }).__S3M_NO_BAKE === true;
+    const secMap =
+      hasAtlasRect && unit1 && !noBake
+        ? (textureByCode.get(texKeyOf(materialName(unit1) ?? unit1.id ?? '')) ?? null)
+        : null;
 
     // 检查并应用 texmodmatrix 纹理变换矩阵
     const texMod = unit0?.texmodmatrix ?? unit0?.matrix;
@@ -337,20 +414,36 @@ export async function buildTileObjects(
 
     const diffuse = m?.diffuse ?? { r: 1, g: 1, b: 1, a: 1 };
     const alphaMode = m?.alphaMode;
-    const transparent = alphaMode === 'AM_BLEND' || (diffuse.a ?? 1) < 0.999 || m?.transparentsorting === true;
+    // SuperMap 的内置水面：纹理单元 id 是 `103.water`，块里**根本没有像素**
+    // （实测 Waters 的 s3mb 只有 1081 字节，textures = 0，材质 diffuse 还是纯白）。
+    // 以前当白色漫反射渲染，整片湖就是一块白板。这里按内置水面材质上色。
+    const isWater = [unit0, unit1].some((u) => /\.water$/i.test(String(materialName(u) ?? u?.id ?? '')));
+    const transparent =
+      alphaMode === 'AM_BLEND' || (diffuse.a ?? 1) < 0.999 || m?.transparentsorting === true || (isWater && !map);
 
     // S3M 的 shininess 是旧式 0~128 高光指数，粗略映射到粗糙度
     const roughness =
       typeof m?.shininess === 'number' && m.shininess > 0 ? Math.max(0.15, 1 - m.shininess / 128) : 0.95;
 
+    // 镂空图集（S3MBLOCK）：建筑照片是异形 alpha 抠图，轮廓顶点会采到 alpha=0 的像素，
+    // 不丢弃的话就是成片的黑面。cutoff 取材质自带的 alphaCutoff（实测 0.01）。
+    // rect 是图集里的原始子区域（含右 1/3 的内联 mip 列），不做任何裁切，
+    // 这里保留 alphaTest 只为挡掉轮廓外的零星像素，不会再出现整面墙被抠空。
+    const alphaTest = (map as THREE.Texture | null)?.userData?.s3mHasAlpha
+      ? Math.max((m?.alphaCutoff as number) ?? 0, 0.01)
+      : 0;
+
     const mat = createStyledMaterial({
       uniforms,
       map,
-      color: new THREE.Color(diffuse.r ?? 1, diffuse.g ?? 1, diffuse.b ?? 1),
+      color: isWater && !map ? WATER_COLOR.clone() : new THREE.Color(diffuse.r ?? 1, diffuse.g ?? 1, diffuse.b ?? 1),
       side: resolveSide(m),
       transparent,
-      opacity: diffuse.a ?? 1,
-      roughness,
+      opacity: isWater && !map ? 0.86 : (diffuse.a ?? 1),
+      roughness: isWater && !map ? 0.12 : roughness,
+      alphaTest,
+      atlas: hasAtlasRect && !!map,
+      secMap,
     });
     return mat;
   };
@@ -388,21 +481,61 @@ export async function buildTileObjects(
       ? toBufferAttribute(batchAttr)
       : new THREE.BufferAttribute(new Float32Array(vertexCount).fill(-1), 1);
 
+    // S3MBLOCK 图集：逐顶点带子区域矩形，平铺的 fract 交给片元做（顶点上做会画反）。
+    // 烘焙图（材质 unit1）用第二套原始 UV，这里另开一个 aSecUv 槽位，不跟 three 的 uv1 语义纠缠。
+    const rects = tile.atlasRects?.[name];
+    if (rects) {
+      attributes.aAtlasRect = new THREE.BufferAttribute(rects.uv ?? new Float32Array(vertexCount * 4), 4);
+      // 没有第二套 UV 的骨架不做烘焙：给一个退化矩形，片元里据此跳过
+      const uv1 = attributes.uv1 as THREE.BufferAttribute | undefined;
+      if (rects.uv2 && uv1) {
+        attributes.aAtlasRect1 = new THREE.BufferAttribute(rects.uv2, 4);
+        attributes.aSecUv = uv1;
+      } else {
+        attributes.aAtlasRect1 = new THREE.BufferAttribute(new Float32Array(vertexCount * 4), 4);
+        attributes.aSecUv = (attributes.uv as THREE.BufferAttribute) ?? new THREE.BufferAttribute(new Float32Array(vertexCount * 2), 2);
+      }
+    }
+
     const instanced = vp.instanceIndex !== -1 && (vp.instanceMode === 16 || vp.instanceMode === 17);
     // 注意：indexPackages 属于 Skeleton（geoPackage[name]），不在 vertexPackage 里
-    skeletonInfo.set(name, { indexPackages: geo.indexPackages ?? [], instanced });
+    //
+    // 一个索引包都没有的骨架 = 纯点集：高斯泼溅（3DGaussianSplatting）和无索引点云
+    // 都是这种——顶点就是点，没有任何三角形可画。不补一个「顶点即点」的伪包，
+    // 下面就不会产出任何对象，整块瓦片最后落到「tile 无可用几何」被丢掉。
+    let packs = geo.indexPackages ?? [];
+    if (packs.length === 0 && vertexCount > 0) {
+      packs = [
+        {
+          indexCount: 0,
+          indexType: 0,
+          useIndex: 0,
+          primitiveType: POINT_PRIMITIVE,
+          indices: null,
+          passNames: [],
+        },
+      ];
+    }
+    skeletonInfo.set(name, { indexPackages: packs, instanced });
     stats.vertices += vertexCount;
 
-    (geo.indexPackages ?? []).forEach((pack, pi) => {
-      const geometry = new THREE.BufferGeometry();
+    packs.forEach((pack, pi) => {
+      let geometry = new THREE.BufferGeometry();
       for (const [k, v] of Object.entries(attributes)) geometry.setAttribute(k, v);
       const idx = toIndex(pack);
       if (idx) geometry.setIndex(idx);
       else geometry.setDrawRange(0, vertexCount);
 
+
+
       // 如果数据本身没有法线且是三角网格，必须在绑定了 index 之后计算法线
       // 绝不能在未索引的 attributes.position 上算，否则非连续顶点会导致法线朝向错乱甚至越界 NaN 导致死黑面
-      if (!isLinePrimitive(pack.primitiveType) && !geometry.getAttribute('normal')) {
+      // 线 / 点包不需要法线
+      if (
+        !isLinePrimitive(pack.primitiveType) &&
+        !isPointPrimitive(pack.primitiveType) &&
+        !geometry.getAttribute('normal')
+      ) {
         geometry.computeVertexNormals();
       }
 
@@ -435,6 +568,7 @@ export async function buildTileObjects(
     let hasUv1 = false;
     let hasAColor = false;
     let hasABatchId = false;
+    let hasAtlas = false;
 
     for (const c of candidates) {
       const g = c.cached.geometry;
@@ -446,6 +580,7 @@ export async function buildTileObjects(
       if (g.attributes.uv1) hasUv1 = true;
       if (g.attributes.aColor) hasAColor = true;
       if (g.attributes.aBatchId) hasABatchId = true;
+      if (g.attributes.aAtlasRect) hasAtlas = true;
     }
 
     const mergedPos = new Float32Array(totalVertices * 3);
@@ -454,6 +589,31 @@ export async function buildTileObjects(
     const mergedUv1 = hasUv1 ? new Float32Array(totalVertices * 2) : null;
     const mergedColor = hasAColor ? new Float32Array(totalVertices * 3) : null;
     const mergedBatchId = hasABatchId ? new Float32Array(totalVertices) : null;
+    const mergedRect0 = hasAtlas ? new Float32Array(totalVertices * 4) : null;
+    const mergedRect1 = hasAtlas ? new Float32Array(totalVertices * 4) : null;
+    const mergedSecUv = hasAtlas ? new Float32Array(totalVertices * 2) : null;
+
+    /** 逐顶点拷一个 n 分量的浮点属性；缺失时用 fallbackRect / 0 兜底 */
+    const copyAttr = (
+      dst: Float32Array,
+      attr: THREE.BufferAttribute | THREE.InterleavedBufferAttribute | undefined,
+      comp: number,
+      vCount: number,
+      vertexOffset: number,
+      fallback?: (i: number, out: number[]) => void
+    ) => {
+      if (attr) {
+        const src = attr.array as ArrayLike<number>;
+        for (let i = 0; i < vCount; i++)
+          for (let k = 0; k < comp; k++) dst[(vertexOffset + i) * comp + k] = src[i * comp + k] ?? 0;
+        return;
+      }
+      for (let i = 0; i < vCount; i++) {
+        const out: number[] = [];
+        fallback ? fallback(i, out) : out.push(...new Array(comp).fill(0));
+        for (let k = 0; k < comp; k++) dst[(vertexOffset + i) * comp + k] = out[k] ?? 0;
+      }
+    };
 
     const IndexArrayType = totalVertices > 65535 ? Uint32Array : Uint16Array;
     const mergedIndices = new IndexArrayType(totalIndices);
@@ -582,7 +742,14 @@ export async function buildTileObjects(
         }
       }
 
-      // 7. Indices
+      // 7. 图集矩形（S3MBLOCK）
+      if (mergedRect0) {
+        copyAttr(mergedRect0, g.attributes.aAtlasRect, 4, vCount, vertexOffset, (_i, out) => out.push(0, 0, 0, 0));
+        copyAttr(mergedRect1!, g.attributes.aAtlasRect1, 4, vCount, vertexOffset, (_i, out) => out.push(0, 0, 0, 0));
+        copyAttr(mergedSecUv!, g.attributes.aSecUv, 2, vCount, vertexOffset);
+      }
+
+      // 8. Indices
       if (g.index) {
         const idxArr = g.index.array as ArrayLike<number>;
         const iCount = g.index.count;
@@ -607,6 +774,11 @@ export async function buildTileObjects(
     if (mergedUv1) mergedGeo.setAttribute('uv1', new THREE.BufferAttribute(mergedUv1, 2));
     if (mergedColor) mergedGeo.setAttribute('aColor', new THREE.BufferAttribute(mergedColor, 3));
     if (mergedBatchId) mergedGeo.setAttribute('aBatchId', new THREE.BufferAttribute(mergedBatchId, 1));
+    if (mergedRect0) {
+      mergedGeo.setAttribute('aAtlasRect', new THREE.BufferAttribute(mergedRect0, 4));
+      mergedGeo.setAttribute('aAtlasRect1', new THREE.BufferAttribute(mergedRect1!, 4));
+      mergedGeo.setAttribute('aSecUv', new THREE.BufferAttribute(mergedSecUv!, 2));
+    }
     mergedGeo.setIndex(new THREE.BufferAttribute(mergedIndices, 1));
     mergedGeo.computeBoundingBox();
     mergedGeo.computeBoundingSphere();
@@ -632,7 +804,7 @@ export async function buildTileObjects(
     matrix: THREE.Matrix4 | null
   ): THREE.Object3D => {
     const { geometry, pack } = cached;
-    const material = makeMaterial(pack.passNames?.[0]);
+    const material = makeMaterial(pack.passNames?.[0], !!geometry.getAttribute('aAtlasRect'));
     let object: THREE.Mesh | THREE.InstancedMesh;
 
     const info = skeletonInfo.get(name);
@@ -656,6 +828,28 @@ export async function buildTileObjects(
       return lines;
     }
 
+    // 点云包：顶点即点，按 THREE.Points 渲染。索引只是点序号，直接走 drawRange。
+    if (isPointPrimitive(pack.primitiveType)) {
+      // PointsMaterial 的顶点色读内置 'color' 槽位，与 aColor 共享同一份 buffer
+      if (!geometry.getAttribute('color')) {
+        geometry.setAttribute('color', geometry.getAttribute('aColor')!);
+      }
+      const points = new THREE.Points(geometry, getPointCloudMaterial());
+      // 点云不是 Mesh：viewer 的样式 / 拾取 / 卸载链路都靠这个标记放行
+      points.userData.isPointCloud = true;
+      points.userData.skeletonName = name;
+      points.userData.geoRef = geo;
+      points.userData.tileRef = tile;
+      points.userData.primitiveType = pack.primitiveType;
+      if (matrix && !matrix.equals(IDENTITY)) {
+        matrix.decompose(points.position, points.quaternion, points.scale);
+      }
+      group.add(points);
+      objects.push(points);
+      stats.meshes++;
+      return points;
+    }
+
     if (info?.instanced && vp.instanceBuffer && vp.instanceCount > 0) {
       // 逐实例的两条属性：
       //   aInstanceBatchId —— 单体控制位，着色器靠它查状态纹理（改色 / 隐藏 / 抬高）
@@ -822,7 +1016,8 @@ export async function buildTileObjects(
       if (list.length === 1) {
         placeObject(list[0].cached, list[0].name, list[0].geo, list[0].matrix);
       } else {
-        const material = makeMaterial(matKey === '__default__' ? undefined : matKey);
+        const hasAtlasRect = !!list[0].cached.geometry.getAttribute('aAtlasRect');
+        const material = makeMaterial(matKey === '__default__' ? undefined : matKey, hasAtlasRect);
         const batchedMesh = mergeBatchGeometries(list, material, tile);
         group.add(batchedMesh);
         objects.push(batchedMesh);
@@ -836,5 +1031,6 @@ export async function buildTileObjects(
 
   if (!group.children.length) stats.skipped.push('tile 无可用几何');
 
-  return { group, stats, objects };
+  group.userData.textureKeys = usedTextureKeys;
+  return { group, stats, objects, textureKeys: usedTextureKeys };
 }