s3m-three 0.4.25 → 0.4.27

package/docs/API.md

@@ -170,13 +170,19 @@ new S3MViewer(options?: S3MViewerOptions)
 | （随 `useWorker`）纹理解码 | `boolean` | `true` | DXT / CRN / WEBP 纹理解码与 `.s3mb` 解析共用同一个 Worker（`core/TextureDecode.ts` 三方共用同一份实现，WEBP 走可 transfer 的 ImageBitmap）；失败自动回主线程，产物逐字节一致 |
 | （随 `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 解码 |
+| `perTilePlacement` | `boolean` | `true` | 瓦片级切平面放置与拾取反解（**默认开启**）。每块瓦片用自身中心纬度计算墨卡托比例与反解拾取，消除「全场景共用一个常量切平面」在大范围（距场景锚点 20 km 处 0.26% 误差，约 26 m；200 km 处 2.8 km）下的累积尺度误差与拾取偏移。逆矩阵自动缓存在瓦片 group 上避免拾取性能损耗。可显式传 `false` 回退旧版单一全场景切平面（下游若缓存了旧坐标或与旧数据对齐时使用） |
+| `bakeMercator` | `boolean` | `undefined`（自动） | 全球大尺度下逐顶点烘焙精确 Web 墨卡托偏移（Issue #15）。消除大范围单瓦片内因墨卡托纬度非线性缩放导致的视差游动与呼吸效应。默认 `undefined`：当瓦片集根节点包围球半径 > 25 km 时自动启用；<= 25 km 时保持关闭（顶点 buffer 逐字节与旧版相同）。传 `true` / `false` 强制开关 |
 | `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 |
 | `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 压缩直传与图集不受影响。**图层级**，但只影响之后解码的纹理（已解码的不重解） |
 | `maxImageCache` | `number` | `128` | 纹理缓存条数上限。一条 = 一张已解码的瓦片纹理，1024² RGBA 约 4MB，128 条即约 512MB 显存；低端设备 32~48。LRU，降下来下次淘汰时释放 |
 | `materialQuality` | `'pbr' \| 'lambert'` | `'pbr'` | 光照模型。`lambert` 用 `MeshLambertMaterial` 替换 PBR，去掉 GGX 与环境球谐，片元约省一半；白模 / 纯色 / 按高度着色几乎无差。**图层级**：同页多个图层各用各的，互不覆盖；不传则跟随模块级默认（`setMaterialQuality`）。只影响之后创建的材质 |
 | `colorPipeline` | `'linear' \| 'direct'` | `'linear'` | 颜色管线。`direct` = 官方 iClient3D 的 sRGB 直乘（同时关掉纹理解码），`lightingPreset: 'supermap'` 会选它。**图层级**：同页多图层各用各的；已加载瓦片可运行时 `setColorPipeline(q, { duration })` 走 fade-through 平滑切过去（重建材质 + 重传纹理，不重下瓦片） |
+| `motionBlur` | `{ mode?: 'afterimage' \| 'velocity'; damp?: number \| 'auto'; maxOffset?: number }` | 不传 = 关闭 | 可选的运动模糊后处理（**默认关闭**，不传时渲染路径与旧版逐字一致）。低端 / 移动设备低帧率下，用帧间残影在感知层面填补卡顿与边缘闪烁。`afterimage`（缺省）= 当前帧 + 上一帧全屏混合，几乎零边际 GPU 成本；`velocity` = 按上一帧 ↔ 当前帧相机矩阵逐像素反推屏幕速度、沿速度方向 8 tap 采样（方向感知，只覆盖相机运动）。`damp` 为拖尾长度（仅 afterimage），`'auto'`（缺省）按实时 FPS 收敛（`0.55^(fps/60)` 封顶 0.92），数值钳 [0, 0.98]；`maxOffset` 为拖影上限（仅 velocity），速度向量的最大屏幕偏移按绘图缓冲宽度的百分比计，缺省 `0.05`，数值钳 [0, 1]。运行时 `setMotionBlur(null)` 关闭并释放 RT。仅 WebGL2（WebGL1 静默回退直渲）；已知限制：拖影只在当前帧几何覆盖范围内（合成 quad 依赖本帧深度保住遮挡正确性）；RT 用 HalfFloatType 存线性值（高光不被 clamp，代价是三张全屏纹理显存 ×2） |
+| `depthMode` | `'scene' \| 'clear' \| 'auto'` | `'scene'` | 本层绘制前深度缓冲处理策略。`'scene'`（默认）：保留宿主深度，建筑/管线等离散对象受地形正常遮挡；`'clear'`：先清深度再画，贴地倾斜摄影/开挖地表/大范围 DEM 化模型消除共面 z-fighting；`'auto'`：按 ground 覆盖或数据集类型自动推断 |
 | `buildTile` | `BuildTileFn \| null` | — | 自定义瓦片构建器（测试 / 服务端渲染时注入） |
 | `attributes` | `AttributeQueryOptions` | — | 可选的 iServer 数据服务配置，配了才能用 `colorByField()` 等便利方法；不配就自己取数 + `setFeaturesStyle()`，见[业务字段](#业务字段锚点在库内对应关系在外部) |
 | `onRequestRepaint` | `() => void` | — | 宿主请求重画的信号：纯 three 宿主接自己的渲染循环 |
@@ -207,6 +213,15 @@ prewarmShading(): Promise<void>        // 手动预热另一种 shading 变体
 
 `geo` 是可写的 `GeoAdapter | null`：`null` 用内置的墨卡托兜底（`worldFromLngLat` / `lngLatFromWorld`），地图宿主注入适配器以支持任意 CRS / 自定义投影。
 
+内置兜底使用高精度 **WGS84 椭球模型**（$a=6378137, f=1/298.257223563$）：
+- `worldFromLngLat` 返回带有各向异性尺度的对象：`{ x, y, z, meterInMercatorEast, meterInMercatorNorth, meterInMercatorUp, meterInMercator, altitude }`
+  - 东西向尺度对应卯酉圈半径 $N(\varphi) = a / \sqrt{1 - e^2 \sin^2\varphi}$：$1 / (2\pi N \cos\varphi)$
+  - 南北向尺度对应子午圈半径 $M(\varphi) = a(1 - e^2) / (1 - e^2 \sin^2\varphi)^{3/2}$：$1 / (2\pi M \cos\varphi)$
+  - 竖直向高程尺度 `meterInMercatorUp` 取东向尺度（局部正圆保角）
+  - `meterInMercator` 保留作为向前兼容属性，取值从旧版球面近似 $1/(2\pi R\cos\varphi)$ 升级为真实的 WGS84 椭球东向尺度（属于精度修正，默认生效且更精准）
+  - 彻底消除传统单标量模型在南北/东西方向上 0.4%~0.67% 的各向异性拉伸与米级系统残差。
+- 包导出了高精度大地测量工具：`primeVerticalRadius`, `meridianRadius`, `enuToLngLat`, `lngLatToEnu` 及 `WGS84_A`, `WGS84_E2` 常量。
+
 ### 数据集管理
 
 ```ts
@@ -515,6 +530,8 @@ type ClipOptions =
 ```ts
 setLodRangeScale(scale: number, datasetId?: string): void
 readonly lodRangeScale: number
+readonly lodTransition: 'binary' | 'incremental'
+setLodTransition(mode: 'binary' | 'incremental'): void
 setLodPixelRatioCap(cap: number): void        // Infinity = 不截断（默认）
 readonly lodPixelRatioCap: number
 setMaxTriangles(n: number, datasetId?: string): void   // Infinity = 不限制（默认）
@@ -526,6 +543,10 @@ readonly anisotropyCap: number
 setMaxTextureSize(n: number): void            // Infinity = 不限制（默认）
 readonly maxTextureSize: number
 readonly maxImageCache: number
+setDepthMode(mode: DepthMode): void            // 运行时调整深度处理策略（'scene' | 'clear' | 'auto'）
+readonly depthMode: DepthMode                  // 当前深度策略
+setMotionBlur(cfg: MotionBlurOptions | null): void  // 运行时开关运动模糊；null = 关闭并释放 RT 显存
+readonly motionBlur: MotionBlurOptions | null       // 当前配置（归一化后的副本）
 readonly stats: Stats
 readonly fps: number
 getBounds(): [[number, number], [number, number]] | null  // 合并经纬度范围
@@ -1366,9 +1387,9 @@ bun run test:meshopt
 
 **这两条 GS 流的量化格式还没标定**（4 字节 / 点，既不像 3 个 float，也不像明显四元数），所以渲染层目前只是把它们带到顶点属性上备用，没有接进真正的 splat 着色器。
 
-### Draco 点云几何
+### Draco 几何（点云与三角网格）
 
-v3.01 的点云数据还有一条 Draco 压缩分支（骨架 tag = `DRACO`）。接法与 MeshOpt 相同：内联 wasm 解码器（约 266KB）只在真的遇到时动态 `import`，解码后并入同一套 attribute 组装，点云按 `primitiveType = 1` 交给 `THREE.Points`，分类码 / 强度 / 权重三种自定义属性一并解出来。
+v3.01 支持 Draco 压缩分支（骨架 tag = `DRACO`），涵盖点云与三角网格（`TRIANGULAR_MESH`）。接法与 MeshOpt 相同：内联 wasm 解码器（约 266KB）只在遇到时动态 `import`，解码后并入同一套 attribute 组装：点云按 `primitiveType = 1` 交给 `THREE.Points`（分类码/强度/权重一并解出）；三角网格按面解出顶点索引与法线，按 `primitiveType = 4` 交给 `THREE.Mesh`。遇到未知几何类型自动 warn 降级并跳过，避免整层崩溃。
 
 **这个分支的字段顺序与规范描述对不上，是从真实瓦片逐字节标定的**（偏移以骨架 tag 字段之后为 0）：
 
@@ -1404,16 +1425,25 @@ ts.update([0, 0, 500], 0.64, 900); // 相机在局部 ENU 的位置
 https://host/iserver/services/3D-xxx/rest/realspace/datas/<数据源名>/config
 ```
 
-数据源名可以是中文（如 `寿宁阁`），`new URL()` 会自动百分号编码；后缀只能写 `config`，写 `config.xml` 会 406。只给到 `…/realspace/datas` 时拿到的是一个资源清单数组，`JSON.parse` 不报错但没有 `position` / `rootTiles`，表现为「视角跳到 (0,0) + 一句缺少 root tile」——先用 `…/datas.json` 列出数据源，再逐个拼 `/config`。
+数据源名可以是中文（如 `寿宁阁`），`new URL()` 会自动百分号编码；后缀只能写 `config`，写 `config.xml` 会 406。只给到 `…/realspace/datas` 时拿到的是一个资源清单数组，`JSON.parse` 不报错但没有 `position` / `rootTiles`，表现为「视角跳到 (0,0) + 一句缺少 root tile」——先用 `…/datas.json` 列出数据源，再逐个拼 `/config`。这类报错会带上 config 的类型标记（`FileExtentName` / `Type` / `fileType` / `dataType`），便于区分「清单当配置」和「桌面导出漏瓦片清单」两种病因。
+
+混合服务（模型 + 地形 + 影像共存）里还有第三种触发面：地形/影像数据集的 config 也是 XML，但**没有瓦片清单**。`init` 会按类型标记提前拒绝并说明病因（见 [FORMAT-NOTES 第二章](./FORMAT-NOTES.md#二先判断是哪一种数据)），不再落到「缺少 root tile」：
+
+```
+Error: 数据集 beijingdem 是地形缓存（FileExtentName=Terrainz），本层仅支持模型类 S3M 数据集
+```
 
-配套导出的三个纯函数，方便自建数据集列表与做体检：
+配套导出的五个纯函数，方便自建数据集列表与做体检：
 
 ```ts
-parseConfigText(text)      // JSON 与 SuperMapCache XML 两种配置统一成同一种形状（含 fileType）
+parseConfigText(text)      // JSON 与 SuperMapCache XML 两种配置统一成同一种形状（含 fileType / fileExtentName / cacheType）
+classifyDatasetKind(config) // → 'model' | 'terrain' | 'imagery'；只有认出确凿的非模型标记才判 terrain / imagery
 usableGeoBounds(bounds)    // 判断 geoBounds 是否真的可用；不可用返回 null（见「锚点」）
 fixPathEncoding(url)       // 补路径里没编码但服务端会改写的字符：+ → %2B、空格 → %20
 ```
 
+`classifyDatasetKind` 的判别字段来自实测：地形 = `FileExtentName=Terrainz`；影像 = `Type=Image`（影像的 `FileExtentName` 是 `jpg_png` 这类扩展名样式，不可靠）。认不出标记的一律返回 `'model'`，保证行为与旧版一致；`init` 对非模型数据集抛出的错误上带 `datasetKind` 属性，数据集列表 UI 可以据此标注或跳过。
+
 `fixPathEncoding` 这条是硬需求：OSGB 转出来的瓦片名就是 `Tile_+002_+001`，而 iServer 按 `URLDecoder` 解路径，未编码的 `+` 会变成空格 → 404「瓦片数据不存在」。`new URL()` 认为 `+` 在 path 里合法，不会替我们编码，所以拼完 URL 必须补这一刀（query 里的 `+` 不动，那本来就是空格约定）。
 
 失败处理分两类：**网络类**错误退避重试（`maxRetries`，默认 2 次）；**格式类**错误（`e.permanent === true`，例如 S3M 1.x 容器）直接判失败不重试，并且整棵瓦片树里同类错误只回调一次 `onError`，避免几十块瓦片刷同样的日志。
@@ -1441,6 +1471,7 @@ buildAttributes({ smid, box, triangles, floorHeight })  // → S3MFeatureAttribu
 | `maxTextureSize` | 纹理长边像素上限，默认不限制。手机上 1024 即可，显存降到 1/4 |
 | `maxImageCache` | 纹理缓存条数，默认 128。低端机 32~48，和 `maxTextureSize` 一起管显存 |
 | `materialQuality: 'lambert'` | 换成 Lambert 光照，片元约省一半。白模 / 按高度配色看不出差别，贴图模式会略平。图层级设置，同页其它图层不受影响 |
+| `motionBlur: { mode: 'afterimage' }` | 运动模糊后处理（默认关闭）。低端机低帧率下用帧间残影填卡顿：`afterimage` 每帧只多两次全屏混合，`damp: 'auto'` 按实时 FPS 自适应拖尾长度。建议与上面的预算开关搭配用。注意 RT 为 HalfFloat（半精度浮点，显存 / 带宽 ×2），显存极度吃紧时权衡是否开启 |
 | `maxImageCache` | 原始图集与 leaf 段图像记录的 LRU 缓存容量上限（默认 128），超限自动淘汰旧缓存，防止漫游时内存不断累积 |
 | 纹理引用计数 | 瓦片淘汰时按引用计数释放未被其他瓦片复用的 `Texture` 并调用 `dispose()`，真正归还 GPU 显存 |
 | 几何/材质深度释放 | 瓦片注销时深度遍历对象树，彻底释放 `Mesh`、`Points`（点云/高斯泼溅）以及 `LineSegments`（棱线包）的 `BufferGeometry` 与材质 |

package/docs/FORMAT-NOTES.md

@@ -33,6 +33,16 @@ C 级的处置原则：**只在新样本进来时提高级别，不靠推理提
 | SuperMapCache / S3M 1.x | **XML**（`<SuperMapCache>`，`sml:FileType = OSGBFile`） | `.s3m`（整棵 LOD 树同一种容器） | `S3M1Parser` |
 | 高斯泼溅 | JSON，`dataType = "3DGaussianSplatting"` | `.s3mb` v3.01 + MeshOpt，**无索引包** | `S3MBParser` + `MeshOpt` |
 
+还有第四种撞法（issue #7）：**容器形态识别对了（XML），但内容不是模型**。混合服务（模型 + 地形 + 影像共存，iServer / supermapol 上很常见）里地形/影像数据集的 config 也是 SuperMapCache XML，只是按 `Level0Width/Level0Height + Levels` 的金字塔寻址、**没有瓦片清单**。实测判别字段（3D-OlympicGreen_Plan，2026-10-30）：
+
+| 数据集 | config 根节点 | 判别字段 |
+|:---|:---|:---|
+| `beijingdem`（地形） | `<SuperMapCache>` | `sml:FileExtentName = Terrainz` |
+| `beijingimg`（影像） | `<SuperMapCache_Unicode>` | `sml:Type = Image`（它的 FileExtentName 是 `jpg_png` 这种扩展名样式，**不可靠**） |
+| `Building` 等（模型） | `<SuperMapCache>` | `sml:FileType = OSGBFile / OSGBCacheFile`，无 FileExtentName / Type |
+
+`classifyDatasetKind(config)` 按上表识别，认出地形/影像时 `S3MTileset.init` 会在解析锚点之前明确报错（错误带 `datasetKind` 属性），不再落到误导性的「配置中缺少 root tile」。
+
 **S3M 1.x 必须靠魔数分流，不能靠配置。** 头 4 字节 `73 33 6D 00`（`"s3m\0"`）紧接 `78 da` 的 zlib。不分流的话，头 4 字节会被 float32 读成 1e-38 的「版本号」，再把 zlib 头当长度，报出来的是 `RangeError: Invalid typed array length` —— 一个彻底误导人的错。
 
 ---

package/package.json

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

package/src/core/BakeMercator.ts

@@ -0,0 +1,96 @@
+/**
+ * 全球大尺度精确 Web 墨卡托烘焙（issue #15）。
+ *
+ * ## 背景与原理
+ *
+ * S3M 场景通常只有一个切平面：`_enuMatrix` 用场景锚点纬度的常量 `meterInMercator`
+ * 把整个场景缩放进 Web 墨卡托。但在跨度超过几十公里的全球或大区域场景中，
+ * 墨卡托投影比例随纬度变化（k = 1 / cos(φ)）。
+ * 即使有 `perTilePlacement`（issue #12）按瓦片重置了原点与缩放，瓦片内部仍然存在
+ * 线性切平面与真实墨卡托投影之间的微小残差。
+ *
+ * 烘焙方案：
+ * 1. 预先或在组装瓦片几何时，逐顶点计算其精确的 Web 墨卡托坐标；
+ * 2. 减去瓦片中心的精确墨卡托坐标，得到相对于瓦片中心的相对偏移量 `aMercatorOffset`（float32）；
+ * 3. 为什么是相对偏移：
+ *    Web 墨卡托全局坐标在 0..1 之间，若直接用 float32（24 位尾数）存储绝对坐标，
+ *    分辨率约为 40000000 / 2^24 ≈ 2.38 米；
+ *    若改为相对瓦片中心（瓦片半径通常 <= 100 km），float32 尾数精度可达：
+ *    100000 / 2^24 ≈ 0.0059 米（小于 6 毫米），常规 2 km 瓦片下更是达到 0.1 毫米以内。
+ * 4. 着色器重构：
+ *    顶点着色器在局部对象空间中还原出抵消瓦片尺度与中心平移后的坐标：
+ *    `transformed = uTilePivot + vec3(aMercatorOffset.x, -aMercatorOffset.y, aMercatorOffset.z) * uInvTileScale;`
+ *    其中 `uInvTileScale = 1 / (sScene * k) = 1 / sTile`。
+ *    经过瓦片矩阵变换与 `_enuMatrix` 缩放平移后，刚好恒等于真实的世界墨卡托坐标，误差 < 1 cm。
+ */
+
+import {
+  EARTH_RADIUS,
+  enuToLngLat as geoEnuToLngLat,
+  mercatorFromLngLat,
+} from '../render/GeoAdapter.js';
+
+/** 超过此半径（米）的瓦片在未指定参数时自动开启墨卡托烘焙（25 km） */
+export const AUTO_BAKE_RADIUS_THRESHOLD = 25000;
+
+export interface TileAnchorLike {
+  lon: number;
+  lat: number;
+  height?: number;
+}
+
+export interface TileCenterLike {
+  x: number;
+  y: number;
+  z?: number;
+}
+
+/**
+ * 局部 ENU 偏移（东, 北 米）→ 经纬度（对接 GeoAdapter 的 WGS84 高精度模型）。
+ */
+export function enuToLngLat(anchor: TileAnchorLike, east: number, north: number): [number, number] {
+  return geoEnuToLngLat(anchor.lon, anchor.lat, east, north);
+}
+
+/**
+ * 逐顶点计算 Web 墨卡托相对于瓦片中心的偏移量。
+ *
+ * @param positions 顶点位置数组（x, y, z...）
+ * @param vertexCount 顶点数
+ * @param tileAnchor 数据集/瓦片地理锚点
+ * @param tileCenter 瓦片中心在数据集局部 ENU 中的位置（米）
+ * @param stride 每个顶点的分量数（默认为 3）
+ * @param target 可选的复用 Float32Array
+ * @returns 长度为 vertexCount * 3 的 Float32Array，存 [dx, dy, dz, ...]
+ */
+export function bakeMercatorOffsets(
+  positions: ArrayLike<number>,
+  vertexCount: number,
+  tileAnchor: TileAnchorLike,
+  tileCenter: TileCenterLike,
+  stride = 3,
+  target?: Float32Array
+): Float32Array {
+  const out = target && target.length >= vertexCount * 3 ? target : new Float32Array(vertexCount * 3);
+
+  const centerAlt = (tileAnchor.height ?? 0) + (tileCenter.z ?? 0);
+  const [centerLon, centerLat] = enuToLngLat(tileAnchor, tileCenter.x, tileCenter.y);
+  const cMerc = mercatorFromLngLat(centerLon, centerLat, centerAlt);
+
+  for (let i = 0; i < vertexCount; i++) {
+    const idx = i * stride;
+    const vx = positions[idx];
+    const vy = positions[idx + 1];
+    const vz = positions[idx + 2] ?? 0;
+
+    const vAlt = (tileAnchor.height ?? 0) + vz;
+    const [vLon, vLat] = enuToLngLat(tileAnchor, vx, vy);
+    const vMerc = mercatorFromLngLat(vLon, vLat, vAlt);
+
+    out[i * 3 + 0] = vMerc.x - cMerc.x;
+    out[i * 3 + 1] = vMerc.y - cMerc.y;
+    out[i * 3 + 2] = vMerc.z - cMerc.z;
+  }
+
+  return out;
+}

package/src/core/CustomAttributes.ts

@@ -0,0 +1,53 @@
+import type { VertexAttribute, VertexPackage } from './types.js';
+
+/**
+ * 根据 descript（来自瓦片内嵌或 config.json 的 vertexAttributeDescript）
+ * 将 custom 扩展属性槽（如 custom0, custom1...）重命名为实际的语义名（如 VertexWeight, TextureCoordMatrix）。
+ */
+export function applyCustomAttributeSemantics(
+  vp: VertexPackage,
+  extAttrs?: VertexAttribute[],
+  configDescript?: unknown
+): void {
+  const attrsToRemap = extAttrs ?? vp.vertexAttributes.filter((a) => a.semantic.startsWith('custom'));
+  if (attrsToRemap.length === 0) return;
+
+  const descript = vp.customVertexAttribute ?? configDescript;
+
+  for (let i = 0; i < attrsToRemap.length; i++) {
+    const attr = attrsToRemap[i]!;
+    if (!attr.semantic.startsWith('custom')) continue;
+    const slotMatch = attr.semantic.match(/^custom(\d+)$/);
+    const slot = slotMatch ? parseInt(slotMatch[1]!, 10) : i;
+
+    let category: string | undefined;
+
+    const resolveCategory = (source: unknown): string | undefined => {
+      if (!source || typeof source !== 'object') return undefined;
+      if (Array.isArray(source)) {
+        const item = source[slot];
+        if (typeof item === 'string') return item;
+        if (item && typeof item === 'object' && typeof item.category === 'string') return item.category;
+        return undefined;
+      }
+      for (const [k, v] of Object.entries(source as Record<string, unknown>)) {
+        if (v === slot) return k;
+      }
+      return undefined;
+    };
+
+    category = resolveCategory(descript);
+    if (!category && configDescript && configDescript !== descript) {
+      category = resolveCategory(configDescript);
+    }
+
+    if (category) {
+      delete vp.attrLocation[attr.semantic];
+      delete vp.attrLocation[`a${attr.semantic}`];
+      attr.semantic = category;
+      const idx = vp.vertexAttributes.indexOf(attr);
+      vp.attrLocation[category] = idx;
+      vp.attrLocation[`a${category}`] = idx;
+    }
+  }
+}

package/src/core/Draco.ts

@@ -1,4 +1,4 @@
-/**
+/**
  * S3M v3 Draco 几何压缩（Skeleton 的 Draco 分支）
  *
  * 与 MeshOpt 一样，这里的布局不是照规范写的 —— 规范里的 Draco 分支描述和实际数据
@@ -33,7 +33,7 @@
  */
 import type { BinaryReader } from './BinaryReader.js';
 import type { AttrDType, IndexPackage, VertexPackage } from './types.js';
-import type { DracoModule, DracoPointAttribute, DracoPointCloud } from '../vendor/draco_decoder.module.js';
+import type { DracoMesh, DracoModule, DracoPointAttribute, DracoPointCloud } from '../vendor/draco_decoder.module.js';
 
 /* ------------------------------------------------------------ draco 枚举（本地副本） */
 
@@ -57,6 +57,9 @@ const DRACO_MAGIC = 'DRACO';
 /** primitiveType = 1：点云包（渲染层据此走 THREE.Points） */
 const POINT_PRIMITIVE = 1;
 
+/** primitiveType = 4：三角网格包（渲染层据此走 THREE.Mesh，对应 gl.TRIANGLES） */
+const TRIANGLE_PRIMITIVE = 4;
+
 /** 单个 skeleton 的点数上限，防头读错时开出天文数字的缓冲 */
 const MAX_POINTS = 64 * 1024 * 1024;
 
@@ -243,13 +246,27 @@ export async function parseDracoGeometry(r: BinaryReader, vp: VertexPackage): Pr
   /* ---- 2. 解码 ---- */
 
   const decoder = new draco.Decoder();
+  const geomType = decoder.GetEncodedGeometryType(data);
+
+  if (geomType === GEOM_TRIANGULAR_MESH) {
+    // 三角网格分支：draco mesh 内部自带面索引，不需要容器里的 IndexPackage
+    // 官方 S3ModelParser 对 Draco 分支的索引包解析阶段是空操作（see Issue #5）
+    const mesh = new draco.Mesh();
+    try {
+      return decodeDracoMesh(draco, decoder, mesh, data, vp, posUniqueId, normalUniqueId, colorUniqueId);
+    } finally {
+      try { draco.destroy(decoder); draco.destroy(mesh); } catch { /* ignore */ }
+    }
+  }
+
+  // 点云分支（GEOM_POINT_CLOUD）或其他未知类型
   const geometry = new draco.PointCloud();
   try {
-    const geomType = decoder.GetEncodedGeometryType(data);
     if (geomType !== GEOM_POINT_CLOUD) {
-      throw new Error(
-        `[s3m] Draco ${geomType === GEOM_TRIANGULAR_MESH ? '三角网格' : '未知'} 几何暂未实现（仅支持点云）`
-      );
+      // 未知几何类型：warn 并降级为空包，避免整层崩溃
+      console.warn(`[s3m] Draco 未知几何类型 ${geomType}，跳过该骨架`);
+      vp.verticesCount = 0;
+      return [pointPack()];
     }
 
     const status = decoder.DecodeArrayToPointCloud(data, data.length, geometry);
@@ -373,6 +390,151 @@ function pointPack(): IndexPackage {
   };
 }
 
+/**
+ * 解码 Draco TRIANGULAR_MESH 几何体，填充 VertexPackage 并返回带索引的 IndexPackage。
+ *
+ * 按官方 S3MDracoDecode.js 逻辑（Issue #5 调研）：
+ *   - DecodeArrayToMesh → num_faces → 逐面 GetFaceFromMesh → 填入索引缓冲
+ *   - primitiveType = TRIANGLE_PRIMITIVE（4），让渲染层走 THREE.Mesh
+ *   - 容器头（posUniqueId/normalUniqueId/colorUniqueId）与点云共用，直接复用属性装配代码
+ *
+ * 调用方负责 destroy(decoder) 和 destroy(mesh)。
+ */
+function decodeDracoMesh(
+  draco: DracoModule,
+  decoder: InstanceType<DracoModule['Decoder']>,
+  mesh: DracoMesh,
+  data: Uint8Array,
+  vp: VertexPackage,
+  posUniqueId: number,
+  normalUniqueId: number,
+  colorUniqueId: number,
+): IndexPackage[] {
+  const status = decoder.DecodeArrayToMesh(data, data.length, mesh);
+  if (!status.ok()) throw new Error(`[s3m] Draco mesh 解码失败：${status.error_msg()}`);
+
+  const numPoints = mesh.num_points();
+  if (!Number.isInteger(numPoints) || numPoints < 0 || numPoints > MAX_POINTS) {
+    throw new Error(`[s3m] Draco mesh 顶点数异常：${numPoints}`);
+  }
+  const numFaces = mesh.num_faces();
+
+  if (numPoints === 0 || numFaces === 0) {
+    vp.verticesCount = 0;
+    return [meshPack(new Uint8Array(0), 0, 0)];
+  }
+
+  /* ---- 属性装配（与点云分支共用逻辑，但三角网格有法线） ---- */
+
+  for (let i = 0; i < mesh.num_attributes(); i++) {
+    const attr = decoder.GetAttribute(mesh, i);
+    const uid = attr.unique_id();
+    const comps = Math.max(1, attr.num_components());
+
+    if (uid === posUniqueId || attr.attribute_type() === ATTR_POSITION) {
+      if (attr.data_type() !== DT_FLOAT32) {
+        throw new Error(`[s3m] Draco mesh 位置属性不是 float32（dt=${attr.data_type()}）`);
+      }
+      const raw = readAttribute(draco, decoder, mesh, attr) as Float32Array | null;
+      if (!raw) throw new Error('[s3m] Draco mesh 位置属性读取失败');
+      const out = new Float32Array(numPoints * 3);
+      for (let p = 0; p < numPoints; p++) {
+        out[p * 3] = raw[p * comps] ?? 0;
+        out[p * 3 + 1] = raw[p * comps + 1] ?? 0;
+        out[p * 3 + 2] = raw[p * comps + 2] ?? 0;
+      }
+      pushAttr(vp, 'position', new Uint8Array(out.buffer), 3, 12, 0, undefined, 'f32');
+      continue;
+    }
+
+    if (uid === normalUniqueId || attr.attribute_type() === ATTR_NORMAL) {
+      if (attr.data_type() === DT_FLOAT32) {
+        const raw = readAttribute(draco, decoder, mesh, attr) as Float32Array | null;
+        if (raw) {
+          // 法线量化由 draco 解码时自动还原为 float32
+          const out = new Float32Array(numPoints * 3);
+          for (let p = 0; p < numPoints; p++) {
+            out[p * 3] = raw[p * comps] ?? 0;
+            out[p * 3 + 1] = raw[p * comps + 1] ?? 0;
+            out[p * 3 + 2] = raw[p * comps + 2] ?? 0;
+          }
+          pushAttr(vp, 'normal', new Uint8Array(out.buffer), 3, 12, 0, undefined, 'f32');
+        }
+      }
+      continue;
+    }
+
+    if (uid === colorUniqueId || attr.attribute_type() === ATTR_COLOR) {
+      const raw = readAttribute(draco, decoder, mesh, attr);
+      if (raw) {
+        const out = new Uint8Array(numPoints * 4);
+        const isFloat = raw instanceof Float32Array;
+        for (let p = 0; p < numPoints; p++) {
+          const o = p * comps;
+          if (isFloat) {
+            out[p * 4] = clamp255(raw[o] ?? 1);
+            out[p * 4 + 1] = clamp255(raw[o + 1] ?? 1);
+            out[p * 4 + 2] = clamp255(raw[o + 2] ?? 1);
+          } else {
+            out[p * 4] = raw[o] ?? 255;
+            out[p * 4 + 1] = raw[o + 1] ?? 255;
+            out[p * 4 + 2] = raw[o + 2] ?? 255;
+          }
+          out[p * 4 + 3] = comps >= 4 && !isFloat ? (raw[o + 3] ?? 255) : 255;
+        }
+        pushAttr(vp, 'color', out, 4, 4, 0, undefined, 'u8');
+      }
+      continue;
+    }
+    // 其余属性（texCoord 等）：暂不处理，等真实瓦片来后按需补齐
+  }
+
+  if (vp.attrLocation.position === undefined) {
+    throw new Error('[s3m] Draco mesh 缺少 position 属性');
+  }
+
+  vp.verticesCount = numPoints;
+
+  /* ---- 三角面索引构建（按官方逻辑：numPoints <= 65535 用 U16，否则 U32） ---- */
+  const useU16 = numPoints <= 65535;
+  const indices = useU16
+    ? new Uint16Array(numFaces * 3)
+    : new Uint32Array(numFaces * 3);
+
+  const face = new draco.DracoInt32Array();
+  try {
+    let n = 0;
+    for (let f = 0; f < numFaces; f++) {
+      decoder.GetFaceFromMesh(mesh, f, face);
+      indices[n++] = face.GetValue(0);
+      indices[n++] = face.GetValue(1);
+      indices[n++] = face.GetValue(2);
+    }
+  } finally {
+    draco.destroy(face);
+  }
+
+  return [meshPack(new Uint8Array(indices.buffer), numFaces * 3, useU16 ? 0 : 1)];
+}
+
+/**
+ * 三角网格索引包。
+ *
+ * @param indicesBytes - Uint16Array 或 Uint32Array 的字节视图
+ * @param indexCount   - 索引总数（numFaces × 3）
+ * @param indexType    - 0 = Uint16, 1 = Uint32（与 IndexPackage.indexType 约定一致）
+ */
+function meshPack(indicesBytes: Uint8Array, indexCount: number, indexType: number): IndexPackage {
+  return {
+    indexCount,
+    indexType,
+    useIndex: 1,
+    primitiveType: TRIANGLE_PRIMITIVE,
+    indices: indexCount > 0 ? indicesBytes : null,
+    passNames: [],
+  };
+}
+
 function pushAttr(
   vp: VertexPackage,
   semantic: string,

package/src/core/MeshOpt.ts

@@ -18,6 +18,7 @@
 import type { BinaryReader } from './BinaryReader.js';
 import type { IndexPackage, VertexAttribute, VertexPackage } from './types.js';
 import type { MeshoptDecoder } from '../vendor/meshopt_decoder.module.js';
+import { applyCustomAttributeSemantics } from './CustomAttributes.js';
 
 /** 顶点语义是位标记，不是枚举序号 */
 export const MeshOptSemantic = {
@@ -451,6 +452,7 @@ export async function parseMeshOptGeometry(
   for (let i = 0; i < vp.vertexAttributes.length; i++) {
     vp.attrLocation[`a${vp.vertexAttributes[i].semantic}`] = i;
   }
+  applyCustomAttributeSemantics(vp);
 
   return { info, indexPackages };
 }