s3m-three 0.3.5 → 0.3.6

package/dist/worker/S3MWorkerClient.js

@@ -0,0 +1,120 @@
+/** Worker 崩溃 / 不可用 —— 与「瓦片数据本身有问题」区分开，调用方据此决定降级还是重试 */
+export class WorkerDeadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WorkerDeadError';
+    }
+}
+export class S3MWorkerClient {
+    _worker;
+    _seq = 0;
+    _pending = new Map();
+    /** true = 已崩溃 / 已终止，后续请求直接拒绝 */
+    dead = false;
+    /** 创建失败返回 null（不抛），调用方据此走主线程解析 */
+    static create() {
+        if (typeof Worker === 'undefined')
+            return null;
+        try {
+            // 路径锚定本模块的编译产物（dist/worker/s3mWorker.js）；
+            // Vite 打包时会把这个 pattern 转成独立 worker 资产，IIFE 直引场景由死锁降级兜底
+            const worker = new Worker(new URL('./s3mWorker.js', import.meta.url), { type: 'module' });
+            return new S3MWorkerClient(worker);
+        }
+        catch {
+            return null;
+        }
+    }
+    constructor(worker) {
+        this._worker = worker;
+        worker.onmessage = (e) => {
+            const msg = e.data;
+            const waiter = this._pending.get(msg.id);
+            if (!waiter)
+                return;
+            this._pending.delete(msg.id);
+            if (!msg.ok) {
+                // 还原主线程 parseS3MB 的错误形状：permanent 标记驱动瓦片级的「永久失败」分支
+                const err = new Error(msg.message);
+                err.permanent = msg.permanent;
+                waiter.reject(err);
+            }
+            else if ('tile' in msg) {
+                waiter.resolve(msg.tile);
+            }
+            else {
+                waiter.resolve(msg.data);
+            }
+        };
+        worker.onerror = () => this._die('s3m 解析 Worker 加载失败/崩溃');
+        worker.onmessageerror = () => this._die('s3m 解析 Worker 消息无法反序列化');
+    }
+    /** 解析一块瓦片。buffer 会被 structured clone（不 transfer），主线程保留原 buffer 以便崩溃后降级重解 */
+    parseTile(buffer) {
+        if (this.dead)
+            return Promise.reject(new WorkerDeadError('s3m 解析 Worker 已终止'));
+        const id = ++this._seq;
+        return new Promise((resolve, reject) => {
+            this._pending.set(id, { resolve: resolve, reject });
+            this._worker.postMessage({ type: 'parse', id, buffer });
+        });
+    }
+    /** 解码一张纹理（DXT / CRN / WEBP / RGB 系）。tex.data 走 structured clone，主线程保留原数据 */
+    decodeTexture(tex) {
+        if (this.dead)
+            return Promise.reject(new WorkerDeadError('s3m 解析 Worker 已终止'));
+        const id = ++this._seq;
+        return new Promise((resolve, reject) => {
+            this._pending.set(id, { resolve: resolve, reject });
+            this._worker.postMessage({ type: 'tex', id, tex });
+        });
+    }
+    dispose() {
+        this._die('dispose');
+    }
+    _die(reason) {
+        if (this.dead)
+            return;
+        this.dead = true;
+        try {
+            this._worker.terminate();
+        }
+        catch {
+            /* 已死的 worker terminate 不会再抛 */
+        }
+        const err = new WorkerDeadError(`${reason}，退回主线程解析`);
+        for (const waiter of this._pending.values())
+            waiter.reject(err);
+        this._pending.clear();
+    }
+}
+/* ------------------------------------------------------------------ 共享单例 */
+/**
+ * 进程级共享的解析 Worker（解析 + 纹理解码共用一个线程，避免每个数据集 /
+ * 每个渲染层各起一个 Worker 把内存和调度打爆）。懒创建，崩溃后返回 null。
+ */
+let sharedClient;
+export function getSharedS3MWorker() {
+    if (sharedClient === undefined)
+        sharedClient = S3MWorkerClient.create();
+    if (sharedClient && sharedClient.dead)
+        return null;
+    return sharedClient;
+}
+/**
+ * 纹理解码的「Worker 优先」入口，供 TextureFactory.setTextureOffThreadDecode 装配。
+ * 永不 reject：Worker 不可用 / 崩溃 / 单张解码失败都返回 null，调用方主线程兜底
+ * （解码失败本身在 decodeTextureData 里也不抛错，走 crn(failed) 之类的标记）。
+ */
+export async function decodeTextureWithWorker(tex) {
+    const client = getSharedS3MWorker();
+    if (!client)
+        return null;
+    try {
+        return await client.decodeTexture(tex);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=S3MWorkerClient.js.map

package/dist/worker/S3MWorkerClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"S3MWorkerClient.js","sourceRoot":"","sources":["../../src/worker/S3MWorkerClient.ts"],"names":[],"mappings":"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"}

package/dist/worker/s3mWorker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=s3mWorker.d.ts.map

package/dist/worker/s3mWorker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3mWorker.d.ts","sourceRoot":"","sources":["../../src/worker/s3mWorker.ts"],"names":[],"mappings":""}

package/dist/worker/s3mWorker.js

@@ -0,0 +1,48 @@
+/**
+ * S3M 解析 / 纹理解码 Worker 入口。
+ *
+ * 职责：把 CPU 密集的解码搬离主线程——
+ *   - parse：`.s3mb`（含 S3M 1.x / Draco / MeshOpt 内联 wasm 解码）整块解析；
+ *   - tex：  纹理解码（DXT 解块 / CRN wasm 转码 / WEBP createImageBitmap），
+ *            与主线程共用 core/TextureDecode.ts 的同一份实现。
+ * 抓取（fetch）仍由 S3MTileset 在主线程做——重试、退避、content-type 检查这些
+ * 语义都留在原处不动，Worker 只收字节、吐纯数据结果。
+ *
+ * 协议：
+ *   { type:'parse', id, buffer } → { id, ok:true, tile } | { id, ok:false, message, permanent }
+ *   { type:'tex',  id, tex }     → { id, ok:true, data } | { id, ok:false, message }
+ *
+ * 线程安全：两个入口都无模块级可变状态；每次调用用独立的 reader / 解码器实例。
+ */
+import { parseS3MB } from '../core/S3MBParser.js';
+import { decodeTextureData } from '../core/TextureDecode.js';
+import { collectTransferables } from './transferables.js';
+const ctx = self;
+/** 纹理解码响应的传输清单：RGBA 像素 buffer + WEBP 的 ImageBitmap 都走零拷贝 */
+function texTransferList(data) {
+    const list = collectTransferables(data);
+    if (data.bitmap)
+        list.push(data.bitmap);
+    return list;
+}
+ctx.onmessage = async (e) => {
+    const msg = e.data;
+    const { id } = msg;
+    try {
+        if (msg.type === 'parse') {
+            const tile = await parseS3MB(msg.buffer);
+            // 响应整体过线（零拷贝）；请求 buffer 是主线程 structured clone 过来的副本，无需回传
+            ctx.postMessage({ id, ok: true, tile }, collectTransferables(tile));
+        }
+        else {
+            const data = await decodeTextureData(msg.tex);
+            ctx.postMessage({ id, ok: true, data }, texTransferList(data));
+        }
+    }
+    catch (err) {
+        const permanent = err?.permanent === true;
+        const message = String(err?.message ?? err);
+        ctx.postMessage({ id, ok: false, message, permanent });
+    }
+};
+//# sourceMappingURL=s3mWorker.js.map

package/dist/worker/s3mWorker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3mWorker.js","sourceRoot":"","sources":["../../src/worker/s3mWorker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAY1D,MAAM,GAAG,GAAG,IAAyB,CAAC;AAEtC,4DAA4D;AAC5D,SAAS,eAAe,CAAC,IAAmD;IAC1E,MAAM,IAAI,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,IAAI,CAAC,MAAM;QAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAgC,CAAC,CAAC;IAClE,OAAO,IAAI,CAAC;AACd,CAAC;AAED,GAAG,CAAC,SAAS,GAAG,KAAK,EAAE,CAAwB,EAAE,EAAE;IACjD,MAAM,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC;IACnB,MAAM,EAAE,EAAE,EAAE,GAAG,GAAG,CAAC;IACnB,IAAI,CAAC;QACH,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACzC,yDAAyD;YACzD,GAAG,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAA0B,EAAE,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9F,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,GAAG,MAAM,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC9C,GAAG,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAwB,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,SAAS,GAAI,GAAsC,EAAE,SAAS,KAAK,IAAI,CAAC;QAC9E,MAAM,OAAO,GAAG,MAAM,CAAE,GAAoB,EAAE,OAAO,IAAI,GAAG,CAAC,CAAC;QAC9D,GAAG,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;IACzD,CAAC;AACH,CAAC,CAAC"}

package/dist/worker/transferables.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 传输清单收集：递归扫出对象图里所有可 Transfer 的 ArrayBuffer（去重）。
+ *
+ * 用于 Worker 往返的零拷贝：postMessage 的 transferList 传这个清单后，
+ * 线程间共享同一块内存（structured clone 只拷贝「壳」，不拷字节）。
+ *
+ * 安全性约定：**要么全转，要么不转** —— 同一块 ArrayBuffer 上可能挂着多个视图
+ * （positions / normals 常是同一块顶点缓冲的 subarray），transferList 里出现它一次
+ * 之后所有视图共享的底层数据整体过线，视图本身仍然有效；但如果只转一半视图、
+ * 另一半留在原地，留在原地的会因 detach 变成空数据。所以只允许「把整个对象图
+ * 的 buffer 全部收集」或「完全不收集」两种用法，不支持挑着转。
+ */
+export declare function collectTransferables(root: unknown): ArrayBuffer[];
+//# sourceMappingURL=transferables.d.ts.map

package/dist/worker/transferables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transferables.d.ts","sourceRoot":"","sources":["../../src/worker/transferables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,EAAE,CAyCjE"}

package/dist/worker/transferables.js

@@ -0,0 +1,61 @@
+/**
+ * 传输清单收集：递归扫出对象图里所有可 Transfer 的 ArrayBuffer（去重）。
+ *
+ * 用于 Worker 往返的零拷贝：postMessage 的 transferList 传这个清单后，
+ * 线程间共享同一块内存（structured clone 只拷贝「壳」，不拷字节）。
+ *
+ * 安全性约定：**要么全转，要么不转** —— 同一块 ArrayBuffer 上可能挂着多个视图
+ * （positions / normals 常是同一块顶点缓冲的 subarray），transferList 里出现它一次
+ * 之后所有视图共享的底层数据整体过线，视图本身仍然有效；但如果只转一半视图、
+ * 另一半留在原地，留在原地的会因 detach 变成空数据。所以只允许「把整个对象图
+ * 的 buffer 全部收集」或「完全不收集」两种用法，不支持挑着转。
+ */
+/** 递归深度上限。ParsedTile 的层级是固定的（tile → geoPackage → geode → package），远用不到 12 层 */
+const MAX_DEPTH = 12;
+export function collectTransferables(root) {
+    const buffers = new Set();
+    const seen = new Set();
+    const walk = (value, depth) => {
+        if (value == null || depth > MAX_DEPTH)
+            return;
+        if (ArrayBuffer.isView(value)) {
+            const b = value.buffer;
+            if (b instanceof ArrayBuffer)
+                buffers.add(b);
+            return;
+        }
+        if (value instanceof ArrayBuffer) {
+            buffers.add(value);
+            return;
+        }
+        if (typeof value !== 'object')
+            return;
+        const obj = value;
+        if (seen.has(obj))
+            return;
+        seen.add(obj);
+        if (Array.isArray(obj)) {
+            for (const item of obj)
+                walk(item, depth + 1);
+            return;
+        }
+        if (obj instanceof Map) {
+            for (const [k, v] of obj) {
+                walk(k, depth + 1);
+                walk(v, depth + 1);
+            }
+            return;
+        }
+        if (obj instanceof Set) {
+            for (const item of obj)
+                walk(item, depth + 1);
+            return;
+        }
+        for (const key of Object.keys(obj)) {
+            walk(obj[key], depth + 1);
+        }
+    };
+    walk(root, 0);
+    return [...buffers];
+}
+//# sourceMappingURL=transferables.js.map

package/dist/worker/transferables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transferables.js","sourceRoot":"","sources":["../../src/worker/transferables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,+EAA+E;AAC/E,MAAM,SAAS,GAAG,EAAE,CAAC;AAErB,MAAM,UAAU,oBAAoB,CAAC,IAAa;IAChD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAe,CAAC;IACvC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,MAAM,IAAI,GAAG,CAAC,KAAc,EAAE,KAAa,EAAQ,EAAE;QACnD,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,GAAG,SAAS;YAAE,OAAO;QAC/C,IAAI,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,MAAM,CAAC,GAAI,KAAyB,CAAC,MAAM,CAAC;YAC5C,IAAI,CAAC,YAAY,WAAW;gBAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC7C,OAAO;QACT,CAAC;QACD,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;YACjC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACnB,OAAO;QACT,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO;QACtC,MAAM,GAAG,GAAG,KAAe,CAAC;QAC5B,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO;QAC1B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,KAAK,MAAM,IAAI,IAAI,GAAG;gBAAE,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YAC9C,OAAO;QACT,CAAC;QACD,IAAI,GAAG,YAAY,GAAG,EAAE,CAAC;YACvB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC;gBACzB,IAAI,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;gBACnB,IAAI,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YACrB,CAAC;YACD,OAAO;QACT,CAAC;QACD,IAAI,GAAG,YAAY,GAAG,EAAE,CAAC;YACvB,KAAK,MAAM,IAAI,IAAI,GAAG;gBAAE,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YAC9C,OAAO;QACT,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,IAAI,CAAE,GAA+B,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QACzD,CAAC;IACH,CAAC,CAAC;IAEF,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACd,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;AACtB,CAAC"}

package/docs/API.md

@@ -163,6 +163,8 @@ new S3MViewer(options?: S3MViewerOptions)
 | `totalMaxTiles` | `number` | — | 多数据集全局驻留瓦片总预算；开启后在可见数据集间动态均衡分配，防止叠加爆显存 |
 | `light` | `LightOptions` | — | 场景光照配置，可配环境光与主平行光的颜色、强度、模式与方位角/高度角 |
 | `maxConcurrent` | `number` | `4` | 每个数据集并发请求数 |
+| `useWorker` | `boolean` | `true` | 用 Web Worker 解析经典 `.s3mb` 瓦片（inflate / Draco / MeshOpt 全在 Worker 跑，主线程只做 fetch 与几何组装）；Worker 不可用或崩溃时自动永久降级主线程。S3MBLOCK 路径仍主线程解析 |
+| （随 `useWorker`）纹理解码 | `boolean` | `true` | DXT / CRN / WEBP 纹理解码与 `.s3mb` 解析共用同一个 Worker（`core/TextureDecode.ts` 三方共用同一份实现，WEBP 走可 transfer 的 ImageBitmap）；失败自动回主线程，产物逐字节一致 |
 | `lodRangeScale` | `number` | `1.0` | LOD 切换距离缩放系数，> 1 更倾向保留粗模，< 1 提前细化 |
 | `buildTile` | `BuildTileFn \| null` | — | 自定义瓦片构建器（测试 / 服务端渲染时注入） |
 | `attributes` | `AttributeQueryOptions` | — | 业务属性查询配置，配了才能 `colorByField()`，见[按业务字段着色](#按业务字段着色) |
@@ -291,6 +293,8 @@ flushOverrides(): void          // 手动刷脏标记（紧接着读纹理 / 截
 getAllMeshes(): THREE.Mesh[]    // 当前驻留的全部网格
 ```
 
+`FeatureStyle.opacity` 支持单体独立透明度（batch 粒度）：写入状态纹理第 2 行 alpha，片元里与全局透明度、贴图 alpha 叠乘。约定 `0 < opacity < 1` 生效，`opacity <= 0` 等价 `hidden`，`1` / 不传 = 不覆盖；有淡化单体时该块材质自动开混合，清除后还原为全局透明度语义。与 LOD / 拾取 / 描边兼容（淡化只是改像素 alpha，不参与深度剔除）。
+
 ### 字段着色 / 过滤 / 抬高
 
 ```ts

package/package.json

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

package/src/core/TextureDecode.ts

@@ -0,0 +1,158 @@
+/**
+ * S3M 纹理解码（three 无关，主线程 / Worker 共用同一份实现）
+ *
+ * 职责到「解出像素数据」为止：DXT 族解块成 RGBA8、CRN 先用 crunch wasm 转码回 DXT
+ * 再解块、WEBP 交给 createImageBitmap、RGB 系逐像素重排。产出是纯数据
+ * （DecodedTextureData），包成 three 对象由渲染层的 TextureFactory 负责——
+ * 这样整份文件可以原样搬进 Worker 跑。
+ *
+ * 该走哪条解码路径由 compressType 判定（见 core/TextureFormat.ts）：
+ * v3.00 的 CRN 纹理 pixelFormat 是 13（ABGR）、行标的 CRN 是 32856（GL_RGBA8），
+ * 都不是 26 / 27，所以判定只能看 compressType，不能看 pixelFormat。
+ */
+import DXTTextureDecode from './DXTTextureDecode.js';
+import { transcodeCRN } from './CRNDecode.js';
+import { dxtPixelFormatOf, resolveTextureKind, PixelFormat } from './TextureFormat.js';
+import type { S3MTexture } from './types.js';
+
+/** 解码产物：rgba 与 bitmap 二选一，都为 null = 解码失败 / 格式不支持 */
+export interface DecodedTextureData {
+  /** 实际走的解码路径（'crn->dxt5' / 'dxt1' / 'raw' / 'webp' / 'crn(failed)' / 'unsupported(...)'） */
+  kind: string;
+  width: number;
+  height: number;
+  /** RGBA8 像素（已按需翻行） */
+  rgba: Uint8Array | null;
+  /** WEBP 路径的解码结果（ImageBitmap 可 transfer，主线程直接 new THREE.Texture 包） */
+  bitmap: ImageBitmap | null;
+  hasAlpha: boolean;
+  /** CRN 转码失败时的原始错误（渲染层负责打 warn） */
+  error?: string;
+}
+
+/** 行序翻转（原地）。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' | 'flipY'>): {
+  rgba: Uint8Array;
+  hasAlpha: boolean;
+} {
+  const { width, height, pixelFormat, data } = tex;
+  const out = new Uint8Array(width * height * 4);
+  DXTTextureDecode.decode(out, width, height, data, pixelFormat);
+  if (tex.flipY) flipRows(out, width, height);
+  return { rgba: out, hasAlpha: hasAlphaChannel(pixelFormat) };
+}
+
+function rawRGBA(tex: S3MTexture): { rgba: Uint8Array; hasAlpha: boolean } {
+  const { width, height, pixelFormat, data } = tex;
+  const out = new Uint8Array(width * height * 4);
+  // RGBA / BGRA / ARGB / ABGR 都是 4 字节，前两个是「尾字节是 alpha」，后两个是「首字节是 alpha」
+  const hasAlpha =
+    pixelFormat === PixelFormat.RGBA ||
+    pixelFormat === PixelFormat.BGRA ||
+    pixelFormat === PixelFormat.ARGB ||
+    pixelFormat === PixelFormat.ABGR;
+  const swapRB = pixelFormat === PixelFormat.BGR || pixelFormat === PixelFormat.BGRA;
+  const alphaFirst = pixelFormat === PixelFormat.ARGB || pixelFormat === PixelFormat.ABGR;
+  const src = hasAlpha ? 4 : 3;
+  for (let i = 0, s = 0, d = 0; i < width * height; i++, s += src, d += 4) {
+    const p = alphaFirst ? s + 1 : s;
+    out[d] = swapRB ? data[p + 2] : data[p];
+    out[d + 1] = data[p + 1];
+    out[d + 2] = swapRB ? data[p] : data[p + 2];
+    out[d + 3] = hasAlpha ? data[alphaFirst ? s : s + 3] : 255;
+  }
+  if (tex.flipY) flipRows(out, width, height);
+  return { rgba: out, hasAlpha: hasAlphaChannel(pixelFormat) };
+}
+
+/** 主线程 / Worker 共用的解码入口。不抛错：失败与不支持都体现在返回值里 */
+export async function decodeTextureData(tex: S3MTexture): Promise<DecodedTextureData> {
+  const empty: DecodedTextureData = {
+    kind: 'unsupported(0/0)',
+    width: 0,
+    height: 0,
+    rgba: null,
+    bitmap: null,
+    hasAlpha: false,
+  };
+  if (!tex || !tex.width || !tex.height) return empty;
+
+  const kind = resolveTextureKind(tex.compressType ?? 0, tex.pixelFormat);
+
+  if (kind === 'crn') {
+    try {
+      const crn = await transcodeCRN(tex.data);
+      const decoded = decodeDXT({
+        width: crn.width,
+        height: crn.height,
+        pixelFormat: crn.dxtFormat === 1 ? PixelFormat.DXT1 : PixelFormat.DXT5,
+        data: crn.data,
+      });
+      return {
+        kind: `crn->dxt${crn.dxtFormat}`,
+        width: crn.width,
+        height: crn.height,
+        rgba: decoded.rgba,
+        bitmap: null,
+        hasAlpha: decoded.hasAlpha,
+      };
+    } catch (e) {
+      // 一张纹理坏了不该带崩整个瓦片，如实上报并降级成无贴图
+      return {
+        kind: 'crn(failed)',
+        width: tex.width,
+        height: tex.height,
+        rgba: null,
+        bitmap: null,
+        hasAlpha: false,
+        error: String((e as Error | null)?.message ?? e),
+      };
+    }
+  }
+
+  if (kind === 'dxt1' || kind === 'dxt3' || kind === 'dxt4' || kind === 'dxt5') {
+    const decoded = decodeDXT({ ...tex, pixelFormat: dxtPixelFormatOf(kind) });
+    return { kind, width: tex.width, height: tex.height, rgba: decoded.rgba, bitmap: null, hasAlpha: decoded.hasAlpha };
+  }
+
+  if (kind === 'webp') {
+    const blob = new Blob([tex.data as BlobPart], { type: 'image/webp' });
+    const bitmap = await createImageBitmap(blob);
+    return { kind, width: bitmap.width, height: bitmap.height, rgba: null, bitmap, hasAlpha: true };
+  }
+
+  if (kind === 'raw') {
+    const decoded = rawRGBA(tex);
+    return { kind, width: tex.width, height: tex.height, rgba: decoded.rgba, bitmap: null, hasAlpha: decoded.hasAlpha };
+  }
+
+  // KTX2 / ETC 需要额外解码器，先如实上报而不是静默出错
+  return { ...empty, kind: `unsupported(${tex.compressType}/${tex.pixelFormat})` };
+}

package/src/core/TextureFormat.ts

@@ -18,8 +18,29 @@
  * 真实服务里的 CRN 纹理会被当成未知格式整包丢掉（模型变成无贴图的灰模）。
  */
 
-/** S3M 3.01（行标）compressType 取值 */
-export const TextureCompress = {
+/**
+ * S3M 像素 / 块格式枚举（iClient3D S3MPixelFormat）。
+ *
+ * 原本住在 render/TextureFactory，纹理解码下沉到 core（Worker 复用）后搬到这里；
+ * TextureFactory 保留同名 re-export，对外 API 不变。
+ */
+export const PixelFormat = {
+  RGB: 10,
+  BGR: 11,
+  ARGB: 12,
+  ABGR: 13,
+  BGRA: 14,
+  RGBA: 28,
+  WEBP: 25,
+  DXT1: 17,
+  DXT3: 19,
+  DXT4: 20,
+  DXT5: 21,
+  CRN_DXT5: 26,
+  STANDARD_CRN: 27,
+} as const;
+
+/** S3M 3.01（行标）compressType 取值 */export const TextureCompress = {
   NONE: 0,
   DXT1_RGB: 33776,
   DXT1_RGBA: 33777,

package/src/render/DatasetManager.ts

@@ -31,6 +31,8 @@ export interface S3MDatasetOptions {
   align?: DatasetAlignment;
   /** 垂直高度偏移（米），在 align 对齐基准上的额外偏移，正数抬升，负数下降，默认 0 */
   heightOffset?: number;
+  /** 是否用 Web Worker 解析经典 .s3mb 瓦片（默认开，崩溃自动降级主线程），见 S3MTilesetOptions.useWorker */
+  useWorker?: boolean;
   /**
    * 是否对该数据集生成几何棱线（CPU 端 EdgesGeometry）。
    * - 不填：跟随全局 `style.edges`
@@ -194,6 +196,7 @@ export class DatasetManager {
       maxConcurrent: maxConcurrent,
       lodRangeScale: ds.lodRangeScale ?? defaultLodRangeScale,
       buildTile: buildTile ?? null,
+      useWorker: ds.useWorker,
       uniforms: uniforms,
       onTile: (node) => {
         callbacks.onTile(node, entry);

package/src/render/FeatureStyleManager.ts

@@ -6,7 +6,9 @@
  * 2. 专题图分析（按业务字段分段着色、连续插值着色、字段过滤、高度拉伸）
  * 3. 2 行状态纹理（uBatchTex）的烘焙与 GPU 上传：
  *    - Row 0: [R, G, B, elevation / hidden]
- *    - Row 1: [translationX, translationY, translationZ, reserved]
+ *    - Row 1: [translationX, translationY, translationZ, opacity]
+ *      约定：alpha 0 = 无单体透明覆盖（shader 不乘），(0,1) 开区间为实际透明度，
+ *      opacity <= 0 等价 hidden（走 Row 0 的 -1 隐藏位）
  * 4. 批次冲突审计（auditBatches）
  */
 import * as THREE from 'three';
@@ -26,7 +28,7 @@ export interface FeatureStyle {
   elevation?: number;
   /** 自定义单体三维平移偏移量 [dx, dy, dz]（米） */
   translation?: [number, number, number];
-  /** 自定义单体透明度（0~1） */
+  /** 自定义单体透明度（0~1，batch 粒度；<= 0 等价 hidden，1 / 不传 = 不覆盖） */
   opacity?: number;
   /** 是否隐藏该单体 */
   hidden?: boolean;
@@ -562,6 +564,8 @@ export class FeatureStyleManager {
       if (mat.userData.uBatchTexActive) {
         mat.userData.uBatchTexActive.value = 0;
       }
+      // 单体淡化清除后，把材质 transparent 还原成全局透明度语义
+      if (mat.transparent && mat.opacity >= 0.999) mat.transparent = false;
       return;
     }
 
@@ -569,6 +573,7 @@ export class FeatureStyleManager {
       if (mat.userData.uBatchTexActive) {
         mat.userData.uBatchTexActive.value = 0;
       }
+      if (mat.transparent && mat.opacity >= 0.999) mat.transparent = false;
       return;
     }
 
@@ -611,6 +616,7 @@ export class FeatureStyleManager {
     const colorOfBatch = new Map<number, string>();
     const elevOfBatch = new Map<number, number>();
     const translationOfBatch = new Map<number, [number, number, number]>();
+    const opacityOfBatch = new Map<number, number>();
     const ownersOfBatch = new Map<number, number>();
 
     for (const [smidStr, entry] of Object.entries(pickInfo)) {
@@ -661,6 +667,16 @@ export class FeatureStyleManager {
         continue;
       }
 
+      // 单体独立透明度：<= 0 等价 hidden；(0,1) 写入状态纹理第 2 行 alpha；>= 1 不覆盖
+      const fade = st?.opacity;
+      if (fade != null) {
+        if (fade <= 0) {
+          hiddenBatches.add(bId);
+          continue;
+        }
+        if (fade < 1 && !opacityOfBatch.has(bId)) opacityOfBatch.set(bId, fade);
+      }
+
       const col = st?.color ?? this.thematicColors.get(smid);
       if (col && !colorOfBatch.has(bId)) colorOfBatch.set(bId, col);
 
@@ -704,6 +720,19 @@ export class FeatureStyleManager {
       hasActive = true;
     }
 
+    // 单体独立透明度写在第 2 行 alpha：shader 里 0 = 无覆盖，不会误伤未设置的单体
+    let hasFade = false;
+    for (const [bId, fade] of opacityOfBatch) {
+      if (hiddenBatches.has(bId)) continue;
+      data[(w + bId) * 4 + 3] = fade;
+      hasActive = true;
+      hasFade = true;
+    }
+
+    // 有淡化单体时整块材质要开混合才有透明效果；清除后还原为全局透明度语义
+    if (hasFade && !mat.transparent) mat.transparent = true;
+    else if (!hasFade && mat.transparent && mat.opacity >= 0.999) mat.transparent = false;
+
     let conflicts = 0;
     for (const [bId, owners] of ownersOfBatch) {
       if (owners < 2) continue;

package/src/render/S3MViewer.ts

@@ -23,7 +23,8 @@
 import * as THREE from 'three';
 import { S3MTileset, usableGeoBounds } from '../tileset/S3MTileset.js';
 import type { BuildTileFn, TileNode } from '../tileset/S3MTileset.js';
-import { setMaxAnisotropy } from './TextureFactory.js';
+import { setMaxAnisotropy, setTextureOffThreadDecode } from './TextureFactory.js';
+import { decodeTextureWithWorker } from '../worker/S3MWorkerClient.js';
 import {
   STYLE,
   STYLE_LABELS,
@@ -193,6 +194,8 @@ export interface S3MViewerOptions {
   maxTiles?: number;
   /** 每个数据集并发请求数 */
   maxConcurrent?: number;
+  /** 是否用 Web Worker 解析经典 .s3mb 瓦片（默认开，崩溃自动降级主线程），见 S3MTilesetOptions.useWorker */
+  useWorker?: boolean;
   /** LOD 切换范围缩放系数（默认 1.0），> 1 更倾向保留粗模，< 1 提前换细模 */
   lodRangeScale?: number;
   /** 自定义瓦片构建器（测试 / 服务端渲染时注入） */
@@ -401,6 +404,8 @@ export class S3MViewer {
     );
 
     this.uniforms = createSharedUniforms();
+    // 纹理解码优先派给共享解析 Worker（崩溃自动回主线程，见 decodeTextureWithWorker）
+    setTextureOffThreadDecode(decodeTextureWithWorker);
     this.style = { ...DEFAULT_STYLE, ...(options.style ?? {}) };
     this.outlineMaterial = createOutlineMaterial(this.uniforms);
 
@@ -604,7 +609,8 @@ export class S3MViewer {
 
   private _normalizeDatasets(options: S3MViewerOptions): S3MDatasetOptions[] {
     if (Array.isArray(options.datasets)) return options.datasets.filter((d) => !!d?.configUrl);
-    if (options.configUrl) return [{ id: 'default', name: '默认数据集', configUrl: options.configUrl }];
+    if (options.configUrl)
+      return [{ id: 'default', name: '默认数据集', configUrl: options.configUrl, useWorker: options.useWorker }];
     return [];
   }
 

package/src/render/StyleMaterial.ts

@@ -499,6 +499,12 @@ const FRAG_COLOR = /* glsl */ `
       diffuseColor.rgb = bState.rgb;
       hasCustomColor = true;
     }
+    // 单体独立透明度（状态纹理第 2 行 alpha，0 = 无覆盖）。
+    // 与全局 uOpacity（diffuseColor.a 初值）和图集贴图自带 alpha 逐级叠乘
+    vec4 bOffset = texture2D( uBatchTex, vec2( ( s3mBid + 0.5 ) / uBatchTexWidth, 0.75 ) );
+    if ( bOffset.a > 0.0 ) {
+      diffuseColor.a *= bOffset.a;
+    }
   }
 
   // 3. 选中单体高亮 + 其余压暗